Skip to content

A spawn's path is one line, and no judge finds a child by it - #1238

Merged
Japabu merged 2 commits into
mainfrom
spawnpath
Nov 11, 2026
Merged

Japabu merged 2 commits into
mainfrom
spawnpath

Conversation

@Japabu

@Japabu Japabu commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

SYS_SPAWN's path is a label its caller states; nothing opens it. It was any UTF-8 up to 64 KiB and the kernel quoted it raw in the spawn's record and in each refusal's record. A caller could therefore put a line break and a whole forged kernel record into /log (a job's exit: among them, which a metal verdict reads), or state another program's path so that a judge searching spawn: /system/bin/<x> took the wrong process. Each refused spawn also wrote a record, at a rate its caller chose.

Closes issues/a-spawns-record-quotes-the-path-its-caller-states.md (both parts of its exit) and issues/a-refused-syscall-writes-a-log-record-per-call-and-nothing-bounds-the-caller.md (its first shape).

Resulting behaviour

  • Boundary. toyos_abi::syscall::spawn_path takes at most MAX_PATH (4096) bytes of UTF-8 every character of which spawn_path_holds: no control character (Unicode Cc: C0, DEL, C1), the rule shape process_name has. SYS_SPAWN answers InvalidArgument otherwise, bounded before it copies. White space is allowed: a file name may hold a space, and the path is never a token of a record.
  • The SDK fits the label. A file's name may hold a control character (bcachefs refuses only NUL and /), and nothing opens the spawn's path. So Helper::spawn sends the path with each character spawn_path_holds refuses replaced by U+FFFD, cut at a character to MAX_PATH bytes, as name() fits the process name. The ABI's rule is the one predicate both use. Such a program runs as before; only its label in the record shows the replacement.
  • Record. A landed spawn writes spawn: pid=N (total=Nms) <path>: the kernel's fields first, the caller's text last. With the path first, a path longer than a record's 992-byte message cut the pid off its own record; now a cut, or anything the path says, reaches nothing the kernel said.
  • Refusals are silent. A refused spawn writes no record (six sites in the loader and admission). The error is the answer. InvalidArgument and Gone say why. ResourceExhausted covers depth, the pid space, an address space and a kernel stack alike, and nothing now tells them apart: this is an explicitly reported failure, which a program that cares says in its own ring under logkeeper's limit. process_tree's metal judge, which read the depth refusal's record, now holds that every spawn: record of the boot parses as a landed spawn: red on a kernel that records a refusal.
  • The depth is the guest's. Every refusal is ResourceExhausted, so only where the chain stops says it was the depth bound. The job runs two below the supervisor (supervisor 0, test-runner 1, job 2), and link k runs 2 + k below it. So process_tree now asserts the chain's last link is MAX_DEPTH - 2 (62), where it accepted any stop past link 2, and a link past 62 that starts is reported as unbounded. A kernel that refuses a link early for frames, PCIDs or a miscounted depth, or admits one past the bound, now fails the guest.
  • Judges. None reads a spawn: record's path any more:
    • bootlog::spawned_pid reads the pid from the record's head; the source check holds it to the kernel's format string.
    • The supervisor's boot line names the child's pid (supervisor: started logkeeper pid=N); one_clock and virt_job find the kernel's record of that spawn by it.
    • claims::job_records takes the job's pid from its exit record and its window from the spawn that pid landed by.
    • The audio judges open a job's window at the test runner's own ===TEST_START line, under its registered head with no pid=. A line a job writes into the runner's ring carries one.
    • virt_user_mode and virt_low_ecam wait for the first spawn a program asked for; session_lifecycle for the terminal's own terminal: ready and a spawn landing after the command; the typed ls for its exit: record; the undeclared boot for the holder's own line.
    • run_test no longer moves a spawn record that preceded the test's start marker into the window. Since the console carries logkeeper's rounds in stamp order and the runner stamps its marker before it spawns, the record is never behind the marker. A scan of 199 logs captured on 2026-11-11 (metal readbacks of both benches and harness output) finds the job's own spawn record after its marker at every one of 1508 starts (script and result in the evidence).

Other caller text in kernel records was checked: a process name is one token, last words one line, a crash's frames escape the path, and thread names, namespace names and endowment labels reach no record.

Recorded, not fixed here

  • issues/a-capability-holders-refused-claim-or-stop-writes-a-record-per-call.md: a holder of the device or power right still gets a record per refused PCI claim, late declaration of the root bridges' memory, or stop. Not the same mechanism (those records are what device judges read), so not folded in.
  • issues/a-judge-that-searches-a-whole-line-reads-what-a-record-quotes.md: must_say/must_not_say and marker waits match anywhere in a line, so a quoted path can still answer them.
  • issues/a-metal-judge-takes-a-names-lowest-pid-for-the-job.md gains that the exit record's name is also a spawner's label.

Checks

Head e91c70e. It is 6cdc1d0 plus one comment-only commit, which deletes Admission::ask's stale claim that the log names a refusal (follow-up review). Every check below at 6cdc1d0 holds for it. 6cdc1d0 carries the review's fixes in the PR's main commit, rebased onto main f79df95 (main's new commit touches none of this PR's files). The branch merges cleanly into main at 67713cb. The fixes against 9f94ce8 are r2/fixes.diff in the evidence. Checks follow the owner's targeted-testing policy.

Round 2, at 6cdc1d0 (clean tree)

Host, each exit 0:

  • cargo test -p toyos --lib spawn: 7 passed, among them the new a_path_label_is_the_path_as_the_kernel_takes_one. It checks that spawn_path(path_label(p)) is Some for paths holding control characters, past MAX_PATH, and those that grow past it once replaced.
  • cargo test -p toyos-abi: 50 + 4 passed.
  • cargo test --lib bootlog: 16 passed, among them the_writers_write_the_lines_the_host_reads, whose supervisor needle is now derived from LOGKEEPER_STARTED.
  • cargo test --test toyos-checks: 44 passed, among them metal_audio_judges with its new case: a job's line under the runner's head, carrying pid=, does not open the window.
  • Clippy with warnings denied, in CI's shapes, on toyos-abi, toyos and toyos-build.

Negative controls, each patch checked, applied, run and restored in the same run, and the test green again after:

  • With path_label keeping every character, the SDK test fails with exit 101.
  • With the audio start line's pid= test dropped, metal_audio_judges fails with exit 101.

That Helper::spawn calls path_label is one line, read by inspection; no host test reaches the syscall.

process_tree's link-count assertion, on the T14 at 6cdc1d0. process_tree has no QEMU row (it needs tests/images/proctreecase.toml's launcher, declared cat and shell), so the T14's proctreecase boot is the only place to check it.

  • The orchestrator flashed the staged image; toyos-metal's verdict is passed.
  • I judged it from my worktree detached at 6cdc1d0 with a clean tree, through the build slot: cargo test --test toyos-build -- --metal --metal-readback <dir> process_tree exits 0, "PASS process_tree, 1 passed, 0 failed, 1 boot(s)".
  • The guest says a chain of 62 links stopped at a depth refusal (link 62: its next link was refused: out of memory) and died whole, then process_tree: PASS and exit=0. At this revision the guest asserts started == MAX_DEPTH - 2 (62), so the pass is that assertion holding.
  • All 166 spawn: records of the boot parse as landed spawns.
  • Every job and link in this boot was spawned through the SDK's path_label.

Metal at 9f94ce8 (the T14, judged by the orchestrator from a clean worktree)

cargo test --test toyos-build -- --metal --metal-readback <dir> abuse_spawn_path_and_name process_tree hda_tone hda_tone_resampled tone_beside_a_log_write claim_reuses_its_remapping_entry i219_messages_on_its_msi_vector exited 1: 6 passed, 1 failed, 2 boots.

row boot result
abuse_spawn_path_and_name (shared member) testcases pass: 11 refusals (two lines, an escape, not UTF-8, 4097 bytes among them); the 4096-byte path started pid 118, which exited 0, and its cut record kept the pid
process_tree proctreecase PASS: no spawn: record fails to parse; the chain stopped at link 62
hda_tone testcases PASS
hda_tone_resampled testcases PASS
tone_beside_a_log_write testcases PASS (5981 KiB of lines reached the disk beside the tone)
claim_reuses_its_remapping_entry testcases PASS (00:1f.6: irte3 written by both claims, not present after each release, through claims::job_records by pid)
i219_messages_on_its_msi_vector testcases FAIL: test_rs_i219_msi exited 1

The i219 red is the job's own exit, before any judge this PR touches, and the PR changes no NIC, interrupt or network code. Its lines repeat the signature recorded in issues/i219-msi-passes-only-when-the-network-sends-it-a-frame.md: "no frame arrived on a message under traffic", and "the MAC saw 0 frame(s)". one_clock held on both boots: the kernel's spawn: pid=3 (total=0ms) /system/bin/logkeeper and supervisor: started logkeeper pid=3 are at the same millisecond.

The round-2 changes to the audio judge (start line without pid=) and to claims (none) leave these verdicts as they are. The readback's 13 runner start lines carry no pid=.

Round 1, at cafb947 / 9f94ce8 (still valid)

  • cargo run -- --ci host at cafb947: 108 of 110 steps green, including the kernel's library, the models and clippy. The red steps were the known macOS llvm test (issues/the-llvm-environment-test-breaks-git-on-macos.md) and the workspace host members, whose files vanished under a concurrent build. The kernel is unchanged since then.
  • Negative control at 9f94ce8: without the control-character test in spawn_path, a_spawn_path_is_one_bounded_line fails with exit 101.
  • Guest rows at cafb947: 43031069755, x86-64 (session_lifecycle, a_usb_key_reaches_the_console, a_claim_before_the_declaration_is_refused_at_once), 3 passed. 43030459072, aarch64 (virt_user_mode, virt_low_ecam, virt_first_entry), 3 passed. Round 2 changes nothing these rows run but the SDK's path label, which every spawn they make passes through unchanged.
  • The spawn-order scan: in 199 logs, no job's own spawn record precedes its start marker at any of 1508 starts.

Evidence: https://github.com/ToyOSOrg/evidence/tree/01e8615713ba3af85f7a6f666caf783f3e284689 (README.md maps each file to its command, revision and exit code).

Risks

  • The record's field order changed. Every reader in the tree is updated; old captured logs in issues/ quote the old order as history. A later change that adds kernel fields to the record (stage timings, say) must update bootlog::spawned_pid, the source check's needle and the fixtures together, or process_tree's metal judge reads its records as spawns that did not land. Kernel fields go before the path.
  • claims::job_records inherits the lowest-pid-by-name rule the pid-reuse finding records.
  • No dispatched QEMU row goes through run_test. Its deleted move can change a window only when a job's spawn record precedes its start marker, which the scan never finds, and no QEMU judge reads a spawn: record from a test's window any more. The nightly matrix runs the rest.
  • process_tree now holds the job's depth to 2: test-runner is one of the supervisor's programs and spawns each job itself. A runner started deeper, or jobs launched through another process, would fail the assertion with the link count it saw. That is a loud failure, not a silent pass.

🤖 Generated with Claude Code

@Japabu

Japabu commented Nov 11, 2026

Copy link
Copy Markdown
Collaborator Author

Review of #1238 at 9f94ce8

Architecture

The kernel-side shape is right. The approved exit (a) is to refuse the label at SYS_SPAWN. toyos_abi::syscall::spawn_path sits beside process_name and last_words as the contract for a SpawnArgs field, and the kernel bounds the length before it copies. The kernel has no other caller of this rule. That is fine, because the rule is part of the ABI. Allowing white space is justified. Moving the path to the end of the record is what makes that safe: a reader that takes the pid from the record's head cannot be misled by anything the path says, including spaces, and the record's cut can no longer remove the pid. The T14 readback shows this. The 4096-byte path's record (spawn: pid=118 (total=0ms) aaaa…) was cut at the record bound and kept its pid.

Folding in the refused-syscall issue is the right call. Deleting the six log! calls makes a refused spawn write nothing. That is less mechanism than a counter, and the remaining capability-gated per-call records are recorded separately.

For exit (b), every judge that reads a spawn: record now reads only its pid. The supervisor: started <name> pid=N line, an exit record, or the runner's start line names that pid, and a host test ties the reader to the writers' formats. I checked deleting run_test's move independently, against logkeeper's code rather than the PR's description. round() takes cut first, reads every ring before the kernel's, and writes only lines stamped at or before cut, in stamp order. The runner stamps and publishes ===TEST_START into its ring with no syscall (toyos::log::stdio) before it calls SYS_SPAWN, so the kernel's record has a later stamp. That record can only be written in a round whose ring read already contains the marker. On x86-64 the console is that same replay. On aarch64 virt the kernel writes the PL011 inline, but no virt row uses run_test. I also looked at one of the two starts the scan flagged (spawnperf/runs2/amd): the osbench_procs spawns at pids 686 and later are test_rs_spawn_stages' children, inside that job's window, and the job's own spawn (pid 4718) follows its marker. The deletion is safe, and with the new record format the old matcher could no longer match anyway.

Size: production code is net about +7 lines. The validator's +12 roughly offsets the six deleted log! calls, and the supervisor's line gains its pid. build/bootlog.rs gains about 45 lines of reader code and 30 of test. The harness loses run_test's 24-line move.

Metal (T14 readbacks at 9f94ce8, judged from a clean detached worktree at 9f94ce8)

Command, run through the build slot from a clean worktree (status 0) at 9f94ce8: cargo test --test toyos-build -- --metal --metal-readback <spawnpath>/scratch/metal abuse_spawn_path_and_name process_tree hda_tone hda_tone_resampled tone_beside_a_log_write claim_reuses_its_remapping_entry i219_messages_on_its_msi_vector. It exited 1, with "6 passed, 1 failed, 2 boot(s)". The images were staged at 9f94ce8 from a clean tree (metal-stage-3.log).

row boot result
abuse_spawn_path_and_name (shared member) testcases pass (1 of 1 member with both markers). It made 11 refusals, including two lines, an escape, non-UTF-8 and 4097 bytes. The 4096-byte path started pid 118, which exited 0.
process_tree proctreecase PASS. No spawn: record fails to parse on either boot (160 and 120 records). The chain stopped at link 62.
hda_tone testcases PASS
hda_tone_resampled testcases PASS
tone_beside_a_log_write testcases PASS (5981 KiB of lines reached the disk beside the tone)
claim_reuses_its_remapping_entry testcases PASS (00:1f.6: irte3 written by both claims, not present after each release, through claims::job_records by pid)
i219_messages_on_its_msi_vector testcases FAIL: test_rs_i219_msi exited 1

The i219 red is independent of this change. The job's own lines repeat the signature recorded in issues/i219-msi-passes-only-when-the-network-sends-it-a-frame.md: "no frame arrived on a message under traffic", "the MAC saw 0 frame(s), took 0 good, missed 0", the link up after 2.7 s and 65 descriptors written back. The row went red at the job's own exit, before any judge code this PR touches, and the PR changes no NIC, interrupt or network code.

one_clock on both boots: the kernel's record spawn: pid=3 (total=0ms) /system/bin/logkeeper and the supervisor's line supervisor: started logkeeper pid=3 are both at 10.777 s (proctreecase) and both at 10.707 s (testcases). The boots came back in 71 s and 60 s, and the harness reports no number past its record. wake_onto_busy's exit=51 is its p99 reading, which that job reports through its exit code.

Required

  1. sdk/toyos/src/spawn.rs:210: the SDK sends a raw path, which the kernel now refuses. A program whose file name holds a control character can no longer be spawned.
    Helper::spawn passes s.image/s.program unchanged as path_ptr. bcachefs accepts any name byte except NUL and / (valid_name, lib/bcachefs/src/engine/mount/ops.rs:69), and the fs path has no control-character check. So Command::new(p).spawn() for an existing file p that contains, for example, \x01 or \n now fails with an unexplained InvalidArgument, after the parent has already read and laid out the image. Before this PR it ran. The PR keeps white space because "a file's name may hold a space", and the same reasoning applies here. process_name got the same rule shape and has an SDK side, name() at spawn.rs:408, so an honest caller never hits the kernel's refusal. The path needs the same. The cheapest fix is for Helper::spawn to fit the label: replace each control character, for example with U+FFFD, since nothing opens the path. Add a host unit test next to name()'s that holds spawn_path(fitted).is_some() for any input. The kernel boundary stays as it is.

  2. tests/guest/rust-tests/src/bin/process_tree.rs:330 with tests/toyos.rs:1362/6561: the depth arm no longer has any check that it stopped at the depth bound.
    The deleted metal judge was the only check that the chain's refusal was the depth bound: exactly one record, at depth 65. The guest's own test accepts any refusal after link 2 (assert!(started >= 2)), and every cause is ResourceExhausted. The T14 run's line even reads its next link was refused: out of memory. So a kernel that refuses link 3 for frames, PCIDs or a miscounted depth now passes process_tree on every target, while the guest still prints "stopped at a depth refusal". The registration comment says "the guest carries every verdict", which is no longer true for this arm. The cheapest fix is guest-side and needs no kernel record. The job runs at a fixed depth under the runner (supervisor 0, test-runner 1, job 2), so the guest can assert started == MAX_DEPTH - 2, stating that reason. The T14 readback shows 62, which matches. If you think the host test of toyos_proclife plus inspection is enough, say so. Then make the guest's output and doc, and the registration comment, stop claiming a depth refusal.

Suggestions (optional)

  • tests/common/audio.rs:7,15: "The line is the runner's own" overstates the check. A job the runner spawned writes into the runner's ring under the same test-runner head, with pid=N, and program_line drops the pid=. Either require a line with no pid= (through toyos_logstream::parse's rest) or reword the comment to "under the runner's head". bootlog's existing JOB_DEADLINE_SAID reader has the same property, so this is not a regression.
  • build/bootlog.rs:574-584: the supervisor's needle is a literal and is not derived from LOGKEEPER_STARTED, so changing that constant leaves the test green. Building it with LOGKEEPER_STARTED.replacen("logkeeper", "{}", 1) would tie them. The test name and expect("a kernel module") also no longer describe the supervisor file.
  • tests/checks/audio.rs:21 and its comments ("after its spawn", "held since before the spawn"): the closure named spawn now builds the runner's start line.
  • issues/a-capability-holders-refused-claim-or-stop-writes-a-record-per-call.md:11 says "Two holders still can". pcidev::declare (kernel/src/pcidev/mod.rs:726) also writes one record for each late declaration by the acpi claim holder.
  • Commit message: "the error already says why" is not true of ResourceExhausted, which now covers depth, the pid space, PCID or root-frame exhaustion and the kernel stack, with no record telling them apart. That is acceptable for an explicitly reported failure, but the claim should say so. The message also cites 1610 starts in 176 logs, while the evidence's rerun has 1508 in 199.
  • Old-format fixtures remain in tests/checks/qemu.rs:225, tests/checks/serial.rs:253,280 and lib/logstream/src/lib.rs:988. They test nothing about the format and could be left.

Interfaces the later spawn-path PRs inherit

  • Record format. bootlog::spawned_pid accepts exactly spawn: pid=N (total=Nms) followed by a space and the path, or by nothing. the_kernel_writes_the_records_the_host_reads holds the kernel's format string to it literally. process_tree's metal judge treats any spawn: record that does not parse as a spawn that did not land. So if spawnperf adds stage timings to the record, as an earlier format had with (layout=… tls=… total=…), it must update spawned_pid, the needle and the fixtures together. Otherwise process_tree goes red on metal. Kernel fields go before the path.
  • The ABI. spawn_path holds SpawnArgs.path to at most MAX_PATH bytes with no control character. If endowments ever quotes an endowment label in a record, it needs the same treatment. Today no record quotes one.
  • The supervisor's boot line is supervisor: started <name> pid=<pid>, and the source check holds its format.
  • Judges. claims::job_records takes a job's pid from its lowest-pid exit record by name, which is recorded in issues/a-metal-judge-takes-a-names-lowest-pid-for-the-job.md. run_test no longer moves spawn records.

Evidence checked

  • Guest runs 43031069755 (x86-64: session_lifecycle, a_usb_key_reaches_the_console, a_claim_before_the_declaration_is_refused_at_once) and 43030459072 (aarch64: virt_user_mode, virt_low_ecam, virt_first_entry) are success at cafb947. git diff cafb947fd 9f94ce818 -- . ':!issues' is empty, so they hold for the head.
  • The negative control is the host unit test. With the is_control check removed, the mutated build exits 0 and a_spawn_path_is_one_bounded_line exits 101 on "a\nb". After restoring, the tree is clean and the test exits 0. The guest arm's refusal follows by construction from assert_eq!(answer, Err(InvalidArgument)).
  • I read the spawn-order scan's script and output: 1503 after, 2 before and 3 with no record of their job make 1508 starts. I checked one of the two "before" starts in its log, as described above.

SEND BACK. Two required findings remain. Both fixes are small: the SDK fits the path label, and the depth arm keeps a check of the depth or stops claiming it. What re-review needs: the SDK host test, plus a process_tree run at the fixed head, either a QEMU row through guest-rows.yml or the T14 proctreecase boot, that shows the guest's link-count assertion holding (62 on the T14). Apart from these two findings, the metal evidence above supports landing.

`SYS_SPAWN`'s path is a label its caller states, which the kernel quotes in
the spawn's record, and quoted in each refusal's. It was any UTF-8 up to
64 KiB, so a caller could put a line break and a whole kernel record of its
own writing into `/log`, a job's exit record among them, or state another
program's path.

The boundary: `toyos_abi::syscall::spawn_path` takes a path of at most
`MAX_PATH` bytes of UTF-8 every character of which `spawn_path_holds`: no
control character, the shape `process_name` and `last_words` have.
`SYS_SPAWN` answers `InvalidArgument` for any other before it copies it.
White space stays: a file's name may hold a space.

The SDK states the path it spawns from with each character `spawn_path_holds`
refuses replaced by U+FFFD, cut at a character to `MAX_PATH` bytes, as it
fits a process's name. A file's name may hold a control character, and
nothing opens the label, so such a program still runs.

The record now says the kernel's fields first and the path last,
`spawn: pid=N (total=Nms) <path>`. A path may be 4096 bytes and a record
holds 992, so with the path first a long one cut the pid off its own
record; last, a cut or anything the path says reaches nothing the kernel
said.

`abuse_spawn_path_and_name` holds a path of two lines, one holding an
escape, one that is not UTF-8 and one a byte past the bound refused, and
the longest path starting a child.

A refused spawn writes no record. Each of its six refusals wrote one per
call, naming the path, into the log every program shares, and its caller
chose how often. The error is the answer. `InvalidArgument` and `Gone` say
why; `ResourceExhausted` covers the depth, the pid space, an address space
and a kernel stack alike, and nothing now tells them apart: an explicitly
reported failure, which a program that cares says in its own ring, under
logkeeper's limit. The landed spawn's record is then the one place the
kernel quotes the path. `process_tree`'s metal judge, which read the depth
refusal's record for its depth, now holds that every `spawn:` record of the
boot is of a spawn that landed: red on a kernel that records the chain's
refusal. The depth is the guest's: the job runs two below the supervisor,
so its chain must stop at link `MAX_DEPTH - 2`, since only where it stops
says the refusal was the depth's. The `dlopen` the issue named is gone with
`SYS_DLOPEN`.

The judges: none reads a `spawn:` record's path any more.

- `bootlog::spawned_pid` reads the pid from the record's head, which is the
  kernel's, and is held to the kernel's format string by the source check.
- The supervisor's boot line names the pid it started (`supervisor: started
  logkeeper pid=N`), and `one_clock` and `virt_job` find the kernel's record
  of that spawn by it.
- `claims::job_records` takes the job's pid from its exit record and the
  spawn that pid landed by.
- The audio judges open a job's window at the test runner's own start line,
  one whose head carries no `pid=`, which a job's line in the runner's ring
  does.
- `virt_user_mode` and `virt_low_ecam` wait for the second spawn record, the
  first a program asked for; `session_lifecycle` for the terminal's own line
  and a spawn landing after the command was typed; the typed `ls` for its
  exit record; and the undeclared boot for the holder's own line.
- `run_test` no longer moves a spawn record that preceded its test's start
  marker into the window. It dates from the kernel's records reaching the
  console by another road than a program's lines; since the console carries
  logkeeper's rounds in stamp order the runner's marker, stamped before it
  spawns, is never behind the record. 1508 job starts in 199 captured logs
  show none.

No other kernel record prints a process's text raw: a name is one token
(`process_name`), last words are one line (`last_words`), a crash's frames
escape the path, the firmware's OEM id is debug-printed, and thread names,
namespace names and endowment labels reach no record.

Closes issues/a-spawns-record-quotes-the-path-its-caller-states.md and
issues/a-refused-syscall-writes-a-log-record-per-call-and-nothing-bounds-the-caller.md.
What is left is recorded: a holder of the device or power right still has a
record per refused claim, declaration or stop
(issues/a-capability-holders-refused-claim-or-stop-writes-a-record-per-call.md),
a judge that searches a whole line can be answered by what a spawn's record
quotes
(issues/a-judge-that-searches-a-whole-line-reads-what-a-record-quotes.md),
and an exit record's name is its spawner's label too
(issues/a-metal-judge-takes-a-names-lowest-pid-for-the-job.md).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Japabu

Japabu commented Nov 11, 2026

Copy link
Copy Markdown
Collaborator Author

Follow-up review of #1238 at 6cdc1d0 (round 2)

Scope: the two required findings from the previous review, the code changed to fix them, and the suggestions taken. I read the PR's own interdiff 9f94ce818..6cdc1d015, leaving out main's rebased commit f79df95, which touches none of these files. I also read the callers it relies on. I reran no tests.

Architecture

Both fixes are in the right place. The ABI owns the predicate. spawn_path_holds is the single per-character rule that spawn_path (the kernel's validator) and the SDK's path_label both use, so the SDK cannot drift from the boundary. Replacement happens in the SDK, which is the only party that knows the label is never opened. The depth check is in the guest, which is the only place that can still see it, because a refusal now writes nothing. Round 2 adds about 20 production lines (path_label, the ABI predicate, the audio start-line check) and about 30 test lines.

Required finding 1: SDK path label. Resolved.

  • UTF-8 boundary (sdk/toyos/src/spawn.rs:429). The input is &str, and path_label pushes only whole chars. It stops before the first char that would exceed MAX_PATH. The result is therefore valid UTF-8 and at most MAX_PATH bytes by construction, with no byte truncation.
  • A label that grows during replacement still fits. The bound check uses the replaced char's len_utf8(), which is 3 for U+FFFD. U+FFFD is not Cc, so spawn_path_holds accepts it. The test's grows case covers this: 4096 copies of \u{1} become 1365 copies of U+FFFD (4095 bytes), and a 3-byte char exactly at the bound is left out whole.
  • Every SDK spawn path. sdk/toyos/src/spawn.rs:278 is the only SpawnArgs construction in sdk/, system/, lib/ and apps/. It sits inside Helper::spawn. Both callers of Helper::spawn reach it: std's Command (sdk/std/sys/process.rs:481) and libc's posix_spawn (sdk/libc/src/spawn.rs:353). The supervisor's row starts and its launches go through std's Command. The other direct SpawnArgs builders are guest tests that deliberately speak raw ABI. The label (String) is a local that outlives the syscall.
  • Host test a_path_label_is_the_path_as_the_kernel_takes_one (spawn.rs:512). It holds the identity cases (ASCII, space, non-ASCII) and the replacement of C0, ESC and C1. It holds the cut at a char for both the plain and the grown case, and spawn_path(path_label(p)).is_some() for each input. The control (if true || …) fails with exit 101 on the replacement assertion, and the test passes again after restore (r2/controls/control-sdk.log, clean tree at 6cdc1d0).

Required finding 2: process_tree depth. Resolved in code. Metal confirmation pending.

tests/guest/rust-tests/src/bin/process_tree.rs:335 now has assert_eq!(started, LAST_LINK) with LAST_LINK = MAX_DEPTH - JOB_DEPTH = 62. The arithmetic matches toyos_proclife::tree: depth > MAX_DEPTH is refused, and depth 64 is admitted. Link k is at depth 2 + k, so link 62 is admitted and link 63 is refused. The links write to the chain's one pipe in causal order: a link prints its index before it spawns the next. I traced each other stopping point:

  • Refused before 62, for out-of-memory, PCIDs or any other reason. The refusing link j prints its … refused … line after link j. Then started == j != 62, assert_eq! panics, and the job is red.
  • Admitted past the bound. Link 63 prints link 63 and then unbounded at link 63 (:348 now compares against LAST_LINK), so the loop panics and the job is red.
  • A link dies without a refusal line. Its parked ancestors keep the pipe open, read_line blocks, and the harness ceiling makes it red. This is unchanged from before.

Only a refusal at exactly link 62 for a reason other than the depth is still indistinguishable. That is inherent, because every cause is ResourceExhausted, and the PR states it. The 9f94ce8 T14 boot printed a chain of 62 links stopped at a depth refusal (metal-9f94ce818/proctreecase-kernel.log), so the asserted value matches what metal produced. The registration comment ("the guest carries every verdict but the kernel's silence on a refused spawn") is now true.

The 6cdc1d0 proctreecase boot is staged from a clean tree (r2/metal/staging.log, rev 6cdc1d0, changed=0, exit 2 meaning staged and not run). The guest binary carrying the assertion was built there. The readback had not arrived when this review was written: the directory holds only image.img and the system toml, with no verdict.txt. So process_tree at this head is LAND-pending-that-boot.

Suggestions taken

  • Audio start line (tests/common/audio.rs:14). The new condition is Source::Program("test-runner"), an empty rest that contains no pid=, and text == marker. I checked this against logkeeper: system/logkeeper/src/main.rs:563 writes pid= only when the writer is not the ring's owner. The runner's own line therefore never carries it, and a job's line in the runner's ring always does (the 9f94ce8 readback shows test-runner pid=13 for the job's lines). The planted case (tests/checks/audio.rs:66) would open the window on a session that is short of periods and connected before the output was offered. Its control fails with exit 101 and passes after restore. Correct.
  • build/bootlog.rs:576. LOGKEEPER_STARTED.replacen("logkeeper", "{}", 1) builds say!("supervisor: started {} pid={}", which matches system/supervisor/src/main.rs:3329. A change to the constant now turns the test red. The test name and the expect text fit what they check. Correct.
  • Renames in tests/checks/audio.rs (spawn → start, and the case names and comments). Accurate.
  • The issue's pcidev::declare bullet matches kernel/src/pcidev/mod.rs:726.
  • The commit message now says that ResourceExhausted no longer separates its causes and that this is an explicitly reported failure. It cites 1508 starts in 199 logs, which matches the scan's result.

Findings

BLOCKER

  1. kernel/src/process.rs:523 — Admission::ask's doc says "ResourceExhausted, which the log names, for a child more than MAX_DEPTH below the supervisor or no pid left to issue". This PR deleted exactly those two log! calls in the same function (TooDeep, NoPid). Nothing names it now. This comment states the opposite of the fact that finding 2 depends on: a depth refusal leaves no record, so only the guest's link count shows it. It is false and was introduced by this change. The previous round missed it. Fix: delete ", which the log names,". This is a comment-only edit, so root's testing policy requires no rerun.

SUGGESTION

  • None beyond the round-1 suggestions already settled.

Evidence checked

  • r2/host-targeted/*.log: each one is at rev 6cdc1d0 with a clean tree and exit 0. toyos-abi 50+4 passed, toyos --lib spawn 7 passed, bootlog 16 passed, toyos-checks 44 passed, and clippy -D warnings passed on toyos-abi, toyos and toyos-build. The kernel's only change in this round is through spawn_path, whose signature and behaviour are unchanged. The staged image built the kernel and the guest at 6cdc1d0.
  • r2/controls/: both patches are single-line mutations of the code under test. Each was applied to a clean tree, failed with exit 101, was restored to 0 changed files, and passed again.

SEND BACK, only for the one-line comment above. Both required findings are resolved and the suggestion changes are correct. Once the comment is fixed, this is LAND pending the T14 proctreecase boot at 6cdc1d0 showing process_tree green, judged with cargo test --test toyos-build -- --metal --metal-readback <metal dir> process_tree.

A refused spawn writes no record since the spawn's path became one line, so
the doc no longer says the log names `ResourceExhausted`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Japabu

Japabu commented Nov 11, 2026

Copy link
Copy Markdown
Collaborator Author

Orchestrator: verified e91c70e. git diff 6cdc1d015 e91c70e31 changes only the comment at kernel/src/process.rs:523 (", which the log names," removed). The round-2 required finding is resolved, and the code is identical to the staged and tested 6cdc1d0. Landing waits only for process_tree to be green on the T14 proctreecase boot at 6cdc1d0, which is next on the bench.

@Japabu

Japabu commented Nov 11, 2026

Copy link
Copy Markdown
Collaborator Author

Orchestrator: T14 proctreecase at 6cdc1d0 (the code of e91c70e) judged PASS process_tree: "a chain of 62 links stopped at a depth refusal". The guest's started == MAX_DEPTH - 2 assertion held, and all 166 spawn: records are of landed spawns. Both review rounds are resolved. Queueing; this lands first among the spawn-path changes.

@Japabu
Japabu marked this pull request as ready for review November 11, 2026 17:14
@Japabu
Japabu added this pull request to the merge queue Nov 11, 2026
Merged via the queue into main with commit 6d4b7e4 Nov 11, 2026
10 checks passed
@Japabu
Japabu deleted the spawnpath branch November 11, 2026 17:28
Japabu added a commit that referenced this pull request Nov 11, 2026
…hat a spawn copies

`SYS_NAMESPACE_OPEN`'s name was the last caller of `SyscallContext::user_str`;
#1238 already reads a spawn's path as bytes bounded by `MAX_PATH`. So
`user_str` and `MAX_USER_STR` go, and `KernelStack::heap` charges each thread
for what its largest call copies in and holds while preempted: a spawn's path,
name and build-id at their bounds, its ranges and its endowments, by their
types. It used to charge two 64 KiB strings and a page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Japabu added a commit that referenced this pull request Nov 11, 2026
…hat its spawn copies

`SYS_NAMESPACE_OPEN`'s name was the last caller of `SyscallContext::user_str`;
#1238 already reads a spawn's path as bytes bounded by `MAX_PATH`. So
`user_str` and `MAX_USER_STR` go.

`KernelStack::heap` charged every thread two 64 KiB strings and a page for
what a call copies in. It now charges, by their types, what a spawn copies in
and holds where it may be preempted:
- its path, name and build-id at their bounds;
- its ranges;
- its endowments;
- the mappings of the device claims it moves, in a vector now sized once at
  the first claim so it never grows past that.

It claims nothing for another call. `SYS_SYSINFO`'s roster, larger and held
across a copy-out that can wait, is charged to its caller for the call, in a
commit of its own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Japabu added a commit that referenced this pull request Nov 11, 2026
…hat its spawn copies

`SYS_NAMESPACE_OPEN`'s name was the last caller of `SyscallContext::user_str`;
#1238 already reads a spawn's path as bytes bounded by `MAX_PATH`. So
`user_str` and `MAX_USER_STR` go.

`KernelStack::heap` charged every thread two 64 KiB strings and a page for
what a call copies in. It now charges, by their types, what a spawn copies in
and holds where it may be preempted:
- its path, name and build-id at their bounds;
- its ranges;
- its endowments;
- the mappings of the device claims it moves, in a vector now sized once at
  the first claim so it never grows past that.

It claims nothing for another call. `SYS_SYSINFO`'s roster, larger and held
across a copy-out that can wait, is charged to its caller for the call, in a
commit of its own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Japabu added a commit that referenced this pull request Nov 11, 2026
…cks' spawn records in main's form

Main moved under the branch in three places this branch also changes:
#1241 renamed `machine_shutdown_short_stop` to
`machine_shutdown_with_a_thread_spinning`, which is now that name's
`MACHINE_TESTS` entry; #1238 changed `virt_user_mode`'s arm, which this branch
moved into a function and which now carries the change; and #1238 changed the
kernel's spawn record to `spawn: pid=N (total=Xms) <path>` and the
supervisor's to `started logkeeper pid=N`, which the one-clock check's planted
log now writes beside the T14's first record.

#1238's readers no longer read the older form, so the two bench readbacks
this branch carries as fixtures, written before it, read as a boot with no
record of logkeeper's spawn and a job with no spawn record. Their three
lines each are rewritten in the form the kernel and the supervisor now write,
with the same pids and times.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Japabu added a commit that referenced this pull request Nov 11, 2026
…cks' spawn records in main's form

Main moved under the branch in three places this branch also changes:
#1241 renamed `machine_shutdown_short_stop` to
`machine_shutdown_with_a_thread_spinning`, which is now that name's
`MACHINE_TESTS` entry; #1238 changed `virt_user_mode`'s arm, which this branch
moved into a function and which now carries the change; and #1238 changed the
kernel's spawn record to `spawn: pid=N (total=Xms) <path>` and the
supervisor's to `started logkeeper pid=N`, which the one-clock check's planted
log now writes beside the T14's first record.

#1238's readers no longer read the older form, so the two bench readbacks
this branch carries as fixtures, written before it, read as a boot with no
record of logkeeper's spawn and a job with no spawn record. Their three
lines each are rewritten in the form the kernel and the supervisor now write,
with the same pids and times.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Japabu added a commit that referenced this pull request Nov 11, 2026
…hat its spawn copies

`SYS_NAMESPACE_OPEN`'s name was the last caller of `SyscallContext::user_str`;
#1238 already reads a spawn's path as bytes bounded by `MAX_PATH`. So
`user_str` and `MAX_USER_STR` go.

`KernelStack::heap` charged every thread two 64 KiB strings and a page for
what a call copies in. It now charges, by their types, what a spawn copies in
and holds where it may be preempted:
- its path, name and build-id at their bounds;
- its ranges;
- its endowments;
- the mappings of the device claims it moves, in a vector now sized once at
  the first claim so it never grows past that.

It claims nothing for another call. `SYS_SYSINFO`'s roster, larger and held
across a copy-out that can wait, is charged to its caller for the call, in a
commit of its own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Japabu added a commit that referenced this pull request Nov 11, 2026
…leave the kernel

The kernel kept, for every process, the labels its parent put on each
endowment, compared three of them (`job`, `self`, `quit`), answered them back
through `SYS_ENDOWMENTS`, and held a namespace object that mapped service
names to connectors behind three more calls. None of that is the kernel's:
it is what one program calls a handle it gave another.

Now a spawn moves a list of handles and nothing else. The child's table
starts with its handle to itself (`RawHandle::SELF`), its notice
(`RawHandle::NOTICE`), then the endowments in the order the spawn listed them
(`RawHandle::endowed(i)`); the kernel installs them so and asserts it. What
the parent calls each is a table it writes in the child's startup block,
which the child's SDK checks once, whole, before it looks one up: a table
that is no list of distinct, non-empty UTF-8 names ends the child, said on
its `fd:2` where the table still names one.

- `SpawnArgs::job` replaces the `job` label: a borrowed handle carrying
  `WRITE`, resolved once like the place and the pager, so the commit's
  re-check that the moved handle still named the job goes.
- `SYS_CONNECT` (102, `SYS_NAMESPACE_OPEN`'s number) connects through a
  connector carrying `WRITE`, which a connector is now minted with. One
  without it may only be passed on.
- `SYS_ENDOWMENTS` (99), `SYS_NAMESPACE_BUILD` (101), `SYS_NAMESPACE_NAMES`
  (170), the namespace object, `SpawnEndow`, `EndowEntry`, the label blob
  and its per-process charge go; the freed numbers stay unassigned.
  `MAX_SPAWN_ENDOWMENTS` is 96: the 30 a spawn carried plus the 64 a
  namespace held, so everything one table and one namespace expressed still
  fits. The names are bounded by the startup block alone.
- The supervisor, whose parent is the kernel, starts holding its system
  capability, the file server's image, ROOT's and the boot names at the four
  handles `toyos_abi::boot::supervisor` states.

In userland a service is a connector named `svc:<name>` (a row's
`receives`, its view's `fs:` directories, minted grants) or
`provide:<name>` (one a launching client sent). `endow::service` looks one
up and connects; a helper is given a duplicate of each its parent holds,
narrowed by `CommandExt::services_only`. Everything else is taken once by
name. The supervisor gives a provided connector to a row that does not
receive it without `WRITE`; swap's connector arrives with `WRITE` alone, as
its one holder only connects. The supervisor adopts its own directory
capabilities (`std::os::toyos::fs::adopt_services`), which no child
inherits: so a storage row, whose view is empty, now starts holding no file
grant, where it inherited the supervisor's whole tree.

`SYS_NAMESPACE_OPEN`'s name was the last caller of `SyscallContext::user_str`,
since #1238 reads a spawn's path as bytes bounded by `MAX_PATH`. So
`user_str` and `MAX_USER_STR` go. `KernelStack::heap` charged every thread
two 64 KiB strings and a page for what a call copies in. It now charges, by
their types, what a spawn copies in and holds where it may be preempted:
- its path, name and build-id at their bounds;
- its ranges;
- its endowments;
- the mappings of the device claims it moves, in a vector sized once at the
  first claim so it never grows past that.
It claims nothing for another call.

A block session holds a connector and no service name, so diskserver's two
messages for a session's server that broke the protocol or went silent
name the session by its partition GUID.

Kernel: 55,155 lines in 211 files at main 8188095 to 54,797 in 210.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Japabu added a commit that referenced this pull request Nov 11, 2026
…leave the kernel

The kernel kept, for every process, the labels its parent put on each
endowment, compared three of them (`job`, `self`, `quit`), answered them back
through `SYS_ENDOWMENTS`, and held a namespace object that mapped service
names to connectors behind three more calls. None of that is the kernel's:
it is what one program calls a handle it gave another.

Now a spawn moves a list of handles and nothing else. The child's table
starts with its handle to itself (`RawHandle::SELF`), its notice
(`RawHandle::NOTICE`), then the endowments in the order the spawn listed them
(`RawHandle::endowed(i)`); the kernel installs them so and asserts it. What
the parent calls each is a table it writes in the child's startup block,
which the child's SDK checks once, whole, before it looks one up: a table
that is no list of distinct, non-empty UTF-8 names ends the child, said on
its `fd:2` where the table still names one.

- `SpawnArgs::job` replaces the `job` label: a borrowed handle carrying
  `WRITE`, resolved once like the place and the pager, so the commit's
  re-check that the moved handle still named the job goes.
- `SYS_CONNECT` (102, `SYS_NAMESPACE_OPEN`'s number) connects through a
  connector carrying `WRITE`, which a connector is now minted with. One
  without it may only be passed on.
- `SYS_ENDOWMENTS` (99), `SYS_NAMESPACE_BUILD` (101), `SYS_NAMESPACE_NAMES`
  (170), the namespace object, `SpawnEndow`, `EndowEntry`, the label blob
  and its per-process charge go; the freed numbers stay unassigned.
  `MAX_SPAWN_ENDOWMENTS` is 96: the 30 a spawn carried plus the 64 a
  namespace held, so everything one table and one namespace expressed still
  fits. The names are bounded by the startup block alone.
- The supervisor, whose parent is the kernel, starts holding its system
  capability, the file server's image, ROOT's and the boot names at the four
  handles `toyos_abi::boot::supervisor` states.

In userland a service is a connector named `svc:<name>` (a row's
`receives`, its view's `fs:` directories, minted grants) or
`provide:<name>` (one a launching client sent). `endow::service` looks one
up and connects; a helper is given a duplicate of each its parent holds,
narrowed by `CommandExt::services_only`. Everything else is taken once by
name. The supervisor gives a provided connector to a row that does not
receive it without `WRITE`; swap's connector arrives with `WRITE` alone, as
its one holder only connects. The supervisor adopts its own directory
capabilities (`std::os::toyos::fs::adopt_services`), which no child
inherits: so a storage row, whose view is empty, now starts holding no file
grant, where it inherited the supervisor's whole tree.

`SYS_NAMESPACE_OPEN`'s name was the last caller of `SyscallContext::user_str`,
since #1238 reads a spawn's path as bytes bounded by `MAX_PATH`. So
`user_str` and `MAX_USER_STR` go. `KernelStack::heap` charged every thread
two 64 KiB strings and a page for what a call copies in. It now charges, by
their types, what a spawn copies in and holds where it may be preempted:
- its path, name and build-id at their bounds;
- its ranges;
- its endowments;
- the mappings of the device claims it moves, in a vector sized once at the
  first claim so it never grows past that.
It claims nothing for another call.

A block session holds a connector and no service name, so diskserver's two
messages for a session's server that broke the protocol or went silent
name the session by its partition GUID.

Kernel: 55,416 lines in 212 files at main 75bdec3 to 55,058 in 211.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Japabu added a commit that referenced this pull request Nov 12, 2026
…leave the kernel

The kernel kept, for every process, the labels its parent put on each
endowment, compared three of them (`job`, `self`, `quit`), answered them back
through `SYS_ENDOWMENTS`, and held a namespace object that mapped service
names to connectors behind three more calls. None of that is the kernel's:
it is what one program calls a handle it gave another.

Now a spawn moves a list of handles and nothing else. The child's table
starts with its handle to itself (`RawHandle::SELF`), its notice
(`RawHandle::NOTICE`), then the endowments in the order the spawn listed them
(`RawHandle::endowed(i)`); the kernel installs them so and asserts it. What
the parent calls each is a table it writes in the child's startup block,
which the child's SDK checks once, whole, before it looks one up: a table
that is no list of distinct, non-empty UTF-8 names ends the child, said on
its `fd:2` where the table still names one.

- `SpawnArgs::job` replaces the `job` label: a borrowed handle carrying
  `WRITE`, resolved once like the place and the pager, so the commit's
  re-check that the moved handle still named the job goes.
- `SYS_CONNECT` (102, `SYS_NAMESPACE_OPEN`'s number) connects through a
  connector carrying `WRITE`, which a connector is now minted with. One
  without it may only be passed on.
- `SYS_ENDOWMENTS` (99), `SYS_NAMESPACE_BUILD` (101), `SYS_NAMESPACE_NAMES`
  (170), the namespace object, `SpawnEndow`, `EndowEntry`, the label blob
  and its per-process charge go; the freed numbers stay unassigned.
  `MAX_SPAWN_ENDOWMENTS` is 96: the 30 a spawn carried plus the 64 a
  namespace held, so everything one table and one namespace expressed still
  fits. The names are bounded by the startup block alone.
- `ObjectKind::Namespace` goes and its word 8 stays unused, as `ObjectKind`
  says a word that goes does: `SysCap` through `DeviceSet` keep 9 to 19,
  `from_word` looks a word up rather than indexing by it, the SDK's census
  finds a kind's count by its place in `ALL`, and the SDK's receive test
  takes word 8 and the word past the last kind as ones no kind has.
- The supervisor, whose parent is the kernel, starts holding its system
  capability, the file server's image, ROOT's and the boot names at the four
  handles `toyos_abi::boot::supervisor` states.

In userland a service is a connector named `svc:<name>` (a row's
`receives`, its view's `fs:` directories, minted grants) or
`provide:<name>` (one a launching client sent). `endow::service` looks one
up and connects; a helper is given a duplicate of each its parent holds,
narrowed by `CommandExt::services_only`. Everything else is taken once by
name. The supervisor gives a provided connector to a row that does not
receive it without `WRITE`; swap's connector arrives with `WRITE` alone, as
its one holder only connects. The supervisor adopts its own directory
capabilities (`std::os::toyos::fs::adopt_services`), which no child
inherits: so a storage row, whose view is empty, now starts holding no file
grant, where it inherited the supervisor's whole tree.

A connector a peer sent, as a session's launcher and controls are, is typed
only where the kernel reported a connector (`ReceivedHandle::typed`), and an
endowed one on its parent's word. std's `adopt_services` is `unsafe`, as
`adopt_namespace` was: the handles it takes are its caller's word.

`SYS_NAMESPACE_OPEN`'s name was the last caller of `SyscallContext::user_str`,
since #1238 reads a spawn's path as bytes bounded by `MAX_PATH`. So
`user_str` and `MAX_USER_STR` go. `KernelStack::heap` charged every thread
two 64 KiB strings and a page for what a call copies in. It now charges, by
their types, what a spawn copies in and holds where it may be preempted:
- its path, name and build-id at their bounds;
- its ranges;
- its endowments;
- the mappings of the device claims it moves, in a vector sized once at the
  first claim so it never grows past that.
It claims nothing for another call.

A block session holds a connector and no service name, so diskserver's two
messages for a session's server that broke the protocol or went silent
name the session by its partition GUID.

Kernel: 55,742 lines in 212 files at main 429f772 to 55,384 in 211.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Japabu added a commit that referenced this pull request Nov 12, 2026
…leave the kernel

The kernel kept, for every process, the labels its parent put on each
endowment, compared three of them (`job`, `self`, `quit`), answered them back
through `SYS_ENDOWMENTS`, and held a namespace object that mapped service
names to connectors behind three more calls. None of that is the kernel's:
it is what one program calls a handle it gave another.

Now a spawn moves a list of handles and nothing else. The child's table
starts with its handle to itself (`RawHandle::SELF`), its notice
(`RawHandle::NOTICE`), then the endowments in the order the spawn listed them
(`RawHandle::endowed(i)`); the kernel installs them so and asserts it. What
the parent calls each is a table it writes in the child's startup block,
which the child's SDK checks once, whole, before it looks one up: a table
that is no list of distinct, non-empty UTF-8 names ends the child, said on
its `fd:2` where the table still names one.

- `SpawnArgs::job` replaces the `job` label: a borrowed handle carrying
  `WRITE`, resolved once like the place and the pager, so the commit's
  re-check that the moved handle still named the job goes.
- `SYS_CONNECT` (102, `SYS_NAMESPACE_OPEN`'s number) connects through a
  connector carrying `WRITE`, which a connector is now minted with. One
  without it may only be passed on.
- `SYS_ENDOWMENTS` (99), `SYS_NAMESPACE_BUILD` (101), `SYS_NAMESPACE_NAMES`
  (170), the namespace object, `SpawnEndow`, `EndowEntry`, the label blob
  and its per-process charge go; the freed numbers stay unassigned.
  `MAX_SPAWN_ENDOWMENTS` is 96: the 30 a spawn carried plus the 64 a
  namespace held, so everything one table and one namespace expressed still
  fits. The names are bounded by the startup block alone.
- `ObjectKind::Namespace` goes and its word 8 stays unused, as `ObjectKind`
  says a word that goes does: `SysCap` through `DeviceSet` keep 9 to 19,
  `from_word` looks a word up rather than indexing by it, the SDK's census
  finds a kind's count by its place in `ALL`, and the SDK's receive test
  takes word 8 and the word past the last kind as ones no kind has.
- The supervisor, whose parent is the kernel, starts holding its system
  capability, the file server's image, ROOT's and the boot names at the four
  handles `toyos_abi::boot::supervisor` states.

In userland a service is a connector named `svc:<name>` (a row's
`receives`, its view's `fs:` directories, minted grants) or
`provide:<name>` (one a launching client sent). `endow::service` looks one
up and connects; a helper is given a duplicate of each its parent holds,
narrowed by `CommandExt::services_only`. Everything else is taken once by
name. The supervisor gives a provided connector to a row that does not
receive it without `WRITE`; swap's connector arrives with `WRITE` alone, as
its one holder only connects. The supervisor adopts its own directory
capabilities (`std::os::toyos::fs::adopt_services`), which no child
inherits: so a storage row, whose view is empty, now starts holding no file
grant, where it inherited the supervisor's whole tree.

A connector a peer sent, as a session's launcher and controls are, is typed
only where the kernel reported a connector (`ReceivedHandle::typed`), and an
endowed one on its parent's word. std's `adopt_services` is `unsafe`, as
`adopt_namespace` was: the handles it takes are its caller's word.

`SYS_NAMESPACE_OPEN`'s name was the last caller of `SyscallContext::user_str`,
since #1238 reads a spawn's path as bytes bounded by `MAX_PATH`. So
`user_str` and `MAX_USER_STR` go. `KernelStack::heap` charged every thread
two 64 KiB strings and a page for what a call copies in. It now charges, by
their types, what a spawn copies in and holds where it may be preempted:
- its path, name and build-id at their bounds;
- its ranges;
- its endowments;
- the mappings of the device claims it moves, in a vector sized once at the
  first claim so it never grows past that.
It claims nothing for another call.

A block session holds a connector and no service name, so diskserver's two
messages for a session's server that broke the protocol or went silent
name the session by its partition GUID. #1261's `poll_belongs_to_its_handle`
connects through its connector, where it opened a one-entry namespace.

Kernel: 55,475 lines in 210 files at main a7ca8ad to 55,117 in 209.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Japabu added a commit that referenced this pull request Nov 12, 2026
…leave the kernel

The kernel kept, for every process, the labels its parent put on each
endowment, compared three of them (`job`, `self`, `quit`), answered them back
through `SYS_ENDOWMENTS`, and held a namespace object that mapped service
names to connectors behind three more calls. None of that is the kernel's:
it is what one program calls a handle it gave another.

Now a spawn moves a list of handles and nothing else. The child's table
starts with its handle to itself (`RawHandle::SELF`), its notice
(`RawHandle::NOTICE`), then the endowments in the order the spawn listed them
(`RawHandle::endowed(i)`); the kernel installs them so and asserts it. What
the parent calls each is a table it writes in the child's startup block,
which the child's SDK checks once, whole, before it looks one up: a table
that is no list of distinct, non-empty UTF-8 names ends the child, said on
its `fd:2` where the table still names one.

- `SpawnArgs::job` replaces the `job` label: a borrowed handle carrying
  `WRITE`, resolved once like the place and the pager, so the commit's
  re-check that the moved handle still named the job goes.
- `SYS_CONNECT` (102, `SYS_NAMESPACE_OPEN`'s number) connects through a
  connector carrying `WRITE`, which a connector is now minted with. One
  without it may only be passed on.
- `SYS_ENDOWMENTS` (99), `SYS_NAMESPACE_BUILD` (101), `SYS_NAMESPACE_NAMES`
  (170), the namespace object, `SpawnEndow`, `EndowEntry`, the label blob
  and its per-process charge go; the freed numbers stay unassigned.
  `MAX_SPAWN_ENDOWMENTS` is 96: the 30 a spawn carried plus the 64 a
  namespace held, so everything one table and one namespace expressed still
  fits. The names are bounded by the startup block alone.
- `ObjectKind::Namespace` goes and its word 8 stays unused, as `ObjectKind`
  says a word that goes does: `SysCap` through `DeviceSet` keep 9 to 19,
  `from_word` looks a word up rather than indexing by it, the SDK's census
  finds a kind's count by its place in `ALL`, and the SDK's receive test
  takes word 8 and the word past the last kind as ones no kind has.
- The supervisor, whose parent is the kernel, starts holding its system
  capability, the file server's image, ROOT's and the boot names at the four
  handles `toyos_abi::boot::supervisor` states.

In userland a service is a connector named `svc:<name>` (a row's
`receives`, its view's `fs:` directories, minted grants) or
`provide:<name>` (one a launching client sent). `endow::service` looks one
up and connects; a helper is given a duplicate of each its parent holds,
narrowed by `CommandExt::services_only`. Everything else is taken once by
name. The supervisor gives a provided connector to a row that does not
receive it without `WRITE`; swap's connector arrives with `WRITE` alone, as
its one holder only connects. The supervisor adopts its own directory
capabilities (`std::os::toyos::fs::adopt_services`), which no child
inherits: so a storage row, whose view is empty, now starts holding no file
grant, where it inherited the supervisor's whole tree.

A connector a peer sent, as a session's launcher and controls are, is typed
only where the kernel reported a connector (`ReceivedHandle::typed`), and an
endowed one on its parent's word. std's `adopt_services` is `unsafe`, as
`adopt_namespace` was: the handles it takes are its caller's word.

`SYS_NAMESPACE_OPEN`'s name was the last caller of `SyscallContext::user_str`,
since #1238 reads a spawn's path as bytes bounded by `MAX_PATH`. So
`user_str` and `MAX_USER_STR` go. `KernelStack::heap` charged every thread
two 64 KiB strings and a page for what a call copies in. It now charges, by
their types, what a spawn copies in and holds where it may be preempted:
- its path, name and build-id at their bounds;
- its ranges;
- its endowments;
- the mappings of the device claims it moves, in a vector sized once at the
  first claim so it never grows past that.
It claims nothing for another call.

A block session holds a connector and no service name, so diskserver's two
messages for a session's server that broke the protocol or went silent
name the session by its partition GUID. #1261's `poll_belongs_to_its_handle`
connects through its connector, where it opened a one-entry namespace.

Kernel: 56,188 lines in 212 files at main d1cefba to 55,830 in 211.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant