docs: the security track plan carries its live state on main

The plan is the only progress view from a plain main checkout, and the work
lands on a feature branch that reaches main a group at a time — so between
merges the file said less than was true. It now opens with where the work
is, which branch carries it, and what main itself holds, refreshed on main
after every phase rather than at merges alone.

build-support/build.zig

@@ -0,0 +1,131 @@
+//! The danos build API (docs/build-packages-plan.md): the one shared recipe
+//! for building a user-space binary. A binary package's build.zig names its
+//! binary and EXACTLY the modules its source imports — the moral equivalent
+//! of a C file's include list — and `userBinary` resolves each name from the
+//! library domain package that exports it. Nothing is pre-wired: an @import
+//! the package did not declare is a compile error, and a domain none of the
+//! imports come from never appears in the package's manifest. The only
+//! implicit dependency is the kernel package, because the shared root shim
+//! (root.zig, user.ld) lives there and itself reaches start + logging.
+//!
+//! Consumers declare this package in their build.zig.zon (as "build-support")
+//! and @import its build.zig from their own build.zig; nothing is compiled
+//! from this package itself — it exports build-time functions only.
+
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    _ = b; // nothing to build: this package exports build-time functions only
+}
+
+/// The freestanding x86-64 target every danos binary (kernel and user) is
+/// built for. SSE2 is part of the x86_64 baseline and UEFI leaves it enabled
+/// at handoff, so we keep it: disabling it forces soft-float and makes the
+/// compiler unable to encode the vector ops that std's formatting/runtime
+/// still emit.
+pub fn freestandingTarget(b: *std.Build) std.Build.ResolvedTarget {
+    return b.resolveTargetQuery(.{
+        .cpu_arch = .x86_64,
+        .os_tag = .freestanding,
+        .abi = .none,
+    });
+}
+
+/// Resolve one imported module by searching the packages this binary DECLARED
+/// in its own build.zig.zon — the C include path made literal: an import can
+/// only be satisfied by a domain the binary claims, and each domain's own
+/// build.zig (its addModule exports) is the single statement of who owns
+/// what. There is no name table here to drift.
+fn moduleFromDeclaredDependencies(b: *std.Build, name: []const u8) *std.Build.Module {
+    for (b.available_deps) |declared| {
+        const dependency = b.dependency(declared[0], .{});
+        if (dependency.builder.modules.get(name)) |module| return module;
+    }
+    @panic(b.fmt(
+        "no declared dependency exports a module named '{s}' — declare the domain that owns it in this package's build.zig.zon",
+        .{name},
+    ));
+}
+
+/// What `userBinary` needs to know about one user binary.
+pub const UserBinaryOptions = struct {
+    name: []const u8,
+    /// The program's own source file — it becomes the `program` module the
+    /// root shim imports; a program only defines `pub fn main`.
+    root_source_file: std.Build.LazyPath,
+    /// Exactly the modules the program's source @imports (directly or through
+    /// its same-directory files) — no more, no less. Order is free; sorted
+    /// reads best. An undeclared @import fails the compile; a name no
+    /// declared domain exports fails the build graph, naming the miss.
+    imports: []const []const u8,
+    /// Built multi-threaded (`single_threaded = false`) so real atomics/TLS
+    /// work — required before a binary may call `Thread.spawn`
+    /// (docs/threading.md). Threads are a deliberate per-binary opt-in.
+    threaded: bool = false,
+};
+
+/// Build one user-space binary the same way for every program (init, the
+/// services, the drivers): freestanding, ReleaseSmall, `.large` code model
+/// (the image base is above 4 GiB — smaller models emit 32-bit relocations
+/// that can't reach), linked with the shared user link script. Pinned to
+/// LLVM + LLD so the script's PHDRS (segment permissions) are authoritative —
+/// the kernel's W^X user-ELF loader requires exact perms.
+///
+/// The compilation root is not the program's own file but the shared shim
+/// (the kernel package's root.zig), which supplies the root declarations
+/// (`main` re-export, panic handler, `_start` pull) so a program only defines
+/// `pub fn main`. The program's file becomes the `program` module the shim
+/// imports; reach it through `programModule` to add per-binary non-library
+/// modules (compile-time options).
+pub fn userBinary(b: *std.Build, options: UserBinaryOptions) *std.Build.Step.Compile {
+    const kernel = b.dependency("kernel", .{});
+    var imports: std.ArrayListUnmanaged(std.Build.Module.Import) = .empty;
+    for (options.imports) |name| {
+        imports.append(b.allocator, .{
+            .name = name,
+            .module = moduleFromDeclaredDependencies(b, name),
+        }) catch @panic("OOM");
+    }
+    // Settings (target, optimize, code model, ...) live on the root module
+    // only; the program module inherits them.
+    const program_module = b.createModule(.{
+        .root_source_file = options.root_source_file,
+        .imports = imports.items,
+    });
+    const exe = b.addExecutable(.{
+        .name = options.name,
+        .root_module = b.createModule(.{
+            .root_source_file = kernel.path("root.zig"),
+            .target = freestandingTarget(b),
+            .optimize = .ReleaseSmall,
+            .code_model = .large,
+            .single_threaded = !options.threaded, // a threaded binary needs real atomics/TLS
+            .sanitize_c = .off,
+            .stack_check = false,
+            .stack_protector = false,
+            // The root shim itself imports only start (_start + panic) and
+            // logging (std_options) — straight from the kernel package, so a
+            // program's own import list stays exactly its own.
+            .imports = &.{
+                .{ .name = "start", .module = kernel.module("start") },
+                .{ .name = "logging", .module = kernel.module("logging") },
+                .{ .name = "program", .module = program_module },
+            },
+        }),
+    });
+    exe.setLinkerScript(kernel.path("user.ld"));
+    exe.entry = .{ .symbol_name = "_start" };
+    exe.image_base = 0x7000_0000_0000;
+    exe.use_llvm = true;
+    exe.use_lld = true;
+    return exe;
+}
+
+/// The `program` module of a binary built by `userBinary` — the module rooted
+/// at the program's own source file. Per-binary non-library modules (an
+/// addOptions build_options) go here, not on the root shim: module imports
+/// are not transitive, so an import added to the root would be invisible to
+/// the program's code.
+pub fn programModule(exe: *std.Build.Step.Compile) *std.Build.Module {
+    return exe.root_module.import_table.get("program").?;
+}

build-support/build.zig.zon

@@ -0,0 +1,8 @@
+.{
+    .name = .build_support,
+    .version = "0.0.0",
+    .fingerprint = 0xad91962994f4be41, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{},
+    .paths = .{""},
+}

build.zig.zon

@@ -32,6 +32,49 @@
     // Once all dependencies are fetched, `zig build` no longer requires
     // internet connectivity.
     .dependencies = .{
+        // The danos build API — the shared user-binary recipe every build file
+        // (root and per-binary packages) consumes (docs/build-packages-plan.md).
+        .@"build-support" = .{ .path = "build-support" },
+        // The library domains, each a package exporting its modules.
+        .kernel = .{ .path = "library/kernel" },
+        .device = .{ .path = "library/device" },
+        .client = .{ .path = "library/client" },
+        .protocol = .{ .path = "library/protocol" },
+        .csv = .{ .path = "library/csv" },
+        .@"xkeyboard-config" = .{ .path = "library/xkeyboard-config" },
+        // Binary packages (phase 2), consumed as artifacts for the boot image.
+        .@"pci-bus" = .{ .path = "system/drivers/pci-bus" },
+        .init = .{ .path = "system/services/init" },
+        .fat = .{ .path = "system/services/fat" },
+        .display = .{ .path = "system/services/display" },
+        .@"display-demo" = .{ .path = "system/services/display-demo" },
+        .@"device-manager" = .{ .path = "system/services/device-manager" },
+        .input = .{ .path = "system/services/input" },
+        .logger = .{ .path = "system/services/logger" },
+        // The discovery pair and the /test fixtures are lazy: only what a
+        // given build actually ships gets its build file loaded and compiled
+        // (-Ddiscovery picks one of the pair; -Dtest-case pulls the fixtures).
+        .acpi = .{ .path = "system/services/acpi", .lazy = true },
+        .fdt = .{ .path = "system/services/fdt", .lazy = true },
+        .@"ps2-bus" = .{ .path = "system/drivers/ps2-bus" },
+        .@"usb-xhci-bus" = .{ .path = "system/drivers/usb-xhci-bus" },
+        .@"usb-hid" = .{ .path = "system/drivers/usb-hid" },
+        .@"usb-storage" = .{ .path = "system/drivers/usb-storage" },
+        .@"virtio-gpu" = .{ .path = "system/drivers/virtio-gpu" },
+        .@"vfs-test" = .{ .path = "test/system/services/vfs-test", .lazy = true },
+        .@"fat-test" = .{ .path = "test/system/services/fat-test", .lazy = true },
+        .@"shared-memory-server" = .{ .path = "test/system/services/shared-memory-server", .lazy = true },
+        .@"shared-memory-client" = .{ .path = "test/system/services/shared-memory-client", .lazy = true },
+        .@"crash-test" = .{ .path = "test/system/services/crash-test", .lazy = true },
+        .@"device-list" = .{ .path = "test/system/services/device-list", .lazy = true },
+        .@"pci-cap-test" = .{ .path = "test/system/services/pci-cap-test", .lazy = true },
+        .@"iommu-fault-test" = .{ .path = "test/system/services/iommu-fault-test", .lazy = true },
+        .@"input-source" = .{ .path = "test/system/services/input-source", .lazy = true },
+        .@"input-test" = .{ .path = "test/system/services/input-test", .lazy = true },
+        .@"args-echo" = .{ .path = "test/system/services/args-echo", .lazy = true },
+        .@"process-test" = .{ .path = "test/system/services/process-test", .lazy = true },
+        .@"thread-test" = .{ .path = "test/system/services/thread-test", .lazy = true },
+        .@"user-memory-test" = .{ .path = "test/system/services/user-memory-test", .lazy = true },
         // See `zig fetch --save <url>` for a command-line interface for adding dependencies.
         //.example = .{
         //    // When updating this field to a new URL, be sure to delete the corresponding
@@ -70,12 +113,5 @@
     // Paths are relative to the build root. Use the empty string (`""`) to refer to
     // the build root itself.
     // A directory listed here means that all files within, recursively, are included.
-    .paths = .{
-        "build.zig",
-        "build.zig.zon",
-        "src",
-        // For example...
-        //"LICENSE",
-        //"README.md",
-    },
+    .paths = .{""},
 }

build/images.zig

@@ -0,0 +1,166 @@
+//! Boot-image assembly (docs/build-packages-plan.md, phase 3): everything
+//! between "here are the built binaries" and "here is a bootable volume".
+//! The FHS-shaped zig-out install tree, the boot manifest, the boot capsule,
+//! the FAT32 USB image (+ its serial-enabled twin for the QEMU run steps),
+//! and the release ISO — with their check steps. The root build.zig decides
+//! WHAT ships (the bundled list); this file owns HOW it becomes an image.
+
+const std = @import("std");
+
+/// One user binary and its FHS home on the boot volume (and in zig-out).
+pub const BundledBinary = struct { path: []const u8, binary: std.Build.LazyPath };
+
+pub const Options = struct {
+    /// The installed/flashable kernel (serial follows the root -Dserial).
+    kernel: *std.Build.Step.Compile,
+    /// The serial-enabled kernel variant the `run-x86-64` image boots.
+    kernel_serial: *std.Build.Step.Compile,
+    /// The UEFI loader (BOOTX64).
+    efi: *std.Build.Step.Compile,
+    /// Every user binary and data file at its FHS path.
+    bundled: []const BundledBinary,
+};
+
+/// Wire up the install tree, both FAT32 boot images, the release ISO, and the
+/// check steps. Returns the serial-enabled FAT image for the QEMU run steps.
+pub fn addImageSteps(b: *std.Build, options: Options) std.Build.LazyPath {
+    // Everything installs into a FHS-shaped zig-out: it IS the danos filesystem *and*
+    // the boot volume. Each binary lands at its addressed, leaf-collapsed path — the
+    // kernel at zig-out/system/kernel (from system/kernel/kernel.zig), init at
+    // zig-out/system/services/init, and so on (see docs/README.md). The bootloader
+    // then loads these FHS paths off the volume.
+    const kernel_install = b.addInstallArtifact(options.kernel, .{ .dest_dir = .{ .override = .{ .custom = "system" } } });
+    b.getInstallStep().dependOn(&kernel_install.step);
+
+    // UEFI firmware requires the removable-media loader at exactly \EFI\BOOT\BOOTX64.efi,
+    // so that path is fixed by the firmware (it is /boot's EFI stub, conceptually).
+    const efi_install = b.addInstallArtifact(options.efi, .{ .dest_dir = .{ .override = .{ .custom = "EFI/BOOT" } } });
+    b.getInstallStep().dependOn(&efi_install.step);
+
+    // The boot manifest: the FHS path of every bundled binary, one per line. The
+    // EFI loader reads THIS by name and opens each listed path by name — FAT
+    // name lookup is case-insensitive and firmware-portable, unlike directory
+    // ENUMERATION, whose returned names vary by firmware (bare 8.3 entries come
+    // back uppercase on some FAT drivers). The tree walk remains only as the
+    // loader's fallback for hand-assembled sticks without a manifest.
+    var manifest_text: std.ArrayListUnmanaged(u8) = .empty;
+    for (options.bundled) |item| {
+        manifest_text.append(b.allocator, '/') catch @panic("OOM");
+        manifest_text.appendSlice(b.allocator, item.path) catch @panic("OOM");
+        manifest_text.append(b.allocator, '\n') catch @panic("OOM");
+    }
+    const manifest_files = b.addWriteFiles();
+    const manifest_file = manifest_files.add("manifest", manifest_text.items);
+    const manifest_install = b.addInstallFileWithDir(manifest_file, .prefix, "system/manifest");
+    b.getInstallStep().dependOn(&manifest_install.step);
+
+    // The boot capsule: the same bundled list packed into ONE file (v2
+    // initial_ramdisk format), because a single open + sequential read is the
+    // only firmware file I/O shape that is fast everywhere — a per-file tree
+    // walk measured MINUTES on real firmware. The loader tries this first,
+    // then the manifest, then the walk; the running system cannot tell the
+    // difference (it always receives the same in-RAM table). Derived from the
+    // tree in the same build graph, so the two cannot drift.
+    const mk_capsule = b.addSystemCommand(&.{"python3"});
+    mk_capsule.addFileArg(b.path("tools/pack-system-image.py"));
+    const capsule_img = mk_capsule.addOutputFileArg("system.img");
+    for (options.bundled) |item| {
+        mk_capsule.addArg(item.path);
+        mk_capsule.addFileArg(item.binary);
+    }
+    const capsule_install = b.addInstallFile(capsule_img, "boot/system.img");
+    b.getInstallStep().dependOn(&capsule_install.step);
+
+    // Install every bundled binary to its FHS home, so zig-out is a true image of
+    // the filesystem — the same tree make-fat-image.py lays out on the boot volume.
+    for (options.bundled) |item| {
+        const install = b.addInstallFileWithDir(item.binary, .prefix, item.path);
+        b.getInstallStep().dependOn(&install.step);
+    }
+
+    // --- danos-usb.img: the bootable FAT32 USB image ---
+    // Format a real FAT32 image (the in-repo Python builder, no external tools)
+    // holding the EFI stub, the kernel, and the whole /system tree of user
+    // binaries at their FHS paths. QEMU presents this image as a USB mass-storage
+    // device the guest boots from (see run-x86-64 and the test harness), and the
+    // danos fat driver mounts the same image at /volumes/usb.
+    const fat_image = addBootImage(b, options.kernel.getEmittedBin(), options.efi.getEmittedBin(), manifest_file, capsule_img, options.bundled);
+    const fat_image_install = b.addInstallFile(fat_image, "danos-usb.img");
+    b.getInstallStep().dependOn(&fat_image_install.step);
+
+    // The image `run-x86-64` boots: identical to the flashable one but with the
+    // serial log sink compiled in, so a developer always gets the machine-readable
+    // log captured to serial0 — without baking serial into the image users flash.
+    // Built lazily (only when `run-x86-64` is requested), and never installed.
+    const fat_image_serial = addBootImage(b, options.kernel_serial.getEmittedBin(), options.efi.getEmittedBin(), manifest_file, capsule_img, options.bundled);
+
+    // `zig build check-fat-image` — validate the produced image is a real FAT32
+    // with the EFI stub present (the builder's own --verify, no external tools).
+    const check_fat = b.addSystemCommand(&.{"python3"});
+    check_fat.addFileArg(b.path("tools/make-fat-image.py"));
+    check_fat.addArg("--verify");
+    check_fat.addFileArg(fat_image);
+    const check_fat_step = b.step("check-fat-image", "Verify the FAT32 USB image is valid and bootable");
+    check_fat_step.dependOn(&check_fat.step);
+
+    // --- release-x86-64: danos-x86-64.iso, the flashable release image ---
+    // Wrap the FAT32 boot volume in a hybrid ISO (the in-repo Python builder
+    // again, no xorriso/isohybrid): an ISO9660 whose El Torito EFI boot entry
+    // and MBR ESP partition entry both point at the embedded FAT image. One
+    // file then boots every way release media is consumed — flashed raw to a
+    // USB stick with Etcher or dd, or burned to optical media — while
+    // danos-usb.img stays the raw superfloppy QEMU and the test harness boot.
+    const mk_iso = b.addSystemCommand(&.{"python3"});
+    mk_iso.addFileArg(b.path("tools/make-iso-image.py"));
+    const iso_image = mk_iso.addOutputFileArg("danos-x86-64.iso");
+    mk_iso.addFileArg(fat_image);
+    const iso_install = b.addInstallFile(iso_image, "danos-x86-64.iso");
+    const release_step = b.step("release-x86-64", "Build the flashable x86-64 release ISO (zig-out/danos-x86-64.iso; flash with Etcher or dd)");
+    release_step.dependOn(&iso_install.step);
+
+    // `zig build check-iso-image` — the ISO builder's own --verify (mirroring
+    // check-fat-image): the MBR partition, the El Torito catalog, and the
+    // embedded FAT32 image must all agree.
+    const check_iso = b.addSystemCommand(&.{"python3"});
+    check_iso.addFileArg(b.path("tools/make-iso-image.py"));
+    check_iso.addArg("--verify");
+    check_iso.addFileArg(iso_image);
+    const check_iso_step = b.step("check-iso-image", "Verify the release ISO is a valid hybrid (MBR ESP partition + El Torito EFI entry)");
+    check_iso_step.dependOn(&check_iso.step);
+
+    return fat_image_serial;
+}
+
+/// Assemble the bootable FAT32 image (the in-repo Python builder) holding the
+/// EFI stub, the kernel, and every user binary at its FHS path — the volume's
+/// /system tree IS the system image; the EFI loader walks it at boot and builds
+/// the in-RAM initial_ramdisk from it. Factored so the serial-enabled
+/// `run-x86-64` variant can bundle its own serial kernel while sharing the
+/// loader and user tree (the loader's boot breadcrumbs and init's heartbeat both
+/// follow the top-level -Dserial). Returns the image's LazyPath.
+fn addBootImage(
+    b: *std.Build,
+    kernel_bin: std.Build.LazyPath,
+    efi_bin: std.Build.LazyPath,
+    manifest: std.Build.LazyPath,
+    capsule: std.Build.LazyPath,
+    bundled: []const BundledBinary,
+) std.Build.LazyPath {
+    const mk_fat = b.addSystemCommand(&.{"python3"});
+    mk_fat.addFileArg(b.path("tools/make-fat-image.py"));
+    const fat_image = mk_fat.addOutputFileArg("danos-usb.img");
+    mk_fat.addArg("64"); // MiB
+    mk_fat.addArg("EFI/BOOT/BOOTX64.efi");
+    mk_fat.addFileArg(efi_bin);
+    mk_fat.addArg("system/kernel");
+    mk_fat.addFileArg(kernel_bin);
+    mk_fat.addArg("system/manifest");
+    mk_fat.addFileArg(manifest);
+    mk_fat.addArg("boot/system.img");
+    mk_fat.addFileArg(capsule);
+    for (bundled) |item| {
+        mk_fat.addArg(item.path);
+        mk_fat.addFileArg(item.binary);
+    }
+    return fat_image;
+}

build/qemu.zig

@@ -0,0 +1,176 @@
+//! The QEMU run steps (docs/build-packages-plan.md, phase 3): `run-x86-64`
+//! boots the serial-enabled FAT image via UEFI/OVMF; `run-x86-64-gpu` adds a
+//! virtio-gpu adapter for the native-present display path. OVMF firmware is
+//! probed across distro/OS layouts (-Dovmf-code / -Dovmf-vars override).
+
+const std = @import("std");
+
+/// Wire up the `run-x86-64` and `run-x86-64-gpu` steps around the given
+/// serial-enabled boot image (the guest boots that self-contained image
+/// attached as USB storage, not the installed FHS zig-out).
+pub fn addRunSteps(b: *std.Build, fat_image_serial: std.Build.LazyPath) void {
+    // Firmware lives in different places per OS/distro, so probe the known
+    // layouts (Architecture, Debian/Ubuntu, Fedora, macOS Homebrew) and use the first
+    // that exists. Override with -Dovmf-code / -Dovmf-vars if yours is elsewhere.
+    const ovmf_code = b.option(
+        []const u8,
+        "ovmf-code",
+        "Path to the OVMF_CODE firmware image",
+    ) orelse firstExisting(b.graph.io, &.{
+        "/usr/share/edk2/x64/OVMF_CODE.4m.fd", // Architecture
+        "/usr/share/OVMF/OVMF_CODE_4M.fd", // Debian/Ubuntu
+        "/usr/share/OVMF/OVMF_CODE.fd", // older Debian/Ubuntu
+        "/usr/share/edk2-ovmf/x64/OVMF_CODE.fd", // Fedora
+        "/opt/homebrew/share/qemu/edk2-x86_64-code.fd", // macOS Homebrew (Apple Silicon)
+        "/usr/local/share/qemu/edk2-x86_64-code.fd", // macOS Homebrew (Intel)
+    });
+    const ovmf_vars = b.option(
+        []const u8,
+        "ovmf-vars",
+        "Path to the OVMF_VARS firmware image (a writable copy is made)",
+    ) orelse firstExisting(b.graph.io, &.{
+        "/usr/share/edk2/x64/OVMF_VARS.4m.fd", // Architecture
+        "/usr/share/OVMF/OVMF_VARS_4M.fd", // Debian/Ubuntu
+        "/usr/share/OVMF/OVMF_VARS.fd", // older Debian/Ubuntu
+        "/usr/share/edk2-ovmf/x64/OVMF_VARS.fd", // Fedora
+        "/opt/homebrew/share/qemu/edk2-i386-vars.fd", // macOS Homebrew (Apple Silicon)
+        "/usr/local/share/qemu/edk2-i386-vars.fd", // macOS Homebrew (Intel)
+    });
+
+    // The firmware needs to write NVRAM, so give it a writable copy of the vars.
+    const vars_copy = b.addSystemCommand(&.{ "cp", "-f", ovmf_vars });
+    const vars_out = vars_copy.addOutputFileArg("OVMF_VARS.4m.fd");
+
+    // Capture the guest's serial0 (danos's machine-readable log) to the qemu-test
+    // scratch area — a dev/host artifact, kept out of the boot volume we mount.
+    // (/system/logs on the volume belongs to the guest's own logger.) One
+    // timestamped file per run.
+    const log_dir = b.fmt("{s}/qemu-test", .{b.install_path});
+    const make_log_dir = b.addSystemCommand(&.{ "mkdir", "-p", log_dir });
+
+    // --- run-x86-64: boot the x86-64 kernel in QEMU via UEFI/OVMF ---
+    const run_efi = b.addSystemCommand(&.{
+        "qemu-system-x86_64",
+        "-device",
+        "qemu-xhci,id=xhci",
+        "-device",
+        "usb-mouse,bus=xhci.0",
+        "-device",
+        "usb-kbd,bus=xhci.0",
+        "-machine",
+        "q35",
+        "-m",
+        "128M",
+        "-drive",
+        b.fmt("if=pflash,format=raw,readonly=on,file={s}", .{ovmf_code}),
+    });
+    run_efi.addArg("-drive");
+    run_efi.addPrefixedFileArg("if=pflash,format=raw,file=", vars_out);
+    // Boot off the FAT32 USB image: a mass-storage device on the same xHCI bus as
+    // the keyboard and mouse. OVMF finds \EFI\BOOT\BOOTX64.efi on it and boots.
+    // The serial-enabled variant, so serial0 carries the log for this dev boot.
+    run_efi.addArg("-drive");
+    run_efi.addPrefixedFileArg("if=none,id=bootusb,format=raw,file=", fat_image_serial);
+    run_efi.addArgs(&.{
+        "-device",
+        "usb-storage,bus=xhci.0,drive=bootusb,removable=on,bootindex=0",
+        "-net",
+        "none",
+        // Emulated display advertising 1280x720 as its native (EDID preferred)
+        // resolution, so the kernel's native-resolution switch has something to
+        // find. `-vga none` avoids a second, default adapter.
+        "-vga",
+        "none",
+        "-device",
+        "VGA,edid=on,xres=1280,yres=720",
+    });
+    const serial_log = b.fmt("{s}/run-x86-64-serial0-{s}.log", .{ log_dir, timestamp(b) });
+    run_efi.addArgs(&.{ "-serial", b.fmt("file:{s}", .{serial_log}) });
+    // We boot the self-contained `fat_image_serial` (added as a file arg above, so
+    // it's already a dependency) — not the installed FHS zig-out — so `run-x86-64`
+    // builds only the serial kernel, never the flashable one. Just make the serial
+    // scratch dir first.
+    run_efi.step.dependOn(&make_log_dir.step);
+
+    const run_efi_step = b.step("run-x86-64", "Boot the x86-64 kernel in QEMU (UEFI/OVMF); serial0 is logged to zig-out/qemu-test/run-x86-64-serial0-<timestamp>.log");
+    run_efi_step.dependOn(&run_efi.step);
+
+    // --- run-x86-64-gpu: the same boot plus a virtio-gpu adapter ---
+    // The VGA device still supplies the boot (GOP) framebuffer the compositor starts
+    // on; the virtio-gpu function is discovered by the device-manager stack, its
+    // driver announces a shared scanout, and the compositor upgrades off the GOP
+    // floor to fenced, tear-free native presents (docs/display-v2.md).
+    // This is the interactive twin of the `display-native` test case, and 512M
+    // matches it (the whole driver stack + the compositor's surfaces at once).
+    // QEMU shows one head per adapter: pick the virtio-gpu head in the View menu
+    // to watch the native output.
+    const run_gpu = b.addSystemCommand(&.{
+        "qemu-system-x86_64",
+        "-device",
+        "qemu-xhci,id=xhci",
+        "-device",
+        "usb-mouse,bus=xhci.0",
+        "-device",
+        "usb-kbd,bus=xhci.0",
+        "-machine",
+        "q35",
+        "-m",
+        "512M",
+        "-drive",
+        b.fmt("if=pflash,format=raw,readonly=on,file={s}", .{ovmf_code}),
+    });
+    run_gpu.addArg("-drive");
+    run_gpu.addPrefixedFileArg("if=pflash,format=raw,file=", vars_out);
+    run_gpu.addArg("-drive");
+    run_gpu.addPrefixedFileArg("if=none,id=bootusb,format=raw,file=", fat_image_serial);
+    run_gpu.addArgs(&.{
+        "-device",
+        "usb-storage,bus=xhci.0,drive=bootusb,removable=on,bootindex=0",
+        "-net",
+        "none",
+        "-vga",
+        "none",
+        "-device",
+        "VGA,edid=on,xres=1280,yres=720",
+        "-device",
+        "virtio-gpu-pci",
+    });
+    const gpu_serial_log = b.fmt("{s}/run-x86-64-gpu-serial0-{s}.log", .{ log_dir, timestamp(b) });
+    run_gpu.addArgs(&.{ "-serial", b.fmt("file:{s}", .{gpu_serial_log}) });
+    run_gpu.step.dependOn(&make_log_dir.step);
+
+    const run_gpu_step = b.step("run-x86-64-gpu", "Boot in QEMU with a virtio-gpu adapter: the compositor upgrades to fenced (tear-free) native presents; watch the virtio-gpu head in QEMU's View menu");
+    run_gpu_step.dependOn(&run_gpu.step);
+}
+
+/// Return the first path in `candidates` that exists on the build host, else the
+/// first candidate as a fallback so a missing-firmware error still names a
+/// concrete (and, by convention, the primary) path. Used to locate OVMF firmware
+/// across distro/OS layouts without configuration.
+fn firstExisting(io: std.Io, candidates: []const []const u8) []const u8 {
+    for (candidates) |path| {
+        std.Io.Dir.accessAbsolute(io, path, .{}) catch continue;
+        return path;
+    }
+    return candidates[0];
+}
+
+/// A UTC timestamp like "20260708-153045", for naming a per-run artifact so
+/// repeated runs don't clobber each other's logs. Resolved when `zig build`
+/// runs, which is moments before QEMU launches.
+fn timestamp(b: *std.Build) []const u8 {
+    const ns = std.Io.Clock.now(.real, b.graph.io).nanoseconds;
+    const secs: u64 = @intCast(@divFloor(ns, std.time.ns_per_s));
+    const es = std.time.epoch.EpochSeconds{ .secs = secs };
+    const yd = es.getEpochDay().calculateYearDay();
+    const md = yd.calculateMonthDay();
+    const ds = es.getDaySeconds();
+    return b.fmt("{d:0>4}{d:0>2}{d:0>2}-{d:0>2}{d:0>2}{d:0>2}", .{
+        yd.year,
+        md.month.numeric(),
+        @as(u32, md.day_index) + 1,
+        ds.getHoursIntoDay(),
+        ds.getMinutesIntoHour(),
+        ds.getSecondsIntoMinute(),
+    });
+}

docs/README.md

@@ -208,7 +208,7 @@ the whole reason for the arrangement ([vision.md](vision.md)).
 danos is a **monorepo of sub-projects**. Each service or driver is a directory that is
 its own Zig module — it can hold as many files as it needs, and other sub-projects
 reach it *by module name*, never by a path into its files. The source tree deliberately
-**mirrors the runtime FHS** ([danos-file-system-hierarchy-FSH.md](file-system-development/danos-file-system-hierarchy-FSH.md)):
+**mirrors the runtime file-system hierarchy** ([file-system-hierarchy.md](file-system-development/file-system-hierarchy.md)):
 what you see under `system/` in the source is what a running danos represents under
 `/system`.
 
@@ -216,7 +216,7 @@ what you see under `system/` in the source is what a running danos represents un
 name.** `system/services/init/` contains `init.zig` (its root), and produces a binary
 addressed as **`system/services/init`** — the repeated leaf resolves away:
 
-| Source (root file)                     | Addressed as (module / binary / FHS path) |
+| Source (root file)                     | Addressed as (module / binary / hierarchy path) |
 |----------------------------------------|--------------------------------------------|
 | `system/services/init/init.zig`        | `system/services/init` → `/system/services/init` |
 | `system/drivers/ps2-bus/ps2-bus.zig`   | `system/drivers/ps2-bus` → `/system/drivers/ps2-bus` |
@@ -263,9 +263,20 @@ test/            → /test      the test tree: the QEMU harness (qemu_test.py, h
   system/services/            beside the on-image test fixtures — vfs-test/ thread-test/
                               crash-test/ … — whose repo path IS their boot-volume path
                               (/test/system/services/<name>)
+build-support/                the danos build API (build-time only, nothing on the image):
+                              the shared user-binary recipe + default-import wiring every
+                              build file consumes (docs/build-packages-plan.md)
+build/                        root-build helpers: image assembly (images.zig) + the QEMU
+                              run steps (qemu.zig)
 tools/                        host-side build scripts
 ```
 
+**Builds are packages** (docs/build-packages-plan.md): each `library/` domain owns a
+`build.zig`/`build.zig.zon` exporting its modules (with a standalone `zig build test`),
+every binary directory is a ~15-line package build, and the root `build.zig`
+orchestrates — the kernel + loader, what ships, and the aggregate test step — with
+image assembly in `build/images.zig` and the QEMU run steps in `build/qemu.zig`.
+
 **Wire protocols live in `library/protocol/`**, one module per directory
 (`library/protocol/vfs/vfs-protocol.zig` is the `vfs-protocol` module), imported by module
 name. A protocol is the seam between a low-level driver and the higher-level service it
@@ -320,5 +331,7 @@ exception in [coding-standards.md](coding-standards.md) applies to that seam.
 | System services (init, the `fat` filesystem, the device-manager) | `system/services/` |
 | Device drivers, one sub-project each (`pci-bus`, `ps2-bus`, `usb-xhci-bus` bus drivers) | `system/drivers/` |
 | On-image test fixtures for the QEMU cases (`vfs-test`, `crash-test`, `thread-test`, …) → `/test/system/services` | `test/system/services/` |
-| Build + `run-x86-64` (QEMU/OVMF) + `release-x86-64` (the flashable ISO) | `build.zig` |
+| Build orchestration (kernel + loader, what ships, the aggregate test step) | `build.zig` (root; the shared user-binary recipe is `build-support/`, and each `library/` domain + binary package carries its own `build.zig`) |
+| Image assembly + `release-x86-64` (the flashable ISO) | `build/images.zig` |
+| `run-x86-64` / `run-x86-64-gpu` (QEMU/OVMF) | `build/qemu.zig` |
 | QEMU integration test harness | `test/qemu_test.py` |

docs/build-packages-plan.md

@@ -0,0 +1,179 @@
+# Plan: packages — hierarchical builds for libraries and binaries
+
+**Status: complete** (branch `claude/build-packages-plan-174144`). Phase 0
+(`build-support`), phase 1 (all six library domains), phase 2 (every binary —
+the pci-bus pilot first, then services, drivers, and test fixtures in waves;
+multi-binary directories like ps2-bus and usb-hid are one package exporting
+several artifacts, and the acpi/fdt discovery pair each export an artifact
+named "discovery" that the root's -Ddiscovery picks between), and phase 3 (the
+root split into `build/images.zig` + `build/qemu.zig`; the root `build.zig` is
+~460 lines of orchestration, down from ~1,250). Every phase landed green: unit
+tests, the QEMU suite at parity with main, boot-image file list unchanged.
+The `lazyDependency` payoff (What-this-buys #4) is in too: the /test fixtures
+and the unselected discovery package are lazy — a build loads and compiles
+only what it ships. And imports are exact: the pre-wired default set is gone;
+every binary names precisely the modules its source imports and carries only
+those domains in its manifest (rule 1 below).
+
+## Why
+
+`build.zig` was ~1,250 lines, growing by three hand-written stanzas per binary;
+at a driver per device family that does not scale. More fundamentally: in one
+monolithic build every binary compiles against library *source*, so a library
+interface break is silently absorbed by whoever edits everything in one commit —
+the interface never has to be honest. danos is about isolation; the build should
+mirror it.
+
+A **package** here is a build-time unit only — a directory owning a `build.zig`
+(recipe: what it exports, how to test it) and a `build.zig.zon` (manifest: name
++ dependencies). Binaries remain fully static freestanding ELFs; packages change
+who declares what, not what links to what. Source code is untouched: `@import`
+uses module names (`"pci"`, `"service"`) exactly as today — only build files
+know where anything lives.
+
+## Target shape
+
+```
+build-support/                 package: the danos build API (userBinary(), defaultImports(), targets)
+library/kernel/                package "kernel":   modules abi, ipc, service, memory, process, logging, time, ...   (depends on protocol)
+library/device/                package "device":   modules driver, pci, usb-abi, model, ...   (depends on kernel, protocol, csv)
+library/protocol/              package "protocol": the wire protocols
+library/client/                package "client"    (depends on kernel, protocol)
+library/csv/                   package "csv"
+library/xkeyboard-config/      package "xkeyboard-config"
+system/services/<name>/        one package per binary: ~15-line build.zig + zon
+system/drivers/<name>/         one package per binary
+build.zig (root)               orchestrator: dependency() per binary, image assembly, QEMU, test steps
+```
+
+The three shared contracts: `boot-handoff` stays a root module (only the
+loader↔kernel pair speaks it); `abi` is exported by the kernel package from
+`../../system/abi.zig` (the source stays with the kernel; userspace's one view
+of it lives in the package, so every consumer names the same module instance);
+`device-abi` is exported by device. Reaching outside the package root means the
+kernel package is valid only as an in-repo path dependency — it could never be
+fetched by hash — which is fine: path dependencies are the only way any of
+these packages is consumed.
+
+Rules:
+
+- **Imports are exact and per binary.** A binary's build.zig names precisely
+  the modules its source `@import`s — the moral equivalent of a C file's
+  include list — and its zon names only the domains those modules come from
+  (plus `build-support` and `kernel`, which is implicit in every binary: the
+  root shim and user link script live there). Nothing is pre-wired: an
+  undeclared `@import` is a compile error, and build-support resolves each
+  name by searching the packages the zon declares — the domains' own
+  addModule exports are the single statement of who owns what, with no name
+  table anywhere to drift. Availability
+  never meant bloat — Zig only compiles what a program actually imports — but
+  exactness makes the declared interface honest and machine-checked.
+- **Modules export source, not artifacts** — each consumer compiles libraries
+  with its own flags, so per-binary optimization choices keep working; Zig's
+  cache deduplicates.
+- **Zon paths are relative and that is accepted.** Binaries sit exactly three
+  levels deep, so the `../../../` prefix is a constant idiom; a library-domain
+  move is a rare, already-breaking event fixed by one sed across manifests, and
+  a stale path fails loudly before anything compiles.
+- **Cross-cutting build changes live in `build-support` only** — that is the
+  contract that keeps per-binary build files declarative.
+
+## What this buys
+
+1. Library interfaces become machine-checked: a consumer can only import what
+   it declared — per binary, down to the single module — and each domain's zon
+   declares what it needs (claim-before-touch, applied to source). A keyboard
+   driver carries `xkeyboard-config` in its manifest; nothing else does.
+2. Each library domain gets a standalone `zig build test` — runtime-library
+   stability testing in isolation.
+3. Adding a binary = adding a directory (source + two small files), not editing
+   three places in a 1,250-line file.
+4. `lazyDependency` lets an image target build only what it ships: the /test
+   fixtures resolve only under -Dtest-case, and only the -Ddiscovery-selected
+   discovery package ever loads.
+
+## Phases
+
+Each phase ends green: `zig build test` passes (88/88 QEMU) and the boot
+image's file list is unchanged. Byte-identical binaries are expected but not
+required (module reorganization can perturb symbol order); file list is the
+hard gate.
+
+**Phase 0 — `build-support`.** Extract `addUserBinary`/`addThreadedUserBinary`,
+the freestanding target setup, and the default-import wiring into the
+`build-support` package. Root build consumes it; nothing else moves. This is
+the cross-cutting-change home, so it lands first.
+
+**Phase 1 — library domains become packages.** In dependency order: `protocol`
+and `csv` (the roots) → `kernel` (depends on protocol: file-system speaks
+vfs-protocol) → `device`, `client`; `xkeyboard-config` stands alone. Each gets
+build.zig + zon + a standalone test step (client's is empty until its modules
+grow host tests — kept for uniformity, since the root aggregate depends on
+every domain's test step). The root build swaps its `createModule` calls for
+`b.dependency("<domain>").module("<name>")`. **No binary moves in this phase**
+— the root build is the pilot consumer, which proves the packages without
+touching 30 binaries.
+
+**Phase 2 — binaries become packages, in waves.** The template was shaken out
+by the pci-bus pilot (see Status). Wave A: services (done). Wave B: the
+remaining drivers (done). Wave C: test fixtures (done). Root build shrank to
+orchestration per wave. init's `-Dserial` heartbeat flag rides a dependency
+option; a directory with several binaries (ps2-bus, usb-hid) is one package
+exporting several artifacts.
+
+**Phase 3 — root cleanup (done).** What remained of the root build split into
+`build/images.zig` (the FHS install tree, boot manifest + capsule, FAT32
+images, release ISO, check steps) and `build/qemu.zig` (the run steps + OVMF
+probing), imported by a short root `build.zig`.
+
+**Afterwards** (outside this plan): the intel-uhd-graphics-750 driver is
+(re)created as a greenfield package. The new-driver checklist's build step
+(docs/device-driver-development/new-driver-checklist.md, step 2) is already
+rewritten against the package template.
+
+## Execution notes (the finished shape)
+
+- The shared recipe lives in `build-support/build.zig`: `userBinary` (what
+  every binary package calls; each named import resolves by searching the
+  packages the binary's zon declares) and `programModule` (for per-binary
+  addOptions modules). The `start` root shim and `user.ld` are named through the kernel
+  package (Dependency.path).
+- Adding a binary = adding a directory with source + a ~15-line build.zig +
+  zon (copy any existing binary package, e.g.
+  `system/drivers/pci-bus/build.zig`) listing exactly the modules the source
+  imports and the domains they come from, then one dependency + one bundled
+  entry in the root build.zig and one zon line.
+- The boot-tree array in the root (search `"etc/init.csv"` or
+  `.getEmittedBin()`) is the image file list — the authoritative comparison
+  target for any future build change.
+- Package unit tests live in each package's own `test` step; the root
+  aggregate depends on every test-bearing package's step, so `zig build test`
+  at the root still runs everything.
+
+Verification per phase:
+
+- Unit tests: `zig build test`.
+- QEMU integration suite: `python3 test/qemu_test.py` (docs/testing.md; the
+  full suite, all cases must pass).
+- Image file list: the boot-tree array is the source of truth — snapshot it
+  (paths only) before phase 0 and diff after each phase; `zig build
+  check-fat-image` must also stay green.
+
+Context a fresh session should read first: this doc, docs/testing.md,
+docs/coding-standards.md (kebab-case names, no abbreviations), and the
+`userBinary`/`userBinaryFromImports` bodies in build-support/build.zig. Commit
+style: no Co-Authored-By trailers.
+
+## Risks / notes
+
+- Zig version churn: the package API (`b.dependency`, zon schema) has moved
+  between releases; the work pins against the repo's current Zig and any
+  upgrade lands separately, never mid-phase.
+- The QEMU size-check tests hardcode source paths (e.g. virtio-gpu protocol
+  struct sizes) — they moved into their binaries' packages with their waves,
+  discharging the carry-along obligation.
+- Doc updates ride each phase: docs/README.md (repo layout + source map),
+  docs/device-driver-development/new-driver-checklist.md (step 2) and
+  devices-csv.md ("Adding a driver"), and the docs that cite the build recipe
+  (driver-model.md, threading.md, system-requirements.md) reference build
+  shapes that keep changing.

docs/c-library-compatibility.md

@@ -0,0 +1,205 @@
+# The C library compatibility layer
+
+A design note and milestone plan for **libdanos-c** — the mini C library that lets
+`zig cc` cross-compile C programs for danos. It is milestone **P0** of
+[python-on-danos-milestones.md](python-on-danos-milestones.md), expanded here the
+way [character-devices-and-tty.md](character-devices-and-tty.md) expands P1.
+CPython is the driving consumer, but the layer is general: any portable C program
+within its surface should build.
+
+## What it is — and the three things it is not
+
+The deliverable is a **sysroot**: a set of C headers plus a static `libdanos-c.a`,
+handed to `zig cc -target x86_64-freestanding-none` via `-isystem` and linked into
+every C binary. Three explicit non-goals keep it small:
+
+- **Not a musl port.** Whole-musl assumes Linux syscall semantics at its bottom
+  (the door the Zig roadmap deferred, twice now). We *lift* musl's pure-computation
+  source files and *write* a danos-native bottom — see the layer split below.
+- **Not full POSIX — *yet*.** Stage 1's surface is "what CPython's minimal
+  configuration and ordinary portable C need" — roughly 100–150 functions — and
+  at that stage absence is a *feature*: configure scripts probe and adapt, and a
+  linker error is honest. But the end state is a **full C compatibility layer**
+  (see "The road to full coverage" below); the absence table is a schedule of
+  arrivals, not a wall.
+- **Not a second runtime.** The library is a thin C-ABI re-spelling of the same
+  danos-native surface `runtime` already provides. It contains no policy of its
+  own; when the Zig track's `runtime.os` seam is authored, the libc bottom
+  re-targets it near-mechanically — the fourth appearance of the roadmap's "same
+  surface" symmetry.
+
+One scoping rule sits above all three — the **size doctrine**: this layer serves
+**applications only**. The kernel and the system services never link libdanos-c;
+they stay danos-native Zig over `runtime`, small and static, because leanness is
+an operating-system property. Applications have their own budget and may be as
+big as they need to be. The libc is how big software *lands on* danos, never how
+danos itself is built.
+
+## The layer split: lift the mathematics, write the plumbing
+
+The realization that makes 100–150 functions tractable: a libc is two very
+different kinds of code, and the hard kind is portable.
+
+| Layer | Contents | Source |
+|-------|----------|--------|
+| **Pure computation** | `string.h`/`memcpy` family, all of libm, `strtod`/`dtoa`, `strtol`, `qsort`, `ctype` tables, `gmtime` calendar math, the `printf`/`scanf` engines, `setjmp` (a dozen instructions of x86-64 asm) | **Lift from musl**, vendored under `library/c/third-party/musl/` (MIT; files compile standalone) |
+| **OS plumbing** | fds (`open`/`read`/`write`/`close`/`lseek`/`stat`/`getcwd`/`chdir`/`isatty`), `mmap`/`munmap`, clocks, `exit`, `getenv`, `getentropy` | **Write in Zig**, exporting C ABI over the `runtime` syscall + VFS client surface |
+| **The middle** | `malloc` over danos `mmap` (simple free-list; CPython's arenas sit above), `FILE*` buffering, `errno` | **Write in Zig** (small, danos-shaped) |
+| **Entry** | `crt0`: the existing danos entry shim ([sysv.md](os-development/sysv.md)) bridged to C `main(argc, argv, envp)`, `environ` initialised, `exit` flushing stdio | **Write** |
+
+Two liftings deserve their own line because getting them wrong is silent
+corruption rather than a linker error:
+
+- **`strtod`/float formatting.** Python's float `repr` guarantees shortest
+  round-trip; that property lives entirely in these routines. musl's are correct;
+  an improvised one would be subtly wrong for years. Lift, never write.
+- **The stdio engines.** musl's `vfprintf`/`vfscanf` are self-contained around
+  its `FILE` abstraction (function-pointer read/write slots), so the whole
+  formatted-I/O engine lifts too — we implement only the fd-backed slots
+  (`__stdio_write`-shaped) and the buffering glue.
+
+## Header policy
+
+Hand-write the headers as danos's own minimal set rather than importing musl's
+(musl's are entangled with Linux ABI details), borrowing declarations freely.
+Freestanding compiler headers (`stdint.h`, `stddef.h`, `stdarg.h`, `stdbool.h`,
+`float.h`, `limits.h`) come from clang via `zig cc` — do not duplicate them.
+`errno.h` values are the danos errno enum re-spelled with POSIX names; there is no
+Linux numbering to be compatible with, so the enum is the truth.
+
+Deliberate absences, and their planned arrivals — this table is the
+compatibility matrix, and "the road to full coverage" below is the schedule
+that empties it:
+
+| Absent | Arrives with |
+|--------|--------------|
+| `pthread.h` | the post-P5 pthread subset over `thread_spawn`/futex — but see the risk below |
+| real `signal.h` (beyond no-op `signal()`/`raise` stubs) | M17 signals-over-IPC in the libc |
+| `dlfcn.h` | [dynamic-libraries.md](dynamic-libraries.md) D1 |
+| `fork`/`exec*`/`wait*` | P5 exposes danos spawn as `posix_spawn`; `fork` itself never (see below) |
+| `socket.h` | a future networking track |
+| locale beyond `"C"` | stage 3 evaluation (CPython is UTF-8-mode happy without it) |
+| pipes (`pipe()`) | P5 process-control cluster |
+
+## The road to full coverage
+
+The layer grows in three stages; only stage 1 is a current milestone (P0), but
+the stages exist so stage-1 decisions never have to be unmade:
+
+- **Stage 1 — CPython-minimal** (P0, the slicing below): ~100–150 functions,
+  static-only, absences honest.
+- **Stage 2 — the danos-complete layer**: the full hosted C11 standard library,
+  plus every POSIX facility danos semantics support, landing as its enabling
+  milestone lands — pipes and `posix_spawn` at P5, real signals at M17, the
+  pthread subset after P5, `dlfcn.h` at
+  [dynamic-libraries](dynamic-libraries.md) D1, sockets with networking. Stage 2
+  is not one milestone but the standing rule that **every system capability
+  gets its C spelling when it ships**, so the matrix above drains as the OS
+  grows.
+- **Stage 3 — ecosystem grade**: the point where "portable C program" generally
+  means "builds on danos" (autotools-style probing included). Reaching it is
+  mostly stage 2 compounding, plus the long tail (locale, wide-char,
+  `fnmatch`/`glob`/`regex` — the last three lift from musl like the rest). At
+  this stage, re-evaluate hand-grown-vs-musl-port once with real data; the
+  standing recommendation remains danos-native — musl's bottom assumes Linux
+  syscall semantics, and by stage 3 the danos bottom exists and is tested —
+  with musl continuing as the quarry for computation code.
+
+Two boundaries are permanent and worth stating at every stage: **`fork` never
+comes** — danos is a spawn-shaped OS, and `fork`'s address-space-duplication
+semantics are hostile to everything from capabilities to threads; software that
+hard-requires `fork` (not `posix_spawn`) stays off the platform. And the
+**public ABI stays the vDSO + IPC protocols** — a full libc is a compatibility
+*layer*, not a second stable system ABI.
+
+## Milestone slicing
+
+1. **sysroot-skeleton** — layout under `library/c/` (a build package:
+   `include/`, Zig sources, vendored musl subtree); `crt0`; string/mem +
+   `ctype` lifted; a `build.zig` step making C binaries first-class targets.
+   *Test:* a C program using only computation links and runs in QEMU
+   (`c-hello` printing via a raw `write` extern to `debug_write`).
+2. **fd-plumbing** — `errno`; open/read/write/close/lseek/stat/unlink/mkdir/
+   rename over the `runtime` VFS client; `getcwd`/`chdir`/`getenv`/
+   `getentropy` arriving as P1 lands them (stubbed truthfully until then:
+   `getenv` empty, `getentropy` `ENOSYS`). *Test:* QEMU `c-file-io` — create,
+   write, reopen, read back, stat size + mtime through FAT.
+3. **malloc** — free-list allocator over danos `mmap`; `calloc`/`realloc`/
+   `free`; alignment guarantees documented. *Test:* host + QEMU allocator
+   torture (interleaved sizes, realloc growth, alignment asserts).
+4. **stdio** — `FILE*`, buffering modes, the lifted printf/scanf engines wired
+   to the fd slots; `snprintf` family; stdin/stdout/stderr over fd 0/1/2.
+   *Test:* host round-trip suite for format engines (especially `%.17g`
+   float round-trip); QEMU `c-stdio` cooked-line echo once P1's console exists.
+5. **mathematics-and-time** — libm lifted wholesale; `strtod`/`strtol`;
+   `clock_gettime` (monotonic + realtime over `clock`/`wall_clock`);
+   `gmtime`/`mktime`/`strftime` (UTC only — no timezone database);
+   `setjmp`/`longjmp`; `qsort`/`bsearch`; `abort`/`assert`. *Test:* host
+   `strtod`/`dtoa` vectors against known-hard cases; QEMU `c-time` sanity
+   against the wall clock.
+
+Slices 1, 3, 4-host, and 5-host have **no dependency on P1** and can start
+immediately; slice 2 and the QEMU halves interleave with P1 as it lands.
+
+**Exit for the layer as a whole** (= P0's exit): `c-hello` and `c-file-io` green
+in the QEMU suite, and the host-side computation tests green — at which point P2
+(CPython configure) becomes the layer's real integration test.
+
+## Testing strategy: two targets, on purpose
+
+The computation layer is target-independent, so it is unit-tested **on the host**
+(built for the host triple, compared against the host libc's answers —
+thousands of cheap oracle checks for `strtod`, `printf`, libm edge cases). The
+plumbing layer only means anything **on danos**, so it is tested in the QEMU
+suite like every other subsystem. Keeping the split explicit stops the slow-QEMU
+suite from absorbing tests that a host `zig test` runs in milliseconds.
+
+## Risks and gotchas
+
+- **CPython's configure may insist on pthreads.** WASI-class targets build
+  threadless, but verify this *first* in P2 bring-up; the fallback is a
+  truthfully-single-threaded `pthread.h` stub set (create returns `EAGAIN`,
+  mutexes are no-ops — valid when only one thread can exist). Decide from
+  evidence, not assumption.
+- **`long double` is x87 80-bit on x86-64.** musl's libm handles it, but keep
+  CPython away from it (`configure` uses `double` throughout by default);
+  don't hand-write anything touching x87.
+- **errno is a contract, not a convention.** The Zig plumbing must map every
+  `runtime` error to a POSIX name consistently — CPython turns errno into
+  exception types (`FileNotFoundError` is `ENOENT`). One table, tested.
+- **`malloc` alignment**: 16-byte minimum on x86-64 (SSE spills in
+  compiled C). The free-list must guarantee it from day one; retrofitting
+  alignment bugs out of an allocator is misery.
+- **Vendoring discipline.** The musl subtree is lift-only — never edited in
+  place (patches live beside it if ever needed), pinned to one musl release,
+  with the file list documented so a version bump is a re-copy, not an
+  archaeology dig.
+- **stdio buffering vs. crashes.** Buffered stdout + a crashing program eats
+  output — the classic debugging trap. `stderr` stays unbuffered (per C
+  standard) and `exit`/`abort` flush; document that `_exit` does not.
+
+## Decisions needing sign-off
+
+- **Lift-from-musl for all pure computation** (vendored, pinned, unedited) rather
+  than writing or porting whole-musl.
+- **Hand-written danos-native headers**; danos errno values are the numbering.
+- **`library/c/` as a build package** producing both the sysroot and the
+  first-class C-binary build step.
+- The **deliberate-absence table** as the living compatibility matrix, drained
+  by the three-stage road above — with exactly one permanent "never": `fork`.
+- **Full coverage as the end state** (stage 3), reached by the standing rule
+  that every system capability ships with its C spelling — not by a musl port.
+
+## Related
+
+- [python-on-danos-milestones.md](python-on-danos-milestones.md) — this is P0.
+- [dynamic-libraries.md](dynamic-libraries.md) — ships in this sysroot
+  (`dlfcn.h` + the loader) once its D1 lands.
+- [python-on-danos.md](python-on-danos.md) — the design note that scoped the
+  layer.
+- [character-devices-and-tty.md](character-devices-and-tty.md) — P1; supplies
+  the console that makes stdio interactive.
+- [zig-self-hosting.md](zig-self-hosting.md) — the `runtime.os` seam the
+  plumbing layer will re-target when it exists.
+- [os-development/sysv.md](os-development/sysv.md) — the entry stack `crt0`
+  bridges.

docs/character-devices-and-tty.md

@@ -0,0 +1,174 @@
+# Character devices, the console, and the tty question
+
+A design note for the **stream** half of the device world. danos has block devices
+(the USB storage service behind the FAT mount) but no character devices — and three
+tracks now need them at once: the terminal application, Zig self-hosting Phase 1
+("wire fd 0/1/2 to a console byte stream"), and [Python on danos](python-on-danos.md)
+Phase 1. This note settles what a character device *is* on danos before any of those
+tracks build one.
+
+## The Unix picture, briefly
+
+Unix splits devices in two: **block devices** are seekable arrays of fixed-size
+sectors (disks); **character devices** are unseekable byte streams (keyboards,
+serial ports, terminals, `/dev/null`, entropy). A **tty** is the canonical
+character device — a byte stream plus a *line discipline* (echo, line buffering,
+erase handling, Ctrl-C-to-signal) that lives in the kernel. A **pty** is a pair of
+character devices (master/slave) that exists so a *userspace* program — a terminal
+emulator — can impersonate terminal hardware to the kernel's in-kernel line
+discipline.
+
+The identification asked for and confirmed: yes, tty and pty are character
+devices in this taxonomy.
+
+## The realization that shapes everything: danos already has the mechanism
+
+A Unix character device is an in-kernel dispatch table: major/minor numbers route
+`read()`/`write()` to a driver. danos already has exactly that dispatch — the VFS:
+`fs_resolve` routes a path to a mounted backend service, and `Operation.mount`
+attaches a backend *endpoint* at a prefix. What is missing is not a device model;
+it is **one node kind with stream semantics**. And the protocol already reserved
+it: `NodeKind.character_device = 2` sits unimplemented in
+[vfs-protocol.zig](../library/protocol/vfs/vfs-protocol.zig), exactly like
+`symbolic_link`.
+
+So the design is small:
+
+**A character device on danos is a VFS node, served by an ordinary service over
+the existing VFS wire protocol, whose read/write have stream semantics.**
+
+No device numbers, no `/dev` special casing, no new syscalls, no new protocol —
+a service is reachable at a path, clients open it with `runtime.fs` like any
+file, and the node kind says what it is. (Since the protocol namespace landed
+in design, that path is `/protocol/console` — a protocol node, see
+[os-development/protocol-namespace.md](os-development/protocol-namespace.md) —
+rather than a mounted device file; the stream semantics below are unchanged.)
+
+### Stream semantics (the actual contract change)
+
+For a node whose kind is `character_device`:
+
+- **`offset` is ignored** on read and write; there is no seek position. (`lseek`,
+  when the C layer exists, returns `ESPIPE`.)
+- **Reads block** until at least one byte is available, then return what is there —
+  **short reads are normal**, not EOF. A zero-length read reply means the stream
+  is closed (hangup), not end-of-file-at-size.
+- **`FileStatus.size` is 0** and means nothing; `mtime` may be 0.
+- Writes may be short if the service's buffer is full; the client loops as it
+  already must for the 256-byte message cap.
+
+This is a semantics note on existing operations, not a wire change — the `Request`
+and `Reply` structs are untouched. The one true protocol addition is a **`control`
+operation** (appended to `Operation`, values stable): a typed request the stream's
+service interprets. Deliberately *not* an `ioctl` grab-bag — the control payloads
+are enumerated per protocol, starting with the terminal set below.
+
+## The first character device is a pseudo-device
+
+The first device is deliberately **not hardware**: an in-memory **loopback** — a
+byte queue served over the stream contract, where bytes written to one end are
+read from the other. It is the reference implementation of the semantics above
+(blocking reads, short reads, hangup on close, the `control` round-trip), it
+tests deterministically with no QEMU serial scripting, and it keeps hardware off
+the critical path entirely. `null` and `zero` come along nearly for free as
+degenerate cases. This is a decision, not a convenience: the dead-COM1 boot bug
+on real hardware already proved serial cannot be assumed present or alive, so
+**nothing in this milestone writes to COM1**. (A serial-backed stream node can
+exist *later* as one more optional backend for headless debugging; it is on
+nobody's critical path.)
+
+The loopback is also not throwaway — it is the seed of P5's `pipe()`, which is
+the same object with two fds.
+
+## The console service
+
+A `console` service owns the line discipline — **in userspace**, where a
+microkernel wants it, not in the kernel as Unix has it:
+
+- **The discipline is a pure library first**: bytes and key events in, bytes
+  out, no I/O of its own — developed and host-tested against in-memory buffers,
+  then shared verbatim between the console and the future terminal application.
+- **Input**: subscribes to keyboard `InputEvent` IPC (the structured events that
+  exist today) and cooks them into bytes. Cooked mode is the default: echo, line
+  buffering, backspace/erase, so a line is delivered on Enter. Raw mode delivers
+  bytes as they come (the REPL's line editor and any full-screen program need it).
+- **Output is a pluggable sink**, and the stream contract is independent of it:
+  the bring-up sink is in-memory (readable back by tests, mirrored to the boot
+  log), and the real one is the framebuffer text renderer when the display
+  track's font work lands.
+- **Control set** (the `control` payloads): mode raw/cooked, echo on/off, and
+  window-size query — the minimal termios. Ctrl-C-to-signal joins when M17
+  signals-over-IPC lands; until then Ctrl-C is just a byte.
+- Mounts itself at `/device/console` as a `character_device` node.
+
+**fd 0/1/2** then stop being special: spawn hands the child three open handles
+(console by default; anything else if the parent chooses), and `runtime`'s fd
+table maps 0/1/2 to them. `isatty` is simply "does `status` say
+`character_device`" — no side channel needed.
+
+## The pty answer: there is no pty
+
+The pty exists in Unix *because the line discipline is in the kernel* — userspace
+terminal emulators need a kernel gadget to impersonate hardware. On danos the
+terminal emulator is already a userspace server, so the pair collapses:
+
+**The graphical terminal application serves the VFS stream protocol itself and
+hands its own endpoints to the children it spawns as their fd 0/1/2.**
+
+The terminal *is* the console service for its children — same protocol, same
+control set, same line discipline code (shared as a library with the boot
+console). No master/slave device pair, no `/dev/pts`, no new kernel object. When
+CPython arrives, the libc's `isatty`/read/write see a character device and are
+none the wiser; when xonsh eventually wants job control, that lands as control
+messages + M17 signals, still with no pty object.
+
+What this costs: programs that *specifically* manipulate Unix ptys
+(`os.openpty()`, `pexpect`-style tools) have no direct equivalent — the danos
+answer is "spawn the child yourself with your own stream endpoints," which is the
+same capability with less machinery. Accepted.
+
+## Milestone slicing
+
+1. **pseudo-devices** — VFS honors `character_device` semantics end to end;
+   `Operation.control` added; the in-memory **loopback** (plus `null`/`zero`)
+   as the first device. QEMU test: one client writes, another reads — open,
+   offsetless read/write, blocking read, short read, hangup on close, control
+   round-trip. No hardware anywhere.
+2. **console-service** — the line-discipline library (host-tested, pure) plus
+   the console composing keyboard `InputEvent`s with an in-memory output sink;
+   mounted at `/device/console`. QEMU test injects key events and reads cooked
+   lines and raw bytes back through the sink.
+3. **fd-inheritance** — spawn passes 0/1/2 handles; `runtime` fd table; `isatty`
+   via `status`; existing binaries' stdout migrates from `debug_write` to fd 1
+   (the logger keeps its own path).
+4. **terminal-as-server** — deferred to the terminal application milestone
+   (Python track P3): the terminal reuses the discipline library and serves its
+   children directly.
+
+Steps 1–3 are exactly the shared seam that Zig self-hosting Phase 1 and Python
+Phase 1 both list; neither track repeats them.
+
+## Decisions needing sign-off
+
+- **No pty object; the terminal serves its children directly** (the section
+  above) — the load-bearing simplification.
+- **`control` as an enumerated, typed operation** rather than an ioctl-style
+  opaque pass-through.
+- **Line discipline in userspace services** (console + terminal, shared library),
+  never in the kernel.
+
+## Related
+
+- [python-on-danos.md](python-on-danos.md) — consumes this as its Phase 1.
+- [zig-self-hosting.md](zig-self-hosting.md) — ditto ("stdio as fds").
+- [file-system-development/vfs-protocol.md](file-system-development/vfs-protocol.md) —
+  the wire protocol this note extends.
+- [file-system-development/file-system-hierarchy.md](file-system-development/file-system-hierarchy.md)
+  — the tree the console surfaces in.
+- [os-development/protocol-namespace.md](os-development/protocol-namespace.md) —
+  supersedes this note's device-node naming: the console lands as a protocol
+  (`/protocol/console`, a protocol node), not a `/dev`-style device file. The
+  stream semantics designed here (line discipline, cooked/raw modes) carry over
+  unchanged.
+- [device-driver-development/input.md](device-driver-development/input.md) — the
+  `InputEvent` stream the console cooks.

docs/device-driver-development/devices-csv.md

@@ -96,7 +96,15 @@ in different namespaces — against the right `bus` column.
 
 ## Adding a driver
 
-1. Build the driver binary and bundle it at `/system/drivers/<name>` (build.zig).
+(The step-by-step walkthrough with a worked example is
+[new-driver-checklist.md](new-driver-checklist.md).)
+
+1. Create `system/drivers/<name>/` with the driver source plus a ~15-line
+   package `build.zig` + `build.zig.zon` (copy an existing driver package,
+   e.g. `system/drivers/pci-bus/`; per-driver extras go through
+   `build_support.programModule`). Then bundle it at `/system/drivers/<name>`:
+   one dependency + one bundled entry in the root `build.zig`, one line in the
+   root `build.zig.zon`.
 2. Add a row to `etc/devices.csv` naming the identity it binds and its full path.
 
 No device-manager change is required — the registry is the seam.

docs/device-driver-development/display-plan.md

@@ -20,9 +20,10 @@ Read [display.md](display.md) first for the *why*; this is the *what* and the *o
 
 Follow [coding-standards.md](../coding-standards.md): spell out non-acronym abbreviations in
 full, kebab-case file names, no `Co-Authored-By` trailers on commits. New user binaries
-go through `addUserBinary` in [build.zig](../../build.zig) and get packed into the
-initial-ramdisk; protocols are `b.addModule("…-protocol", …)` and imported into the
-`runtime` module.
+go through build-support's shared user-binary recipe and get packed into the
+initial-ramdisk; protocols are modules exported by the `library/protocol` package.
+(This section predates the build-packages split; see
+[build-packages-plan.md](../build-packages-plan.md) for the current build shape.)
 
 ## How to verify along the way
 

docs/device-driver-development/display-v2-plan.md

@@ -18,9 +18,11 @@ lands on its own and ends in a **verifiable gate** — shaped for a `/loop` run,
 
 Follow [coding-standards.md](../coding-standards.md): spell out non-acronym abbreviations,
 kebab-case file names, no `Co-Authored-By` trailers. New user binaries go through
-`addUserBinary` and get packed into the initial-ramdisk; protocols are
-`b.addModule("…-protocol", …)` imported into `runtime`; new syscalls extend
-[abi.zig](../../system/abi.zig) `SystemCall` + a `library/runtime` wrapper.
+build-support's shared user-binary recipe and get packed into the initial-ramdisk;
+protocols are modules exported by the `library/protocol` package; new syscalls extend
+[abi.zig](../../system/abi.zig) `SystemCall` + a `library/kernel` wrapper.
+(This section predates the build-packages split; see
+[build-packages-plan.md](../build-packages-plan.md) for the current build shape.)
 
 ## How to verify along the way
 

docs/device-driver-development/display.md

@@ -29,7 +29,7 @@ which one you're holding decides what you can do.
 
 - **The PCI class-0x03 device is the raw controller** — BARs, config space, registers,
   IO ports. It is what you actually *own* after boot. On QEMU's emulated adapter
-  ([`-device VGA,edid=on`](../../build.zig), the Bochs VBE/DISPI model) the `base` GOP handed
+  ([`-device VGA,edid=on`](../../build/qemu.zig), the Bochs VBE/DISPI model) the `base` GOP handed
   you *is* that device's linear-framebuffer BAR — the same physical memory, seen through
   a different door. On a real discrete GPU, GOP's `base` is an aperture inside the GPU's
   VRAM BAR. danos already decodes this device

docs/device-driver-development/driver-model.md

@@ -138,13 +138,17 @@ a higher-level service (block ↔ filesystem, a scanout driver ↔ the composito
 private wire to its *hardware* — virtio-gpu's command set — is not that; it stays a
 driver-private file, like the virtio-pci transport beside it.
 
-The build side of this has since landed: [`addUserBinary`](build.zig) injects the
-default modules — the library/kernel concern modules (`ipc`, `memory`, `process`, `time`,
-`logging`, `file-system`, `thread`, `service`), the device/service clients (`driver`,
-`block`, `display`, `input`), plus `mmio`, `xkeyboard-config`, `acpi-ids` — into every user
-binary, and per-binary extras — protocol modules, bus logic — are added with
-`programModule(exe).addImport(...)`. That's the *entire* mechanism — Zig modules
-already give you everything else.
+The build side of this has since landed: every binary owns a package whose
+~15-line `build.zig` names EXACTLY the modules its source imports — the moral
+equivalent of a C file's include list — and the shared recipe in
+[`build-support/build.zig`](../../build-support/build.zig) (`userBinary`)
+resolves each name from the library domain that exports it (kernel's concern
+modules, the device driver libraries, the service clients, the protocols). An
+undeclared `@import` is a compile error, and a domain none of the imports come
+from never appears in the binary's manifest — a keyboard driver declares
+`xkeyboard-config`; nothing else does (see
+[build-packages-plan.md](../build-packages-plan.md)). That's the *entire*
+mechanism — Zig modules already give you everything else.
 
 The discipline that makes this work: **a class driver must not import a bus's *hardware*
 logic module.** `usb-hid` imports `usb` (the transfer client) and `input-protocol`, never

docs/device-driver-development/ipc.md

@@ -1,34 +1,70 @@
-# IPC: message-passing channels
+# IPC: the kernel-ipc transport
 
 Inter-process communication is the **backbone of a microkernel**. Once drivers and
 services run isolated in their own address spaces ([vision](../vision.md)), they can't
-just call each other — a request becomes a **message**. In a microkernel, whatever
+just call each other — a request becomes bytes on a wire. In a microkernel, whatever
 was a function call across a monolithic kernel is IPC, so it's a first-class
 concern, not an afterthought.
 
-There are two layers, built a milestone apart:
+This document describes **one transport** — the bottom layer (L0) of the
+communication stack defined in
+[communication.md](../os-development/communication.md), which owns the model
+and the vocabulary (*protocol*, *channel*, *packet*, *signal*, *endpoint*).
+kernel-ipc is the **first** transport, not the only possible one: in
+buffer-plus-doorbell terms it is a kernel-owned mailbox with the scheduler as
+the doorbell. Its distinguishing properties, which the layers above may rely
+on where they say so:
 
-- **`system/kernel/ipc.zig`** — a bounded blocking channel between *kernel threads*,
-  described below. The primitive, and where the blocking discipline was worked out.
-- **`system/kernel/ipc-synchronous.zig`** — synchronous call/reply between *processes*, across
-  address spaces. What user-space servers and drivers actually talk over. It's the
-  second half of this document.
+- **Rendezvous.** A call is a synchronous meeting, copied sender-page to
+  receiver-page — natural backpressure, no queue to size.
+- **Capability carriage.** The *only* transport that can move a handle
+  between processes. Channels are therefore always established over
+  kernel-ipc, and it remains every channel's control path even when bulk
+  data is negotiated onto a fatter transport (a shared-memory ring).
+- **Verified source.** Every delivery carries the kernel-stamped badge — the
+  identity the channel layer attaches to received packets.
+- **Bounded packets.** 256 bytes call/reply, 64 pushed — the floor every
+  protocol may assume on any transport.
 
-## The channel
+Three properties keep the networking analogy honest — kernel-ipc is
+networking-*shaped*, not TCP:
 
-The first form is a **bounded blocking channel** (`system/kernel/ipc.zig`): a fixed-size
-ring buffer of messages with a producer/consumer rendezvous, built on the
-scheduler's [wait queues](../os-development/scheduling.md).
+- **Channels over it are RPC-shaped, not streams.** Packets, call/reply,
+  datagram pushes — closer to UDP plus RPC than to a byte stream. Ordering
+  exists per exchange (a reply answers its call), not across a channel.
+- **Possession is the connection.** There is no handshake state in the
+  kernel: holding the capability *is* having the channel. A provider's one
+  endpoint terminates every client's channel at once, demultiplexed by badge
+  — like every client sharing the server's listening socket, with
+  per-connection state living in the provider, keyed by badge. A *private*
+  channel (a dedicated endpoint pair) is built when wanted: that is exactly
+  what `subscribe` does.
+- **Packets never fragment.** If it doesn't fit in a packet, it isn't a
+  packet: bulk data lives in shared memory and a packet (or signal) is the
+  doorbell. The display path already works this way.
+
+The rest of this document is the implementation, bottom-up: the kernel-thread
+queue the blocking discipline was worked out on, then endpoints — this
+transport's termination points.
+
+## The kernel-thread queue
+
+The first form is a **bounded blocking queue** (`system/kernel/ipc.zig`): a
+fixed-size ring buffer of messages with a producer/consumer rendezvous, built
+on the scheduler's [wait queues](../os-development/scheduling.md). (Its type
+is still named `Channel(T, capacity)` — it predates the vocabulary above, and
+is a *queue between kernel threads in one address space*, not a channel in
+the model's sense; a rename can ride a later flag-day.)
 
 `Channel(T, capacity)` is generic over the message type and buffer size. It holds a
 ring buffer, a count, and two wait queues:
 
-- **`send(msg)`** — if the channel is full, block on the *not-full* queue; otherwise
+- **`send(msg)`** — if the queue is full, block on the *not-full* queue; otherwise
   write the message, bump the count, and wake a waiting receiver.
-- **`receive()`** — if the channel is empty, block on the *not-empty* queue; otherwise
+- **`receive()`** — if the queue is empty, block on the *not-empty* queue; otherwise
   take a message, drop the count, and wake a waiting sender.
 
-Neither side busy-waits: a full channel parks the sender, an empty one parks the
+Neither side busy-waits: a full queue parks the sender, an empty one parks the
 receiver, and each operation wakes the other side when it makes progress possible.
 
 Two details make it correct:
@@ -45,47 +81,52 @@ Two details make it correct:
   CPU. `waitLocked` / `wakeLocked` are the variants that assume the caller already
   holds that critical section.
 
-## Verifying it
+### Verifying it
 
 The `ipc` test (see [testing.md](../testing.md)) runs a producer and a consumer passing
-**100 messages through a 4-slot channel**. The small buffer means the channel goes
+**100 messages through a 4-slot queue**. The small buffer means the queue goes
 full and empty over and over, so both the blocking-send and blocking-receive paths are
 exercised heavily. The messages arrive intact and in order (their sum is the
 expected `5050`), and neither task busy-waits — they block and wake each other.
 
-## Endpoints: call/reply across address spaces
+## Endpoints: the termination points
 
-A channel connects two kernel threads sharing one address space. Real servers are
-*processes*, so the payload has to cross an address-space boundary. That's
+A queue connects two kernel threads sharing one address space. Real providers are
+*processes*, so a packet has to cross an address-space boundary. That's
 `system/kernel/ipc-synchronous.zig`, and its shape is L4's: a synchronous **rendezvous** at an
-`Endpoint`, with the message copied directly from the sender's pages to the receiver's
+`Endpoint`, with the packet copied directly from the sender's pages to the receiver's
 (`copyAcross` walks both sets of page tables through the physmap — no CR3 switch, no
 bounce buffer).
 
-Two syscalls carry it:
+Two syscalls carry the request/reply exchange:
 
-- **`ipc_call(h, msg, reply)`** — copy `msg` to the server, block until it replies.
+- **`ipc_call(h, msg, reply)`** — copy the request packet to the provider, block
+  until the reply packet comes back.
 - **`ipc_reply_wait(h, reply, recv)`** — reply to the client you're still holding (if
-  any), then block for the next request. One syscall, because a server's steady state
+  any), then block for the next request. One syscall, because a provider's steady state
   is *always* "finish the last one, wait for the next".
 
 An endpoint is reached by **handle** — a small integer index into the process's handle
-table (`Task.handles`), exactly like a file descriptor, and just as unforgeable. The
-bootstrap problem (how do you get the first handle?) is solved by a tiny name registry:
-a server calls `ipc_register(service_id, h)` under a well-known small integer, and a
-client calls `ipc_lookup(service_id)`.
+table (`Task.handles`), exactly like a file descriptor, and just as unforgeable.
+The provider never learns the client's identity beyond the **badge** delivered
+alongside each packet: the caller's task id, stamped by the kernel —
+unforgeable source addressing, a property a network's source field lacks.
 
-The server never learns the client's identity beyond a **badge**, delivered alongside
-the message: the caller's task id.
+The bootstrap problem — how a channel is first established — is the subject of
+[protocol-namespace.md](../os-development/protocol-namespace.md): a protocol is
+resolved by name and the channel arrives as a capability. (The mechanism this
+replaces, `ipc_register`/`ipc_lookup` under compile-time `ServiceId` integers,
+is retired by that design.)
 
-### Interrupts are messages too
+### Interrupts are signals
 
-`notifyFromIsr` posts an *asynchronous* notification to an endpoint — no payload, no
+`notifyFromIsr` posts an *asynchronous* signal to an endpoint — no payload, no
 reply owed — and wakes whoever is blocked in `reply_wait`. Its badge has the top bit
 set (`notify_badge_bit`), which is how a driver's single event loop distinguishes "a
-client wants something" from "the hardware wants something". Notifications sit in a
+client wants something" from "the hardware wants something". Signals sit in a
 small coalescing ring on the endpoint, so an interrupt taken while the driver was busy
-elsewhere is not lost.
+elsewhere is not lost — coalesced, never dropped, which is exactly a signal's
+contract (the *count* may collapse; the *fact* may not).
 
 This is what makes a user-space driver possible at all, and it's the subject of
 [drivers.md](drivers.md).
@@ -93,40 +134,44 @@ This is what makes a user-space driver possible at all, and it's the subject of
 ## What's next (partly done since)
 
 - **Priority inheritance** through IPC — still open: a high-priority client
-  blocked on a low-priority server suffers unbounded priority inversion.
+  blocked on a low-priority provider suffers unbounded priority inversion.
 - **Handle transfer.** *Landed as cap-passing (M13)*: `ipc_call` and
   `ipc_reply_wait` carry an optional capability alongside the bytes (`send_cap`),
-  copying an endpoint or shared-memory handle into the peer's table. First user:
-  [input](input.md) subscribers register by handing over their own endpoint, and
-  class drivers get a private channel to one device.
+  copying an endpoint or shared-memory handle into the peer's table — the
+  mechanism by which channels are established and private channels built. First
+  user: [input](input.md) subscribers register by handing over their own
+  endpoint, and class drivers get a private channel to one device.
 - **Asynchronous / buffered send** for the cases where a rendezvous is the wrong
-  shape (logging, notifications between servers). *Landed as `ipc_send`* — a
-  non-blocking post to an endpoint's bounded payload queue, delivered through
-  `reply_wait` as a buffered message (badge bit `notify_message_bit`). Built for, and
-  first used by, the [input service](input.md)'s keyboard-event broadcast, where a
-  synchronous push would let one dead subscriber hang the fan-out. A full queue drops
-  the oldest (discrete messages, not a coalescing level like the notification ring).
-- **A bounded reply** — half landed. The copy is still 256 bytes
-  (`MESSAGE_MAXIMUM`) under the big kernel lock, but bulk transfer got its shared
+  shape (logging, event fan-out). *Landed as `ipc_send`* — a
+  non-blocking post of an event packet (≤ 64 bytes) to an endpoint's bounded
+  queue, delivered through `reply_wait` (badge bit `notify_message_bit`). Built
+  for, and first used by, the [input service](input.md)'s keyboard-event
+  broadcast, where a synchronous push would let one dead subscriber hang the
+  fan-out. A full queue drops the oldest — event packets are droppable by
+  design ([protocol-namespace.md](../os-development/protocol-namespace.md)'s
+  wiring section states the rule).
+- **A bounded reply** — half landed. The copy is still one packet
+  (256 bytes) under the big kernel lock, but bulk transfer got its shared
   pages: `shared_memory_create`/`map`/`physical`, the region handle delegated as
-  a capability (above). virtio-gpu's scanout surface is the first user
+  a capability (above) — the packets-never-fragment rule in practice.
+  virtio-gpu's scanout surface is the first user
   ([display-v2.md](display-v2.md)).
 
 ## Lifecycle conventions over IPC (M17)
 
 Three conventions from [process-lifecycle.md](../os-development/process-lifecycle.md) ride the
-notification mechanism:
+signal mechanism:
 
-- **Signals** arrive as notifications on the endpoint a process nominated with
-  `signal_bind` (`process.bindSignals`): badge = the signal bit plus the
-  coalesced pending mask (`process.signalsFrom` decodes). Statements,
+- **Process signals** arrive as endpoint signals on the endpoint a process
+  nominated with `signal_bind` (`process.bindSignals`): badge = the signal bit
+  plus the coalesced pending mask (`process.signalsFrom` decodes). Statements,
   never questions; no payload, no reply.
 - **One-shot timers** (`timer_bind`, `time.timerOnce`) land as a
-  timer-bit notification — the timed wait: a service arms a deadline and keeps
+  timer-bit signal — the timed wait: a service arms a deadline and keeps
   serving, instead of blocking in sleep.
 - **The universal ping**: a **zero-length request is the liveness probe**,
   answered with a zero-length reply by the service harness itself
   (`service.run`). No protocol's requests start at length zero, so the
   encoding cannot collide, and a wedged service simply fails to answer — which
   is the diagnosis. Deep health ("can I reach my hardware?") stays a per-service
-  protocol message.
+  protocol packet.

docs/device-driver-development/new-driver-checklist.md

@@ -0,0 +1,218 @@
+# New driver: the minimum steps
+
+The shortest path from "a device shows up in the boot log" to "my process is
+running with its registers mapped". This is the checklist; the reasoning behind
+every step lives in [Writing a driver](drivers.md), the matching rules in
+[devices.csv](devices-csv.md), and interrupts in
+[device interrupts](device-interrupts.md).
+
+Worked example throughout: the Intel UHD 750 iGPU, which the boot log reports as
+
+```
+pci-bus: 0:2.0  bus=pci base=03 class=00 prog_if=00 vendor=8086 device=4C8A ...
+```
+
+## 1. Create the source file
+
+`system/drivers/<name>/<name>.zig` — kebab-case, abbreviations spelled out
+([coding standards](../coding-standards.md)). The directory name, the binary
+name, and the `devices.csv` driver path must all agree; a mismatch fails
+silently (the device-manager logs the spawn failure, nothing else happens).
+
+The complete minimal driver — claims its device, logs every resource, maps the
+register window, then sleeps in the harness loop:
+
+```zig
+//! /system/drivers/intel-uhd-graphics-750 — spawned by the device manager with
+//! the device-tree id as argv[1]; claims that device and no other.
+
+const std = @import("std");
+const device = @import("driver");
+const ipc = @import("ipc");
+const memory = @import("memory");
+const process = @import("process");
+const service = @import("service");
+
+/// No protocol yet: the kernel's IPC ceiling (MESSAGE_MAXIMUM) sizes the buffers.
+const message_maximum = 256;
+
+var controller_id: u64 = 0;
+var register_base: usize = 0;
+
+fn initialise(endpoint: ipc.Handle) bool {
+    _ = endpoint; // needed later, for irq binding and timers
+
+    if (!device.claim(controller_id)) {
+        std.log.err("unable to claim device {d}", .{controller_id});
+        return false;
+    }
+
+    // Fetch our own descriptor back for the device's resources.
+    const buffer = memory.allocator().alloc(device.DeviceDescriptor, 64) catch return false;
+    defer memory.allocator().free(buffer);
+    const total = device.enumerate(buffer);
+    const descriptor = for (buffer[0..@min(total, buffer.len)]) |d| {
+        if (d.id == controller_id) break d;
+    } else {
+        std.log.err("device {d} not in the device tree", .{controller_id});
+        return false;
+    };
+
+    // Log every resource BEFORE choosing one (see step 5).
+    var register_index: u64 = 0;
+    for (descriptor.resources[0..@intCast(descriptor.resource_count)], 0..) |resource, index| {
+        std.log.info("resource {d}: kind={d} start=0x{x} len=0x{x}", .{
+            index, resource.kind, resource.start, resource.len,
+        });
+        // The 16 MiB window is GTTMMADR, the register BAR (this device also has
+        // a 256 MiB memory BAR, GMADR — "first memory resource" would be wrong).
+        if (resource.kind == @intFromEnum(device.ResourceKind.memory) and
+            resource.len == 16 * 1024 * 1024) register_index = index;
+    }
+    if (register_index == 0) {
+        std.log.err("register BAR not found", .{});
+        return false;
+    }
+
+    register_base = device.mmioMap(controller_id, register_index) orelse {
+        std.log.err("mmio_map failed", .{});
+        return false;
+    };
+    std.log.info("registers mapped at 0x{x}", .{register_base});
+    return true;
+}
+
+fn onMessage(message: []const u8, reply: []u8, sender: u32, capability: ?ipc.Handle) usize {
+    _ = message;
+    _ = reply;
+    _ = sender;
+    _ = capability;
+    return 0; // no protocol yet; the zero-length ping is answered by the harness
+}
+
+pub fn main(init: process.Init) void {
+    const argument = init.arguments.get(1) orelse {
+        std.log.err("missing device id (argv[1])", .{});
+        return;
+    };
+    controller_id = std.fmt.parseInt(u64, argument, 10) catch {
+        std.log.err("malformed device id '{s}'", .{argument});
+        return;
+    };
+    service.run(message_maximum, .{
+        .init = initialise,
+        .on_message = onMessage,
+        // .on_notification only once an IRQ or timer is bound
+    });
+}
+```
+
+`claim` is the capability gate: MMIO mapping, DMA grants, and IRQ binding all
+require it, and it pins the IOMMU domain to this process
+([drivers.md — claim before touch](drivers.md#the-capability-claim-before-touch)).
+
+## 2. Create the build package and register it in the root build
+
+The driver directory is its own build package
+([build-packages-plan.md](../build-packages-plan.md)): a ~15-line `build.zig`
+plus a `build.zig.zon` beside the source. Copy both from an existing driver —
+`system/drivers/pci-bus/` is the template — and adjust the name, root source
+file, and the import list. The list names EXACTLY the modules the driver's
+source `@import`s (the moral equivalent of its include list; an undeclared
+import is a compile error):
+
+```zig
+pub fn build(b: *std.Build) void {
+    const exe = build_support.userBinary(b, .{
+        .name = "intel-uhd-graphics-750",
+        .root_source_file = b.path("intel-uhd-graphics-750.zig"),
+        .imports = &.{ "driver", "ipc", "memory", "process", "service" },
+    });
+    b.installArtifact(exe);
+}
+```
+
+The zon declares `build-support`, `kernel` (implicit in every binary: the root
+shim lives there), and the homes of the listed imports — for the minimal
+driver above that is kernel alone plus `device` (for `driver`); add
+`protocol`, `client`, ... only when an import comes from them (again, copy
+pci-bus's zon and adjust). For the `.fingerprint` field, leave the copied
+value in place and `zig build` will reject it and suggest the fresh one to
+paste.
+
+Then three one-liners in the root build register the package: the dependency
+and a row in the boot-tree array in `build.zig` (search for
+`virtio_gpu_package` to land in the right places),
+
+```zig
+const intel_uhd_graphics_750_exe = b.dependency("intel-uhd-graphics-750", .{}).artifact("intel-uhd-graphics-750");
+```
+
+```zig
+.{ .path = "system/drivers/intel-uhd-graphics-750", .binary = intel_uhd_graphics_750_exe.getEmittedBin() },
+```
+
+and the path entry in the root `build.zig.zon`:
+
+```zig
+.@"intel-uhd-graphics-750" = .{ .path = "system/drivers/intel-uhd-graphics-750" },
+```
+
+Without the boot-tree row the binary never reaches the image and the
+device-manager has nothing to spawn. (The package also builds standalone:
+`cd system/drivers/intel-uhd-graphics-750 && zig build`.)
+
+## 3. Add the match rule to `etc/devices.csv`
+
+One row: bus, class triplet, vendor/device, driver path. **Copy the class
+triplet from the pci-bus boot log line, not from another row** — for the iGPU
+above the correct rule is
+
+```
+pci,    03,  00,   00,     8086,  4C8A,  *,        *,        /system/drivers/intel-uhd-graphics-750
+```
+
+Field-by-field rules and the most-specific-wins policy: [devices.csv](devices-csv.md).
+The registry is authoritative: an unmatched device is logged unbound, never
+guessed — so a wrong nibble here means the driver simply never starts.
+
+## 4. First contact: read, predict, verify
+
+Before writing any register, read one whose value you can predict from state
+the firmware already programmed (for a display controller: the pipe source
+size of the live mode). Registers are volatile loads at `register_base +
+offset`, where `offset` is what the device's manual lists:
+
+```zig
+fn read32(offset: usize) u32 {
+    return @as(*volatile u32, @ptrFromInt(register_base + offset)).*;
+}
+```
+
+A matching read proves the whole chain — CSV match, spawn, claim, BAR choice,
+mapping — with zero risk to the hardware.
+
+## 5. Verify the plumbing
+
+- `zig build test` still passes.
+- On the image: `/var/log/<boot-stamp>/system/services/device-manager.log`
+  shows `spawned <name> for device <N>`, and
+  `/var/log/<boot-stamp>/system/drivers/<name>.log` holds the resource list and
+  your first read.
+- If the driver did not spawn, diagnose in this order: binary on the image
+  (step 2) → CSV row matches the log line exactly (step 3) → path identical in
+  both (step 1).
+
+## Later, when the device needs them
+
+- **Interrupts**: MSI/MSI-X via the `pci` module, delivered as notifications to
+  `on_notification` — see [device interrupts](device-interrupts.md) and the
+  xHCI driver's `setupMsi` (QEMU trap documented there: enable MSI-X before
+  unmasking the device's own interrupt-enable bit).
+- **DMA**: grant-backed buffers, bounded by the IOMMU domain established at
+  claim time ([driver model](driver-model.md)).
+- **Children**: a bus driver publishes what it finds via `device_register`
+  ([drivers.md — publishing children](drivers.md#publishing-children-device_register)).
+- **A protocol**: replace `message_maximum` with the protocol's own maximum and
+  dispatch on the operation word in `onMessage` — every service under
+  `system/services/` is an example.

docs/dynamic-libraries.md

@@ -0,0 +1,124 @@
+# Dynamic libraries on danos
+
+A design note and milestone plan for shared objects: building them, loading them
+with `dlopen`, and — the part that needs kernel work — actually *sharing* them
+between processes. Directional, post-P5 of
+[python-on-danos-milestones.md](python-on-danos-milestones.md); nothing on the
+CPython bring-up path depends on it.
+
+## Reconciling the earlier "rejected"
+
+Dynamic libraries were evaluated once before and rejected — but as an answer to a
+*different question*: whether they could claw back ReleaseSafe's measured ~2×
+code size. They cannot (the safety checks inline at every call site; no library
+scheme dedups them), and that verdict stands for that question. The reasons to
+build them now are the ones that investigation never weighed:
+
+- **`ctypes` and runtime FFI** — Python calling into a danos library without
+  rebuilding the interpreter. This is the piece that makes Python prototyping
+  self-serve: drop a `.so` on the image, `ctypes.CDLL` it, iterate.
+- **Loadable CPython extension modules** — today every C extension means
+  relinking the interpreter (`Modules/Setup`); with `dlopen`, an extension is a
+  file.
+- **One interpreter image, many Python services** — a statically-linked CPython
+  is tens of megabytes *per process*. A shared `libpython` mapped read-only once
+  (milestone D3 below) makes Python services cheap enough to be the default way
+  to prototype one.
+- **Plugin-shaped applications** — the UI toolkit and the terminal will want
+  them eventually.
+
+The scoping that dissolves the apparent contradiction is the **size doctrine**:
+leanness is an *operating-system* property — the kernel and system services stay
+small and statically linked, and none of them ever link the loader — while
+*applications* have their own budget and may be big. Dynamic libraries are an
+**application-layer facility**, full stop.
+
+What also does **not** change: the public ABI stays the vDSO + the IPC
+protocols. Shared objects are artifacts *within* one system image, versioned by
+the build — not a new stable ABI surface for the OS.
+
+## Design
+
+- **Format and codegen are free.** ELF shared objects with position-independent
+  code; `zig cc -fPIC -shared` against the [libdanos-c](c-library-compatibility.md)
+  sysroot already emits them. The work is entirely on the loading side.
+- **The loader lives in userspace, inside the libc.** `dlopen` reads the `.so`
+  through the VFS, maps its segments, applies relocations, resolves symbols
+  against the process and the `DT_NEEDED` dependency graph, runs constructors,
+  returns a handle. No kernel loader changes in v1 — segments land in anonymous
+  `mmap` as private copies.
+- **Bind-now, always.** All relocations resolved at `dlopen` time
+  (`RTLD_NOW` semantics only). Lazy PLT binding buys startup latency danos does
+  not care about, at the price of a writable GOT dance and a much subtler
+  loader. Not worth it; keep it out permanently.
+- **W^X from day one.** Map, relocate, then flip text pages read-execute —
+  which requires memory-protection change (`mprotect`-shaped) in the danos
+  `mmap` surface if it is not already there. No page is ever writable and
+  executable at once.
+- **TLS in shared objects is deferred.** Thread-local storage models
+  (initial-exec vs. general-dynamic) are the deep end of every dynamic linker.
+  v1 refuses a `.so` with a TLS segment; revisit alongside the post-P5 pthread
+  subset, which is when it could matter.
+- **Executables stay static until D4.** v1 is "a static binary that can
+  `dlopen`" — no `PT_INTERP`, no program interpreter, no dynamically-linked
+  `main` binaries. That keeps process startup untouched.
+
+## Milestones
+
+1. **D1 — dlopen in-process.** The `.so` build target; the loader in libdanos-c:
+   map, relocate (`RELATIVE`/`GLOB_DAT`/`JUMP_SLOT`), resolve, constructors;
+   `dlopen`/`dlsym`/`dlerror`/`dlclose`; private anonymous mappings; no TLS.
+   *Test:* QEMU `dlopen-hello` — load a `.so`, call a symbol, unload, reload.
+2. **D2 — the FFI payoff.** `DT_NEEDED` dependency graphs; a **libffi port**
+   (x86-64 SysV assembly is upstream; the port is its closure-allocation paths,
+   which must respect W^X); CPython's `ctypes` enabled; extension modules
+   loadable from file. *Test:* QEMU — a Python script `ctypes.CDLL`s a danos
+   `.so` and round-trips a call; a `.so` extension module imports.
+3. **D3 — actual sharing (the kernel milestone).** Shared read-only file-backed
+   mappings — a page-cache-shaped facility so N processes mapping `libpython`
+   hold one physical copy. This is the memory-win milestone and the only one
+   touching the kernel; design it with the existing shm machinery in view
+   (the shared-fate walks already locked the relevant paths). *Test:* N Python
+   services up; measure physical pages against N× the static baseline.
+4. **D4 — dynamically-linked executables** (optional, evaluate after D3):
+   `PT_INTERP`, a danos program interpreter, and the spawn path teaching the
+   loader about it. Only worth it if the image-size or update story demands it.
+
+## Risks and gotchas
+
+- **Scope creep is the failure mode.** Every dynamic linker grows toward glibc.
+  The fences: bind-now only, no lazy binding ever, no TLS until pthreads demand
+  it, no dlopen-from-memory, no versioned symbols. Each fence removed is a
+  design discussion, not a patch.
+- **Code loading is a security event.** `dlopen` turns file bytes into executable
+  code, so W^X discipline is table stakes and *what may be dlopened* is a
+  capability question — the natural danos answer is that loadability follows VFS
+  readability of the `.so`, and services' images are supervised like any other
+  artifact. Revisit explicitly at D3 when mappings become shared.
+- **`dlclose` is where loaders go to die.** Constructors/destructors,
+  dangling function pointers, re-open identity. Keep v1 semantics honest and
+  simple: `dlclose` runs destructors and unmaps; holding pointers past it is
+  undefined; no reference-counted deferral cleverness.
+- **The ReleaseSafe fact still applies to `.so`s** — a ReleaseSafe shared object
+  carries its inlined checks like any static code; D3's sharing saves *copies*,
+  not check overhead. Size expectations should be set accordingly.
+
+## Decisions needing sign-off
+
+- Dynamic libraries join the roadmap at all (this note exists because the
+  earlier size-motivated rejection was re-opened for ABI/sharing reasons).
+- **Bind-now only; no lazy binding, permanently.**
+- **Loader in userspace libc; kernel involvement only at D3** (shared read-only
+  mappings).
+- **Static executables until D4**, and D4 only on demonstrated need.
+
+## Related
+
+- [c-library-compatibility.md](c-library-compatibility.md) — the sysroot the
+  loader ships in; its absence table gains `dlfcn.h` at D1.
+- [python-on-danos.md](python-on-danos.md) — the `ctypes` story this unlocks.
+- [python-on-danos-milestones.md](python-on-danos-milestones.md) — sequencing;
+  this work is post-P5.
+- [os-development/memory-map.md](os-development/memory-map.md) /
+  [os-development/paging.md](os-development/paging.md) — where W^X and shared
+  mappings land.

docs/file-system-development/danos-file-system-hierarchy-FSH.md

@@ -1,128 +0,0 @@
-# DanOS Filesystem Hierarchy Standard (DFHS)
-
-Most modern Unix and Unix-like operating systems follow the FHS. DanOS has its own FHS structure which extends the unix FHS. Root path resolution is provided by the kernel-resident VFS root (`fs_resolve`, `system/kernel/vfs.zig`); mounted filesystem servers serve the subtrees they own.
-
-## Directory structure
-
-| Path             | Description                                                                                                                                                         |
-|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| /                | Primary hierarchy root and root directory of the entire file system hierarchy.                                                                                      |
-| /bin             | Essential command binaries that need to be available in single-user mode, including to bring up the system or repair it, for all users (e.g., cat, ls, cp).         |
-| /boot            | Boot loader files (e.g., EFI, initial-ramdisk.img ).                                                                                                                |
-| /dev             | POSIX Device files (e.g., /dev/null, /dev/disk0, /dev/tty, /dev/random).                                                                                            |
-| /etc             | Host-specific system-wide configuration files.                                                                                                                      |
-| /home            | Users' home directories, containing saved files, personal settings, etc.                                                                                            |
-| /lib             | Libraries essential for the binaries in /bin and /sbin. eg realtime, system, ipc etc.                                                                               |
-| /sbin            | Essential system binaries (e.g init)                                                                                                                                |
-| /srv             | Site-specific data served by this system, such as data and scripts for web servers, data offered by FTP servers, and repositories for version control systems       |
-| /system          | DanOS operating system files (similar idea to C:\Windows). A true representation of danos — its layout mirrors the source tree, so `/system` is what danos *is*.    |
-| /system/devices  | danos virtual device tree e.g. similar to /sys on linux but with danos device tree conventions (the structures in the devices module)                               |
-| /system/drivers  | driver binaries, one sub-project each (e.g. /system/drivers/pci-bus, /system/drivers/ps2-bus)                                                                       |
-| /system/services | system-service binaries — init, the FAT server, and other user-mode servers (e.g. /system/services/init, /system/services/fat)                                      |
-| /system/kernel   | the kernel image                                                                                                                                                    |
-| /test            | Test fixtures for the QEMU integration suite. Read-only and initrd-backed like /system, and its layout likewise mirrors the source tree (the repo's test/ directory). Present on development and test images; a volume without it still boots. |
-| /test/system/services | test-fixture binaries (e.g. /test/system/services/vfs-test, /test/system/services/thread-test) — the same path in the repo source tree and on the boot volume  |
-| /tmp             | Directory for temporary files (see also /var/tmp). Often not preserved between system reboots and may be severely size-restricted.                                  |
-| /usr             | Secondary hierarchy for read-only user data; contains the majority of (multi-)user utilities and applications. Should be shareable and read-only.                   |
-| /var             | Variable files: files whose content is expected to continually change during normal operation of the system, such as logs, spool files, and temporary e-mail files. |
-
-## File types
-
-POSIX specifies the long format of the ls command to represent the Unix file type as the first letter for an entry.
-
-| type              | symbol | Description                                                                                                                                                           |
-|-------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| regular           | -      | An ordinary file holding an uninterpreted byte stream. Reads and writes are positional, and the file grows on demand (e.g., a binary in /bin, a config file in /etc). |
-| directory         | d      | A container mapping names to other files. It may only be modified through directory operations, never written to directly.                                            |
-| symbolic link     | l      | A file whose contents are a path that is resolved in its place. The target need not exist, and may cross mount points.                                                |
-| FIFO special      | p      | A named pipe: an in-order byte stream between processes, where writers block until a reader opens the other end.                                                      |
-| block special     | b      | A device node addressed in fixed-size blocks with the kernel free to buffer and reorder access (e.g., /dev/disk0).                                                    |
-| character special | c      | A device node addressed as an unbuffered byte stream, delivered to the driver in order (e.g., /dev/tty, /dev/null).                                                   |
-| socket            | s      | A named endpoint for bidirectional message-passing between processes, bound to a path rather than an address.                                                         |
-
-## /dev
-
-`/dev` holds the names through which processes reach devices. It is deliberately not
-the device tree: the tree — every node discovered by ACPI or PCI enumeration, with its
-resources and its parent — lives under [/system/devices](#directory-structure) and is
-addressed by device id. `/dev` is the much smaller set of devices that have a driver
-willing to serve them, addressed by name.
-
-A device node is not a file the VFS can read. The bytes live in a driver process
-([drivers.md](../device-driver-development/drivers.md)), so opening a `/dev` name has to resolve to that driver's
-IPC endpoint, and subsequent reads and writes are calls against it. Resolve-to-endpoint
-is exactly what the kernel's `fs_resolve` already does for any mounted backend, and
-`FileStatus.kind` is the field that marks a device node; **what is not implemented today
-is `/dev` itself** — no service mounts it. (The flat eight-node ramfs this section once
-described is retired: the kernel-resident VFS root in `system/kernel/vfs.zig` serves a
-read-only initrd mount per top-level tree — `/system`, and `/test` on images that carry
-the fixtures — with real directories and node kinds, and filesystem
-backends such as the FAT server mount the rest.) The three sections below describe the
-intended shape, and are honest about which parts the kernel can already support.
-
-### Character devices
-
-A character device is a byte stream with no addressable position: bytes are delivered
-to the driver in the order written, and a read consumes what is there. Terminals,
-serial lines, keyboards and mice are all of this shape. These are the natural first
-device nodes in danos, because a character driver needs nothing the kernel doesn't
-already provide — it claims its device, maps its registers with `mmio_map`, and blocks
-on `replyWait` for either an interrupt or a client request. `system/drivers/ps2-bus/ps2-bus.zig`
-is already that program, minus the file-node client half.
-
-The obstacle was never the file type; it is which hardware a ring-3 driver can reach.
-Direct `in`/`out` from user space is still a #GP (no TSS I/O bitmap, IOPL never raised),
-but a driver no longer needs it: **`io_read`/`io_write`** grant port access the same way
-`mmio_map` grants memory — gated by `device_claim` and the device's discovered `io_port`
-resource. So the 16550 UART at `0x3F8` and the PS/2 controller at `0x60`/`0x64` (and thus
-`/dev/ttyS0` and a keyboard node) are now writable as ordinary ring-3 drivers; the
-low-rate legacy hardware that needs port I/O is fine with a syscall per access. A
-memory-mapped device such as the framebuffer, needing no port I/O at all, remains the
-easiest first entry.
-
-### Block devices
-
-A block device is addressed in fixed-size blocks and, unlike a character device, the
-layer above is free to buffer, reorder, coalesce and retry requests against it. Disks
-and other persistent storage are the whole population of this class.
-
-A block driver is now **writable, but not yet memory-safe.** Every storage controller
-worth naming is a bus master: it is programmed by handing it the physical address of a
-descriptor ring and left to read and write memory on its own. That ring is exactly what
-**`dma_alloc`** now provides — physically contiguous, pinned, uncacheable, with its
-physical address disclosed — and **`/lib/device/mmio`**'s barriers order the descriptor writes
-against the doorbell, and **`msi_bind`** delivers completions. So an AHCI or NVMe driver
-can be written today (the M14/M15 work in [driver-model.md](../device-driver-development/driver-model.md); the earlier
-"cannot host a block driver at all" is no longer true).
-
-What is *not* yet true is that it is safe. A device programmed with an arbitrary physical
-address writes to arbitrary physical memory, and page tables do not sit between a device
-and RAM — an IOMMU does. The IOMMU is now *detected* (M16), but no translation domains
-are programmed, so granting a DMA-capable device to a driver process is still equivalent
-to granting ring 0. Until per-device domains confine a driver's DMA to the buffers it
-`dma_alloc`'d, a block driver works but forfeits the isolation that motivates user-space
-drivers — enforcement is the next step, and lands with that first driver. A ramdisk over
-the initial ramdisk remains the one block-shaped thing that needs no driver process at all.
-
-### Pseudo-devices
-
-A pseudo-device has the interface of a device and no hardware behind it: `/dev/null`
-discarding writes and reading as end-of-file, `/dev/zero` reading as an endless run of
-zero bytes, `/dev/full` failing writes with `ENOSPC`, `/dev/random` and `/dev/urandom`
-yielding unpredictable bytes.
-
-These are the only `/dev` entries danos can implement immediately, and they are the
-sensible place to start, because they are exactly the entries that need no driver
-process, no `device_claim`, no MMIO grant and no interrupt. A future pseudo-device
-service would answer them out of its own address space — `null` and `zero` are a few
-lines each in its `read` and `write` handlers — and mount itself at `/dev` the way the
-FAT server mounts `/mnt/usb`. The two pieces of structure every later device node
-depends on (and that the flat ramfs of the time lacked) exist now: directories, so that
-`/dev/null` is a path rather than a name; and a populated `FileStatus.kind`, so that a
-caller can tell a character device from a regular file.
-
-`/dev/random` is the one that is not free. It needs an entropy source, and the honest
-options on this kernel are `RDRAND`/`RDSEED` where CPUID advertises them, and the HPET
-counter's low bits as a poor fallback. Neither is a seeded CSPRNG, and a `/dev/random`
-that is merely unpredictable-looking is worse than none — nothing should be keyed from
-it until it is a real one.

docs/file-system-development/file-system-hierarchy.md

@@ -0,0 +1,90 @@
+# The danos file-system hierarchy
+
+danos is not unix, and its tree does not follow the unix FHS. Paths are the
+system's universal namespace — files, the device inventory, and protocol
+endpoints all live in one tree — but what a path *yields* differs by subtree:
+bytes, facts, or a connection. Root path resolution is provided by the
+kernel-resident VFS root (`fs_resolve`, `system/kernel/vfs.zig`); mounted
+backends serve the subtrees they own.
+
+Naming follows the codebase conventions: kebab-case, full words, no
+abbreviations. Every top-level name says what its subtree *is*.
+
+## The tree
+
+| Path                    | What it is                                                                                                                                              |
+|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `/`                     | The root of the one namespace.                                                                                                                          |
+| `/applications`         | Installed applications, one directory per application — the directory is the identity, the same rule as source sub-projects. *(Planned; empty today.)*  |
+| `/protocol`             | The contract namespace: one protocol node per contract, grouped into directories by domain (`/protocol/display`, `/protocol/networking/ip`). Synthetic — no bytes; opening a name yields a connection to the current provider. See [protocol-namespace.md](../os-development/protocol-namespace.md). |
+| `/system`               | The operating system — what danos *is*. Its program subtrees mirror the source tree exactly.                                                            |
+| `/system/kernel`        | The kernel image.                                                                                                                                       |
+| `/system/drivers`       | Driver binaries, one per sub-project (`/system/drivers/pci-bus`, `/system/drivers/ps2-bus`).                                                            |
+| `/system/services`      | System-service binaries (`/system/services/init`, `/system/services/fat`).                                                                              |
+| `/system/devices`       | The device inventory: every node hardware discovery found, with its resources and parent — the structures of the devices module, as a browsable virtual tree. Informational only; you *read about* hardware here and *talk to* it through `/protocol`. *(Planned; served by device-manager.)* |
+| `/system/configuration` | Machine configuration (`init.csv`, `devices.csv`). Writable, served from the boot volume.                                                               |
+| `/system/logs`          | Per-boot logs: `/system/logs/<boot-stamp>/<binary-path>.log`. Writable, served from the boot volume.                                                    |
+| `/test`                 | Test fixtures for the QEMU integration suite. Read-only and initrd-backed like the program subtrees of `/system`, mirroring the repo's `test/` directory. Present on development and test images; a volume without it still boots. |
+| `/volumes`              | Attached storage volumes, one directory per volume (`/volumes/usb`). A volume's own tree appears beneath its name.                                      |
+
+Read-only and writable halves of `/system`: the program subtrees (`kernel`,
+`drivers`, `services`) and the future `devices` are immutable at runtime —
+initrd-backed or synthetic — while `configuration` and `logs` are mutable
+machine state served by the boot-volume FAT backend. The kernel's
+reserved-prefix rule (no mount may shadow `/system`, `/test`, or `/protocol`)
+needs a carve-out for exactly these two writable subtrees; that lands with the
+path migration below.
+
+Deliberately not defined yet: a temporary-files location and per-application
+mutable storage. Both belong to the `/applications` design and will be
+specified there, not guessed at here.
+
+## Node kinds
+
+What a path resolves to. These fill `FileStatus.kind` and
+`DirectoryEntry.kind` in the [vfs protocol](vfs-protocol.md)
+(`library/protocol/vfs/vfs-protocol.zig`); enum values are append-only.
+
+| Kind               | Meaning                                                                                                                                        |
+|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
+| `regular`          | An ordinary file: an uninterpreted byte stream, positional reads and writes, grows on demand.                                                   |
+| `directory`        | A container mapping names to nodes; modified only through directory operations.                                                                 |
+| `character_device` | A node whose read/write have **stream semantics**: unseekable, reads block until bytes exist, size is meaningless. The console and every tty-shaped node ([character-devices-and-tty.md](../character-devices-and-tty.md)); what a POSIX layer's `isatty` detects. |
+| `block_device`     | A node addressed in fixed-size sectors — a raw volume. Reserved: recognized, nothing serves one yet.                                            |
+| `symbolic_link`    | Reserved: a recognized value, not implemented by any backend.                                                                                   |
+| `fifo`             | Reserved for the future pipe object (wanted by the POSIX compatibility layer); not implemented.                                                 |
+| `protocol`         | A node naming a contract: `open` yields an IPC connection (an endpoint capability) instead of a file id — the kind of every leaf under `/protocol`. *(Being added; see protocol-namespace.md.)* |
+
+Note the layering: `protocol` says what *opening the name* does (you get a
+conversation); `character_device`/`block_device` say what *read and write
+mean* on a node a provider serves you. The two compose — `/protocol/console`
+is a protocol node in the registry, and the node opened over that connection
+reports `character_device`, which is what gives it stream semantics. Only
+`socket` is retired (its value stays reserved for wire stability): a named
+rendezvous point is exactly what a protocol node is.
+
+## What is deliberately absent
+
+There is no `/bin`, `/boot`, `/dev`, `/etc`, `/home`, `/lib`, `/mnt`, `/sbin`,
+`/srv`, `/tmp`, `/usr`, or `/var`. These encode unix history — the
+binary/library split of small disks, configuration-as-scattered-text, devices
+as magic files — that danos does not carry. A POSIX compatibility layer (the
+Python track's mini-libc) may *present* whichever of these its programs
+expect, mapped onto the real tree; the tree itself stays danos-native.
+
+## Migration
+
+The tree above is the specification; some code still writes the unix paths it
+replaced. The flag-day converting them:
+
+| Today (in code)                          | Becomes                                   | Where                                                          |
+|------------------------------------------|-------------------------------------------|-----------------------------------------------------------------|
+| `/etc/init.csv`                          | `/system/configuration/init.csv`          | `system/services/init/init.zig`                                |
+| `/etc/devices.csv`                       | `/system/configuration/devices.csv`       | `system/services/device-manager/device-manager.zig`            |
+| `/var/log/...`                           | `/system/logs/...`                        | `system/services/logger/logger.zig`, the FAT server's `/var` mount |
+| `/mnt/usb`                               | `/volumes/usb`                            | `system/services/fat/fat.zig`, the fat/vfs tests               |
+| `ServiceId` lookup                       | resolve + open under `/protocol`          | every service and client; [protocol-namespace.md](../os-development/protocol-namespace.md) |
+
+The boot-image builder and the on-volume directory layout move in the same
+change, so a freshly written image and the paths the services expect never
+disagree.

docs/file-system-development/vfs-protocol.md

@@ -149,8 +149,8 @@ Bitwise OR in `Request.flags`, meaningful for `open` only:
 
 ## NodeKind
 
-Aligned to the FSH file-type table
-(docs/danos-file-system-hierarchy-FSH.md):
+Aligned to the node-kind table in the file-system hierarchy
+(docs/file-system-development/file-system-hierarchy.md):
 
 | value | kind |
 |------:|------|
@@ -163,7 +163,12 @@ Aligned to the FSH file-type table
 | 6 | socket |
 
 Clients should map unknown values to *regular* rather than reject — the
-table can grow.
+table can grow. Kind 6 (`socket`) keeps its wire value but is retired from
+the design — a named rendezvous point is exactly what a `protocol` node is,
+planned as value 7 with the protocol namespace
+(docs/os-development/protocol-namespace.md). `character_device` (stream
+semantics — the tty/console shape) and `block_device` (raw sector-addressed
+volumes, reserved) remain part of the design.
 
 ## Lifetimes and trust
 

docs/os-development/communication.md

@@ -0,0 +1,120 @@
+# Communication: the four layers
+
+*Design, agreed 2026-07-31. The model document — the vocabulary and layering
+every other communication document speaks.*
+
+danos separates **what is said** from **how the bytes move**, so that the
+mechanism is replaceable. The shape is a network stack's, cut into four
+layers; a program only ever touches the top two.
+
+```
+L3  namespace   /protocol/... names establishment points          protocol-namespace.md
+L2  protocol    the language: packet schemas, verbs, targets      the envelope, library/protocol/*
+L1  channel     two ends exchanging packets and signals           the client library's Channel
+L0  transport   a buffer + a doorbell: moves the bytes            ipc.md (kernel-ipc), later shm-ring, …
+```
+
+## Vocabulary
+
+| Term | Meaning |
+|---|---|
+| **protocol** | The language: which packets exist, what their fields mean, which verbs a provider answers. Defined transport-independently in a `library/protocol/*` module. |
+| **channel** | An open conversation between two processes, speaking one protocol. Established by opening a `/protocol/...` name; both ends can send and receive. |
+| **packet** | The unit a protocol transmits: a bounded, atomic header+payload. Never fragmented — if it doesn't fit, it isn't a packet; bulk data rides shared memory with a packet as the doorbell. |
+| **signal** | A payload-less poke below the packet layer: "something happened, come look." Coalescing — the count may collapse, the fact may not. |
+| **transport** | What moves the bytes of one channel: a buffer plus a doorbell. Chosen (and upgradable) at establishment, invisible above L1. |
+| **endpoint** | A termination point where a transport delivers. The kernel-ipc transport's endpoint is its kernel mailbox object. |
+
+## Addressing: parties by channel, objects by target
+
+There are no network-style addresses in a packet. The two questions addresses
+answer are answered at different layers:
+
+- **Who am I talking to?** The **channel**, decided once at establishment.
+  Opening `/protocol/input` yields a channel; every packet sent on it goes to
+  the peer. Nothing to route per-packet — like TCP, where no HTTP request
+  carries the server's IP.
+- **Who sent this?** Attached to every received packet **by the channel
+  layer**, from identity the transport can verify — under kernel-ipc, the
+  kernel-stamped badge. The sender never writes a source field, which is what
+  makes source unforgeable (the property a network's spoofable source header
+  lacks).
+- **Which of your things?** The packet's **`target`** field: *object*
+  addressing within the already-chosen peer — the vfs protocol's node id, the
+  display protocol's layer id, a block volume. `target = 0` addresses the
+  provider itself; a protocol without objects never uses it.
+
+`target` is how instance multiplicity stays out of the namespace. Ten USB
+sticks and the namespace still holds exactly one name, `/protocol/block`: a
+channel to the provider, `enumerate` lists the current volumes as targets, a
+`targets_changed` signal announces hotplug, and a read names its volume in
+`target`. The unix `/dev/sda`,`/dev/sdb` problem is dissolved, not renamed.
+
+If a future transport genuinely routes between machines, *it* carries real
+source/destination addressing internally at L0 — the way IP runs under TCP —
+and none of it surfaces into the packet header. Protocols stay ignorant of
+distance.
+
+## The transport (L0): a buffer and a doorbell
+
+Strip any transport to its skeleton and the same two parts remain:
+
+| Transport | Buffer | Doorbell | Status |
+|---|---|---|---|
+| **kernel-ipc** | kernel-owned mailbox (the `Endpoint`) | the scheduler (rendezvous wake) | the first transport — [ipc.md](../device-driver-development/ipc.md) |
+| **shm-ring** | user-owned shared-memory ring | a signal | exists ad hoc (display bulk); to be formalized — the unlock for the 256-byte ceiling |
+| network | NIC queue | an interrupt | someday, when danos networks |
+
+Transports differ in their **properties**, which the channel layer exposes and
+the protocol layer may depend on:
+
+- **packet ceiling** — kernel-ipc: 256 bytes request/reply, 64 pushed. An
+  shm-ring's ceiling is its slot size. Kernel-ipc's 256 is the *floor* every
+  protocol may assume everywhere.
+- **synchrony** — kernel-ipc's call is a rendezvous: natural backpressure, no
+  queue to size. An asynchronous transport buffers, so a channel over one
+  needs explicit flow control. Backpressure is a *transport property*, not a
+  channel guarantee — protocols that rely on it say so.
+- **droppability** — pushed event packets may drop when a ring fills;
+  request/reply may not.
+- **capability carriage** — **only kernel-ipc can move a capability.**
+  Handles are kernel objects; a user-space ring cannot transfer one. So
+  kernel-ipc is always the *establishment and control* transport — channels
+  are born on it, capabilities ride it — even when a channel's data is
+  negotiated onto something fatter.
+
+That negotiation is the upgrade path: a channel starts on kernel-ipc; the
+protocol's handshake may then delegate a shared-memory region (as a
+capability, over kernel-ipc) and move its bulk traffic there. The display
+path already does exactly this by hand; formalizing it in the channel layer
+makes it every protocol's option.
+
+## The channel (L1)
+
+A channel has two ends, and **the ends are peers**: each may send packets,
+each may receive, each may signal. Request/reply is a *pattern* over the
+channel — a send with a correlated receive, which the kernel-ipc transport
+happens to accelerate as a single rendezvous — not the definition of it. The
+event stream (subscribe, then pushes) and the change signal (poke, then
+re-read) are the other two patterns; all three are catalogued in
+[protocol-namespace.md](protocol-namespace.md)'s wiring section.
+
+The channel layer's obligations: deliver packets whole, attach the verified
+source to every receive, expose the transport's properties, and hide the
+transport's mechanics. The client library's `Channel` type is this layer made
+concrete — a program holds channels that speak protocols and never touches a
+raw handle.
+
+## The protocol (L2) and the namespace (L3)
+
+A protocol defines its packets through the envelope — every packet begins
+`{operation, target}`, reserved verbs (`describe`, `enumerate`, `subscribe`,
+`unsubscribe`) mean the same thing in every protocol, and `Define` checks
+every packet against the transport floor at compile time. The full treatment,
+including how names are granted, resolved, and restricted per process, is
+[protocol-namespace.md](protocol-namespace.md).
+
+Establishment points are named by contract — `/protocol/display`, never
+`/protocol/ipc-1` — because the name must outlive the mechanism: a
+transport named in the namespace could never be swapped, which would defeat
+this document's premise.

docs/os-development/efi.md

@@ -24,8 +24,9 @@ EFI/BOOT/BOOTX64.efi         <- the "removable media" default for x86-64
 ```
 
 The boot volume is **FHS-shaped** (see the repository-layout note in
-[README.md](../README.md)): `build.zig` installs `boot/efi.zig` (built for the `uefi`
-target) at `EFI/BOOT/BOOTX64.efi` — the one path UEFI firmware fixes — and lays
+[README.md](../README.md)): the root `build.zig` compiles `boot/efi.zig` (built
+for the `uefi` target) and `build/images.zig` places it at
+`EFI/BOOT/BOOTX64.efi` — the one path UEFI firmware fixes — and lays
 the rest out by FHS path: the kernel at `system/kernel`, init at
 `system/services/init`, the pre-packed boot capsule at `boot/system.img`
 ([system-image.md](system-image.md)).

docs/os-development/protocol-namespace.md

@@ -0,0 +1,472 @@
+# The protocol namespace
+
+*Design, agreed 2026-07-31. Supersedes the `ServiceId` registry. Not yet implemented —
+the migration plan at the end is the work list.*
+
+How a program finds, connects to, and is restricted from the things it talks to.
+Three ideas, kept deliberately separate:
+
+1. **Naming** — a path under `/protocol` names a *contract*, not a service.
+2. **Access** — resolving that path yields an endpoint *capability*; what a process
+   cannot resolve, it cannot reach.
+3. **Transport** — unchanged: packets over channels, moved by whichever
+   transport the channel rides (kernel-ipc first).
+   This document is layers **L3** (the namespace) and **L2** (the protocol
+   and its envelope) of the communication stack;
+   [communication.md](communication.md) owns the model and the vocabulary
+   (*protocol* the language, *channel* the conversation, *packet* the
+   transmitted unit, *signal* the payload-less poke, *transport* the
+   replaceable mechanism), and
+   [ipc.md](../device-driver-development/ipc.md) is the first transport.
+
+## Why ServiceId has to go
+
+Today a service calls `ipc_register(service_id, endpoint)` and a client calls
+`ipc_lookup(service_id)`, where `ServiceId` is a compile-time enum in `abi.zig`
+backed by a flat 16-slot table in the kernel. Three defects, in rising order:
+
+- **Static.** The id space is baked into the ABI at compile time. A third-party
+  program can never introduce a service; the one place danos is *less* dynamic
+  than its own design.
+- **Ungated.** `ipc_register` is callable by any process and *replaces* an
+  existing registration. Any process can hijack `.fat` or `.display` and
+  impersonate it. `ipc_lookup` is equally ambient.
+- **Unrestrictable.** Because lookup is a syscall available to everyone, there is
+  no point at which "this process may not talk to the display" can be enforced.
+  Any future file-access restriction would be bypassable by speaking to the FAT
+  server directly.
+
+## Naming: contracts, not services
+
+`/protocol/<name>` names a protocol — the contract a conversation follows — and
+resolving it connects you to whatever process currently provides that contract.
+The client never cared *which* binary answers; it cares that its messages are
+understood. Naming the contract makes that explicit, and buys:
+
+- **Swappable providers.** Replace the display server; `/protocol/display`
+  routes to the new one; clients notice nothing.
+- **Test fakes.** Spawn a program whose namespace wires `/protocol/display` to a
+  mock. The name promises the protocol; the mock speaks it.
+- **One vocabulary.** The names mirror `library/protocol/`: a program imports
+  the `display-protocol` module, then opens `/protocol/display`. What you
+  compiled against and what you ask the namespace for are the same word.
+
+A leaf names one contract — kebab-case, full words, matching the
+`library/protocol/` module that defines its wire format — and related
+contracts group into directories: `/protocol/networking/ip`,
+`/protocol/networking/bluetooth`. Directories organize *contracts only*;
+they never encode addressing (see below), so a directory appears because a
+domain has several contracts, never because hardware multiplied. The module
+tree mirrors the namespace (`library/protocol/networking/ip` ↔
+`/protocol/networking/ip`), and registrar grants scope naturally to subtrees
+— an application installed at `/applications/foo` can be granted
+`/protocol/applications/foo/...` and nothing above it. `/protocol` is
+top level, beside `/system` and `/applications`, because the boundary it names
+is spoken on both sides: applications talk to protocols as much as the OS does
+(see [file-system-hierarchy.md](../file-system-development/file-system-hierarchy.md)).
+
+**Addressing lives inside the protocol, never in the path.** Which volume, which
+layer, which input device — that is a destination field in the messages, the way
+TCP carries a destination address, and the way danos protocols already work (the
+display protocol multiplexes layer ids; the vfs protocol addresses node ids).
+The namespace answers exactly one question — *may this process speak this
+protocol at all* — so `/protocol/block` is one name no matter how many disks are
+attached. The source address is never in the message either: it is the IPC
+badge, stamped by the kernel per message, unforgeable — a property TCP's source
+address does not have.
+
+`/system/devices` (the device inventory) stays purely informational: facts for
+diagnosis, never a routing mechanism. Unix conflated the two in `/dev`; danos
+does not. You *read about* hardware in `/system/devices`; you *talk to* it
+through `/protocol`.
+
+## Resolution: a protocol node in the VFS
+
+The kernel VFS router already does the hard part: `fs_resolve` matches a mount
+prefix and installs the backend's endpoint capability in the caller's handle
+table. The registry is just a backend mounted at `/protocol` — ring 3, like FAT.
+Connecting is a normal vfs-protocol `open` with one twist in the reply:
+
+```
+client                      kernel router                registry backend
+  │ fs_resolve("/protocol/display")                             │
+  │──────────────────────────▶│ prefix match: /protocol         │
+  │◀── registry endpoint ─────│ (capability installed)          │
+  │ vfs open("display") ──────────────────────────────────────▶│
+  │◀───────────────── Reply + capability = provider endpoint ──│
+  │ ipc_call(provider, display-protocol messages...)            │
+```
+
+Both capability moves use machinery the kernel already has: request-direction
+and reply-direction `send_cap` on `call`/`replyWait`. The vfs protocol needs two
+additions, both append-only:
+
+- `NodeKind.protocol` — a node that names a contract; its `open` establishes
+  a **channel** (delivered as an endpoint capability) instead of returning a
+  file id. The node is the protocol, the channel is the conversation, and the
+  addressing inside the packets decides where within the provider each one
+  lands. `readdir` over `/protocol` lists protocol nodes like any others, so
+  the tree stays browsable for diagnosis.
+- The convention that an `open` reply may carry a capability. File backends
+  (FAT) never use it; synthetic backends (the registry, later the device
+  inventory) do.
+
+The path lookup happens once, at connect time. The hot path — `ipc_call` on the
+cached endpoint — is untouched. A provider crash turns the cached endpoint dead
+(`-EPEER`), and the client's recovery is to re-resolve: the restart story falls
+out of the naming layer for free.
+
+## Registration: the registrar, held by init
+
+The registry backend is **init**. It is already PID 1, already spawns every
+service from its manifest, and already holds the supervision link to each — it
+is the process that *knows* which binary is which. (If init grows
+uncomfortable, the same design lifts into a dedicated registry service that
+init spawns first and delegates to; nothing below changes.)
+
+- **Binding.** A service creates its endpoint and sends the registry a `bind`
+  request with the protocol name as payload and the endpoint attached as the
+  call's capability.
+- **Authorization.** Init's manifest gains a column: the protocols each spawned
+  binary may bind. A `bind` from any process not granted that name is refused
+  (`-EPERM`) — the badge identifies the caller, the supervision records map
+  badge to binary. This is the registrar authority; it never leaves init.
+- **Collision is an error.** A name already bound refuses a second bind — never
+  last-writer-wins. When a provider dies, init (its supervisor) unbinds its
+  names; the restarted instance binds again.
+- **Provenance.** The registry records name → task id → binary path, so a
+  diagnostic listing answers "who serves this?" at a glance:
+
+  ```
+  /protocol/display   pid 12   /system/services/display
+  /protocol/input     pid 7    /system/services/input
+  ```
+
+`ipc_register` and `ipc_lookup` retire; the `ServiceId` enum leaves `abi.zig`.
+The kernel keeps one residual rule: `/protocol` becomes a reserved prefix like
+`/system` — `fs_mount` refuses to shadow it, and init's boot-time mount is the
+only one it will ever hold. (Full gating of `fs_mount` is a separate item on
+the security track; the reserved prefix closes the hole for this namespace
+without waiting for it.)
+
+## Restriction: per-process namespaces, not ACLs
+
+danos has no users and no principals, deliberately. Restriction is therefore
+**delegation**: what a process may open is decided by whoever spawned it, and
+enforcement is absence — a protocol you cannot resolve does not exist for you.
+"Permission denied" and "not found" are the same answer, which is the same
+discipline the device layer already follows: the claim is the capability; here,
+the resolvable name is the capability.
+
+Two stages, deliberately ordered so the useful half lands first:
+
+**Stage one — the registry filters by badge.** Init is both the spawner and the
+registry, so its manifest already knows which binary may *open* which protocols
+(a second manifest column, beside the bind grants). An `open` from a process
+whose binary is not granted that protocol is refused. No new kernel mechanism
+at all; the display driver's view can be narrowed to nothing, a future
+downloaded application's to `display` and `input`, today.
+
+**Stage two — spawn passes the namespace.** `spawn` gains an initial
+capability: the child's connection to *its* registry view, chosen by the
+spawner. A newly spawned process starts with an empty handle table and this one
+handle — its world is whatever its parent wired in. This removes the last
+ambient reach (`fs_resolve` finding `/protocol` globally), lets any supervisor
+— not just init — narrow or fake a child's view (an application launcher
+granting an app only what its manifest declares; a test harness substituting
+every provider), and composes down the supervision tree. Stage one's manifest
+column becomes the *content* of the view init builds, so nothing is thrown
+away.
+
+### A worked example: the microphone prompt
+
+The scenario stage two exists for: an application opens
+`/protocol/audio-input`, and the user should be asked. The supervisor is an
+ordinary user process — an application launcher — and the flow needs no new
+security concepts:
+
+1. The launcher spawned the app with a namespace channel that terminates at
+   **the launcher itself**. The app's whole world is a conversation with its
+   supervisor.
+2. The app's `open("audio-input")` packet lands in the launcher,
+   badge-stamped. The launcher spawned the app, so badge → binary path
+   (`/applications/foo`) is its own supervision record — "remember my choice"
+   needs no identity system.
+3. Grant unknown → the launcher parks the request and shows a prompt (it is a
+   user process with display access; init never does UI). Blocking an open on
+   a human is architecturally fine: opens are connect-time, never hot-path.
+4. **Yes** → the launcher opens `/protocol/audio-input` in *its own*
+   namespace and attaches the resulting channel to the parked reply. The app
+   cannot tell a prompt happened — a consented open is indistinguishable from
+   a direct one, merely slower.
+5. **No** → refuse the open, indistinguishable from "no such protocol" — or
+   hand the app a **fake**: a silence-generating provider. The test-fake
+   mechanism doubles as a privacy feature.
+
+The capability discipline holds throughout: the launcher can only grant what
+it holds — if init never gave the launcher `audio-input`, no prompt can
+conjure it. Consent is delegation flowing down the supervision tree, never a
+global ACL edit. And the provider still sees the app's badge on every packet,
+so a coarser second check at the audio service remains possible.
+
+Two mechanical requirements this scenario pins on stage two:
+
+- **Parked replies.** A prompt takes seconds, and the service loop holds one
+  outstanding reply today — the launcher must park request A, keep serving B
+  and C, and reply to A later (by badge). The kernel already tracks owed
+  replies (that is how death delivers `-EPEER`); multiple parked replies is
+  the extension, in the harness and, if needed, the kernel.
+- **Granted channels are dedicated, hence revocable.** Once the app holds a
+  channel capability, nobody reaches into its handle table — so a
+  prompt-granted channel must be one that can be *killed*: a dedicated
+  endpoint pair (or per-client session at the provider) whose death turns
+  the app's capability into `-EPEER`. Revoking microphone access is then
+  killing that channel, using machinery that already exists.
+
+One adjacent problem, named and deferred: **trusted UI**. The prompt is only
+meaningful if the app cannot draw a convincing fake or overlay the real one —
+a display-layer question (a reserved surface for the supervisor chain), owned
+by the display track, not this one.
+
+Fine-grained restriction *within* a protocol (this process may use volume A but
+not volume B) is not the namespace's job. The capability-shaped answer, when it
+is needed: the supervisor pre-opens a connection scoped to one target and passes
+that connection to the child, which never opens `/protocol/block` at all.
+Delegation again, not ACLs.
+
+## The envelope: one addressing scheme for every protocol
+
+Every protocol module today hand-rolls its `Request`/`Reply` with an
+`operation` first field. That convention becomes a library, so addressing is
+uniform and the rules are enforced by construction rather than by review. New
+module: **`library/protocol/envelope`** (the one protocol-layer module that is
+not itself a protocol).
+
+```zig
+/// Every packet a danos protocol transmits begins with this header.
+pub const Header = extern struct {
+    operation: u32, // the verb; values 0..15 are reserved universal verbs
+    _padding: u32 = 0,
+    /// Object addressing, never party addressing: which of the peer's
+    /// objects this packet operates on — a volume, layer, node, device.
+    /// 0 addresses the provider itself. Parties are addressed by the
+    /// channel; the protocol defines target's meaning; the field's place
+    /// and width are universal.
+    target: u64 = 0,
+};
+
+/// Reserved verbs, answered by every provider.
+pub const operation_describe: u32 = 0; // -> protocol name, version, target kinds
+pub const operation_enumerate: u32 = 1; // -> the current targets, one per reply page
+pub const operation_subscribe: u32 = 2; // capability = the subscriber's endpoint
+pub const operation_unsubscribe: u32 = 3;
+pub const first_protocol_operation: u32 = 16;
+
+/// Every reply begins with this.
+pub const Status = extern struct {
+    status: i32, // 0 or a negative errno
+    _padding: u32 = 0,
+    len: u32 = 0, // payload bytes following the header
+    _padding2: u32 = 0,
+};
+```
+
+A protocol is then *defined through* the envelope, not beside it:
+
+```zig
+pub const Protocol = envelope.Define(.{
+    .name = "display",
+    .version = 1,
+    .operations = &.{
+        .{ .name = "configure_layer", .request = ConfigureLayer, .reply = void },
+        .{ .name = "blit", .request = Blit, .reply = void },
+        ...
+    },
+});
+```
+
+`Define` is comptime and is where the enforcement lives:
+
+- verbs are numbered automatically from `first_protocol_operation`, so no
+  protocol can collide with the reserved range;
+- every packet is size-checked at compile time against the kernel-ipc floor
+  — `packet_maximum` (256) for request/reply, `post_maximum` (64) for event
+  packets. Ceilings are transport properties
+  ([communication.md](communication.md)); the floor is what every protocol
+  may assume on any transport. The errors that today surface as runtime
+  truncation become compile errors, and packets-never-fragment is enforced
+  at the source;
+- the generated type carries encode/decode helpers and a provider-side dispatch
+  table, so a provider answers `describe` automatically and unknown operations
+  with `-ENOSYS` uniformly;
+- the service harness (`library/kernel/service.zig`) accepts the generated
+  dispatch type, which is what makes the envelope *enforced*: a protocol that
+  bypasses `Define` does not plug into the harness.
+
+Universal conventions that ride on the reserved verbs:
+
+- **`describe`** is the version handshake. Version lives in the handshake, not
+  in every message — the 256-byte budget is too small to spend per call.
+- **`enumerate`** is how multi-target protocols expose their targets, and the
+  standard `targets_changed` notification (a notify bit) tells subscribers to
+  re-enumerate — arrival and removal of volumes, layers, devices all take the
+  same shape. Hotplug fits the notification ring far better than a filesystem
+  tree ever did.
+- **Source is the badge.** No protocol defines a "sender" field; the kernel's
+  per-message badge is the only source identity, and providers key per-client
+  state on it.
+
+### Paths resolve once; integers do the work
+
+A rule the envelope makes official: **a path appears in a conversation at most
+once — at resolve or open — and everything after it addresses integers.** The
+namespace resolves `/protocol/display` to an endpoint; a backend's `open`
+resolves a path payload to a node id; from then on every packet carries the
+integer in `target`. Integers compare in one instruction and fit the fixed
+header, and the 256-byte message budget never re-carries path strings on the
+hot path. This is already the system's shape — vfs node ids, display layer ids
+— and the envelope pins it as the required shape for every protocol.
+
+Two integer identities, not to be confused:
+
+- **An open handle** — what vfs `open` returns today: transient, meaningful
+  only within one client's session with one provider, swept when the client
+  exits. Cheap, and all a protocol usually needs. Handles must be **scoped per
+  client** — validated against the badge, or drawn from a per-client id
+  namespace. (Today the FAT server's node ids are guessable small integers
+  honoured across clients; that hole closes with this rule.)
+- **A persistent node identity** — a unix inode number, stable across opens
+  and renames. danos deliberately does not promise this, because FAT cannot
+  deliver it: a FAT file's identity is its directory entry, and rename or
+  truncation moves every candidate anchor. If a future filesystem or a cache
+  layer needs stable identity, that is the backend's promise to make, never
+  the protocol's assumption.
+
+The five existing protocol modules (`vfs`, `display`, `input`, `power`,
+`block`, plus `scanout`, `usb-transfer`, `device-manager`) rebase onto the
+envelope during the migration flag-day. `input-protocol`'s subscribe/publish
+split and `vfs-protocol`'s node addressing both map cleanly (`node` and layer
+ids become `target`).
+
+## Wiring: how conversations flow
+
+The patterns below are channel-layer (L1) shapes; the delivery mechanics are
+the kernel-ipc transport's, described here because it is the transport every
+channel starts on. Kernel-ipc provides exactly three delivery shapes, and
+every one is unicast. An endpoint is a mailbox owned by one process — its
+creator receives; anyone holding its capability sends into it. That direction
+never reverses:
+
+1. **Synchronous call** — request/reply. The kernel parks the caller and
+   `replyWait` delivers the reply straight back, so the provider answers
+   without holding any capability to the client. Badge-stamped, blocking, and
+   the *only* shape that carries capabilities (in the request, and in the
+   reply — which is how a reverse path is bootstrapped).
+2. **Asynchronous send** — an event packet pushed into the receiver's post
+   ring, at most `post_maximum` (64) bytes, no reply owed, never blocks the
+   sender. Strictly one-way: to be pushed to, you must first hand the pusher
+   your endpoint.
+3. **Signals** — payload-less notification bits, below the packet layer,
+   coalescing: "something changed, come look."
+
+A bidirectional link is therefore always **a pair of endpoints**, one per
+direction, each delivered by cap-passing. Three conversation patterns are
+built from these, and the envelope names all three:
+
+- **Request/response** — the synchronous call. The default, and the only
+  place capabilities move.
+- **Event stream** — `subscribe` (a synchronous call whose attached
+  capability is the subscriber's own endpoint), after which the provider
+  pushes events asynchronously; `unsubscribe` or subscriber exit ends it.
+  Listened-to, not blocked-on.
+- **Change signal** — a signal plus re-read: `targets_changed` →
+  `enumerate`. For state whose truth lives with the provider.
+
+**Broadcast is a provider pattern, never a kernel primitive.** The kernel
+does not know subscriber sets — a service does. The input service is the
+model: sources *publish* (a unicast call to the service), the service
+*broadcasts* (a fan-out loop of asynchronous sends over its subscriber list,
+so one dead subscriber can never stall the rest). One fan-out point per event
+domain, owned by the service that defines the event.
+
+The harness owns the machinery: the subscriber table, the dead-subscriber
+sweep (via process-exit notifications), and the fan-out loop — all written by
+hand in `input.zig` today, lifted into the service harness so every protocol
+gets identical semantics. `Define` declares a protocol's events (`.events`),
+and each event type is checked against `post_maximum` at compile time,
+generalizing the assert `input-protocol` already carries.
+
+**Event packets are droppable.** A slow subscriber's ring fills, and the
+provider must not block on it — so an event stream is a hint or a coalescing
+signal, never a ledger. Anything that must not be lost is either re-readable
+state (the change-signal pattern) or bulk data in shared memory with a
+packet as the doorbell, which is how the display path already works — the
+packets-never-fragment rule and this one are the same rule seen from two
+sides.
+
+**Source direction (open point).** Today event sources are *clients*: an
+input driver resolves `/protocol/input` and delivers each event as a
+synchronous `publish` call — one capability, obtained by resolution, covers
+everything, and the badge tells the service exactly who each event came from.
+The inversion — the service subscribing to each driver — would require every
+driver to be individually discoverable and its endpoint ferried to the
+service, machinery whose payoff (the service choosing its sources) the
+namespace already provides more cheaply: only a process granted open on
+`/protocol/input` can publish into it. Sources stay clients for now;
+revisited at restriction stage two, when a supervisor can wire capabilities
+at spawn time.
+
+## What this deliberately does not solve
+
+The wider security track, for which this namespace is the foundation, not the
+whole:
+
+- **File access restriction** — the point of the exercise. The same stage-two
+  namespace mechanism extends from protocol names to file paths: the spawner
+  decides which subtrees resolve. Designed separately once this lands.
+- `fs_mount` gating beyond the reserved prefixes; `system_spawn` gating;
+  `klog_read` being world-readable; backends checking the badge on per-node
+  operations (the FAT server honours node ids across clients today).
+- Kernel hardening items already noted in-tree: SMEP/SMAP and SYSRET
+  canonical-RIP, now designed in [smep-smap.md](smep-smap.md).
+- Pipes/FIFOs for the POSIX layer — a byte-stream object *beside* message IPC,
+  wanted by the Python track, unrelated to naming.
+- **Trusted UI** — a permission prompt an application cannot fake or overlay
+  (see the microphone example). A display-track concern: the supervisor chain
+  needs a reserved surface.
+
+## Migration plan
+
+Flag-day per phase, in the style of the DMA-capability conversion — no
+dual-stack periods, the QEMU suite green at each phase boundary.
+
+**P1 — mechanics, no behavior change.** The `envelope` module with its comptime
+`Define`, unit tests; `NodeKind.protocol` and the open-reply-capability
+convention in `vfs-protocol`; existing protocols untouched.
+
+**P2 — the registry.** Init serves `/protocol` (bind with manifest
+authorization, collision refusal, unbind on provider death, provenance);
+kernel reserves the `/protocol` prefix; every service converts from
+`ipc_register` to `bind`, every client from `ipc_lookup` to resolve-and-open;
+`ServiceId`, `ipc_register`, `ipc_lookup` deleted. Tests: unauthorized bind
+refused, collision refused, provider restart re-binds and a client re-resolves.
+
+**P3 — restriction, stage one.** The open-grant column in init's manifest;
+registry refuses ungranted opens. Test: a fixture process denied a protocol its
+neighbour is granted.
+
+**P4 — protocol rebase.** Existing protocol modules re-expressed through
+`Define`; providers move onto the generated dispatch; `describe`/`enumerate`
+answered everywhere; the conformance test fixture exercises the reserved verbs
+against every registered provider.
+
+**P5 — restriction, stage two.** Spawn's initial capability; namespace views
+built by the spawner; ambient resolution of `/protocol` retired. Includes the
+two requirements the microphone example pins: **parked replies** (a
+supervisor parks an open, keeps serving, replies later by badge) and
+**dedicated, killable granted channels** (revocation = channel death →
+`-EPEER`). Scoped separately — it touches `spawn`, the loader contract, and
+every supervisor — and lands together with the file-path half of namespacing.
+
+The unix-path migration ([file-system-hierarchy.md](../file-system-development/file-system-hierarchy.md#migration))
+is independent of P1–P5 and can land before or after.

docs/os-development/smep-smap.md

@@ -0,0 +1,143 @@
+# SMEP and SMAP — supervisor-mode hardening
+
+*Design, 2026-07-31. Not yet implemented. Companion to
+[protocol-namespace.md](protocol-namespace.md) on the security track — this is
+the hardware half; that is the namespace half.*
+
+Two CR4 bits that make the CPU refuse the two things a kernel should never do
+with user memory:
+
+- **SMEP** (Supervisor Mode Execution Prevention, CR4 bit 20): instruction
+  fetch in ring 0 from a page whose U/S bit says *user* → #PF. Kills the
+  classic ret2usr exploit shape — a kernel bug that redirects control flow
+  can no longer land in attacker-prepared user code.
+- **SMAP** (Supervisor Mode Access Prevention, CR4 bit 21): data read/write
+  in ring 0 to a user page → #PF, unless `EFLAGS.AC` is set. `stac`/`clac`
+  open and close deliberate access windows; danos's design needs no windows
+  at all (below).
+
+Detection is CPUID leaf 7, subleaf 0, EBX bit 7 (SMEP) and bit 20 (SMAP).
+Both bits are per-core state: the BSP and every AP must set them.
+
+## Why, in danos terms
+
+Every syscall argument is an attacker-controlled integer, and several take
+pointers. A kernel bug that dereferences a crafted pointer reads, writes, or
+executes memory of the attacker's choosing — the exact bug class the
+isolation tracks exist to prevent. SMEP/SMAP turn that class from "silent
+compromise" into "immediate, attributable #PF with a kernel RIP in the log."
+
+The second benefit matters as much as the first: **SMAP is a permanent
+tripwire.** Once it is on, any *future* syscall that touches user memory
+directly — instead of going through the checked copy layer — faults the
+first time the QEMU suite runs it. The discipline stops depending on review.
+
+## Where danos already stands
+
+The design is closer than it looks, because the IPC layer was built right:
+
+- **The copy layer is already SMAP-proof.** `copyAcross` and `copyFromUser`
+  (`system/kernel/ipc-synchronous.zig:305,333`) never dereference a user
+  virtual address: they walk the page tables and move bytes through the
+  physmap — kernel mappings throughout. SMAP cannot object.
+- **Syscall entry already clears AC.** `SFMASK = 0x4_0700` clears IF, TF,
+  DF, **AC** on every `syscall`
+  (`system/kernel/architecture/x86_64/per-cpu.zig:76`). The syscall path is
+  SMAP-clean from day one.
+- **The interrupt path is not.** Hardware does *not* clear AC on IDT
+  delivery, and ring 3 can set AC with `popfq` — so a hostile process could
+  take an interrupt with AC=1 and have the handler run with SMAP suspended.
+  `isr_common` (`system/kernel/architecture/x86_64/isr.s:366`) needs a
+  `clac` beside its `swapgs`.
+- **CR4 today:** the BSP inherits firmware CR4 (no kernel write anywhere);
+  APs set PAE/OSFXSR/OSXMMEXCPT in `trampoline.s:62-68`. Neither path sets
+  SMEP/SMAP yet, and both must.
+- **The stragglers.** Nine syscalls still dereference user pointers raw
+  after a bounds check — every one is a SMAP #PF waiting to happen, and
+  every one is *already* a latent kernel fault today (an unmapped-but-in-
+  range user page oopses the kernel instead of failing the call). The
+  verified sweep of `system/kernel/process.zig` (2026-07-31; a
+  whole-kernel `@ptrFromInt` audit found no user-address dereference
+  outside this file):
+
+  | Syscall | Raw access | Direction |
+  |---|---|---|
+  | `system_spawn` | name + argument blob (`:972`, `:980`) | read |
+  | `fs_resolve` | path in (`:1780`), result out (`:1797`) | read + write |
+  | `fs_mount` | prefix + rewrite strings (`:1864`, `:1865`) | read |
+  | `fs_unmount` | prefix string (`:1883`) | read |
+  | `fs_node` | read buffer out (`:1820`) | write |
+  | `debug_write` | message bytes (`:1700`; read twice — memcpy `:1710` and `log.append` `:1717`) | read |
+  | `klog_read` | log bytes out (`:1741`) | write |
+  | `klog_status` | status struct out (`:1758`) | write |
+  | `process_enumerate` | descriptor array out (`:1132`) | write |
+  | `device_enumerate` | descriptor array out (`:388`) | write |
+
+  For the write-direction rows the `@ptrFromInt` is in process.zig but the
+  stores happen in callees (`scheduler.enumerate`
+  `system/kernel/scheduler.zig:1209`, `devices_broker.enumerate`
+  `devices-broker.zig:136`, `log.readAt` `log.zig:209`, the vfs node calls
+  `vfs.zig:257/269/289`) — converting them means bounce buffers plus
+  `copyToUser` around those calls, not just editing the process.zig lines.
+  (Some paths already do it right — the futex word and the device-register
+  descriptor go through `copyFromUser` (`:1087`, `:924`). The write
+  direction has no public helper yet, but the mechanism exists:
+  `copyAcross` with a kernel source is exactly how IPC replies reach user
+  buffers, so `copyToUser` is a mechanical mirror.)
+
+- **One known gap inside the copy layer itself:** the walk checks presence,
+  not the leaf U/S and writable bits (`ipc-synchronous.zig:20-22` flags
+  this). Today that is nearly moot — the user half contains only mappings
+  the kernel itself created for that process — but it must close before
+  shared or copy-on-write mappings exist, and closing it is part of making
+  the copy layer the single trusted door.
+
+## The plan
+
+**H1 — copy discipline (the real work).** A `user-memory` kernel module:
+`copyFromUser` / `copyToUser` (the missing write direction) via the physmap
+walk, with U/S and writable leaf checks closing the in-tree TODO. Convert
+the nine stragglers. This fixes the latent unmapped-page kernel fault on
+its own — it is worth doing even if SMEP/SMAP never shipped. QEMU suite
+green; no behavior change visible to correct programs.
+
+**H2 — SMEP.** A leaf-7 feature probe (the kernel has per-leaf `cpuid`
+helpers in `apic.zig` to generalize); set CR4.SMEP during per-CPU bring-up
+on BSP and APs — prefer the Zig-side per-CPU init over the trampoline
+assembly, so one code path covers every core and the trampoline stays
+minimal. Audit first that ring 0 never executes user-mapped pages: kernel
+text lives in the kernel half, `jump_to_user` is kernel code, and the AP
+trampoline page is kernel-mapped — expected clean, verify before flipping.
+
+**H3 — SMAP.** Add `clac` at `isr_common` entry. `clac` is #UD on CPUs
+without SMAP, so the instruction is a 3-byte NOP in the image, patched to
+`clac` at boot when CPUID advertises SMAP (one-time patch beats a
+conditional branch in the hottest path in the kernel). Then set CR4.SMAP in
+the same per-CPU init. From this point the whole QEMU suite doubles as the
+enforcement test: any missed raw dereference is a vector-14 with a kernel
+RIP and a user CR2 — loud and attributable.
+
+**H4 — keep it honest.** A line in the coding standards: kernel code
+touches user memory only through `user-memory`; there is no `stac` anywhere
+in the tree, and a PR that adds one is wrong by definition. SMAP enforces
+the rule mechanically at test time.
+
+Feature-gating follows the timekeeping rule (work on any VM, real Intel,
+real AMD): both bits are probed, absence is logged and tolerated — like the
+IOMMU's fail-open, the machine still boots, just unhardened. QEMU: TCG
+implements both; KVM inherits the host (Intel Ivy Bridge+ for SMEP,
+Broadwell+ for SMAP; AMD Zen+ for both). The test images should run with
+`-cpu max` so the suite always exercises the enabled paths.
+
+## Adjacent, deliberately separate
+
+- **SYSRET canonical-RIP hardening** (`isr.s:192-194` documents it): a
+  non-canonical return RIP makes `sysretq` #GP *in ring 0* on Intel. Same
+  hardening bucket, independent fix (validate RCX before `sysretq`, fall
+  back to `iretq`), should ride the same branch as H2/H3 but is not
+  SMEP/SMAP.
+- **KPTI / Meltdown-class leaks are out of scope.** SMEP/SMAP police
+  architectural accesses, not speculative ones. danos runs one kernel
+  mapping in every address space and accepts that on affected hardware;
+  revisit only if the threat model ever includes hostile native code on
+  shared machines.

docs/os-development/system-image.md

@@ -11,7 +11,7 @@ sequential pass and hands the bytes to the kernel unmodified.
 
 The capsule is a *performance artifact*, not a source of truth. The boot
 volume's `/system` and `/test` file trees remain the canonical layout (see
-[danos-file-system-hierarchy-FSH.md](../file-system-development/danos-file-system-hierarchy-FSH.md));
+[file-system-hierarchy.md](../file-system-development/file-system-hierarchy.md));
 the capsule is a pre-baked snapshot of the same binaries, derived from the same
 build graph, so the running system is identical whether the loader read the
 capsule or walked the tree.
@@ -36,11 +36,11 @@ so it need be no fancier. Little-endian throughout:
 
 ```
 Header        magic: u32 = "DNR2" (0x32524E44), count: u32
-Entry × count name: [64]u8 (NUL-padded FHS path), offset: u64, len: u64
+Entry × count name: [64]u8 (NUL-padded hierarchy path), offset: u64, len: u64
 blobs...      each entry's file bytes, at its offset within the image
 ```
 
-- **Names are full FHS paths** (`/system/services/init`), not basenames — that
+- **Names are full hierarchy paths** (`/system/services/init`), not basenames — that
   is what "v2" means. The 64-byte capacity matches `abi.maximum_process_name`,
   so a task named after its binary path is never truncated. Paths longer than
   63 bytes are a build error (`pack-system-image.py` rejects them).
@@ -54,14 +54,14 @@ blobs...      each entry's file bytes, at its offset within the image
 
 ## How it is built
 
-`build.zig` maintains one `bundled` list — every user binary and its FHS home.
+`build.zig` maintains one `bundled` list — every user binary and its hierarchy home.
 Three artifacts are derived from that same list, in the same build graph, so
 they cannot drift apart:
 
-1. **The tree**: each binary installed at its FHS path (`zig-out/system/...`
+1. **The tree**: each binary installed at its hierarchy path (`zig-out/system/...`
    and `zig-out/test/...`, mirrored onto the FAT boot volume by
    `tools/make-fat-image.py`).
-2. **The manifest** (`system/manifest`): the FHS path of every bundled binary,
+2. **The manifest** (`system/manifest`): the hierarchy path of every bundled binary,
    one per line — the loader's per-file fallback input.
 3. **The capsule**: `tools/pack-system-image.py` packs the same binaries into
    the v2 container, installed at `zig-out/boot/system.img` and placed on the
@@ -103,7 +103,7 @@ the kernel (`kernel.zig`) then publishes the same bytes twice, to two
 consumers:
 
 - **The process layer** (`process.zig`): `system_spawn` looks binaries up in
-  the ramdisk via `Reader.find` — exact FHS path, or unique basename for
+  the ramdisk via `Reader.find` — exact hierarchy path, or unique basename for
   pre-path callers — and loads them as fresh ring-3 processes. The stored path
   becomes the task's name.
 - **The VFS root** (`vfs.zig`, `setInitialRamdisk`): the image is mounted as
@@ -111,7 +111,7 @@ consumers:
   paths, so `/system` and, when the fixtures are bundled, `/test`. Directory
   nodes are derived from the entry paths (the unique parents), so the trees
   are listable and their files readable over the normal VFS protocol — the
-  FHS boot tree every process sees comes straight out of the capsule bytes.
+  boot tree every process sees comes straight out of the capsule bytes.
 
 The image is never copied after the handoff and never mutated: the initrd is
 immutable, which is what makes the VFS's node serving lock-free.

docs/os-development/threading-plan.md

@@ -22,11 +22,12 @@ lands on its own and ends in a **verifiable gate** — shaped for a `/loop` run,
 ## Conventions
 
 Follow [coding-standards.md](../coding-standards.md): spell out non-acronym abbreviations,
-kebab-case file names, no `Co-Authored-By` trailers. New user binaries go through
-`addUserBinary` (with the new `threaded` flag where a binary spawns threads) and get
-packed into the initial-ramdisk; new syscalls extend [abi.zig](../../system/abi.zig)
-`SystemCall` + a `library/runtime` wrapper; test services live beside the code they
-exercise and register a `ServiceId` if they must be looked up.
+kebab-case file names, no `Co-Authored-By` trailers. New user binaries are
+packages whose build.zig calls `build_support.userBinary` (with `.threaded =
+true` where a binary spawns threads) and get packed into the initial-ramdisk;
+new syscalls extend [abi.zig](../../system/abi.zig) `SystemCall` + a
+`library/kernel` wrapper; test services live beside the code they exercise and
+register a `ServiceId` if they must be looked up.
 
 ## How to verify along the way
 

docs/os-development/threading.md

@@ -61,9 +61,10 @@ runtime — rebuilt in lockstep — knows the mapping.
    backend would either bake danos syscall numbers into std (breaking ABI privacy and
    renumbering) or fork std to route back through the runtime — a permanent rebase
    cost that buys nothing the native type doesn't.
-2. **Our user binaries are built `single_threaded = true`** ([build.zig](../../build.zig)
-   `addUserBinary`), which compiles threading out entirely and makes atomics and TLS
-   single-threaded. Threads need this flipped per binary regardless.
+2. **Our user binaries are built `single_threaded = true`** (the shared recipe in
+   [build-support/build.zig](../../build-support/build.zig)), which compiles threading
+   out entirely and makes atomics and TLS single-threaded. Threads need this flipped
+   per binary regardless.
 
 So we take the *shape* of `std.Thread`, not the *type*. The cost of replicating the
 surface (spawn/join/Mutex/Condition) is small; the cost of the std type is the ABI
@@ -236,9 +237,10 @@ see the intro). Two scoped pieces, as built:
 
 ### Build: multi-threaded codegen, opt-in
 
-A binary opts in by being added with `addThreadedUserBinary` — as `addUserBinary`,
-but the shared implementation builds it `single_threaded = false` — so atomics and
-(later) TLS are real. Threads and atomics are unsound in a `single_threaded` image,
+A binary opts in with `.threaded = true` in its package's
+`build_support.userBinary` call — the shared recipe in build-support then builds it
+`single_threaded = false` — so atomics
+and (later) TLS are real. Threads and atomics are unsound in a `single_threaded` image,
 so a binary must opt in **before** it may call `Thread.spawn`. Everyone else
 stays single-threaded and lean.
 

docs/python-on-danos-milestones.md

@@ -0,0 +1,192 @@
+# Python on danos: the milestone plan
+
+The execution plan for [python-on-danos.md](python-on-danos.md). That note holds
+the *why* and the design decisions; this one slices the work into milestones with
+concrete deliverables, tests, and exit criteria. Milestones are numbered **P0–P5**
+(track-local — the global M-series stays with the driver/lifecycle tracks).
+
+Dependencies at a glance:
+
+```
+P0 toolchain + mini-libc ──┐
+P1 streams + console + seam ─┴─→ P2 CPython minimal ─→ P3 terminal + REPL
+                                        │                    │
+                                        └─→ P4 danos module  │
+                                             + Python service│
+P5 process control + shell ←─────────────────────────────────┘
+```
+
+P0 and P1 are independent of each other and can proceed in parallel. P1 is shared
+work — it is also Zig self-hosting Phase 1 and the first three slices of
+[character-devices-and-tty.md](character-devices-and-tty.md).
+
+## P0 — Toolchain + the C library compatibility layer
+
+**Goal:** a C hello-world, cross-compiled on the host with `zig cc`, runs on danos.
+
+Design and slicing live in
+[c-library-compatibility.md](c-library-compatibility.md): the **libdanos-c**
+sysroot (hand-written danos-native headers + `libc.a`) as a `library/c/` build
+package — pure computation (string, libm, `strtod`, the printf/scanf engines)
+lifted from a vendored, pinned musl subtree; the OS plumbing written in Zig over
+the `runtime` surface (re-targeting `runtime.os` when the Zig track authors it);
+`malloc` over danos `mmap`; a `crt0` bridging the danos entry shim to C `main`.
+Driven by `zig cc -target x86_64-freestanding-none -isystem` (the triple becomes
+`x86_64-danos` if the Zig fork lands first; nothing else changes).
+
+Its five slices (sysroot-skeleton, fd-plumbing, malloc, stdio,
+mathematics-and-time) carry their own tests — host-side oracle suites for the
+computation layer, QEMU cases (`c-hello`, `c-file-io`, `c-stdio`, `c-time`) for
+the plumbing.
+
+**Exit:** `c-hello` and `c-file-io` green in the QEMU suite; host computation
+tests green.
+
+## P1 — Stream nodes, console, and the seam pieces
+
+**Goal:** the shared Phase-1 surface exists: byte-stream stdio, cwd, environment,
+entropy. Design and slicing live in
+[character-devices-and-tty.md](character-devices-and-tty.md); this milestone is
+its slices 1–3 plus three small seam pieces:
+
+- **cwd/chdir** — per-process current directory used by path resolution (the
+  kernel already anchors a VFS root per `fs_resolve`; the cwd is the same idea,
+  process-scoped, with `getcwd`/`chdir` exposed through `runtime` and the libc).
+- **Environment** — spawn carries an environment block; the SysV entry stack's
+  `envp` slot ([sysv.md](os-development/sysv.md)) stops being empty; `getenv`
+  reads it. An empty block stays valid.
+- **Entropy** — a kernel `entropy` syscall (RDSEED/RDRAND with a jitter fallback,
+  mirroring the TSC-reliability posture of not trusting one CPU feature blindly);
+  the libc exposes `getentropy`.
+
+- **Tests.** QEMU: the character-device tests from the tty note (offsetless
+  read/write, blocking read, cooked/raw control round-trip), plus `cwd-basics`
+  (chdir + relative open), `env-roundtrip` (spawn with env, child reads it),
+  `entropy-sane` (nonzero, changing, correct length).
+
+**Exit:** a C program reads a cooked line from fd 0 and echoes it to fd 1 —
+injected key events in, bytes read back through the console's in-memory sink,
+all under QEMU with no hardware involved — and `getcwd`/`getenv`/`getentropy`
+return real answers.
+
+## P2 — CPython, minimal configuration
+
+**Goal:** `python -c 'print(2**100)'` runs on danos under QEMU.
+
+- Pin **CPython 3.13.x**; vendor as `third-party/cpython/` or fetch via the build
+  (decide with the build-packages conventions).
+- Host build-Python of the same version (`--with-build-python`).
+- `config.site` cache for the cross answers; `config.sub` patch so
+  `x86_64-unknown-danos` parses; a small `configure`/`pyconfig` patch set kept as
+  rebasable diffs, WASI-style.
+- `--disable-shared`; static `Modules/Setup`: `posix errno _io _codecs _weakref
+  time math _stat _collections itertools _functools _locale _sre` plus what the
+  interpreter core insists on; threadless build (WASI precedent).
+- `Lib/` on the FAT image under the hierarchy (e.g. `/system/python/lib`);
+  `PYTHONHOME` set accordingly; `.pyc` written with **checked-hash
+  invalidation** (FAT's 2-second mtime granularity makes mtime-based validation
+  lie during fast edit-run cycles).
+- `PYTHONHASHSEED` pinned only if P1's entropy slipped — otherwise real
+  hash randomization from day one.
+- **Tests.** QEMU: `python-expr` (the exit criterion), `python-file` (run a
+  script from FAT, write a file, read it back), then a curated slice of CPython's
+  own suite (`test_int`, `test_float`, `test_io`, `test_dict`) as a
+  longer-running target — the suite is the porting harness.
+
+**Exit:** the four QEMU cases green; the CPython test slice green or with a
+short, documented skip list.
+
+## P3 — Terminal + REPL: the first real application
+
+**Goal:** an interactive `python` REPL in a graphical danos terminal — the
+milestone demo for the OS.
+
+- Depends on the display track's font rendering (its stated next step) — until
+  that lands, the REPL is exercised end-to-end through the pseudo-device
+  harness from P1+P2 (scripted input in, output read back), so P2's exit is
+  never blocked on graphics; the graphical terminal is the *interactive* debut.
+- The terminal application: draws with the UI toolkit / display client, consumes
+  keyboard `InputEvent`s, and — per the tty note's load-bearing decision —
+  **serves the VFS stream protocol itself** to its children, reusing the console's
+  line-discipline library. Spawns `python` with its endpoints as fd 0/1/2.
+- Raw mode + the control set give the REPL line editing; window-size control
+  gives it wrapping.
+- **Tests.** QEMU: scripted terminal session (inject key events, assert rendered
+  or captured output). Real-hardware smoke on the Intel box joins the existing
+  checklist.
+
+**Exit:** typing `2+2` into the terminal on the QEMU GPU target prints `4`.
+
+## P4 — The `danos` extension module + a Python service
+
+**Goal:** Python can speak danos: IPC, capabilities, spawn.
+
+- The `danos` module, **written in Zig against `Python.h`**, statically linked
+  via `Modules/Setup`: endpoints (create/send/receive), capability passing,
+  spawn + exit-notification, and the service bootstrap (announce, supervision
+  handshake) — the same surface Zig services use, re-exposed.
+- UI-toolkit bindings as a second module once the toolkit's API settles.
+- Prototype **one real service in Python** — policy-shaped, not data-plane
+  (candidates: hot-plug policy, a settings service) — speaking an existing wire
+  protocol, supervised by the device manager like any service.
+- **Tests.** QEMU: `python-ipc-echo` (Python service echoes over an endpoint, a
+  Zig client asserts), plus the prototype service's own protocol test.
+
+**Exit:** a Python process runs as a supervised danos service exchanging IPC
+with Zig peers.
+
+## P5 — Process control, then the shell
+
+**Goal:** danos can spawn arbitrary programs with arguments and pipes; a small
+Python shell uses it.
+
+The kernel/VFS cluster a shell forces (any shell, any language):
+
+- **exec-of-path** — spawn an arbitrary VFS path, not a named ramdisk binary;
+- **argv/envp** — carried through spawn onto the child's entry stack (env from
+  P1, argv new);
+- **numeric exit status** — extend the exit record beyond the categorical
+  `ExitReason` (the gotcha the Zig roadmap flagged: `WEXITSTATUS` must be real);
+- **fd inheritance + pipes** — a kernel or service pipe (a character device by
+  the tty note's definition) and spawn-time fd mapping.
+
+Then, in order: `subprocess` enabled in CPython (maps onto spawn + the
+exit-notification endpoint — no fork, Windows-style); a **small Python shell** (a
+few hundred lines over `subprocess` + the console: prompt, argv parsing, pipes,
+cwd) as the forcing function that reveals what job control actually needs.
+
+**Explicitly deferred past P5:** the pthread subset over `thread_spawn`/futex,
+signals-in-libc via M17, termios job control (Ctrl-C to foreground child), and
+**xonsh** — which wants all three and is the arc's endpoint, not a milestone.
+
+**Tests.** QEMU: `spawn-argv-exit` (child echoes argv, exits 42, parent sees
+42), `pipe-through` (parent → child → parent), `python-subprocess`, and a
+scripted shell session.
+
+**Exit:** the Python shell runs `program | program` typed at the terminal and
+reports the exit status.
+
+## Post-P5 outlook
+
+Two tracks continue past this plan, each with its own design doc rather than a
+P-number here:
+
+- **Dynamic libraries** ([dynamic-libraries.md](dynamic-libraries.md), D1–D4) —
+  an application-layer facility (the OS stays static and lean): `dlopen` in the
+  libc, then libffi + `ctypes` + loadable extension modules, then shared
+  read-only mappings so N Python services hold one physical `libpython`.
+- **The full C compatibility layer**
+  ([c-library-compatibility.md](c-library-compatibility.md), stages 2–3) — the
+  standing rule that every system capability ships with its C spelling, draining
+  the absence table toward "portable C builds on danos"; `fork` is the one
+  permanent exception.
+
+## Related
+
+- [python-on-danos.md](python-on-danos.md) — the design note this executes.
+- [c-library-compatibility.md](c-library-compatibility.md) — P0's design.
+- [character-devices-and-tty.md](character-devices-and-tty.md) — P1's design.
+- [zig-self-hosting.md](zig-self-hosting.md) — shares P1; its fork makes P0's
+  triple prettier but gates nothing here.
+- [os-development/process-management.md](os-development/process-management.md) —
+  the spawn/exit surface P5 extends.

docs/python-on-danos.md

@@ -0,0 +1,261 @@
+# Python on danos: the CPython milestone
+
+A design note (not built yet) on bringing **CPython** to danos, compiled with the Zig
+toolchain (`zig cc`). Like [zig-self-hosting.md](zig-self-hosting.md), it is
+forward-looking: it sets a direction and the decisions that follow from it.
+
+## Why Python, and why now
+
+The Zig self-hosting road is gated on a compiler fork and a long std-library seam.
+Python is the **stop-gap that removes the wait**: a working CPython gives danos a way
+to write programs — services, tools, application prototypes — *without* the Zig
+compiler being self-hosted, and it brings the pure-Python package ecosystem along as
+a bonus. The intended division of labour:
+
+- **Zig** — the kernel, drivers, and anything on a data plane (interrupt paths,
+  DMA rings, block I/O). Unchanged.
+- **Python** — the control plane and the prototyping surface: services that are
+  event loops over IPC, policy logic that changes often, application experiments,
+  and eventually the shell.
+
+Python is also the scripting language for the terminal-and-shell arc: the first
+real danos application is planned as a terminal, a terminal wants a shell, a shell
+wants a scripting language — and [xonsh](https://xon.sh) (a shell written in
+Python) marks where that road can end.
+
+### Non-goals
+
+- **No drivers in Python.** Interrupt handling, ring management, and DMA stay in
+  Zig. Python may *supervise and configure* drivers; it does not sit in their hot
+  paths (interpreter overhead and garbage-collection pauses in an interrupt path
+  are disqualifying).
+- **No dynamic loading during bring-up, no `pip`.** The whole arc here ships
+  statically linked. Dynamic libraries are a real *later* milestone
+  ([dynamic-libraries.md](dynamic-libraries.md)) — an application-layer
+  facility that unlocks `ctypes` and loadable extension modules; the operating
+  system itself stays static and lean regardless (the size doctrine below).
+  `pip` stays out either way until a networking track exists.
+- **No fork.** `os.fork` will not exist. This costs almost nothing (see "The
+  spawn model fits").
+
+## The realization that shapes everything: the compiler is not the obstacle
+
+`zig cc` is a full Clang-based C cross-compiler, and CPython is portable C with
+official precedent for stranger targets than danos — the WASI port is upstream
+tier-2, and it runs **without fork, without dynamic loading, and without working
+threads**. Every "CPython can't possibly run there" objection has already been
+answered upstream by a target *more* constrained than danos.
+
+What CPython actually needs is a **C environment**: headers and a `libc.a`. danos
+has neither — and that is the whole project. In the language of the Zig roadmap's
+three doors, this is the **door-2-shaped work** (the deferred "musl door"), not the
+`std.os.danos` seam: CPython never touches Zig's std.
+
+### The same surface, a third time
+
+The Zig roadmap observed that door 1 (`std.os.danos`) and door 2 (a libc) implement
+the *same* ~30 danos-facing operations at different layers. CPython consumes that
+identical surface through C spellings. So nothing here is throwaway: the
+danos-native operations backing `runtime.os` are the same ones the libc bottoms out
+in, and the gaps this track must close (stdio byte streams, cwd, environment,
+entropy) are **exactly the Phase-1 gaps the Zig roadmap already lists**. The two
+tracks share a road until Python forks off at "build the libc."
+
+## Where danos stands: coverage vs. the gaps
+
+Judged against the minimal CPython configuration (static, WASI-like):
+
+| CPython need | danos today | Gap |
+|--------------|-------------|-----|
+| open/read/write/close/lseek, readdir | VFS + FAT via `runtime.fs` | none — wrap in C |
+| mkdir / unlink / rename / truncate | done (self-hosting Phase 2) | none |
+| stat with mtime | done (`wall_clock` + FAT mtime) | none |
+| mmap/munmap (object allocator) | native syscalls | none |
+| monotonic + wall clock | `clock` + `wall_clock` syscalls | none |
+| a place for `Lib/` | FAT boot image | none — better than WASI has it |
+| fork / exec | not needed (subprocess disabled at first) | — |
+| dynamic loading | not needed (static extension modules) | — |
+| getcwd / chdir | — | **missing** (shared with Zig Phase 1) |
+| environment variables | `Init` has no env | **missing** (can start empty) |
+| entropy | — | **missing** (hash seed; `PYTHONHASHSEED` pins it meanwhile) |
+| byte-stream stdin/stdout (fd 0/1/2) | `debug_write` out; structured `InputEvent` in | **missing** (shared with Zig Phase 1; the REPL needs it) |
+| signals | — | stubs suffice (WASI precedent); M17 signals-over-IPC maps on later |
+| threads | native `thread_spawn`/futex | build threadless first; a pthread subset later (xonsh needs it) |
+
+The clustering repeats the Zig roadmap's: **files, memory, and time are done; the
+work is the C packaging plus the small seam pieces** (tty bytes, cwd, env, entropy).
+
+## The libc decision: hand-rolled in Zig, computation lifted from musl
+
+Two viable shapes were considered:
+
+| Option | What it is | Verdict |
+|--------|-----------|---------|
+| **Mini-libc in Zig** | C-ABI-exporting Zig library over `runtime.os`/`runtime.fs`, shipped as headers + `libc.a`. | **Take this.** Reuses the danos-native surface directly; no Linux assumptions to fight. |
+| **Port musl** | Full musl with a danos syscall backend. | Defer, again. musl assumes Linux syscall semantics in places; heavier than the need. |
+
+The trick that makes the mini-libc tractable: musl's `string/`, `math/` (libm —
+CPython needs essentially all of it), and number-conversion layers are **pure
+computation with no syscalls**. Lift those wholesale (MIT-licensed, designed to
+compile standalone) and hand-write only:
+
+- the OS-facing bottom: fds, `mmap`, clocks, `exit`, `getcwd` — thin C-ABI wrappers
+  over `runtime.os`;
+- a `FILE*` stdio layer (buffered, over the fd layer);
+- `malloc` over danos `mmap` (a simple allocator is fine; CPython does its own
+  small-object arena management above it);
+- the headers (`stdio.h`, `stdlib.h`, `string.h`, `math.h`, `errno.h`, …).
+
+Estimate: **100–150 functions**, of which the hard 40% (libm, string, printf/strtod
+cores) are lifted, not written. Correctness hot spots are `strtod`/`dtoa` (Python's
+float repr round-trips through them) — another reason to lift musl's, not improvise.
+
+## C interop: static extension modules, not ctypes
+
+"Python can interface with C libraries" is true on danos with one important
+correction: **`ctypes` does not work at first** — it is built on `dlopen` + libffi,
+both of which arrive only with the [dynamic-libraries](dynamic-libraries.md)
+milestone (D2). Until then the interop story is the other, older one:
+
+- **Extension modules statically linked into the interpreter** via CPython's
+  `Modules/Setup` mechanism (the standard route for embedded/static builds).
+- **Zig speaks C ABI natively**, so danos extension modules are written in Zig
+  against `Python.h` — no C required. Two modules are planned from the start:
+  - **`danos`** — the system module: endpoints, send/receive, capability passing,
+    spawn, exit notification. This is what makes a Python *service* possible: an
+    event loop over IPC, speaking the same wire protocols as Zig services.
+  - **UI toolkit bindings** — the in-progress danos UI toolkit exposed to Python,
+    so application prototypes drive real windows.
+
+The package story follows: **pure-Python packages work** (unpack into
+`Lib/site-packages` on the FAT image); packages with C extensions must be
+cross-compiled and baked into the interpreter — a curated set chosen per image,
+not `pip install`. That is the honest shape of the stop-gap.
+
+## The roadmap
+
+### Phase 0 — Toolchain + libc bring-up
+
+`zig cc -target x86_64-freestanding-none` plus `-isystem` the danos headers and the
+mini-libc archive. No compiler fork required — this track deliberately avoids the
+Zig roadmap's Phase-0 gate (if the fork lands first, the triple becomes a clean
+`x86_64-danos`; nothing else changes). Exit criterion: a **hello-world C program**
+compiles on the host and runs on danos, printing via the libc's `write`.
+
+### Phase 1 — The shared seam pieces
+
+The same list as Zig self-hosting Phase 1, closed once for both tracks:
+
+- fd 0/1/2 as console **byte** streams (output exists as `debug_write`; input is a
+  new small thing — cooked line input first, raw mode when the REPL wants editing);
+- `getcwd`/`chdir`;
+- environment variables (an empty block is a valid start);
+- an entropy syscall or service (until then, builds pin `PYTHONHASHSEED`).
+
+### Phase 2 — Cross-compile CPython, minimal configuration
+
+Pin one CPython release (3.13 — strongest WASI-era cross-compile support). The
+mechanics are well-trodden upstream since 3.11:
+
+- a same-version **build-Python on the host** (`--with-build-python`);
+- a `config.site` cache answering what configure cannot probe cross
+  (`ac_cv_file__dev_ptmx=no` and friends);
+- a `config.sub` patch so `x86_64-unknown-danos` parses;
+- `--disable-shared`, static `Modules/Setup` with a minimal module set
+  (`posix`, `errno`, `_io`, `_codecs`, `time`, `math`, …);
+- `Lib/` shipped on the FAT image; `PYTHONHOME` pointed at it.
+
+Exit criterion: `python -c 'print(2**100)'` runs on danos under QEMU.
+
+### Phase 3 — Terminal + REPL: the first real application
+
+Depends on the display track's font rendering (already its stated next step) and
+Phase 1's tty. A terminal emulator drawing a `python` REPL is the milestone demo:
+interactive, self-evidently real, and it needs **zero** process-control machinery.
+
+### Phase 4 — The `danos` module and Python services
+
+Write the `danos` extension module and the UI-toolkit bindings; prototype one real
+service in Python (a policy-shaped one — e.g. hot-plug policy or a settings
+service) speaking the existing IPC protocols. This is the payoff phase for
+"prototyping a service or application."
+
+### Phase 5 — Process control, then the shell
+
+The shell — any shell, in any language — forces the surface danos has deferred so
+far: **exec-of-path, argv/envp passing, numeric exit status (`WEXITSTATUS`, not the
+categorical `ExitReason`), fd inheritance, and pipes.** That is a kernel/VFS
+milestone cluster of its own. Then, in order:
+
+1. `subprocess` enabled in CPython (maps onto danos spawn — see below);
+2. a **small Python shell** (a few hundred lines over `subprocess` + line input, no
+   job control) — the forcing function that reveals which process-control pieces
+   actually matter;
+3. **explicitly deferred:** a pthread subset over `thread_spawn`/futex
+   (create/join/mutex/condition/thread-locals), signals via M17 signals-over-IPC,
+   termios job control — and then **xonsh**, which wants all three.
+
+### The spawn model fits
+
+One genuinely good alignment: **CPython does not need fork.** `subprocess` maps
+cleanly onto a posix_spawn-style model — exactly what danos has — and the existing
+exit-notification-via-endpoint is a *better* fit for `Popen.wait` than Unix's
+`wait` semantics. `os.fork` simply won't exist, as on Windows, and almost nothing
+in practice cares.
+
+## Risks and gotchas
+
+- **Binary size — and the size doctrine that makes it acceptable.** danos's
+  leanness mandate applies to the **operating system**: the kernel and the system
+  services stay small (the kernel is measured in kilobytes, not megabytes), and
+  nothing in this track changes that — Python never enters the OS layer. An
+  **application** budget is different: a statically-linked CPython with its
+  module set will be tens of megabytes in ReleaseSafe (the measured ~2×
+  safety-check factor compounds it), and that is *allowed* — applications live
+  on the FAT image, not in the kernel's world. It still shapes the image, and it
+  means every Python service shares one interpreter binary + per-service
+  scripts, so the spawn model needs **argv** before "run this .py" works at all.
+- **FAT mtime granularity is 2 seconds.** CPython's `.pyc` cache validation is
+  mtime-based by default; a rapid edit-run cycle can see stale bytecode. Use
+  hash-based `.pyc` invalidation (PEP 552, `--invalidation-mode checked-hash` at
+  freeze time) or accept the quirk during bring-up.
+- **FAT name lookups are case-insensitive.** Long file names preserve case but
+  match insensitively — the same world Python inhabits on Windows/macOS, so
+  importlib copes, but two modules differing only by case cannot coexist on the
+  image.
+- **`strtod`/float repr correctness.** Python's float round-tripping is exacting;
+  lift musl's conversions rather than writing them, and run CPython's float tests
+  early.
+- **Threadless build is load-bearing, initially.** Like WASI, the first builds have
+  no working `threading`. The escape hatch is real (danos has native threads and
+  futexes; a pthread subset is Phase-5 work) but keep the configuration honestly
+  single-threaded until then.
+- **The test suite is the porting harness.** CPython ships its own conformance
+  suite; getting `test_builtin`, `test_int`, `test_float`, `test_io` running on
+  danos early converts "it seems to work" into a checklist. Budget image space for
+  the test `Lib/` tree during bring-up.
+- **Entropy before exposure.** `PYTHONHASHSEED=0` is fine for bring-up and wrong
+  forever; hash randomization exists because attacker-controlled dict keys are a
+  denial-of-service vector. Land the entropy source before any Python service
+  parses external input.
+
+## Related
+
+- [python-on-danos-milestones.md](python-on-danos-milestones.md) — the execution
+  plan (P0–P5) for this note.
+- [c-library-compatibility.md](c-library-compatibility.md) — the mini-libc
+  (libdanos-c) design behind Phase 0.
+- [character-devices-and-tty.md](character-devices-and-tty.md) — the stream-node /
+  console / no-pty design behind Phase 1.
+- [zig-self-hosting.md](zig-self-hosting.md) — the sibling track; shares Phase 1,
+  diverges at the libc.
+- [os-development/syscall.md](os-development/syscall.md) — the kernel ABI the
+  mini-libc bottoms out in.
+- [os-development/vdso.md](os-development/vdso.md) — the public ABI boundary the
+  `danos` extension module wraps.
+- [os-development/sysv.md](os-development/sysv.md) — the entry stack (argv/envp)
+  the spawn-argv work extends.
+- [device-driver-development/ipc.md](device-driver-development/ipc.md) — the IPC
+  surface Python services speak.
+- [file-system-development/file-system-hierarchy.md](file-system-development/file-system-hierarchy.md)
+  — where `Lib/` and `site-packages` land on the image.

docs/security-track-plan.md

@@ -0,0 +1,481 @@
+# Security track execution plan: paths, protocol namespace, SMEP/SMAP
+
+The design is settled in
+[communication.md](os-development/communication.md),
+[protocol-namespace.md](os-development/protocol-namespace.md),
+[file-system-hierarchy.md](file-system-development/file-system-hierarchy.md),
+and [smep-smap.md](os-development/smep-smap.md). This file is the build order
+— one phase at a time, each phase green before the next starts. Delete or
+archive this file when the last milestone lands.
+
+**Context a fresh session should read first:** the four design docs above,
+then this plan's *Settled decisions* section — those decisions came out of a
+full-code grounding pass (2026-07-31) and must not be re-derived or reopened.
+
+**Definition of green, every phase:** `zig build` clean, `zig build test`
+clean, `python3 test/qemu_test.py` passes (existing scenarios plus the
+phase's new ones — record the suite count in the checkbox), and the relevant
+design doc's status/known-gap lines updated in the same commit. Commit per
+green phase, style `area: lower-case declarative summary`, **no co-author
+trailers**. On a suite failure, read
+`zig-out/qemu-test/<case>-failed-serial.log` before changing anything.
+
+**Workflow:** work in a dedicated git worktree on feature branches cut from
+`main` (one branch per milestone group as marked below); when a group's
+phases are all green, merge to `main` and push. The loop marks a phase `[x]`
+in the same commit that lands it.
+
+**Numbering note:** milestones use the design docs' own names (PM, H1–H3,
+HS, P1–P4) — the M-number sequence is left alone (M19–M22 are reserved by
+the logging/USB-lifecycle track).
+
+## Status
+
+**Live state — updated on `main` after every phase, so this file read from a
+plain `main` checkout always tells the truth about where the work is.**
+
+| | |
+|---|---|
+| Working on | **P3** — green at 109/109, adversarial review running, not yet committed |
+| Branch carrying it | `feat/security-group-2` (pushed to origin) |
+| On `main` | through the group 1 merge (`f3bc23c`): Phase 0, PM, H1 |
+| Committed on the branch, awaiting the group 2 merge | P1 (`1ff0991`), P2 (`1379b69`) |
+| Suite | 109 cases, all passing |
+| Last updated | 2026-08-01 |
+
+A checkbox below means the phase met its definition of green and was
+committed — on the branch named above, which reaches `main` at the next
+group boundary.
+
+- [x] **Phase 0** — baseline: suite green on `main` (106/106, 2026-07-31; `zig build` + `zig build test` clean at 9a32380), plan committed
+- [x] **PM** — path-migration flag-day (`/etc`→`/system/configuration`, `/var/log`→`/system/logs`, `/mnt/usb`→`/volumes/usb`; vfs carve-out for the two writable `/system` subtrees, FAT's `/var` mount split in two; suite 106/106)
+- [x] **H1** — the `user-memory` module; nine stragglers converted; leaf U/S+W checks (plus physmap-coverage confirmation, so an `mmio_map`'d buffer cannot fault ring 0 — this also closes the same hazard on the IPC path; `fs_resolve`'s out-capacity bound made overflow-safe; suite 107/107)
+- [x] **merge** group 1 → main, push (f3bc23c, 2026-07-31)
+- [x] **P1** — envelope module + `Define`; vfs `NodeKind.protocol` + open-reply-capability; client `Channel` (mechanics only, nothing converted; suite unchanged at 107)
+- [x] **P2** — registry in init; `/protocol` reserved; ServiceId flag-day (11 binds, 17 lookups; `protocol.csv` grants, chain-attested identity, dead-owner rebind; the kernel's endpoint-death sweep generalized off the retired registry; suite 108/108). Three adversarial review rounds closed six defects a green suite had missed: a forged power event could shut the machine down; the ping path leaked a capability per call, first in init and then in the shared harness; supervisor attestation by name was defeated by a laundering deputy; and the kernel let any handle-holder bind signals, timers, exits and IRQs to an endpoint it did not own.
+- [x] **P3** — open grants: `protocol.csv` enforcement, denial test. `onOpen`
+  consults the manifest with the same chain-attested identity a bind uses, and a
+  refused caller gets the *same* answer as one naming a contract nobody bound —
+  `-ENOENT`, no capability, the same reply bytes, no log line, and both questions
+  asked on every open so there is nothing to time. Twenty-seven `open` rows cover
+  the whole live client set. One wrinkle the plan had not foreseen: the driver
+  tree is three deep (device manager → PS/2 bus → keyboard/mouse) and attestation
+  is one hop, so a legitimate grandchild read exactly like a laundering deputy;
+  the manifest gained a third permission, `supervise`, which names an authorized
+  supervising task per contract and is deliberately **open-only**, leaving P2's
+  bind attestation and every refusal it makes untouched (suite 109/109)
+- [ ] **merge** group 2 → main, push
+- [ ] **P4a** — clean protocols rebased onto `Define` (vfs, block, display, scanout, input)
+- [ ] **P4b** — misfit protocols rebased (device-manager, power, usb-transfer)
+- [ ] **P4c** — harness subscriber lift + badge-scoped per-client integers
+- [ ] **merge** group 3 → main, push
+- [ ] **H2** — SMEP on every core
+- [ ] **HS** — SYSRET canonical-RIP guard
+- [ ] **H3** — SMAP + boot-patched `clac`; `-cpu max` in the harness; negative tests
+- [ ] **merge** group 4 → main, push
+
+---
+
+## Settled decisions (grounding pass, 2026-07-31 — do not reopen)
+
+These resolve every open wrinkle the code inventory surfaced. Where one
+amends a design doc, the amendment lands in the same commit as the phase
+that implements it.
+
+1. **Every packet — request, reply, and event — begins with the envelope
+   `Header`, exactly as the design says; the header is FOLDED, never
+   stacked.** It absorbs each protocol's existing operation/id fields
+   rather than sitting on top of them, so the two apparent 64-byte-limit
+   offenders fit: `ChildAdded` re-lays to 60 bytes (its packed operation
+   byte and `device_id` become `Header.operation`/`.target`);
+   `InterruptReport` puts `device_token` in `Header.target` and trims
+   inline data 48 → 40 bytes (largest real report today is 8). A
+   headerless-events variant was considered and REJECTED (2026-07-31): it
+   re-invents per-protocol mini-headers and breaks uniform tooling. No
+   design-doc amendment; `Define`'s event check stays ≤ 64 *including*
+   the header.
+2. **Bind/open authorization is chain-attested identity: the
+   kernel-stamped binary name PLUS the supervision chain**, both read from
+   the kernel's process records (`ProcessDescriptor` carries `name` and
+   `supervisor`; init walks the chain with `process_enumerate` — no new
+   protocol). A grant row names the binary *and* the supervisor expected
+   in its chain, so a malicious process re-spawning a granted binary
+   (ungated `spawn`, hostile argv — the confused deputy) is refused: its
+   chain roots at the attacker, not at init or device-manager. Name alone
+   is NOT sufficient — that was considered and rejected (2026-07-31).
+   Pure delegation (device-manager forwarding driver binds as
+   capabilities — "option B") is deliberately deferred to P5, whose
+   spawner-wired namespaces subsume it. Amends protocol-namespace.md's
+   "Authorization" bullet in P2.
+3. **Grants live in a new manifest, `/system/configuration/protocol.csv`**
+   (rows: `binary-path, supervisor, bind|open, protocol-name`, where
+   `supervisor` is the binary expected in the caller's supervision chain —
+   `init` for init's own children, `kernel` for harness-spawned fixtures),
+   not in extra init.csv columns — today every post-path init.csv field is
+   argv, and overloading that is ambiguous. init parses both files.
+   *(P2 spelling: the supervisor column carries the binary exactly as the
+   kernel stamped it, so init's own children say `/system/services/init` and
+   the drivers say `/system/services/device-manager`; `kernel` stays a bare
+   word because a kernel task has no binary. A trailing `*` on any field
+   matches a subtree, which is how decision 4's `/test/` rule is expressed.)*
+   *(Clarification, 2026-08-01: the supervisor column names **the authorized
+   supervising task, matched by identity** — the binary is how the row spells
+   it, but init checks the task id. `kernel` is satisfied only by supervisor
+   id 0 (which only the kernel confers — user `system_spawn` always stamps the
+   caller); init's own path only by this init's task id; any other path only by
+   a task init spawned itself or one the kernel spawned. Matching the supervisor
+   by *name* alone is defeated by a laundering deputy — an attacker runs its own
+   instance of `/system/services/init`, has that spawn `/system/services/input`,
+   and both stamped names satisfy the row while the chain is entirely the
+   attacker's. Walking to the root of the chain does not fix it either, since
+   the laundered chain still roots at the real PID 1.)*
+   *(P3 amendment: a third permission, `supervise`, joins `bind|open`. One-hop
+   attestation cannot express the one three-deep chain in the tree — the device
+   manager starts the PS/2 bus, and the bus starts the keyboard and mouse
+   drivers — and nothing structural tells that chain apart from the laundering
+   deputy, since both are a granted binary spawned by a granted binary. Only
+   policy can: a `supervise` row names the authorized supervising task the way
+   every other row names a claimant (binary, its own supervisor, the contract it
+   concerns), and an `open` row may then name that task in its supervisor
+   column. The delegate is itself attested the ordinary strict way, so the chain
+   still anchors in init or the kernel one hop above it and the recursion stops
+   there. It is **open-only** on purpose — a delegate may vouch for what its
+   children *reach*, never for what they *claim* — so the bind path is
+   byte-for-byte P2's and the laundering-deputy refusal is untouched.)*
+4. **Test fixtures bind under `/protocol/test/...`**, granted to any
+   binary whose path starts `/test/` — the subtree-scoping rule from the
+   design doc, dogfooded. `shared_memory_test` (the borrowed-ServiceId
+   hack) becomes `/protocol/test/shared-memory`; process-test's child gets
+   `/protocol/test/process`.
+5. **Rebind after provider death:** a `bind` hitting an existing binding
+   succeeds only if the current owner process is dead (init checks
+   liveness); otherwise `-EBUSY`. Init also unbinds in `restartChild`
+   before respawning its own children. This preserves collision-refusal
+   while making restart work for providers init does not supervise.
+6. **Cross-thread service access** (the display mouse-listener's
+   per-thread self-lookup, `display.zig:512`): threads resolve and open
+   `/protocol/<name>` like any client — once, at thread startup. No
+   special mechanism.
+7. **The envelope module is `library/protocol/envelope/envelope.zig`**
+   (module name `envelope`) — the one protocol-package module not ending
+   in `-protocol`, because it is not a protocol. Wired as a new
+   `addModule` row in `library/protocol/build.zig` with its host tests in
+   that package's test step.
+8. **The QEMU harness gains `-cpu max`** (in `qemu_args`,
+   `test/qemu_test.py:66-83`) so TCG exposes SMEP/SMAP — without it the
+   enabled paths never execute in CI. Landed in H2 so the flag soaks
+   before H3 depends on it.
+9. **Scenario fixtures that need the registry are init-driven.** Kernel
+   test cases that today spawn providers directly (shared-memory,
+   process-test) either spawn init first or move to init.csv-driven
+   scenario boots — resolved per-case in P2 with the suite as the
+   arbiter.
+   *(P2 resolution: init gained a `registry` argv role — it mounts
+   `/protocol`, reads the grants, and starts no services — and each affected
+   case calls `spawnRegistry(rd)` before its own providers. Every case keeps
+   its own spawn set, so no scenario had to be re-shaped.)*
+10. **The capsule-staleness caveat is documented, not fixed.** On-volume
+    edits to `/system/configuration/*.csv` do not reach the initrd copy
+    the loader boots (capsule shadows tree). Same drift exists today with
+    `/etc`; PM adds the note to file-system-hierarchy.md and moves on.
+
+---
+
+## PM — path-migration flag-day
+
+One commit, everything moves together. The authoritative site inventory is
+the grounding pass; the checklist order:
+
+1. Move repo `etc/` → `configuration/` sources; fix the three CSVs'
+   self-referencing headers (`etc/init.csv:1,12`, `etc/devices.csv:1`,
+   `etc/init-diagnose.csv:1`).
+2. `build.zig:309-311`: bundled entries `etc/...` →
+   `system/configuration/...` (this alone re-shapes the image, manifest,
+   and capsule — `tools/make-fat-image.py` and the EFI loader need
+   nothing; the tree-walk fallback even starts picking the CSVs up, a
+   bonus fix).
+3. `system/kernel/vfs.zig` `mountBackend` (`:332-340`): allow exactly
+   `/system/configuration` and `/system/logs` as backend prefixes beneath
+   the initrd `/system` mount; keep refusing everything else under
+   `/system` and `/test`.
+4. `system/services/fat/fat.zig`: `mount_point` → `/volumes/usb` (`:25`);
+   replace the `/var` mount (`:155`) with two `mountRewritten` calls for
+   `/system/configuration` and `/system/logs`; update the mount log lines
+   (the harness matches them).
+5. `system/services/init/init.zig:76` and
+   `system/services/device-manager/device-manager.zig:48`: open the new
+   CSV paths; update the message strings (`init.zig:77,92`,
+   `device-manager.zig:49,61-63,454`).
+6. `system/services/logger/logger.zig:44`: `base = "/system/logs"`
+   (buffers derive from `base.len` comptime — nothing else changes).
+7. `system/kernel/tests.zig:2808-2810`: exclude `/system/configuration/`
+   from the spawn-everything sweep (the CSVs are not programs).
+8. Tests: `fat-test.zig` and `vfs-test.zig` `/mnt/usb` literals →
+   `/volumes/usb`; harness regexes `test/qemu_test.py:175,211,632,717`.
+9. Comment sweep (init, device-manager, logger, fat, engine, vfs, abi,
+   file-system, csv, device, protocol/device-manager, drivers, acpi,
+   build.zig — full list in the grounding inventory); delete vestigial
+   repo `var/`.
+
+**Test:** no new case — the existing 106 are the test, since fat/logger/
+init/device-manager scenarios all assert the new paths through their
+regexes. Suite stays 106.
+
+## H1 — user-memory copy discipline
+
+New kernel module `system/kernel/user-memory.zig`:
+
+- `copyFromUser` moves from ipc-synchronous.zig (which re-exports or
+  imports it); new `copyToUser(user_as, user_va, source) bool` — the
+  mechanical mirror (kernel-source `copyAcross` already does this for IPC
+  replies at `ipc-synchronous.zig:431,460`).
+- The page walk gains leaf U/S and writable checks: `paging.translateIn`
+  (`architecture/x86_64/paging.zig:513-525`) tests only `present` today —
+  add a flags-accumulating variant (2 MiB leaves included); reads require
+  U/S, writes require U/S+W. Closes the TODO at
+  `ipc-synchronous.zig:20-22`.
+- Convert the nine stragglers (table in smep-smap.md). Read direction is
+  local to `process.zig`; the write direction restructures callees with
+  kernel bounce buffers: `scheduler.enumerate` (`scheduler.zig:1209`),
+  `devices_broker.enumerate` (`devices-broker.zig:136`), `log.readAt`
+  (`log.zig:209`), and the `fs_node` flows through
+  `vfs.nodeRead/nodeStatus/nodeReaddir` (`vfs.zig:257/269/289`).
+
+**Test:** kernel unit coverage in `system/kernel/tests.zig` for
+`copyToUser` bounds/permission refusals; one new QEMU case `user-memory` —
+a fixture passes an unmapped-but-in-range buffer to `klog_read`,
+`process_enumerate`, and `fs_resolve` and asserts `-EFAULT` returns with
+the system still alive (today each would oops the kernel). Suite 107.
+
+## P1 — envelope, vfs additions, Channel
+
+- `library/protocol/envelope/envelope.zig`: `Header` {operation:u32, pad,
+  target:u64}, `Status`, reserved verbs (describe=0, enumerate=1,
+  subscribe=2, unsubscribe=3, protocol verbs from 16), `packet_maximum`
+  = 256 / `post_maximum` = 64 (the floor constants protocols compile
+  against — nothing exports them today), and comptime
+  `Define(.{name, version, operations, events})` generating request/reply
+  types, encode/decode, a provider dispatch table (automatic `describe`,
+  `-ENOSYS` for unknown verbs), and compile-time size checks: 
+  request/reply ≤ 256, each `.events` entry ≤ 64 *including* its Header
+  (decision 1). Host unit tests in the protocol package's test step.
+- `library/protocol/vfs/vfs-protocol.zig`: `NodeKind.protocol = 7`; the
+  open-reply-may-carry-capability convention documented in the module.
+  Rewrite the value-pinning unit test (`:108-117`) to pin the *new*
+  stable values.
+- `library/kernel/file-system.zig` + a new `Channel` type in
+  `library/kernel` (or `library/client`): `open("/protocol/<name>")` →
+  resolve, vfs open, receive the reply capability → a `Channel` wrapping
+  the handle with `call`/typed helpers. Nothing uses it yet — P2 converts
+  the world.
+- Docs: vfs-protocol.md's NodeKind table gains value 7 (no
+  protocol-namespace.md amendment — decision 1 conforms to it as written).
+
+**Test:** host unit tests only (envelope round-trips, size-check compile
+errors via `error` tests, Channel plumbing against a mock). Suite stays
+107.
+
+## P2 — the registry; ServiceId flag-day
+
+The single biggest phase; one branch, may be several commits, green at the
+end of each.
+
+- **init as registry backend** (`system/services/init/init.zig`): a second
+  endpoint (the supervision endpoint's reply-empty loop is unsuitable for
+  a vfs backend); serve vfs `open`/`readdir` over `/protocol` plus the
+  `bind` operation (name payload + capability). Mount `/protocol` before
+  spawning children. Parse `/system/configuration/protocol.csv`
+  (decision 3). Authorization by chain-attested identity (decision 2):
+  badge → kernel process records → binary name **and** supervision chain
+  (walk `supervisor` links) checked against the grant row's expected
+  supervisor. Unbind on child death in `restartChild`; dead-owner rebind
+  rule (decision 5).
+  Provenance: readdir/diagnostics show name → pid → binary path.
+- **Kernel:** reserve `/protocol` — `mountBackend` refuses mounts at or
+  under it once bound, `installMount`'s remount-replace path refuses it,
+  and `fs_unmount` refuses it (`vfs.zig:164-181,332-351`,
+  `process.zig:1879-1889`). First mount wins (init is PID 1).
+- **Harness:** `library/kernel/service.zig` `Callbacks.service:
+  ?abi.ServiceId` becomes a protocol name; the register call (`:49-51`)
+  becomes bind-with-retry via the registry.
+- **Flag-day conversion** — all 11 registration sites and 17 lookup sites
+  from the grounding inventory: providers (input:123, ps2-bus:223,
+  device-manager:569, acpi:193, usb-xhci-bus:676, usb-storage:205,
+  fat:307, display:699, virtio-gpu:550, shared-memory-server:43,
+  process-test:130 → `/protocol/test/...` per decision 4); clients
+  (input-client:53, display-client:28, driver.zig:173, usb.zig:139,
+  block.zig:72+87, ps2-bus keyboard:35 + mouse:34, virtio-gpu:478,
+  display:314+512 (decision 6), acpi:212, init:218+245 — init
+  short-circuits its own registry, shared-memory-client:22,
+  process-test:85, device-list:22, crash-test:32). Retry loops keep their
+  cadence, wrapping resolve+open instead of lookup.
+- **Delete:** `abi.zig:36-37` (syscall ids — leave holes),
+  `abi.zig:287-303` (enum), `process.zig:223-224,314-343`,
+  `ipc-synchronous.zig:41-43,646-664` and the registry sweep in
+  `:121-140`; the wrappers `library/kernel/ipc.zig:33-35,47-50`; comment
+  sweep (irq.zig:50, tests.zig:3744, vdso.md's syscall table, the docs
+  list in the inventory).
+- Kernel-spawned test scenarios made init-driven where they need the
+  registry (decision 9).
+
+**Test:** new QEMU case `protocol-registry`: a fixture asserts (a) bind of
+an ungranted name → `-EPERM`, (b) bind collision with a live owner →
+`-EBUSY`, (c) provider kill → re-resolve reaches the restarted instance.
+Every existing scenario doubles as conversion proof. Suite 108.
+
+## P3 — open grants (restriction stage one)
+
+- `protocol.csv` `open` rows enforced in the registry's `open` handler,
+  same name-based identity as bind. Default rows grant what today's
+  clients need (from the P2 conversion table); a deliberate hole for the
+  test fixture.
+- Docs: protocol-namespace.md stage-one section gets its "landed" line.
+
+**Test:** new QEMU case `protocol-denied`: a fixture granted
+`/protocol/test/shared-memory` but not `/protocol/display` asserts open of
+the first succeeds and the second fails identically to not-found. Suite
+109.
+
+*Landed. Four things the plan did not foresee, recorded because P4 and P5
+inherit them:*
+
+- *`supervise` — decision 3's amendment. The PS/2 keyboard and mouse drivers
+  are started by the PS/2 bus driver, which the device manager started: the
+  tree's one three-deep chain, and one hop deeper than attestation reaches.
+  Nothing structural separates it from the laundering deputy, so the manifest
+  says which delegate is authorized, per contract. Open-only, so P2's bind
+  attestation is unchanged.*
+- *Indistinguishability is a claim about work, not only about bytes. `onOpen`
+  refreshes the process table, identifies the caller, scans the grants and
+  scans the bindings on **every** open and forms one verdict at the end; and
+  it logs nothing on any branch, because `klog_read` is ungated (a line
+  written on one branch is a line the refused caller can read) and a serial
+  line is milliseconds it could time. The operator's diagnosis is the pair the
+  namespace publishes anyway: `readdir /protocol` for what is bound, the
+  manifest for who may reach it.*
+- *The fixture is `protocol-denied-test`, and its scenario boots the **input
+  service** so the forbidden name is genuinely bound — the fixture reads the
+  namespace listing to prove it before asking for it. Without a live provider
+  the case would be comparing two boot races and asserting nothing.*
+- *Two channels stay open by design, named rather than papered over: `readdir`
+  over `/protocol` lists every bound name to anyone (deliberate — the tree is
+  diagnosable), and `/system/configuration/protocol.csv` is world-readable on
+  the `/system` mount. Stage one hides neither the set of contracts nor the
+  policy; what it removes is the **oracle in the reply**, which is what stage
+  two's parked and faked opens depend on.*
+
+## P4a — clean protocols onto Define
+
+vfs, block, display, scanout, input — the modules whose shapes map
+directly (grounding inventory §1,3,4,6,8):
+
+- vfs: `node` → `target`; `Reply.node` (open's result) moves to reply
+  payload — `library/kernel/file-system.zig` decoders change; readdir
+  stays a protocol verb.
+- block: pure renumber; `attach`'s DMA cap rides the call as today.
+- display: the overloaded 40-byte `Request` becomes per-operation structs
+  (attach_scanout's field abuse dies); `layer` → `target`; blit payload
+  grows to 224 bytes.
+- scanout: renumber; drop its bogus `message_maximum=64` (sync floor is
+  256); fix virtio-gpu's hard-coded `service.run(256, …)` to the
+  generated constant.
+- input: subscribe merges into reserved subscribe; publish renumbers;
+  the event re-lays onto the Header folded (operation = event kind,
+  target = 0; 16 + 28-byte payload = 44 ≤ 64); **input moves onto the
+  service harness** (it is the last hand-rolled loop, no ping/terminate
+  compliance today).
+
+**Test:** new QEMU case `protocol-conformance`: a fixture opens every
+registered protocol and asserts `describe` answers (name, version) and an
+unknown verb returns `-ENOSYS`. Existing input/display/fat scenarios prove
+the rebase. Suite 110.
+
+## P4b — misfit protocols onto Define
+
+device-manager, power, usb-transfer (inventory §2,5,7 — the u8-operation
+re-layouts and raw-offset readers):
+
+- device-manager: u8 operations → Header; its enumerate=4/subscribe=5
+  merge into the reserved verbs; `ChildAdded` splits its dual role —
+  request struct and event, both Header-first (folded to 60 B ≤ 64);
+  `ChildRemoved`'s (parent, bus_address) addressing stays payload.
+- power: u8 operations → Header; subscribe merges; **init's raw
+  byte-offset event parsing (`init.zig:171-173`) and acpi's
+  `message[0]` dispatch (`acpi.zig:435-467`) are rewritten against the
+  generated types** — the two silent-breakage sites, called out so the
+  loop treats them as first-class conversions, not collateral.
+- usb-transfer: `device_token` → `target` (already layout-identical);
+  `InterruptReport` re-lays onto the Header (`device_token` → `target`,
+  inline data trimmed 48 → 40 — largest real report is 8); control/bulk
+  budgets re-verified by `Define` (Status absorbs `actual_length`).
+
+**Test:** existing scenarios are the proof (device hot-add, power button,
+USB storage/HID all exercise these wires); the conformance case now covers
+three more providers. Suite 110.
+
+## P4c — harness subscriber lift + badge scoping
+
+- `library/kernel/service.zig` grows the subscriber table, exit-
+  notification sweep, and fan-out loop declared via `Define(.events)`;
+  input (:33-116), acpi (:67-68,393-406), and device-manager (:155-166)
+  delete their hand-rolled variants. One sweep idiom: exit notifications
+  (fat's pattern), replacing input's process-list polling and acpi's
+  none-at-all.
+- Badge-scoped per-client integers (the guessable-id holes): fat node ids
+  gain owner checks on every operation (`fat.zig:72-76`), xhci device
+  tokens validate sender and sweep on exit (`usb-xhci-bus.zig:66-88,479`),
+  display layers gain an owner field.
+
+**Test:** extend the fat scenario: a second fixture guesses the first's
+node id and asserts refusal; kernel-side unit test for the harness sweep.
+Suite 111.
+
+## H2 — SMEP
+
+- Generalize the cpuid helper (`apic.zig:351-365`, private, subleaf-0) to
+  a shared probe; gate on `cpuid(0).eax >= 7`.
+- Set CR4 bit 20 in `per-cpu.zig:initSystemCall` (or a sibling called
+  from both `cpu.zig:148` and `smp.zig:181` — the one path both BSP and
+  every AP already execute). Log enabled/absent (fail-open, IOMMU style).
+- Harness: add `-cpu max` to `qemu_args` (decision 8).
+
+**Test:** new QEMU case `fault-smep` mirroring the `fault-*` injector
+pattern (`tests.zig:3906-3938`): ring-0 call through a pointer into a
+user-mapped page; expect `page fault (vector 14)` + `error code : 0x11` +
+kernel-half IP, machine reports the exception (deliberate-exception cases
+put the text in `expect`, per `qemu_test.py:189`). Suite 112.
+
+## HS — SYSRET canonical-RIP guard
+
+- `isr.s` syscall exit (`:256`): validate RCX canonicality before
+  `sysretq`; non-canonical → `iretq` fallback (or kill), per the hazard
+  note at `isr.s:192-194`.
+
+**Test:** kernel unit case driving a thread whose return RIP is forged
+non-canonical via the syscall path if constructible cheaply; otherwise the
+review-level proof plus the existing fault cases regression. Suite 112.
+
+## H3 — SMAP
+
+- `clac` patch site at `isr_common` (`isr.s:367`, before the CPL test —
+  ring-0 nesting inherits AC too): assemble a 3-byte NOP, patch to `clac`
+  at boot through the physmap (the `process.zig:1990-1995` /
+  `smp.zig:79-111` precedent), BSP-only before AP bring-up.
+- Set CR4 bit 21 in the same per-CPU init as SMEP.
+- Coding standards: kernel code touches user memory only through
+  `user-memory`; no `stac` anywhere, ever.
+
+**Test:** new QEMU case `fault-smap`: ring-0 deliberate read of a mapped
+user page; expect vector 14 + `error code : 0x1` + kernel IP. And the
+whole suite becomes the tripwire — any missed straggler now fails loudly.
+Suite 113.
+
+---
+
+**Explicitly out of scope** (own tracks, after this plan): P5 restriction
+stage two (spawn's initial capability, namespace views, parked replies,
+dedicated killable channels — needs a design session on the spawn
+contract), file-path namespacing, trusted UI (display track), pipes/FIFOs
+(Python track), `/applications` and its storage, `fs_mount`/`spawn`/
+`klog_read` gating beyond the `/protocol` reserved prefix, KPTI, IPC
+priority inheritance.

docs/system-requirements.md

@@ -95,9 +95,9 @@ hypervisor configured for UEFI firmware and an xHCI USB controller.
 
 | Requirement | Detail | Source |
 |---|---|---|
-| **x86-64, 64-bit only** | Kernel and loader are built exclusively for `x86_64`; the loader rejects any non-x86-64 kernel ELF (`error.WrongArchitecture`). | `build.zig:481`, `boot/efi.zig:622` |
+| **x86-64, 64-bit only** | Kernel and loader are built exclusively for `x86_64`; the loader rejects any non-x86-64 kernel ELF (`error.WrongArchitecture`). | `build-support/build.zig` (`freestandingTarget`), `boot/efi.zig:622` |
 | **Long mode + PAE + NX** | AP trampoline sets `CR4.PAE`, `EFER.LME`, `EFER.NXE`; NX is used in kernel page-table entries. | `system/kernel/architecture/x86_64/trampoline.s:62` |
-| **SSE / SSE2** | Baseline: the compiler emits SSE for ordinary struct copies. Trampoline enables `CR4.OSFXSR` + `OSXMMEXCPT` and clears `CR0.EM`. | `build.zig:477`, `trampoline.s:62` |
+| **SSE / SSE2** | Baseline: the compiler emits SSE for ordinary struct copies. Trampoline enables `CR4.OSFXSR` + `OSXMMEXCPT` and clears `CR0.EM`. | `build-support/build.zig` (`freestandingTarget`), `trampoline.s:62` |
 | **`syscall` / `sysret`** | Primary user↔kernel entry path. `EFER.SCE` enabled; `STAR`/`LSTAR`/`SFMASK` programmed per core. (`int 0x80` exists as a parallel gate.) | `architecture/x86_64/per-cpu.zig:71`, `isr.s:196` |
 | **Local APIC (xAPIC)** | LAPIC accessed via MMIO at `0xFEE00000`. LAPIC ID read as a `u8` — classic xAPIC. **x2APIC is not supported** (no MSR path). | `apic.zig:67`, `apic.zig:646` |
 | **CPUID + RDTSC** | CPUID leaf `0x15` for TSC frequency; RDTSC is the monotonic clock. | `apic.zig:333`, `apic.zig:113` |
@@ -108,7 +108,7 @@ hypervisor configured for UEFI firmware and an xHCI USB controller.
 - **UEFI only.** A custom UEFI application loader is installed to
   `\EFI\BOOT\BOOTX64.efi`. There is **no BIOS, multiboot, or limine** path. The
   loader tolerates UEFI Class-3 machines with no legacy PIC/PIT.
-  (`build.zig:246`, `boot/efi.zig`)
+  (`build/images.zig` — the EFI/BOOT install — and `boot/efi.zig`)
 - **ACPI is the hardware-discovery mechanism.** The RSDP is taken from the UEFI
   configuration table (ACPI 2.0 GUID preferred, 1.0 fallback). Without a valid
   RSDP there is **no device discovery** — no SMP, no IOAPIC routing, no PCI/USB.

docs/testing.md

@@ -12,7 +12,9 @@ There are two layers:
   `system/abi.zig`, `library/device/model/device-abi.zig`) now spans ~26 modules:
   protocol and on-wire definitions (VFS, USB, virtio-gpu), the FAT engine, the
   display compositor, PS/2 and HID decoding, the kernel log ring, and the
-  runtime's `time`/`thread` — the full list is the test step in `build.zig`.
+  runtime's `time`/`thread` — the list is distributed across the library-domain
+  and binary packages' own `test` steps, which the root `zig build test`
+  aggregates (docs/build-packages-plan.md).
   These compile for the host and run natively.
 - **QEMU integration tests** (`python3 test/qemu_test.py`) — boot the real kernel
   and check its behaviour. This is the interesting part.

docs/zig-self-hosting.md

@@ -347,7 +347,7 @@ Two current decisions fall out of this roadmap:
 - [syscall.md](os-development/syscall.md) — the kernel↔runtime ABI `runtime.os` is built on.
 - [sysv.md](os-development/sysv.md) — the entry stack (`argc/argv/envp/auxv`) danos already constructs.
 - [ipc.md](device-driver-development/ipc.md) — the IPC the VFS/FAT operations travel over.
-- [danos-file-system-hierarchy-FSH.md](file-system-development/danos-file-system-hierarchy-FSH.md) — the
+- [file-system-hierarchy.md](file-system-development/file-system-hierarchy.md) — the
   filesystem layout the file surface serves.
 - [coding-standards.md](coding-standards.md) — danos naming (why the compat spellings
   are confined, and now retired).

library/client/build.zig

@@ -0,0 +1,38 @@
+//! The "client" library domain (library/client): userspace-service clients —
+//! they talk to services over IPC, not to the kernel. Client modules end in
+//! `-client` the way wire protocols end in `-protocol`, so a service, its
+//! protocol, and its client never share a name (`display` the service,
+//! `display-protocol` the wire contract, `display-client` a program's view).
+
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const kernel = b.dependency("kernel", .{});
+    const protocol = b.dependency("protocol", .{});
+
+    const ipc = kernel.module("ipc");
+    const time = kernel.module("time");
+
+    _ = b.addModule("display-client", .{
+        .root_source_file = b.path("display/display-client.zig"),
+        .imports = &.{
+            .{ .name = "ipc", .module = ipc },
+            .{ .name = "time", .module = time },
+            .{ .name = "display-protocol", .module = protocol.module("display-protocol") },
+        },
+    });
+    _ = b.addModule("input-client", .{
+        .root_source_file = b.path("input/input-client.zig"),
+        .imports = &.{
+            .{ .name = "ipc", .module = ipc },
+            .{ .name = "time", .module = time },
+            .{ .name = "input-protocol", .module = protocol.module("input-protocol") },
+        },
+    });
+
+    // Standalone `zig build test`, kept for uniformity across the domains (the
+    // root aggregate depends on every domain's test step). The clients have no
+    // host-runnable unit tests yet — they are thin IPC conversation wrappers —
+    // so the step is empty until one grows some.
+    _ = b.step("test", "Run the client unit tests (none yet)");
+}

library/client/build.zig.zon

@@ -0,0 +1,13 @@
+.{
+    .name = .client,
+    .version = "0.0.0",
+    .fingerprint = 0xc74404553e73d4ff, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{
+        // The clients converse over ipc with time-bounded waits.
+        .kernel = .{ .path = "../kernel" },
+        // Each client speaks its service's wire protocol.
+        .protocol = .{ .path = "../protocol" },
+    },
+    .paths = .{""},
+}

library/csv/build.zig

@@ -0,0 +1,20 @@
+//! The "csv" library domain: shared CSV helpers (comment stripping, field
+//! iteration) for the /system/configuration/*.csv config files — the device registry and the
+//! init service list both parse them.
+
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    _ = b.addModule("csv", .{ .root_source_file = b.path("csv.zig") });
+
+    // Standalone `zig build test` for this domain alone; the root build keeps
+    // its aggregate test step.
+    const test_step = b.step("test", "Run the csv unit tests");
+    const csv_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("csv.zig"),
+            .target = b.resolveTargetQuery(.{}),
+        }),
+    });
+    test_step.dependOn(&b.addRunArtifact(csv_tests).step);
+}

library/csv/build.zig.zon

@@ -0,0 +1,8 @@
+.{
+    .name = .csv,
+    .version = "0.0.0",
+    .fingerprint = 0x8a4525791f4e5b6, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{},
+    .paths = .{""},
+}

library/csv/csv.zig

@@ -1,5 +1,5 @@
-//! Minimal CSV helpers shared by the `/etc/*.csv` config files — the device
-//! registry (`/etc/devices.csv`) and the init service list (`/etc/init.csv`).
+//! Minimal CSV helpers shared by the `/system/configuration/*.csv` config files — the device
+//! registry (`/system/configuration/devices.csv`) and the init service list (`/system/configuration/init.csv`).
 //! Freestanding, no allocator: returned fields are slices into the source line,
 //! so the source must outlive them. `#` starts a comment (whole-line or trailing);
 //! whitespace around a field is trimmed, so columns may be padded for alignment.

library/device/build.zig

@@ -0,0 +1,137 @@
+//! The "device" library domain (library/device): what a driver author imports.
+//! The flat reference data (device-abi, pci-class, acpi-ids, usb-abi, usb-ids),
+//! typed MMIO access, the driver-side client libraries (driver, pci, usb,
+//! block), the AML interpreter, and the data-driven device registry.
+
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const kernel = b.dependency("kernel", .{});
+    const protocol = b.dependency("protocol", .{});
+    const csv = b.dependency("csv", .{});
+
+    const abi = kernel.module("abi");
+    const system_call = kernel.module("system-call");
+    const ipc = kernel.module("ipc");
+    const time = kernel.module("time");
+
+    // The devices sub-project's public interface (the flat wire types),
+    // importable by user space, unlike the kernel-internal device model it
+    // also feeds (system/kernel/device-model.zig).
+    const device_abi = b.addModule("device-abi", .{
+        .root_source_file = b.path("model/device-abi.zig"),
+    });
+    // PCI class-code decoding (class/subclass/prog-IF -> names). Pure reference
+    // data, shared by kernel discovery and any user-space PCI tool.
+    const pci_class = b.addModule("pci-class", .{
+        .root_source_file = b.path("pci/pci-class.zig"),
+    });
+    // ACPI/PnP hardware-ID (_HID) names — the flat analog of pci-class.
+    _ = b.addModule("acpi-ids", .{
+        .root_source_file = b.path("acpi/acpi-ids.zig"),
+    });
+    // The AML interpreter, a build module so the ring-3 acpi service can run
+    // the same parser the kernel does (docs/discovery.md). Pure Zig, no kernel
+    // imports — one source, two builds.
+    _ = b.addModule("aml", .{
+        .root_source_file = b.path("acpi/aml/aml.zig"),
+    });
+    // The USB device-framework wire ABI (chapter-9 set-up packets, standard +
+    // class requests, descriptors) and the USB class-code taxonomy.
+    const usb_abi = b.addModule("usb-abi", .{
+        .root_source_file = b.path("usb/usb-abi.zig"),
+    });
+    const usb_ids = b.addModule("usb-ids", .{
+        .root_source_file = b.path("usb/usb-ids.zig"),
+    });
+    // Typed volatile MMIO register access + memory-ordering barriers, for
+    // drivers on top of an mmio_map grant. Depends only on `builtin`.
+    const mmio = b.addModule("mmio", .{
+        .root_source_file = b.path("mmio/mmio.zig"),
+    });
+    // The driver author's interface: device access + the device-manager hello
+    // handshake, folded together.
+    const driver = b.addModule("driver", .{
+        .root_source_file = b.path("driver/driver.zig"),
+        .imports = &.{
+            .{ .name = "abi", .module = abi },
+            .{ .name = "device-abi", .module = device_abi },
+            .{ .name = "system-call", .module = system_call },
+            .{ .name = "ipc", .module = ipc },
+            .{ .name = "time", .module = time },
+            .{ .name = "device-manager-protocol", .module = protocol.module("device-manager-protocol") },
+        },
+    });
+    // A device driver's view of its claimed PCI function: config-space header
+    // fields, BAR decode + map, capability walks (legacy + extended), MSI/MSI-X
+    // programming, power state, and function-level reset — the generic PCI
+    // mechanics every leaf PCI driver used to re-derive inline.
+    _ = b.addModule("pci", .{
+        .root_source_file = b.path("pci/pci.zig"),
+        .imports = &.{
+            .{ .name = "driver", .module = driver },
+            .{ .name = "mmio", .module = mmio },
+            .{ .name = "pci-class", .module = pci_class },
+            .{ .name = "time", .module = time },
+        },
+    });
+    // The USB class-driver transfer client: open a device on the xHCI bus and
+    // drive it (control / interrupt / bulk). Re-exports usb-abi / usb-ids as
+    // usb.abi / usb.ids for a single USB import.
+    _ = b.addModule("usb", .{
+        .root_source_file = b.path("usb/usb.zig"),
+        .imports = &.{
+            .{ .name = "ipc", .module = ipc },
+            .{ .name = "time", .module = time },
+            .{ .name = "usb-transfer-protocol", .module = protocol.module("usb-transfer-protocol") },
+            .{ .name = "usb-abi", .module = usb_abi },
+            .{ .name = "usb-ids", .module = usb_ids },
+        },
+    });
+    // The block-device client — a device type, so it lives here.
+    _ = b.addModule("block", .{
+        .root_source_file = b.path("block/block.zig"),
+        .imports = &.{
+            .{ .name = "ipc", .module = ipc },
+            .{ .name = "time", .module = time },
+            .{ .name = "block-protocol", .module = protocol.module("block-protocol") },
+        },
+    });
+    // The device registry: parse /system/configuration/devices.csv into match rules and bind a
+    // reported device to a driver. Pure logic (no hardware, no syscalls), so it
+    // unit-tests on the host; the device manager imports it.
+    _ = b.addModule("device-registry", .{
+        .root_source_file = b.path("registry/device-registry.zig"),
+        .imports = &.{.{ .name = "csv", .module = csv.module("csv") }},
+    });
+
+    // Standalone `zig build test` for this domain alone; the root build keeps
+    // its aggregate test step.
+    const test_step = b.step("test", "Run the device library unit tests");
+    for ([_][]const u8{
+        "model/device-abi.zig", // wire-type sizes
+        "pci/pci-class.zig", // class/subclass/prog-IF name decoding
+        "acpi/acpi-ids.zig", // _HID name decoding
+        "acpi/aml/aml.zig", // AML parse + interpret, incl. Notify dispatch
+        "usb/usb-abi.zig", // wire sizes + bit packings + set-up packet encodings
+        "usb/usb-ids.zig", // class/subclass/protocol code assignments
+        "mmio/mmio.zig", // barriers assemble + registers round-trip
+    }) |root| {
+        const device_tests = b.addTest(.{
+            .root_module = b.createModule(.{
+                .root_source_file = b.path(root),
+                .target = b.resolveTargetQuery(.{}),
+            }),
+        });
+        test_step.dependOn(&b.addRunArtifact(device_tests).step);
+    }
+    // The registry needs its csv import wired, so it doesn't fit the loop.
+    const registry_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("registry/device-registry.zig"),
+            .target = b.resolveTargetQuery(.{}),
+            .imports = &.{.{ .name = "csv", .module = csv.module("csv") }},
+        }),
+    });
+    test_step.dependOn(&b.addRunArtifact(registry_tests).step);
+}

library/device/build.zig.zon

@@ -0,0 +1,15 @@
+.{
+    .name = .device,
+    .version = "0.0.0",
+    .fingerprint = 0x92fb68eace23a4f, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{
+        // driver/block/usb/pci build on the kernel library's concern modules.
+        .kernel = .{ .path = "../kernel" },
+        // driver speaks device-manager-protocol; block/usb their transfer protocols.
+        .protocol = .{ .path = "../protocol" },
+        // device-registry parses /system/configuration/devices.csv with the shared csv helpers.
+        .csv = .{ .path = "../csv" },
+    },
+    .paths = .{""},
+}

library/device/model/device-abi.zig

@@ -126,7 +126,7 @@ pub const DeviceDescriptor = extern struct {
     // names with the pci-class module.
     pci_class: u64,
     // Numeric identity beyond the class triple, mirrored in the bus report's
-    // ChildAdded so /etc/devices.csv can bind on it: `vendor`/`device` are the PCI
+    // ChildAdded so /system/configuration/devices.csv can bind on it: `vendor`/`device` are the PCI
     // vendor/device (or USB idVendor/idProduct), `subsystem` is the PCI subsystem id
     // packed `(subsystem_vendor << 16) | subsystem_device`. Zero where the bus has no
     // such concept. Defaulted so existing descriptor literals keep compiling and lay

library/device/registry/device-registry.zig

@@ -1,4 +1,4 @@
-//! The device registry: parse `/etc/devices.csv` into match rules and bind a
+//! The device registry: parse `/system/configuration/devices.csv` into match rules and bind a
 //! reported device to a driver. This is the data-driven replacement for the
 //! device manager's three hand-written `switch` tables (`pciDriverForIdentity`,
 //! `hidDriverFor`, `usbDriverForIdentity`); the registry is now **authoritative**
@@ -11,7 +11,7 @@
 //! That keeps this module freestanding and unit-testable with plain `zig test`.
 //!
 //! The file format (docs/device-driver-development/device-manager.md, and the
-//! `/etc/devices.csv` header itself): one rule per line, nine comma-separated
+//! `/system/configuration/devices.csv` header itself): one rule per line, nine comma-separated
 //! fields, `#` starts a comment (whole-line or trailing), blank lines ignored.
 //!
 //!     bus, base, class, prog_if, vendor, device, subsystem, hid, driver
@@ -226,7 +226,7 @@ fn parseLine(line: []const u8) Line {
     } };
 }
 
-/// Parse a whole `/etc/devices.csv` into `out_rules`. The string fields of the
+/// Parse a whole `/system/configuration/devices.csv` into `out_rules`. The string fields of the
 /// returned rules point into `source`, which must outlive them.
 pub fn parse(source: []const u8, out_rules: []Rule) ParseResult {
     var result: ParseResult = .{ .count = 0, .malformed = 0, .truncated = false };

library/kernel/build.zig

@@ -0,0 +1,104 @@
+//! The "kernel" library domain (library/kernel): the userspace private-ABI
+//! library (kernel32-style), split by concern into directly-importable
+//! modules. The graph is a DAG: memory depends on thread (heap needs
+//! Thread.Mutex), and thread does its own raw mmap so there is no cycle.
+//!
+//! This package also exports `abi` — the kernel <-> user contract (SystemCall
+//! numbers, mmap prot flags, page_size). Its source lives with the kernel in
+//! system/abi.zig, outside this directory, but userspace's one view of it is
+//! exported here so every consumer names the same module instance. Reaching
+//! outside the package root means this package is valid only as an in-repo
+//! path dependency (never fetchable by hash) — fine, since path dependencies
+//! are the only way danos packages are consumed.
+//!
+//! The root shim (root.zig) and the user link script (user.ld) are plain
+//! files, not modules; build-support reaches them through this package's
+//! directory (Dependency.path).
+
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const protocol = b.dependency("protocol", .{});
+
+    const abi = b.addModule("abi", .{
+        .root_source_file = b.path("../../system/abi.zig"),
+    });
+    const system_call = b.addModule("system-call", .{
+        .root_source_file = b.path("system-call.zig"),
+        .imports = &.{.{ .name = "abi", .module = abi }},
+    });
+    const ipc = b.addModule("ipc", .{
+        .root_source_file = b.path("ipc.zig"),
+        .imports = &.{ .{ .name = "abi", .module = abi }, .{ .name = "system-call", .module = system_call } },
+    });
+    const time = b.addModule("time", .{
+        .root_source_file = b.path("time.zig"),
+        .imports = &.{.{ .name = "system-call", .module = system_call }},
+    });
+    const thread = b.addModule("thread", .{
+        .root_source_file = b.path("thread.zig"),
+        .imports = &.{ .{ .name = "abi", .module = abi }, .{ .name = "system-call", .module = system_call } },
+    });
+    const logging = b.addModule("logging", .{
+        .root_source_file = b.path("logging.zig"),
+        .imports = &.{ .{ .name = "abi", .module = abi }, .{ .name = "system-call", .module = system_call } },
+    });
+    const process = b.addModule("process", .{
+        .root_source_file = b.path("process.zig"),
+        .imports = &.{
+            .{ .name = "abi", .module = abi },
+            .{ .name = "system-call", .module = system_call },
+            .{ .name = "ipc", .module = ipc },
+            .{ .name = "time", .module = time },
+        },
+    });
+    _ = b.addModule("file-system", .{
+        .root_source_file = b.path("file-system.zig"),
+        .imports = &.{
+            .{ .name = "abi", .module = abi },
+            .{ .name = "system-call", .module = system_call },
+            .{ .name = "ipc", .module = ipc },
+            .{ .name = "vfs-protocol", .module = protocol.module("vfs-protocol") },
+        },
+    });
+    _ = b.addModule("memory", .{
+        .root_source_file = b.path("memory/memory.zig"),
+        .imports = &.{
+            .{ .name = "abi", .module = abi },
+            .{ .name = "system-call", .module = system_call },
+            .{ .name = "ipc", .module = ipc },
+            .{ .name = "thread", .module = thread },
+        },
+    });
+    _ = b.addModule("service", .{
+        .root_source_file = b.path("service.zig"),
+        .imports = &.{
+            .{ .name = "abi", .module = abi },
+            .{ .name = "ipc", .module = ipc },
+            .{ .name = "process", .module = process },
+        },
+    });
+    _ = b.addModule("start", .{
+        .root_source_file = b.path("start.zig"),
+        .imports = &.{ .{ .name = "process", .module = process }, .{ .name = "logging", .module = logging } },
+    });
+
+    // Standalone `zig build test` for this domain alone; the root build keeps
+    // its aggregate test step. time and thread pull in the syscall wrappers,
+    // which need the `abi` module; their danos seams fall back to host
+    // primitives off the danos target, so they run with real host threads.
+    const test_step = b.step("test", "Run the kernel library unit tests");
+    for ([_][]const u8{
+        "time.zig", // Instant/Duration arithmetic
+        "thread.zig", // Mutex/Condition/RwLock/WaitGroup state machines
+    }) |root| {
+        const kernel_tests = b.addTest(.{
+            .root_module = b.createModule(.{
+                .root_source_file = b.path(root),
+                .target = b.resolveTargetQuery(.{}),
+                .imports = &.{.{ .name = "abi", .module = abi }},
+            }),
+        });
+        test_step.dependOn(&b.addRunArtifact(kernel_tests).step);
+    }
+}

library/kernel/build.zig.zon

@@ -0,0 +1,11 @@
+.{
+    .name = .kernel,
+    .version = "0.0.0",
+    .fingerprint = 0x5dd29aab36503453, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{
+        // file-system speaks the VFS wire protocol.
+        .protocol = .{ .path = "../protocol" },
+    },
+    .paths = .{""},
+}

library/kernel/file-system.zig

@@ -305,7 +305,7 @@ pub fn makePath(path: []const u8) bool {
         while (end < path.len and path[end] != '/') end += 1;
         const prefix = path[0..end];
         if (prefix.len == 0 or (prefix.len == 1 and prefix[0] == '/')) continue;
-        // Best-effort per prefix: components at or above a mount point ("/mnt")
+        // Best-effort per prefix: components at or above a mount point ("/volumes")
         // are router names, not filesystem nodes — they neither exist as nodes
         // nor accept mkdir, and that is fine. Only the final verdict counts.
         if (!exists(prefix)) _ = makeDirectory(prefix);
@@ -348,8 +348,9 @@ pub fn mount(target: []const u8, backend: ipc.Handle) bool {
 }
 
 /// As `mount`, with a backend-side rewrite prefix: a path under `target` reaches
-/// the backend as `rewrite` + the mount-relative tail. How one volume serves two
-/// mounts ("/mnt/usb" from its root, "/var" from its /var subtree).
+/// the backend as `rewrite` + the mount-relative tail. How one volume serves
+/// several mounts ("/volumes/usb" from its root, "/system/logs" from its
+/// /system/logs subtree).
 pub fn mountRewritten(target: []const u8, backend: ipc.Handle, rewrite: []const u8) bool {
     return fsMount(target, backend, rewrite);
 }

library/protocol/build.zig

@@ -0,0 +1,46 @@
+//! The "protocol" library domain: the wire protocols — each service's public
+//! interface, exposed as its own module (docs/driver-model.md). Both sides of
+//! every conversation depend on the contract by name; neither reaches into the
+//! other's files. Pure flat wire types: no protocol module imports anything.
+//!
+//!   vfs-protocol             : the VFS server <-> the file layer (unistd/stdio)
+//!   input-protocol           : the input fan-out service <-> sources + subscribers
+//!   block-protocol           : a filesystem <-> a block driver (usb-storage)
+//!   usb-transfer-protocol    : a USB class driver <-> the xHCI bus driver
+//!   device-manager-protocol  : the device manager <-> drivers + discovery
+//!   display-protocol         : the compositor's client-facing surface
+//!   scanout-protocol         : the compositor -> a native scanout driver (docs/display-v2.md)
+//!   power-protocol           : system power's domain-named surface (docs/power.md)
+
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    for ([_]struct { name: []const u8, root: []const u8 }{
+        .{ .name = "vfs-protocol", .root = "vfs/vfs-protocol.zig" },
+        .{ .name = "input-protocol", .root = "input/input-protocol.zig" },
+        .{ .name = "block-protocol", .root = "block/block-protocol.zig" },
+        .{ .name = "usb-transfer-protocol", .root = "usb-transfer/usb-transfer-protocol.zig" },
+        .{ .name = "device-manager-protocol", .root = "device-manager/device-manager-protocol.zig" },
+        .{ .name = "display-protocol", .root = "display/display-protocol.zig" },
+        .{ .name = "scanout-protocol", .root = "scanout/scanout-protocol.zig" },
+        .{ .name = "power-protocol", .root = "power/power-protocol.zig" },
+    }) |protocol| {
+        _ = b.addModule(protocol.name, .{ .root_source_file = b.path(protocol.root) });
+    }
+
+    // Standalone `zig build test` for this domain alone; the root build keeps
+    // its aggregate test step.
+    const test_step = b.step("test", "Run the protocol unit tests");
+    for ([_][]const u8{
+        "vfs/vfs-protocol.zig", // NodeKind / DirectoryEntry sizes + op values
+        "display/display-protocol.zig", // pack(): native pixel encoding per format
+    }) |root| {
+        const protocol_tests = b.addTest(.{
+            .root_module = b.createModule(.{
+                .root_source_file = b.path(root),
+                .target = b.resolveTargetQuery(.{}),
+            }),
+        });
+        test_step.dependOn(&b.addRunArtifact(protocol_tests).step);
+    }
+}

library/protocol/build.zig.zon

@@ -0,0 +1,8 @@
+.{
+    .name = .protocol,
+    .version = "0.0.0",
+    .fingerprint = 0xc8c0bc4c4d551283, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{},
+    .paths = .{""},
+}

library/protocol/device-manager/device-manager-protocol.zig

@@ -12,7 +12,7 @@
 pub const version: u16 = 1;
 
 /// Which bus a `child_added` came from — stated by the reporting bus driver so
-/// the manager's /etc/devices.csv matcher knows how to read the report's identity
+/// the manager's /system/configuration/devices.csv matcher knows how to read the report's identity
 /// (a PCI class triple vs a USB class triple are the same 24 bits but different
 /// namespaces) and which `bus` column a rule must name to bind it. `unknown` is
 /// the zero default, so an un-upgraded reporter fails to match rather than
@@ -96,7 +96,7 @@ pub const ChildAdded = extern struct {
     /// for an unregistered leaf (a USB port before the descriptor track).
     device_id: u64 = no_device,
     /// The vendor id (PCI vendor / USB idVendor), or 0 when the bus has no such
-    /// concept (ACPI). Carried so the manager's /etc/devices.csv matcher can bind
+    /// concept (ACPI). Carried so the manager's /system/configuration/devices.csv matcher can bind
     /// on vendor — a level the bus-native `identity` (a class triple) cannot express.
     vendor: u16 = 0,
     /// The device id (PCI device / USB idProduct), or 0. The most specific numeric

library/protocol/vfs/vfs-protocol.zig

@@ -33,8 +33,8 @@ pub const Operation = enum(u32) {
     rename, // rename(old\0new payload) -> status
 };
 
-/// The type of a filesystem node, aligned to the FSH file-type table
-/// (docs/danos-file-system-hierarchy-FSH.md). Fills `FileStatus.kind` and
+/// The type of a filesystem node, aligned to the node-kind table
+/// (docs/file-system-development/file-system-hierarchy.md). Fills `FileStatus.kind` and
 /// `DirectoryEntry.kind`; `regular = 0` keeps the historical hardcoded value.
 pub const NodeKind = enum(u32) {
     regular = 0,

library/xkeyboard-config/build.zig

@@ -0,0 +1,31 @@
+//! The "xkeyboard-config" library domain: keyboard layouts compiled from the
+//! X11 xkeyboard-config database into native Zig (keycode + modifiers ->
+//! keysym/character). The `layouts` tables are generated by
+//! tools/make-xkeyboard-config.py; `xkeyboard-config` is the hand-written API
+//! over them.
+
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const layouts = b.addModule("layouts", .{
+        .root_source_file = b.path("generated/layouts.zig"),
+    });
+    _ = b.addModule("xkeyboard-config", .{
+        .root_source_file = b.path("xkeyboard-config.zig"),
+        .imports = &.{.{ .name = "layouts", .module = layouts }},
+    });
+
+    // Standalone `zig build test` for this domain alone; the root build keeps
+    // its aggregate test step. The keycode->character assertions are the
+    // end-to-end proof that the xkb-data -> generator -> Zig-lookup pipeline
+    // is correct.
+    const test_step = b.step("test", "Run the xkeyboard-config unit tests");
+    const xkb_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("xkeyboard-config.zig"),
+            .target = b.resolveTargetQuery(.{}),
+            .imports = &.{.{ .name = "layouts", .module = layouts }},
+        }),
+    });
+    test_step.dependOn(&b.addRunArtifact(xkb_tests).step);
+}

library/xkeyboard-config/build.zig.zon

@@ -0,0 +1,8 @@
+.{
+    .name = .xkeyboard_config,
+    .version = "0.0.0",
+    .fingerprint = 0xea5abe82f08b6eae, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{},
+    .paths = .{""},
+}

system/abi.zig

@@ -295,7 +295,7 @@ pub const ServiceId = enum(u32) {
     power = 5, // system power: events (button, lid, battery) + shutdown (docs/power.md; domain-named per docs/discovery.md — the acpi service registers it on x86, a PSCI service will on ARM)
     usb_bus = 6, // the xHCI host-controller driver's transfer endpoint; USB class drivers look it up and `callCap`-open their device to get a private per-device transfer channel (docs/driver-model.md)
     block = 7, // a block-device driver (USB mass storage today): read/write of fixed-size blocks, the storage a filesystem sits on
-    fat = 8, // the FAT filesystem server; the VFS mounts it and forwards paths under its mount point (/mnt/usb) to it
+    fat = 8, // the FAT filesystem server; the VFS mounts it and forwards paths under its mount point (/volumes/usb) to it
     display = 9, // the display service: owns the framebuffer, composites a layer stack, presents frames (docs/display.md)
     shared_memory_test = 10, // the shared-memory test server (V2): a client passes it a shared-memory capability, it maps + verifies (docs/display-v2.md)
     scanout = 11, // a native scanout driver (virtio-gpu): the compositor finds it here to upgrade off the GOP framebuffer (docs/display-v2.md)

system/configuration/devices.csv

@@ -1,4 +1,4 @@
-# /etc/devices.csv — the device→driver registry.
+# /system/configuration/devices.csv — the device→driver registry.
 #
 # The device manager reads this at boot and binds each device a bus driver
 # reports to the driver named here. It is AUTHORITATIVE: a device that no row

system/configuration/init-diagnose.csv

@@ -1,9 +1,10 @@
-# /etc/init.csv — diagnose variant (-Ddiagnose), bundled at /etc/init.csv.
+# /system/configuration/init.csv — diagnose variant (-Ddiagnose), bundled at
+# /system/configuration/init.csv.
 #
 # The display stack (display, display-demo) is omitted so the kernel's timestamped
 # on-screen boot transcript is never suppressed — the bring-up timeline (USB,
-# storage, logger) stays readable on real hardware with no serial. See etc/init.csv
-# for the format; this file must otherwise track it.
+# storage, logger) stays readable on real hardware with no serial. See
+# system/configuration/init.csv for the format; this file must otherwise track it.
 #
 # service                          args...
 /system/services/input

system/configuration/init.csv

@@ -1,4 +1,4 @@
-# /etc/init.csv — the services init (PID 1) starts at boot, in order.
+# /system/configuration/init.csv — the services init (PID 1) starts at boot, in order.
 #
 # init reads this at startup and spawns each service supervised (restarting it on
 # a crash, up to a cap). Startup order is top->bottom; shutdown is the reverse, so
@@ -9,7 +9,7 @@
 # '#' starts a comment (whole-line or trailing); blank lines are ignored. The
 # first field is the service binary path; any fields after it are the service's
 # argv. Drivers are absent on purpose — the device manager discovers hardware and
-# spawns those (see /etc/devices.csv).
+# spawns those (see /system/configuration/devices.csv).
 #
 # service                          args...
 /system/services/input

system/drivers/pci-bus/build.zig

@@ -0,0 +1,18 @@
+//! The pci-bus driver as a binary package (docs/build-packages-plan.md):
+//! this file names the binary and EXACTLY the modules its source imports —
+//! build-support resolves each name from the domains this zon declares.
+
+const std = @import("std");
+const build_support = @import("build-support");
+
+pub fn build(b: *std.Build) void {
+    const exe = build_support.userBinary(b, .{
+        .name = "pci-bus",
+        .root_source_file = b.path("pci-bus.zig"),
+        .imports = &.{
+            "device-manager-protocol", "driver", "ipc", "logging", "memory", "pci-class",
+            "process", "service",
+        },
+    });
+    b.installArtifact(exe);
+}

system/drivers/pci-bus/build.zig.zon

@@ -0,0 +1,16 @@
+.{
+    .name = .pci_bus,
+    .version = "0.0.0",
+    .fingerprint = 0x283fca121f0bb145, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{
+        // build-support supplies the shared recipe; kernel is implicit in
+        // every binary (the root shim + link script live there). The rest
+        // are exactly the homes of this binary's declared imports.
+        .@"build-support" = .{ .path = "../../../build-support" },
+        .kernel = .{ .path = "../../../library/kernel" },
+        .device = .{ .path = "../../../library/device" },
+        .protocol = .{ .path = "../../../library/protocol" },
+    },
+    .paths = .{""},
+}

system/drivers/pci-bus/pci-bus.zig

@@ -21,7 +21,7 @@ const logging = @import("logging");
 const device_manager_protocol = @import("device-manager-protocol");
 const pci_class = @import("pci-class");
 
-/// Log a discovered function as its would-be /etc/devices.csv columns (bus, base,
+/// Log a discovered function as its would-be /system/configuration/devices.csv columns (bus, base,
 /// class, prog_if, vendor, device, subsystem) followed by the human-readable
 /// class/subclass/prog-IF names — so a row for a new driver reads straight off the
 /// boot log. `subsystem` prints as `*` when the function has none, matching the CSV
@@ -154,7 +154,7 @@ fn registerAndReport(bus: u64, dev: u64, function: u64, class_triple: u32) void
     descriptor.class = @intFromEnum(device.DeviceClass.pci_device);
     descriptor.pci_class = class_triple;
     // Vendor/device from the first config dword (0x00): low half vendor, high half
-    // device. These carry to the manager's /etc/devices.csv matcher so a function
+    // device. These carry to the manager's /system/configuration/devices.csv matcher so a function
     // can bind on its exact 1AF4:1050 identity, not just its class triple.
     const vendor_device = configRead(bus, dev, function, 0x00);
     descriptor.vendor = @truncate(vendor_device);

system/drivers/ps2-bus/build.zig

@@ -0,0 +1,50 @@
+//! The ps2-bus driver as a binary package (docs/build-packages-plan.md):
+//! this file names the binary and EXACTLY the modules its source imports —
+//! build-support resolves each name from the domains this zon declares.
+
+const std = @import("std");
+const build_support = @import("build-support");
+
+pub fn build(b: *std.Build) void {
+    const ps2_bus_exe = build_support.userBinary(b, .{
+        .name = "ps2-bus",
+        .root_source_file = b.path("ps2-bus.zig"),
+        .imports = &.{ "acpi-ids", "driver", "ipc", "logging", "memory", "process", "service", "time" },
+    });
+    b.installArtifact(ps2_bus_exe);
+
+    const ps2_keyboard_exe = build_support.userBinary(b, .{
+        .name = "ps2-keyboard",
+        .root_source_file = b.path("keyboard.zig"),
+        .imports = &.{
+            "acpi-ids", "driver", "input-client", "input-protocol", "ipc", "logging", "memory",
+            "process", "time", "xkeyboard-config",
+        },
+    });
+    b.installArtifact(ps2_keyboard_exe);
+
+    const ps2_mouse_exe = build_support.userBinary(b, .{
+        .name = "ps2-mouse",
+        .root_source_file = b.path("mouse.zig"),
+        .imports = &.{
+            "acpi-ids", "driver", "input-client", "input-protocol", "ipc", "logging", "memory",
+            "process", "time",
+        },
+    });
+    b.installArtifact(ps2_mouse_exe);
+
+    // Standalone `zig build test`; the root aggregate depends on this step.
+    const test_step = b.step("test", "Run the ps2-bus unit tests");
+    for ([_][]const u8{
+        "scancode.zig", // set-2 decode + keyboard state machine
+        "mouse-packet.zig", // 3-byte mouse packet assembly
+    }) |test_root| {
+        const unit_tests = b.addTest(.{
+            .root_module = b.createModule(.{
+                .root_source_file = b.path(test_root),
+                .target = b.resolveTargetQuery(.{}),
+            }),
+        });
+        test_step.dependOn(&b.addRunArtifact(unit_tests).step);
+    }
+}

system/drivers/ps2-bus/build.zig.zon

@@ -0,0 +1,18 @@
+.{
+    .name = .ps2_bus,
+    .version = "0.0.0",
+    .fingerprint = 0x642a365353bf7de9, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{
+        // build-support supplies the shared recipe; kernel is implicit in
+        // every binary (the root shim + link script live there). The rest
+        // are exactly the homes of this binary's declared imports.
+        .@"build-support" = .{ .path = "../../../build-support" },
+        .kernel = .{ .path = "../../../library/kernel" },
+        .client = .{ .path = "../../../library/client" },
+        .device = .{ .path = "../../../library/device" },
+        .protocol = .{ .path = "../../../library/protocol" },
+        .@"xkeyboard-config" = .{ .path = "../../../library/xkeyboard-config" },
+    },
+    .paths = .{""},
+}

system/drivers/ps2-bus/keyboard.zig

@@ -19,7 +19,7 @@ const device = @import("driver");
 const ipc = @import("ipc");
 const process = @import("process");
 const time = @import("time");
-const input = @import("input");
+const input = @import("input-client");
 const memory = @import("memory");
 const logging = @import("logging");
 const xkb = @import("xkeyboard-config");

system/drivers/ps2-bus/mouse.zig

@@ -19,7 +19,7 @@ const device = @import("driver");
 const ipc = @import("ipc");
 const process = @import("process");
 const time = @import("time");
-const input = @import("input");
+const input = @import("input-client");
 const memory = @import("memory");
 const logging = @import("logging");
 const ps2 = @import("ps2-library.zig");

system/drivers/usb-hid/build.zig

@@ -0,0 +1,42 @@
+//! The usb-hid driver as a binary package (docs/build-packages-plan.md):
+//! this file names the binary and EXACTLY the modules its source imports —
+//! build-support resolves each name from the domains this zon declares.
+
+const std = @import("std");
+const build_support = @import("build-support");
+
+pub fn build(b: *std.Build) void {
+    const usb_hid_keyboard_exe = build_support.userBinary(b, .{
+        .name = "usb-hid-keyboard",
+        .root_source_file = b.path("keyboard.zig"),
+        .imports = &.{
+            "driver", "input-client", "input-protocol", "ipc", "logging", "process", "service",
+            "usb", "usb-abi", "xkeyboard-config",
+        },
+    });
+    b.installArtifact(usb_hid_keyboard_exe);
+
+    const usb_hid_mouse_exe = build_support.userBinary(b, .{
+        .name = "usb-hid-mouse",
+        .root_source_file = b.path("mouse.zig"),
+        .imports = &.{
+            "driver", "input-client", "input-protocol", "ipc", "logging", "process", "service",
+            "usb", "usb-abi",
+        },
+    });
+    b.installArtifact(usb_hid_mouse_exe);
+
+    // Standalone `zig build test`; the root aggregate depends on this step.
+    const test_step = b.step("test", "Run the usb-hid unit tests");
+    for ([_][]const u8{
+        "hid-report.zig", // HID boot-report keyboard/mouse decode
+    }) |test_root| {
+        const unit_tests = b.addTest(.{
+            .root_module = b.createModule(.{
+                .root_source_file = b.path(test_root),
+                .target = b.resolveTargetQuery(.{}),
+            }),
+        });
+        test_step.dependOn(&b.addRunArtifact(unit_tests).step);
+    }
+}

system/drivers/usb-hid/build.zig.zon

@@ -0,0 +1,18 @@
+.{
+    .name = .usb_hid,
+    .version = "0.0.0",
+    .fingerprint = 0x66328b738fffff01, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{
+        // build-support supplies the shared recipe; kernel is implicit in
+        // every binary (the root shim + link script live there). The rest
+        // are exactly the homes of this binary's declared imports.
+        .@"build-support" = .{ .path = "../../../build-support" },
+        .kernel = .{ .path = "../../../library/kernel" },
+        .client = .{ .path = "../../../library/client" },
+        .device = .{ .path = "../../../library/device" },
+        .protocol = .{ .path = "../../../library/protocol" },
+        .@"xkeyboard-config" = .{ .path = "../../../library/xkeyboard-config" },
+    },
+    .paths = .{""},
+}

system/drivers/usb-hid/keyboard.zig

@@ -18,7 +18,7 @@ const std = @import("std");
 const ipc = @import("ipc");
 const process = @import("process");
 const service = @import("service");
-const input = @import("input");
+const input = @import("input-client");
 const device_manager = @import("driver");
 const logging = @import("logging");
 const usb = @import("usb");

system/drivers/usb-hid/mouse.zig

@@ -14,7 +14,7 @@ const std = @import("std");
 const ipc = @import("ipc");
 const process = @import("process");
 const service = @import("service");
-const input = @import("input");
+const input = @import("input-client");
 const device_manager = @import("driver");
 const logging = @import("logging");
 const usb = @import("usb");

system/drivers/usb-storage/build.zig

@@ -0,0 +1,33 @@
+//! The usb-storage driver as a binary package (docs/build-packages-plan.md):
+//! this file names the binary and EXACTLY the modules its source imports —
+//! build-support resolves each name from the domains this zon declares.
+
+const std = @import("std");
+const build_support = @import("build-support");
+
+pub fn build(b: *std.Build) void {
+    const exe = build_support.userBinary(b, .{
+        .name = "usb-storage",
+        .root_source_file = b.path("usb-storage.zig"),
+        .imports = &.{
+            "block-protocol", "driver", "ipc", "logging", "memory", "process", "service",
+            "time", "usb",
+        },
+    });
+    b.installArtifact(exe);
+
+    // Standalone `zig build test`; the root aggregate depends on this step.
+    const test_step = b.step("test", "Run the usb-storage unit tests");
+    for ([_][]const u8{
+        "bulk-only-transport.zig", // CBW/CSW wrapper sizes
+        "scsi.zig", // SCSI CDB encodings (big-endian)
+    }) |test_root| {
+        const unit_tests = b.addTest(.{
+            .root_module = b.createModule(.{
+                .root_source_file = b.path(test_root),
+                .target = b.resolveTargetQuery(.{}),
+            }),
+        });
+        test_step.dependOn(&b.addRunArtifact(unit_tests).step);
+    }
+}

system/drivers/usb-storage/build.zig.zon

@@ -0,0 +1,16 @@
+.{
+    .name = .usb_storage,
+    .version = "0.0.0",
+    .fingerprint = 0xce09fdc4c50bb4fe, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{
+        // build-support supplies the shared recipe; kernel is implicit in
+        // every binary (the root shim + link script live there). The rest
+        // are exactly the homes of this binary's declared imports.
+        .@"build-support" = .{ .path = "../../../build-support" },
+        .kernel = .{ .path = "../../../library/kernel" },
+        .device = .{ .path = "../../../library/device" },
+        .protocol = .{ .path = "../../../library/protocol" },
+    },
+    .paths = .{""},
+}

system/drivers/usb-xhci-bus/build.zig

@@ -0,0 +1,19 @@
+//! The usb-xhci-bus driver as a binary package (docs/build-packages-plan.md):
+//! this file names the binary and EXACTLY the modules its source imports —
+//! build-support resolves each name from the domains this zon declares.
+
+const std = @import("std");
+const build_support = @import("build-support");
+
+pub fn build(b: *std.Build) void {
+    const exe = build_support.userBinary(b, .{
+        .name = "usb-xhci-bus",
+        .root_source_file = b.path("usb-xhci-bus.zig"),
+        .imports = &.{
+            "device-manager-protocol", "driver", "input-client", "ipc", "logging", "memory",
+            "mmio", "pci", "process", "service", "time", "usb-abi", "usb-ids",
+            "usb-transfer-protocol",
+        },
+    });
+    b.installArtifact(exe);
+}

system/drivers/usb-xhci-bus/build.zig.zon

@@ -0,0 +1,17 @@
+.{
+    .name = .usb_xhci_bus,
+    .version = "0.0.0",
+    .fingerprint = 0x46d21373f05f6b20, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{
+        // build-support supplies the shared recipe; kernel is implicit in
+        // every binary (the root shim + link script live there). The rest
+        // are exactly the homes of this binary's declared imports.
+        .@"build-support" = .{ .path = "../../../build-support" },
+        .kernel = .{ .path = "../../../library/kernel" },
+        .client = .{ .path = "../../../library/client" },
+        .device = .{ .path = "../../../library/device" },
+        .protocol = .{ .path = "../../../library/protocol" },
+    },
+    .paths = .{""},
+}

system/drivers/usb-xhci-bus/usb-xhci-bus.zig

@@ -19,7 +19,7 @@ const ipc = @import("ipc");
 const process = @import("process");
 const service = @import("service");
 const time = @import("time");
-const input = @import("input");
+const input = @import("input-client");
 const device_manager = @import("driver");
 const memory = @import("memory");
 const logging = @import("logging");
@@ -459,7 +459,7 @@ fn reportInterface(manager: ipc.Handle, port: u32, interface: library.InterfaceI
         return null;
     };
     // The devices.csv columns (bus=usb, and the class triple as base/class/prog_if)
-    // then the human-readable interface name — a would-be /etc/devices.csv row read
+    // then the human-readable interface name — a would-be /system/configuration/devices.csv row read
     // straight off the boot log.
     std.log.info("port {d} interface {d}  bus=usb base={X:0>2} class={X:0>2} prog_if={X:0>2}  —  {s}  registered as device {d}", .{
         port,

system/drivers/virtio-gpu/build.zig

@@ -0,0 +1,33 @@
+//! The virtio-gpu driver as a binary package (docs/build-packages-plan.md):
+//! this file names the binary and EXACTLY the modules its source imports —
+//! build-support resolves each name from the domains this zon declares.
+
+const std = @import("std");
+const build_support = @import("build-support");
+
+pub fn build(b: *std.Build) void {
+    const exe = build_support.userBinary(b, .{
+        .name = "virtio-gpu",
+        .root_source_file = b.path("virtio-gpu.zig"),
+        .imports = &.{
+            "display-protocol", "driver", "ipc", "logging", "memory", "mmio", "pci", "process",
+            "scanout-protocol", "service", "time",
+        },
+    });
+    b.installArtifact(exe);
+
+    // Standalone `zig build test`; the root aggregate depends on this step.
+    const test_step = b.step("test", "Run the virtio-gpu unit tests");
+    for ([_][]const u8{
+        "virtio-gpu-protocol.zig", // virtio-gpu command struct sizes
+        "virtio-pci.zig", // virtio 1.0 PCI transport struct sizes
+    }) |test_root| {
+        const unit_tests = b.addTest(.{
+            .root_module = b.createModule(.{
+                .root_source_file = b.path(test_root),
+                .target = b.resolveTargetQuery(.{}),
+            }),
+        });
+        test_step.dependOn(&b.addRunArtifact(unit_tests).step);
+    }
+}

system/drivers/virtio-gpu/build.zig.zon

@@ -0,0 +1,16 @@
+.{
+    .name = .virtio_gpu,
+    .version = "0.0.0",
+    .fingerprint = 0xfb704899c18b9a23, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{
+        // build-support supplies the shared recipe; kernel is implicit in
+        // every binary (the root shim + link script live there). The rest
+        // are exactly the homes of this binary's declared imports.
+        .@"build-support" = .{ .path = "../../../build-support" },
+        .kernel = .{ .path = "../../../library/kernel" },
+        .device = .{ .path = "../../../library/device" },
+        .protocol = .{ .path = "../../../library/protocol" },
+    },
+    .paths = .{""},
+}

system/drivers/virtio-gpu/virtio-gpu.zig

@@ -205,7 +205,7 @@ fn initialise(endpoint: ipc.Handle) bool {
         return false;
     };
 
-    // Config space is resource 0. The registry (/etc/devices.csv) bound this driver by the
+    // Config space is resource 0. The registry (/system/configuration/devices.csv) bound this driver by the
     // exact virtio-gpu identity (vendor 0x1AF4 / device 0x1050), so there is no re-confirm to
     // do here any more — map config space and enable memory-space decode + bus mastering (the
     // device DMAs the ring and backing out of RAM; pci-bus only preserves whatever the firmware

system/kernel/acpi.zig

@@ -106,12 +106,6 @@ pub const PlatformInformation = struct {
     /// INCLUDE_PCI_ALL (the catch-all unit; falls back to the first), or the AMD-Vi
     /// IOMMU's control-register base from the first IVHD.
     iommu_base: u64 = 0,
-    /// The unit's Version register (offset 0x00) — its low byte is major.minor;
-    /// reading it back nonzero confirms a real, mappable VT-d unit.
-    iommu_version: u32 = 0,
-    /// The unit's Capability register (offset 0x08): supported address widths, number
-    /// of domains, etc. Consumed by the IOMMU core when it enables translation.
-    iommu_capabilities: u64 = 0,
     /// Whether the selected unit carries INCLUDE_PCI_ALL. False means every unit is
     /// device-scoped (unusual) — the core still enables on the selected unit but
     /// devices outside its scope remain untranslated.
@@ -502,7 +496,7 @@ fn handleTable(device_tree: *DeviceTree, hal: Hal, sdt_physical: u64) !void {
     } else if (std.mem.eql(u8, &sig, &SPCR)) {
         parseSpcr(header);
     } else if (std.mem.eql(u8, &sig, &DMAR)) {
-        parseDmar(hal, header);
+        parseDmar(header);
     } else if (std.mem.eql(u8, &sig, &IVRS)) {
         parseIvrs(header);
     } else if (std.mem.eql(u8, &sig, &SSDT)) {
@@ -822,7 +816,7 @@ const scope_path_offset = 6;
 /// and records single-path endpoint RMRRs for the IOMMU core to pre-map before it
 /// enables translation. Multi-hop RMRR scopes are skipped loudly: better a named gap
 /// than a silent one.
-fn parseDmar(hal: Hal, header: *const SystemDescriptorTableHeader) void {
+fn parseDmar(header: *const SystemDescriptorTableHeader) void {
     const base: [*]align(1) const u8 = @ptrCast(header);
     const total: usize = header.length;
 
@@ -840,13 +834,14 @@ fn parseDmar(hal: Hal, header: *const SystemDescriptorTableHeader) void {
                 const replace = !platform_information.iommu_present or
                     (include_all and !platform_information.iommu_include_all);
                 if (replace) {
+                    // Table facts only: the unit's registers are the IOMMU
+                    // backend's business (it maps and validates them at
+                    // detect) — discovery records where they live, never
+                    // reads them.
                     if (platform_information.iommu_present) platform_information.iommu_extra_units += 1;
-                    const regs = hal.mapMmio(register_base, abi.page_size, true);
                     platform_information.iommu_present = true;
                     platform_information.iommu_base = register_base;
                     platform_information.iommu_include_all = include_all;
-                    platform_information.iommu_version = @as(*const volatile u32, @ptrFromInt(regs + 0x00)).*;
-                    platform_information.iommu_capabilities = @as(*const volatile u64, @ptrFromInt(regs + 0x08)).*;
                 } else {
                     platform_information.iommu_extra_units += 1;
                 }

system/kernel/architecture/x86_64/cpu.zig

@@ -17,6 +17,11 @@ const io = @import("io.zig");
 const smp = @import("smp.zig");
 const pcpu = @import("per-cpu.zig");
 
+/// The x86-64 IOMMU backends (Intel VT-d, AMD-Vi) behind their dispatch
+/// surface — the architecture-neutral IOMMU core (system/kernel/iommu.zig)
+/// reaches the hardware only through this.
+pub const iommu = @import("iommu.zig");
+
 /// The saved register/trap frame passed to a fault handler.
 pub const CpuState = idt.CpuState;
 
@@ -252,6 +257,16 @@ pub fn translate(root: u64, virtual: u64) ?u64 {
     return paging.translateIn(root, virtual);
 }
 
+/// `translate` for an address the kernel is about to touch *on a process's
+/// behalf*: the walk additionally demands the permission ring 3 would need — the
+/// leaf user-accessible (U/S set at every level), and writable (R/W at every
+/// level) when `for_write`. Null means "the process itself could not do this",
+/// which the checked copy layer (system/kernel/user-memory.zig) turns into
+/// -EFAULT instead of a kernel dereference.
+pub fn translateUser(root: u64, virtual: u64, for_write: bool) ?u64 {
+    return paging.translateUserIn(root, virtual, for_write);
+}
+
 /// Map a page accessible from ring 3 (U/S bit at every level). The caller keeps
 /// W^X: code read-only + executable, data writable + no-execute.
 pub fn mapUserPage(virtual: u64, physical: u64, writable: bool, executable: bool) void {

system/kernel/architecture/x86_64/iommu-amd.zig

@@ -1,5 +1,6 @@
-//! system/kernel/iommu-amd.zig — AMD-Vi (AMD I/O Virtualization) backend for the IOMMU
-//! core. The AMD analogue of iommu-intel.zig: it supplies the core's `Backend` vtable
+//! AMD-Vi (AMD I/O Virtualization) backend for the IOMMU core, behind the
+//! architecture boundary. The AMD analogue of iommu-intel.zig: it supplies
+//! the architecture-neutral core's `Backend` vtable (iommu.zig beside this file)
 //! with AMD-Vi's page-table entry bits and drives the device table, command buffer, and
 //! event log.
 //!
@@ -14,10 +15,7 @@
 const std = @import("std");
 const abi = @import("abi");
 const boot_handoff = @import("boot-handoff");
-const pmm = @import("pmm.zig");
-const platform = @import("platform");
-const architecture = @import("architecture");
-const log = @import("log.zig");
+const paging = @import("paging.zig");
 const iommu = @import("iommu.zig");
 
 const page_size = abi.page_size;
@@ -88,10 +86,10 @@ fn ram(physical: u64) [*]volatile u64 {
 
 /// Map the register window, allocate the device table / command buffer / event log.
 /// Returns the vtable, or null if the boot-time allocations fail.
-pub fn detect(info: platform.PlatformInformation) ?iommu.Backend {
-    register_base = architecture.mapMmio(info.iommu_base, 16 * 1024, true);
+pub fn detect(discovery: iommu.Discovery) ?iommu.Backend {
+    register_base = paging.mapMmio(discovery.register_base, 16 * 1024, true);
 
-    device_table = pmm.allocContiguous(device_table_pages, ~@as(u64, 0)) orelse return null;
+    device_table = iommu.environment.allocateContiguous(device_table_pages, ~@as(u64, 0)) orelse return null;
     zero(device_table, device_table_pages); // all-zero DTE = V=0 = deny every device
     command_buffer = allocZeroedFrame() orelse return null;
     event_log = allocZeroedFrame() orelse return null;
@@ -100,6 +98,7 @@ pub fn detect(info: platform.PlatformInformation) ?iommu.Backend {
     return iommu.Backend{
         .levels = levels,
         .supports_huge_pages = false, // 4 KiB leaves only (AMD superpage encoding deferred)
+        .enable = enable,
         .makeLeaf = makeLeaf,
         .makeTable = makeTable,
         .isPresent = isPresent,
@@ -114,7 +113,7 @@ pub fn detect(info: platform.PlatformInformation) ?iommu.Backend {
 /// Program the base registers and enable translation. The device table is already
 /// zeroed (every device denied) except any entries `attach` wrote for RMRR/claimed
 /// devices, so turning translation on blocks all other DMA and logs it.
-pub fn enable() void {
+fn enable() void {
     write64(reg_device_table_base, (device_table & address_mask) | (device_table_pages - 1));
     write64(reg_command_buffer_base, (command_buffer & address_mask) | (ring_length_code << 56));
     write64(reg_event_log_base, (event_log & address_mask) | (ring_length_code << 56));
@@ -126,6 +125,12 @@ pub fn enable() void {
     // Buffers first, then the master enable.
     write64(reg_control, control_command_buffer_enable | control_event_log_enable);
     write64(reg_control, control_command_buffer_enable | control_event_log_enable | control_iommu_enable);
+
+    iommu.environment.write("/system/kernel: iommu online (AMD-Vi) — UNTESTED on real AMD hardware (QEMU-verified only)\n");
+    var buffer: [48]u8 = undefined;
+    if (std.fmt.bufPrint(&buffer, "  levels     : {d} (48-bit)\n", .{levels})) |line|
+        iommu.environment.write(line)
+    else |_| {}
 }
 
 // --- Backend vtable ------------------------------------------------------------------
@@ -195,13 +200,14 @@ fn faultDrain() usize {
 fn logFault(source: u16, address: u64) void {
     if (fault_log_budget == 0) return;
     fault_log_budget -= 1;
-    log.print("DANOS-IOMMU-FAULT: bdf={x:0>2}:{x:0>2}.{d} addr=0x{x} reason=amd-io-page-fault\n", .{
+    var buffer: [128]u8 = undefined;
+    if (std.fmt.bufPrint(&buffer, "DANOS-IOMMU-FAULT: bdf={x:0>2}:{x:0>2}.{d} addr=0x{x} reason=amd-io-page-fault\n", .{
         source >> 8,
         (source >> 3) & 0x1F,
         source & 0x7,
         address,
-    });
-    if (fault_log_budget == 0) log.write("DANOS-IOMMU-FAULT: (further faults suppressed)\n");
+    })) |line| iommu.environment.write(line) else |_| {}
+    if (fault_log_budget == 0) iommu.environment.write("DANOS-IOMMU-FAULT: (further faults suppressed)\n");
 }
 
 // --- command ring --------------------------------------------------------------------
@@ -240,7 +246,7 @@ fn completeAndWait() void {
         if (spins > 100_000) {
             if (!completion_warned) {
                 completion_warned = true;
-                log.write("/system/kernel: AMD-Vi COMPLETION_WAIT store not observed — proceeding (QEMU processes commands synchronously)\n");
+                iommu.environment.write("/system/kernel: AMD-Vi COMPLETION_WAIT store not observed — proceeding (QEMU processes commands synchronously)\n");
             }
             return;
         }
@@ -248,7 +254,7 @@ fn completeAndWait() void {
 }
 
 fn allocZeroedFrame() ?u64 {
-    const frame = pmm.alloc() orelse return null;
+    const frame = iommu.environment.allocateFrame() orelse return null;
     zero(frame, 1);
     return frame;
 }

system/kernel/architecture/x86_64/iommu-intel.zig

@@ -1,7 +1,7 @@
-//! system/kernel/iommu-intel.zig — Intel VT-d backend for the IOMMU core.
+//! Intel VT-d backend for the IOMMU core, behind the architecture boundary.
 //!
-//! Provides the core (iommu.zig) with the VT-d hardware specifics behind its `Backend`
-//! vtable: second-level page-table entry bits, the root/context table structure, the
+//! Provides the architecture-neutral core (system/kernel/iommu.zig) with the VT-d
+//! hardware specifics behind the `Backend` vtable (iommu.zig beside this file): second-level page-table entry bits, the root/context table structure, the
 //! translation-enable and invalidation register sequences, and the fault drain. The
 //! core owns the domain table and the page-table walk; this file owns the registers.
 //!
@@ -15,10 +15,7 @@
 const std = @import("std");
 const abi = @import("abi");
 const boot_handoff = @import("boot-handoff");
-const pmm = @import("pmm.zig");
-const platform = @import("platform");
-const architecture = @import("architecture");
-const log = @import("log.zig");
+const paging = @import("paging.zig");
 const iommu = @import("iommu.zig");
 
 const page_size = abi.page_size;
@@ -66,6 +63,7 @@ const slpte_page_size: u64 = 1 << 7; // a 2 MiB leaf (== iommu.huge_leaf_bit)
 const address_mask: u64 = 0x000F_FFFF_FFFF_F000;
 
 var register_base: usize = 0;
+var version: u32 = 0;
 var capabilities: u64 = 0;
 var extended_capabilities: u64 = 0;
 var coherent: bool = true; // ECAP.C — whether clflush is unnecessary
@@ -97,11 +95,15 @@ fn tableAt(physical: u64) [*]volatile u64 {
 }
 
 /// Map the register window, read caps, pick the address width. Returns the vtable, or
-/// null when the unit advertises no address width danos can drive.
-pub fn detect(info: platform.PlatformInformation) ?iommu.Backend {
-    // Remap 16 KiB: FRCD and IOTLB registers can sit past the first page (CAP.FRO /
-    // ECAP.IRO are 16-byte-unit offsets). Idempotent with the detection-time mapping.
-    register_base = architecture.mapMmio(info.iommu_base, 16 * 1024, true);
+/// null when the unit is not live or advertises no address width danos can drive.
+pub fn detect(discovery: iommu.Discovery) ?iommu.Backend {
+    // Map 16 KiB: FRCD and IOTLB registers can sit past the first page (CAP.FRO /
+    // ECAP.IRO are 16-byte-unit offsets).
+    register_base = paging.mapMmio(discovery.register_base, 16 * 1024, true);
+    // The Version register's low byte is major.minor; reading it back nonzero is
+    // the live-mappable-unit sanity check (previously a kernel-test assertion).
+    version = read32(0x00);
+    if (version == 0) return null;
     capabilities = read64(reg_cap);
     extended_capabilities = read64(reg_ecap);
     coherent = (extended_capabilities & ecap_coherent) != 0;
@@ -122,6 +124,7 @@ pub fn detect(info: platform.PlatformInformation) ?iommu.Backend {
     return iommu.Backend{
         .levels = levels,
         .supports_huge_pages = true,
+        .enable = enable,
         .makeLeaf = makeLeaf,
         .makeTable = makeTable,
         .isPresent = isPresent,
@@ -137,7 +140,7 @@ pub fn detect(info: platform.PlatformInformation) ?iommu.Backend {
 /// and populated the RMRR domains (their context entries are live via `attach`), so at
 /// this instant every OTHER device's context entry is not-present and will fault — which
 /// for stale firmware bus-mastering is the desired evidence, not a bug.
-pub fn enable() void {
+fn enable() void {
     write64(reg_rtaddr, root_table); // legacy mode (bits 11:10 = 00)
     setGlobalCommand(gcmd_srtp);
     spinStatus(gsts_rtps);
@@ -145,6 +148,15 @@ pub fn enable() void {
     setGlobalCommand(gcmd_te);
     spinStatus(gsts_tes);
     gcmd_shadow |= gcmd_te;
+
+    iommu.environment.write("/system/kernel: iommu online (Intel VT-d)\n");
+    var buffer: [64]u8 = undefined;
+    if (std.fmt.bufPrint(&buffer, "  version    : 0x{x}\n", .{version})) |line|
+        iommu.environment.write(line)
+    else |_| {}
+    if (std.fmt.bufPrint(&buffer, "  agaw       : {d} levels\n", .{levels})) |line|
+        iommu.environment.write(line)
+    else |_| {}
 }
 
 // --- Backend vtable ------------------------------------------------------------------
@@ -241,16 +253,17 @@ fn faultDrain() usize {
 fn logFault(source: u16, address: u64, reason: u8, is_read: bool) void {
     if (fault_log_budget > 0) {
         fault_log_budget -= 1;
-        log.print("DANOS-IOMMU-FAULT: bdf={x:0>2}:{x:0>2}.{d} addr=0x{x} reason=0x{x} write={d}\n", .{
+        var buffer: [128]u8 = undefined;
+        if (std.fmt.bufPrint(&buffer, "DANOS-IOMMU-FAULT: bdf={x:0>2}:{x:0>2}.{d} addr=0x{x} reason=0x{x} write={d}\n", .{
             source >> 8,
             (source >> 3) & 0x1F,
             source & 0x7,
             address,
             reason,
             @intFromBool(!is_read),
-        });
+        })) |line| iommu.environment.write(line) else |_| {}
         if (fault_log_budget == 0)
-            log.write("DANOS-IOMMU-FAULT: (further faults suppressed)\n");
+            iommu.environment.write("DANOS-IOMMU-FAULT: (further faults suppressed)\n");
     } else {
         faults_suppressed += 1;
     }
@@ -269,7 +282,7 @@ fn spinStatus(bit: u32) void {
     while (read32(reg_gsts) & bit == 0) {
         spins += 1;
         if (spins > 10_000_000) {
-            log.write("/system/kernel: WARNING VT-d status bit never set — translation may be incomplete\n");
+            iommu.environment.write("/system/kernel: WARNING VT-d status bit never set — translation may be incomplete\n");
             return;
         }
     }
@@ -306,7 +319,7 @@ fn iotlbOffset() usize {
 }
 
 fn allocZeroed() ?u64 {
-    const frame = pmm.alloc() orelse return null;
+    const frame = iommu.environment.allocateFrame() orelse return null;
     const table = tableAt(frame);
     var i: usize = 0;
     while (i < 512) : (i += 1) table[i] = 0;

system/kernel/architecture/x86_64/iommu.zig

@@ -0,0 +1,77 @@
+//! x86-64 IOMMU backends, behind the architecture boundary: Intel VT-d
+//! (iommu-intel.zig) and AMD-Vi (iommu-amd.zig). The architecture-neutral
+//! core (system/kernel/iommu.zig) owns the domain table and the shared
+//! page-table walker; it hands this file the firmware discovery facts and an
+//! environment (frame allocation + the log sink, injected the same way
+//! enablePaging receives its frame hooks), and gets back a hardware vtable.
+//! A new architecture supplies its own unit (ARM: the SMMU) from its own
+//! directory with no core change.
+
+const intel = @import("iommu-intel.zig");
+const amd = @import("iommu-amd.zig");
+
+/// What the platform's firmware tables reported: where the unit's registers
+/// live, and which programming model its table implies (an IVRS table
+/// describes AMD-Vi; a DMAR table describes Intel VT-d).
+pub const Discovery = struct {
+    register_base: u64,
+    amd: bool,
+};
+
+/// What the backends need from the generic kernel, injected at detect so this
+/// module never imports kernel internals: physical-frame allocation for the
+/// hardware structures, and the kernel log sink (fault reports, warnings, the
+/// enable banner).
+pub const Environment = struct {
+    allocateFrame: *const fn () ?u64,
+    allocateContiguous: *const fn (count: usize, max_physical: u64) ?u64,
+    write: *const fn (bytes: []const u8) void,
+};
+
+/// The bit encodings and hardware operations a backend supplies to the shared
+/// core. Entry helpers build the raw page-table entries for the backend's
+/// format; the core walks the tree with them. The hardware ops act on a whole
+/// domain (identified by its hardware domain id = core index + 1) or device
+/// (by requester id / bdf).
+pub const Backend = struct {
+    /// Number of page-table levels (3 or 4) the backend selected from hardware caps.
+    levels: u8,
+    /// Largest leaf the walker may emit: 4 KiB always, 2 MiB when the backend allows.
+    supports_huge_pages: bool,
+
+    /// Raw entry bits for a leaf mapping `physical` (with the given size), and for a
+    /// non-leaf entry pointing at `table_physical` at `level` (level counts down to 1
+    /// at the leaf's parent). `isPresent` tests a read-back entry.
+    makeLeaf: *const fn (physical: u64, huge: bool) u64,
+    makeTable: *const fn (table_physical: u64, level: u8) u64,
+    isPresent: *const fn (entry: u64) bool,
+    /// Flush a cache line holding IOMMU structures the hardware reads non-coherently
+    /// (VT-d with ECAP.C==0). A no-op where the unit snoops caches.
+    flushStructure: *const fn (address: usize) void,
+
+    /// Turn translation on (the core has already seeded any pre-claim domains)
+    /// and write the unit's identity lines to the log — the core follows with
+    /// the neutral posture lines.
+    enable: *const fn () void,
+    /// Point `bdf`'s translation structure at `domain` (hardware id) and invalidate the
+    /// context/device caches so the change takes effect.
+    attach: *const fn (bdf: u16, domain: u16, page_table_root: u64) void,
+    /// Return `bdf`'s translation structure to not-present + invalidate — all its DMA
+    /// faults afterward.
+    detach: *const fn (bdf: u16) void,
+    /// Invalidate cached translations for `domain` (after a map or unmap).
+    invalidateDomain: *const fn (domain: u16) void,
+    /// Pull pending faults out of the hardware, log them (rate-limited), return the
+    /// count seen this call.
+    faultDrain: *const fn () usize,
+};
+
+/// The injected kernel services, stored for the backends at detect time.
+pub var environment: Environment = undefined;
+
+/// Probe the discovered unit and return its vtable, or null when it is
+/// unusable (the core stays fail-open and says so).
+pub fn detect(discovery: Discovery, injected: Environment) ?Backend {
+    environment = injected;
+    return if (discovery.amd) amd.detect(discovery) else intel.detect(discovery);
+}

system/kernel/architecture/x86_64/paging.zig

@@ -524,6 +524,58 @@ pub fn translateIn(pml4: u64, virtual: u64) ?u64 {
     return (pte & address_mask) | (virtual & (page_size - 1));
 }
 
+/// `translateIn` with the ring-3 permission bits enforced: the walk accumulates
+/// the protection flags of every level it descends through and refuses the
+/// translation unless the *effective* permission allows the access ring 3 would
+/// be allowed — U/S set at every level, and (for `for_write`) R/W set at every
+/// level too. A bit cleared anywhere on the path denies, which is exactly how
+/// the MMU combines them, so a checked kernel copy sees the same permissions the
+/// process itself does.
+///
+/// This is the walk `system/kernel/user-memory.zig` copies through, and the
+/// reason a kernel copy can never be steered at a kernel-only mapping or made to
+/// write a read-only user page (a process's own text, say).
+///
+/// Huge pages: a 2 MiB PDE leaf resolves like `translateIn`, with its own U/S and
+/// R/W folded into the accumulator first. A PDPTE with PS set (a 1 GiB leaf) is
+/// refused rather than descended into — danos never builds one, and denying is
+/// the safe direction for a permission-checked walk.
+pub fn translateUserIn(pml4: u64, virtual: u64, for_write: bool) ?u64 {
+    // Start all-ones and AND in each level: a cleared bit at any level denies.
+    var effective: u64 = ~@as(u64, 0);
+
+    const pml4e = tableAt(pml4)[(virtual >> 39) & 0x1FF];
+    if (pml4e & present == 0) return null;
+    effective &= pml4e;
+
+    const pdpte = tableAt(pml4e & address_mask)[(virtual >> 30) & 0x1FF];
+    if (pdpte & present == 0) return null;
+    if (pdpte & page_size_bit != 0) return null; // 1 GiB leaf: never built here, refuse
+    effective &= pdpte;
+
+    const pde = tableAt(pdpte & address_mask)[(virtual >> 21) & 0x1FF];
+    if (pde & present == 0) return null;
+    effective &= pde;
+    if (pde & page_size_bit != 0) { // 2 MiB huge leaf: frame base is bits 51:21
+        if (!permits(effective, for_write)) return null;
+        return (pde & address_mask & ~@as(u64, huge_page_size - 1)) | (virtual & (huge_page_size - 1));
+    }
+
+    const pte = tableAt(pde & address_mask)[(virtual >> 12) & 0x1FF];
+    if (pte & present == 0) return null;
+    effective &= pte;
+    if (!permits(effective, for_write)) return null;
+    return (pte & address_mask) | (virtual & (page_size - 1));
+}
+
+/// Whether accumulated walk flags allow a ring-3 access: user-accessible always,
+/// and writable when the access is a store.
+fn permits(effective: u64, for_write: bool) bool {
+    if (effective & user == 0) return false;
+    if (for_write and effective & writable == 0) return false;
+    return true;
+}
+
 fn invalidate(virtual: u64) void {
     // invlpg needs its operand via a register-indirect memory reference that Zig
     // inline asm won't form directly, so stage the address in a register first.

system/kernel/devices-broker.zig

@@ -132,13 +132,31 @@ fn record(node: *platform.Device, parent_id: u64) u64 {
 }
 
 /// Copy up to `out.len` device descriptors into `out`; returns the total count
-/// available (which may exceed `out.len`).
+/// available (which may exceed `out.len`). For kernel callers with a buffer big
+/// enough to take the whole table in one go.
 pub fn enumerate(out: []device_abi.DeviceDescriptor) usize {
-    const n = @min(count, out.len);
-    @memcpy(out[0..n], devices[0..n]);
+    _ = enumerateFrom(0, out);
     return count;
 }
 
+/// How many devices the table holds — the total `device_enumerate` reports back
+/// however few of them fit in the caller's buffer.
+pub fn deviceCount() usize {
+    return count;
+}
+
+/// Copy up to `out.len` descriptors starting at table index `start`, returning how
+/// many were filled (0 once `start` reaches the end). The chunked form: the
+/// `device_enumerate` system call bounces the table out through a small kernel
+/// buffer, one chunk at a time, because a descriptor is far too big to stage a
+/// whole user-requested array of them on a 16 KiB kernel stack.
+pub fn enumerateFrom(start: usize, out: []device_abi.DeviceDescriptor) usize {
+    if (start >= count) return 0;
+    const n = @min(count - start, out.len);
+    @memcpy(out[0..n], devices[start..][0..n]);
+    return n;
+}
+
 /// Take exclusive ownership of device `id` for task `owner`. Fails if the id is
 /// out of range or already claimed.
 pub fn claim(id: u64, owner: u32) bool {

system/kernel/iommu.zig

@@ -1,5 +1,6 @@
-//! system/kernel/iommu.zig — vendor-neutral IOMMU core: per-device DMA translation
-//! domains over an Intel VT-d or AMD-Vi backend.
+//! system/kernel/iommu.zig — architecture-neutral IOMMU core: per-device DMA
+//! translation domains over a backend the architecture module supplies
+//! (x86-64: Intel VT-d or AMD-Vi, behind architecture/x86_64/iommu.zig).
 //!
 //! The problem this closes: without an IOMMU, a claimed bus-mastering device can DMA to
 //! ANY physical address, so a compromised or buggy driver reaches all of memory through
@@ -13,11 +14,12 @@
 //!     physical address they program into hardware; a domain simply makes that same
 //!     address the ONLY thing the device can reach. No IOVA allocator, and every
 //!     driver's register-programming code is untouched.
-//!   - **Vendor-neutral**: this file owns the domain table and a shared 512-entry
-//!     page-table walker; a `Backend` vtable supplies the hardware specifics (VT-d in
-//!     iommu-intel.zig, AMD-Vi in iommu-amd.zig) — the entry-bit encodings, the
-//!     enable/invalidate register dances, and the fault drain.
-//!   - **Fail-open**: when no IOMMU is found, `kind == .none` and every entry point is a
+//!   - **Architecture-neutral**: this file owns the domain table and a shared
+//!     512-entry page-table walker; the architecture module's `Backend` vtable
+//!     supplies the hardware specifics — the entry-bit encodings, the
+//!     enable/invalidate register dances, and the fault drain — with the frame
+//!     allocator and log sink injected the other way.
+//!   - **Fail-open**: when no IOMMU is found, nothing activates and every entry point is a
 //!     success no-op, so callers in process.zig stay unconditional and behavior is
 //!     byte-for-byte the pre-IOMMU kernel. The boot log states the posture.
 //!
@@ -29,54 +31,18 @@ const abi = @import("abi");
 const boot_handoff = @import("boot-handoff");
 const pmm = @import("pmm.zig");
 const platform = @import("platform");
+const architecture = @import("architecture");
 const devices_broker = @import("devices-broker.zig");
 const log = @import("log.zig");
-const intel = @import("iommu-intel.zig");
-const amd = @import("iommu-amd.zig");
 
 const page_size: u64 = abi.page_size;
 const page_mask: u64 = page_size - 1;
 const huge_page_size: u64 = 2 * 1024 * 1024;
 
-pub const Kind = enum { none, intel_vtd, amd_vi };
-
 /// One domain per claimed PCI function. 64 mirrors devices-broker's device cap.
 pub const maximum_domains = 64;
 pub const invalid_domain: u16 = 0xFFFF;
 
-/// The bit encodings and hardware operations a backend supplies to the shared core.
-/// Entry helpers build the raw page-table entries for the backend's format; the core
-/// walks the tree with them. The hardware ops act on a whole domain (identified by its
-/// hardware domain id = core index + 1) or device (by requester id / bdf).
-pub const Backend = struct {
-    /// Number of page-table levels (3 or 4) the backend selected from hardware caps.
-    levels: u8,
-    /// Largest leaf the walker may emit: 4 KiB always, 2 MiB when the backend allows.
-    supports_huge_pages: bool,
-
-    /// Raw entry bits for a leaf mapping `physical` (with the given size), and for a
-    /// non-leaf entry pointing at `table_physical` at `level` (level counts down to 1
-    /// at the leaf's parent). `isPresent` tests a read-back entry.
-    makeLeaf: *const fn (physical: u64, huge: bool) u64,
-    makeTable: *const fn (table_physical: u64, level: u8) u64,
-    isPresent: *const fn (entry: u64) bool,
-    /// Flush a cache line holding IOMMU structures the hardware reads non-coherently
-    /// (VT-d with ECAP.C==0). A no-op where the unit snoops caches.
-    flushStructure: *const fn (address: usize) void,
-
-    /// Point `bdf`'s translation structure at `domain` (hardware id) and invalidate the
-    /// context/device caches so the change takes effect.
-    attach: *const fn (bdf: u16, domain: u16, page_table_root: u64) void,
-    /// Return `bdf`'s translation structure to not-present + invalidate — all its DMA
-    /// faults afterward.
-    detach: *const fn (bdf: u16) void,
-    /// Invalidate cached translations for `domain` (after a map or unmap).
-    invalidateDomain: *const fn (domain: u16) void,
-    /// Pull pending faults out of the hardware, log them (rate-limited), return the
-    /// count seen this call.
-    faultDrain: *const fn () usize,
-};
-
 const Domain = struct {
     in_use: bool = false,
     owner: u32 = 0, // task that owns the attached device
@@ -85,53 +51,44 @@ const Domain = struct {
     rmrr: bool = false, // a firmware reserved-region domain (persists across claims)
 };
 
-var kind: Kind = .none;
-var backend: Backend = undefined;
+var active: bool = false;
+var backend: architecture.iommu.Backend = undefined;
 var domains: [maximum_domains]Domain = .{Domain{}} ** maximum_domains;
 
-pub fn kindOf() Kind {
-    return kind;
-}
 pub fn enabled() bool {
-    return kind != .none;
+    return active;
 }
 
-/// Detect the IOMMU, pick a backend, pre-map firmware reserved regions, and enable
-/// translation. Fail-open (kind stays .none) when no unit exists — the caller logs the
-/// posture. Must run after platform discovery and before any user process starts.
+/// Detect the IOMMU (the architecture module probes the discovered unit and
+/// returns its backend), pre-map firmware reserved regions, and enable
+/// translation. Fail-open (nothing activates) when no usable unit exists — the
+/// caller logs the posture. Must run after platform discovery and before any
+/// user process starts.
 pub fn init() void {
     const info = platform.platformInformation();
-    if (!info.iommu_present) {
-        kind = .none;
-        return;
-    }
-    // Pick the backend by vendor. A present-but-unusable unit stays fail-open with a
-    // logged reason rather than half-enabling.
-    if (info.iommu_is_amd) {
-        if (amd.detect(info)) |be| {
-            backend = be;
-            kind = .amd_vi;
-        } else {
-            kind = .none;
-            log.write("/system/kernel: WARNING AMD-Vi present but unusable — staying fail-open\n");
-            return;
-        }
-    } else {
-        if (intel.detect(info)) |be| {
-            backend = be;
-            kind = .intel_vtd;
-        } else {
-            kind = .none;
+    if (!info.iommu_present) return;
+    // A present-but-unusable unit stays fail-open with a logged reason rather
+    // than half-enabling. The backend receives the kernel services it needs
+    // (frames, the log sink) here — it never imports kernel internals.
+    backend = architecture.iommu.detect(.{
+        .register_base = info.iommu_base,
+        .amd = info.iommu_is_amd,
+    }, .{
+        .allocateFrame = pmm.alloc,
+        .allocateContiguous = pmm.allocContiguous,
+        .write = log.write,
+    }) orelse {
         log.write("/system/kernel: WARNING IOMMU present but unusable — staying fail-open\n");
         return;
-        }
-    }
+    };
+    active = true;
 
     // The translation structures start empty: every device is denied until its driver
     // claims it (confineDevice gives it a private domain). PCI functions are enumerated
     // post-boot by the ring-3 pci-bus driver, so there is nothing to attach at init.
-    if (kind == .amd_vi) amd.enable() else intel.enable();
-    logEnabled(info);
+    // The backend writes its identity lines; the neutral posture lines follow.
+    backend.enable();
+    logPosture(info);
 }
 
 /// Per-claimed-device record: its private domain, so a driver's death tears down
@@ -147,7 +104,7 @@ var confined: [maximum_domains]Confined = .{Confined{}} ** maximum_domains;
 /// the claim back (a claim that can't be confined must not stand). No-op success when no
 /// IOMMU exists (fail-open).
 pub fn confineDevice(device_id: u64, bdf: u16, owner: u32) bool {
-    if (kind == .none) return true;
+    if (!active) return true;
     if (device_id >= confined.len) return true; // unusual id; leave it to fail-open
     const domain = domainCreate(owner, bdf) orelse return false;
 
@@ -174,14 +131,14 @@ fn confinedOf(device_id: u64) ?*Confined {
 /// Map a DMA region into a specific claimed device's domain (the device owner binding a
 /// granted buffer). false if the device is not confined. No-op success without an IOMMU.
 pub fn mapForDevice(device_id: u64, physical: u64, len: u64) bool {
-    if (kind == .none) return true;
+    if (!active) return true;
     const c = confinedOf(device_id) orelse return false;
     return map(c.domain, physical, len);
 }
 
 /// Unmap a DMA region from a specific claimed device's domain. No-op if not confined.
 pub fn unmapForDevice(device_id: u64, physical: u64, len: u64) void {
-    if (kind == .none) return;
+    if (!active) return;
     const c = confinedOf(device_id) orelse return;
     unmap(c.domain, physical, len);
 }
@@ -189,7 +146,7 @@ pub fn unmapForDevice(device_id: u64, physical: u64, len: u64) void {
 /// Map a region into every claimed device owned by `owner` — the auto-bind of a task's
 /// own freshly-`dma_alloc`'d buffer into the devices it drives.
 pub fn mapRegionForOwner(owner: u32, physical: u64, len: u64) void {
-    if (kind == .none) return;
+    if (!active) return;
     for (&confined) |*c| {
         if (c.active and c.owner == owner) _ = map(c.domain, physical, len);
     }
@@ -200,7 +157,7 @@ pub fn mapRegionForOwner(owner: u32, physical: u64, len: u64) void {
 /// use-after-free this prevents. Cross-device because a granted buffer may be bound in a
 /// domain other than its owner's.
 pub fn unmapRegionEverywhere(physical: u64, len: u64) void {
-    if (kind == .none) return;
+    if (!active) return;
     for (&confined) |*c| {
         if (c.active) unmap(c.domain, physical, len);
     }
@@ -210,7 +167,7 @@ pub fn unmapRegionEverywhere(physical: u64, len: u64) void {
 /// device, free the tables) so their DMA is blocked again and a restarted driver
 /// re-claims cleanly. Runs BEFORE the broker claims and the DMA frames are released.
 pub fn releaseAllOwnedBy(owner: u32) void {
-    if (kind == .none) return;
+    if (!active) return;
     for (&confined) |*c| {
         if (c.active and c.owner == owner) {
             detachDevice(c.bdf);
@@ -223,7 +180,7 @@ pub fn releaseAllOwnedBy(owner: u32) void {
 
 /// Allocate an empty domain (an empty top-level table). null when the table is full.
 pub fn domainCreate(owner: u32, bdf: u16) ?u16 {
-    if (kind == .none) return 0; // fail-open: a dummy id the no-op ops ignore
+    if (!active) return 0; // fail-open: a dummy id the no-op ops ignore
     for (&domains, 0..) |*d, index| {
         if (d.in_use) continue;
         const root = allocTable() orelse return null;
@@ -236,7 +193,7 @@ pub fn domainCreate(owner: u32, bdf: u16) ?u16 {
 /// Free a domain's page-table frames and its slot. Precondition: no device attached
 /// (detach first).
 pub fn domainDestroy(domain: u16) void {
-    if (kind == .none) return;
+    if (!active) return;
     const d = &domains[domain];
     if (!d.in_use) return;
     freeTables(d.page_table_root, backend.levels);
@@ -245,7 +202,7 @@ pub fn domainDestroy(domain: u16) void {
 
 /// Attach `bdf`'s device to `domain` and pre-load any RMRR range recorded for it.
 pub fn attachDevice(domain: u16, bdf: u16) void {
-    if (kind == .none) return;
+    if (!active) return;
     const d = &domains[domain];
     d.bdf = bdf;
     backend.attach(bdf, hardwareId(domain), d.page_table_root);
@@ -253,7 +210,7 @@ pub fn attachDevice(domain: u16, bdf: u16) void {
 
 /// Return `bdf`'s device to not-present + invalidate.
 pub fn detachDevice(bdf: u16) void {
-    if (kind == .none) return;
+    if (!active) return;
     backend.detach(bdf);
 }
 
@@ -261,7 +218,7 @@ pub fn detachDevice(bdf: u16) void {
 /// Unconditional domain-selective invalidation after every map — correct under VT-d
 /// caching-mode and free otherwise.
 pub fn map(domain: u16, physical: u64, len: u64) bool {
-    if (kind == .none) return true;
+    if (!active) return true;
     const d = &domains[domain];
     if (!d.in_use) return false;
     if (!mapRange(d.page_table_root, physical, len)) return false;
@@ -273,7 +230,7 @@ pub fn map(domain: u16, physical: u64, len: u64) bool {
 /// invalidation before the caller returns the frames to pmm — a stale IOTLB entry
 /// pointing at a reallocated frame is the use-after-free this ordering prevents.
 pub fn unmap(domain: u16, physical: u64, len: u64) void {
-    if (kind == .none) return;
+    if (!active) return;
     const d = &domains[domain];
     if (!d.in_use) return;
     unmapRange(d.page_table_root, physical, len);
@@ -283,14 +240,14 @@ pub fn unmap(domain: u16, physical: u64, len: u64) void {
 /// Poll the hardware for translation faults, log them, return the count. Called by the
 /// IOMMU test case and opportunistically after a device detaches.
 pub fn faultDrain() usize {
-    if (kind == .none) return 0;
+    if (!active) return 0;
     return backend.faultDrain();
 }
 
 /// The physical address `virtual` maps to in `domain`, or null if unmapped — a test
 /// helper that walks the domain's page tables (identity mappings return `virtual`).
 pub fn translationOf(domain: u16, virtual: u64) ?u64 {
-    if (kind == .none) return virtual;
+    if (!active) return virtual;
     const d = &domains[domain];
     if (!d.in_use) return null;
     var table = d.page_table_root;
@@ -425,24 +382,16 @@ fn isHugeLeaf(entry: u64) bool {
 /// The size-bit the backends set on a 2 MiB leaf (VT-d SL-PTE PS bit 7; AMD encodes a
 /// leaf as next-level 0, so the core marks huge leaves with this software bit — an
 /// ignored bit in both formats — to tell them apart from table pointers when freeing).
-pub const huge_leaf_bit: u64 = 1 << 7;
+const huge_leaf_bit: u64 = 1 << 7;
 
 fn hardwareId(domain: u16) u16 {
     return domain + 1; // id 0 is reserved by both architectures
 }
 
-fn logEnabled(info: platform.PlatformInformation) void {
-    if (kind == .amd_vi) {
-        log.write("/system/kernel: iommu online (AMD-Vi) — UNTESTED on real AMD hardware (QEMU-verified only)\n");
-        log.print("  levels     : {d} (48-bit)\n", .{backend.levels});
-        return;
-    }
-    log.write("/system/kernel: iommu online (Intel VT-d)\n");
-    log.print("  version    : 0x{x}\n", .{info.iommu_version});
-    log.print("  agaw       : {d} levels\n", .{backend.levels});
+fn logPosture(info: platform.PlatformInformation) void {
     log.print("  rmrr       : {d} region(s) premapped\n", .{info.rmrr_count});
     if (info.rmrr_skipped > 0)
         log.print("  rmrr       : WARNING {d} scope(s) skipped — a device keeps an unmapped firmware buffer\n", .{info.rmrr_skipped});
     if (info.iommu_extra_units > 0)
-        log.print("  units      : WARNING {d} other DRHD(s) — their scoped devices are NOT translated\n", .{info.iommu_extra_units});
+        log.print("  units      : WARNING {d} other unit(s) — their scoped devices are NOT translated\n", .{info.iommu_extra_units});
 }

system/kernel/ipc-synchronous.zig

@@ -17,18 +17,20 @@
 //!   endpoint's own FIFO (threaded through the otherwise-idle `Task.next`); servers
 //!   waiting for work use a normal WaitQueue.
 //!
-//! Trust model (bring-up): copies honour only page presence and a user-half bound,
-//! not the leaf U/S or R/W bits and not SMAP — a #PF-tolerant, permission-checked
-//! copy is a later security-track item, matching the existing debug_write gap.
+//! Trust model: every side of a copy that names a *user* address space goes
+//! through system/kernel/user-memory.zig — user-half bound, page presence, and
+//! the leaf permissions ring 3 itself would face (U/S to read, U/S + R/W to
+//! write). A kernel-side buffer is trusted and translated as-is. An unmapped or
+//! wrongly-permissioned page fails the operation; it never faults ring 0.
 
 const std = @import("std");
 const boot_handoff = @import("boot-handoff");
 const abi = @import("abi");
-const architecture = @import("architecture");
 const scheduler = @import("scheduler.zig");
 const sync = @import("sync.zig");
 const heap = @import("heap.zig");
 const pmm = @import("pmm.zig");
+const user_memory = @import("user-memory.zig");
 
 const page_size = abi.page_size;
 const Task = scheduler.Task;
@@ -83,8 +85,9 @@ const PostSlot = struct {
     bytes: [POST_MAXIMUM]u8 = undefined,
 };
 
-/// End of the user (low) canonical half — user buffers must lie below it.
-const user_half_end: u64 = 0x0000_8000_0000_0000;
+/// End of the user (low) canonical half — user buffers must lie below it. One
+/// definition, in the module that owns the user-memory contract.
+const user_half_end: u64 = user_memory.user_half_end;
 
 /// A rendezvous endpoint. Allocated from the kernel heap; referenced by handle
 /// (per process) and/or by a registry slot, counted by `refcount`.
@@ -300,18 +303,22 @@ pub fn abandonSenderLocked(t: *Task) void {
 /// Copy `len` bytes from `source_va` in address space `source_as` to `destination_va` in
 /// `destination_as`, walking each side's page tables through the physmap (no CR3 switch).
 /// `*_as == 0` means the kernel address space (for kernel-task endpoints). User
-/// buffers must lie in the low half. Returns false — never #PFs — if any page is
-/// unmapped or out of range. Handles page-straddling buffers.
+/// buffers must lie in the low half and carry the permission ring 3 would need for
+/// their side of the copy — readable to send from, writable to receive into.
+/// Returns false — never #PFs — if any page is unmapped, out of range, or
+/// wrongly permissioned. Handles page-straddling buffers.
+///
+/// This is the process↔process case, which `user-memory` deliberately does not
+/// cover (it knows one user address space at a time); both sides resolve through
+/// `user_memory.resolve`, so the permission rules are the same ones.
 fn copyAcross(source_as: u64, source_va: u64, destination_as: u64, destination_va: u64, len: usize) bool {
-    const source_root = if (source_as != 0) source_as else architecture.kernelPageTable();
-    const destination_root = if (destination_as != 0) destination_as else architecture.kernelPageTable();
-    if (source_as != 0 and (source_va >= user_half_end or source_va + len > user_half_end)) return false;
-    if (destination_as != 0 and (destination_va >= user_half_end or destination_va + len > user_half_end)) return false;
+    if (source_as != 0 and !user_memory.userRangeOk(source_va, len)) return false;
+    if (destination_as != 0 and !user_memory.userRangeOk(destination_va, len)) return false;
 
     var off: usize = 0;
     while (off < len) {
-        const s = architecture.translate(source_root, source_va + off) orelse return false;
-        const d = architecture.translate(destination_root, destination_va + off) orelse return false;
+        const s = user_memory.resolve(source_as, source_va + off, false) orelse return false;
+        const d = user_memory.resolve(destination_as, destination_va + off, true) orelse return false;
         const s_left = page_size - ((source_va + off) & (page_size - 1));
         const d_left = page_size - ((destination_va + off) & (page_size - 1));
         const n = @min(@min(s_left, d_left), len - off);
@@ -323,27 +330,10 @@ fn copyAcross(source_as: u64, source_va: u64, destination_as: u64, destination_v
     return true;
 }
 
-/// Copy `destination.len` bytes from `user_va` in address space `user_as` into the kernel
-/// buffer `destination`, walking the user page tables through the physmap. Returns false if
-/// the range escapes the user half or any source page is unmapped — so a bad user
-/// pointer *fails the system_call* rather than faulting the kernel (danos has no
-/// fault-recovering copy-in, so a raw dereference of an unmapped user page would halt
-/// the machine). The correct way to pull a fixed-size struct in from user space, and
-/// a single fetch: no TOCTOU against a hostile pointer.
-pub fn copyFromUser(user_as: u64, user_va: u64, destination: []u8) bool {
-    if (user_as == 0) return false; // not a user address space
-    if (user_va >= user_half_end or user_va + destination.len > user_half_end) return false;
-    var off: usize = 0;
-    while (off < destination.len) {
-        const s = architecture.translate(user_as, user_va + off) orelse return false;
-        const s_left = page_size - ((user_va + off) & (page_size - 1));
-        const n = @min(s_left, destination.len - off);
-        const source: [*]const u8 = @ptrFromInt(boot_handoff.physicalToVirtual(s));
-        @memcpy(destination[off..][0..n], source[0..n]);
-        off += n;
-    }
-    return true;
-}
+/// The checked copy-in, re-exported from its home in `user-memory` so the many
+/// `ipc.copyFromUser` call sites keep reading naturally. New code should reach
+/// for `user-memory` directly — it is where the write direction lives too.
+pub const copyFromUser = user_memory.copyFromUser;
 
 // --- the two IPC operations -------------------------------------------------
 

system/kernel/log-ring.zig

@@ -161,7 +161,7 @@ test "append/read round trip" {
     defer std.testing.allocator.destroy(ring);
     ring.* = .{};
 
-    _ = ring.append(7, "/system/services/fat", .info, 123, "mounted /mnt/usb", false);
+    _ = ring.append(7, "/system/services/fat", .info, 123, "mounted /volumes/usb", false);
     _ = ring.append(0, "kernel", .raw, 456, "wall clock online", false);
 
     const first = parseAt(ring, ring.tail);
@@ -169,7 +169,7 @@ test "append/read round trip" {
     try std.testing.expectEqual(abi.KlogLevel.info, first.header.level);
     try std.testing.expectEqual(@as(u64, 123), first.header.timestamp_ns);
     try std.testing.expectEqualStrings("/system/services/fat", first.nameSlice());
-    try std.testing.expectEqualStrings("mounted /mnt/usb", first.messageSlice());
+    try std.testing.expectEqualStrings("mounted /volumes/usb", first.messageSlice());
 
     const second = parseAt(ring, first.next(ring.tail));
     try std.testing.expectEqual(@as(u32, 0), second.header.pid);

system/kernel/process.zig

@@ -31,6 +31,7 @@ const scheduler = @import("scheduler.zig");
 const console = @import("console.zig");
 const sync = @import("sync.zig");
 const ipc = @import("ipc-synchronous.zig");
+const user_memory = @import("user-memory.zig");
 const devices_broker = @import("devices-broker.zig");
 const irq = @import("irq.zig");
 const iommu = @import("iommu.zig");
@@ -110,6 +111,14 @@ pub const maximum_arguments = 8;
 /// Ceiling on the `system_spawn` extra-arguments blob (argv[1..], NUL-separated).
 pub const maximum_argument_bytes = 256;
 
+/// Longest path `fs_resolve` accepts, longest prefix `fs_mount`/`fs_unmount`
+/// accept, and longest backend rewrite prefix. Each is also the size of the
+/// kernel staging buffer the argument is copied into, which is why they are
+/// named here rather than spelled as literals at the check.
+pub const maximum_resolve_path = 224;
+pub const maximum_mount_prefix = 64;
+pub const maximum_mount_rewrite = 32;
+
 /// Auxiliary-vector entry types (System V AMD64 process entry). Only what the
 /// kernel emits today; a C runtime scans the vector until the null terminator.
 const auxiliary_vector_null: u64 = 0; // AT_NULL — end of the vector
@@ -378,6 +387,12 @@ fn systemIpcSend(state: *architecture.CpuState) void {
 
 /// device_enumerate(buffer, maximum) -> total: snapshot the device table into the caller's
 /// buffer (up to `maximum` entries), returning the total device count.
+///
+/// The broker fills a small kernel chunk which `copyToUser` then places in the
+/// caller's buffer: the kernel never stores through a user pointer, so a bad one
+/// is -EFAULT instead of a ring-0 page fault. A DeviceDescriptor is a few hundred
+/// bytes, so the chunk is deliberately tiny — the 16 KiB kernel stack could not
+/// hold a whole user-requested array of them.
 fn systemDeviceEnumerate(state: *architecture.CpuState) void {
     const buffer_ptr = architecture.systemCallArg(state, 0);
     const maximum = architecture.systemCallArg(state, 1);
@@ -385,8 +400,20 @@ fn systemDeviceEnumerate(state: *architecture.CpuState) void {
     if (t.address_space == 0 or buffer_ptr >= user_half_end) return fail(state);
     const sz = @sizeOf(device_abi.DeviceDescriptor);
     const cap = @min(maximum, (user_half_end - buffer_ptr) / sz); // clamp to the user half
-    const out: [*]device_abi.DeviceDescriptor = @ptrFromInt(buffer_ptr);
-    architecture.setSystemCallResult(state, devices_broker.enumerate(out[0..@intCast(cap)]));
+
+    var chunk: [2]device_abi.DeviceDescriptor = undefined;
+    var copied: u64 = 0;
+    var start: usize = 0;
+    while (copied < cap) {
+        const filled = devices_broker.enumerateFrom(start, &chunk);
+        if (filled == 0) break;
+        start += filled;
+        const take = @min(@as(u64, filled), cap - copied);
+        const bytes = std.mem.sliceAsBytes(chunk[0..@intCast(take)]);
+        if (!user_memory.copyToUser(t.address_space, buffer_ptr + copied * sz, bytes)) return failErr(state, ipc.EFAULT);
+        copied += take;
+    }
+    architecture.setSystemCallResult(state, devices_broker.deviceCount());
 }
 
 /// device_claim(id) -> 0/-1: take exclusive ownership of a device for this process.
@@ -969,7 +996,17 @@ fn systemSpawn(state: *architecture.CpuState) void {
     const image = ramdisk_image orelse return fail(state);
     const rd = initial_ramdisk.Reader.init(image) orelse return fail(state);
 
-    const name = @as([*]const u8, @ptrFromInt(ptr))[0..len];
+    // Both buffers come in through the checked copy layer, once. The lengths are
+    // already bounded above, so the staging arrays are small and fixed — and
+    // because the bytes are now the kernel's own, nothing below can be changed
+    // by another thread of the caller between validation and use.
+    var name_storage: [scheduler.maximum_task_name]u8 = undefined;
+    const name = name_storage[0..@intCast(len)];
+    if (!user_memory.copyFromUser(t.address_space, ptr, name)) return failErr(state, ipc.EFAULT);
+    var argument_storage: [maximum_argument_bytes]u8 = undefined;
+    const arguments = argument_storage[0..@intCast(arguments_len)];
+    if (arguments_len != 0 and !user_memory.copyFromUser(t.address_space, arguments_ptr, arguments)) return failErr(state, ipc.EFAULT);
+
     // Exact path first, basename fallback second; either way argv[0] (and hence
     // the task name, and the log ring's attribution) is the stored full path.
     const item = rd.find(name) orelse return fail(state); // no bundled binary by that name
@@ -977,8 +1014,7 @@ fn systemSpawn(state: *architecture.CpuState) void {
     argv[0] = item.name;
     var argc: usize = 1;
     if (arguments_len != 0) {
-        const blob = @as([*]const u8, @ptrFromInt(arguments_ptr))[0..arguments_len];
-        var pieces = std.mem.tokenizeScalar(u8, blob, 0);
+        var pieces = std.mem.tokenizeScalar(u8, arguments, 0);
         while (pieces.next()) |piece| {
             if (argc == maximum_arguments) return fail(state);
             argv[argc] = piece;
@@ -1129,8 +1165,27 @@ fn systemProcessEnumerate(state: *architecture.CpuState) void {
     if (t.address_space == 0 or buffer_ptr >= user_half_end) return fail(state);
     const sz = @sizeOf(abi.ProcessDescriptor);
     const cap = @min(maximum, (user_half_end - buffer_ptr) / sz); // clamp to the user half
-    const out: [*]abi.ProcessDescriptor = @ptrFromInt(buffer_ptr);
-    architecture.setSystemCallResult(state, scheduler.enumerate(out[0..@intCast(cap)]));
+
+    // The scheduler describes a chunk of the table into kernel memory, then
+    // `copyToUser` places it — the kernel never stores through the user pointer.
+    // Once the caller's buffer is full the walk continues with an empty chunk,
+    // because the result is the true live count, not what fitted.
+    var chunk: [8]abi.ProcessDescriptor = undefined;
+    var copied: u64 = 0;
+    var total: u64 = 0;
+    var cursor: usize = 0;
+    while (true) {
+        const room: []abi.ProcessDescriptor = if (copied < cap) chunk[0..@intCast(@min(chunk.len, cap - copied))] else chunk[0..0];
+        const found = scheduler.enumerateFrom(&cursor, room);
+        total += found.live;
+        if (found.filled != 0) {
+            const bytes = std.mem.sliceAsBytes(chunk[0..found.filled]);
+            if (!user_memory.copyToUser(t.address_space, buffer_ptr + copied * sz, bytes)) return failErr(state, ipc.EFAULT);
+            copied += found.filled;
+        }
+        if (found.done) break;
+    }
+    architecture.setSystemCallResult(state, total);
 }
 
 /// process_kill(id) -> 0 / -ESRCH / -EPERM: end the process `id`. Only its
@@ -1682,9 +1737,10 @@ fn systemIrqAck(state: *architecture.CpuState) void {
 /// The pointer must lie in the user (low) half, so kernel addresses and
 /// non-canonical values fall outside it and the read below can't be steered at
 /// kernel data. Length is checked first so the upper-bound add can't overflow.
-/// Known gap (fine for trusted user code): a pointer into an *unmapped* hole in
-/// the user half passes the check and the read #PFs -> on_fault halts — a
-/// self-DoS, not an isolation break. Fault-recovering copy-in is a later item.
+/// The message then comes in ONCE through the checked copy layer: an unmapped
+/// hole in the user half is -EFAULT rather than a kernel fault, and the bytes the
+/// log stamps are the same bytes that were validated (the old code read the user
+/// buffer twice — once to stage it, once again inside `log.append`).
 ///
 /// The emit runs under the kernel lock, so a message is atomic on the wire — two
 /// processes writing from different cores can interleave *messages*, never bytes.
@@ -1697,7 +1753,6 @@ fn systemDebugWrite(state: *architecture.CpuState) void {
     const len = architecture.systemCallArg(state, 1);
     const level_raw = architecture.systemCallArg(state, 2);
     if (len <= write_buffer.len and ptr < user_half_end and ptr + len <= user_half_end) {
-        const source: [*]const u8 = @ptrFromInt(ptr);
         // Levels above the enum range clamp to raw — old two-arg callers land
         // there naturally (garbage in arg 2 stays harmless).
         const level: abi.KlogLevel = if (level_raw <= @intFromEnum(abi.KlogLevel.raw))
@@ -1707,14 +1762,16 @@ fn systemDebugWrite(state: *architecture.CpuState) void {
         const t = scheduler.current();
         const flags = sync.enter();
         defer sync.leave(flags);
-        @memcpy(write_buffer[0..len], source[0..len]); // keep the latest message
+        // One copy in, under the lock; `write_buffer` (the latest message, which
+        // the kernel tests assert on) doubles as the staging buffer the log reads.
+        if (!user_memory.copyFromUser(t.address_space, ptr, write_buffer[0..len])) return failErr(state, ipc.EFAULT);
         write_len = len;
         write_from_user = architecture.fromUser(state);
         write_count += 1;
         // The kernel stamps the sender's identity — attribution is structural,
         // not a prefix convention the payload could forge (and it is stamped
         // per line inside log.append).
-        log.append(t.id, t.name(), level, source[0..len]);
+        log.append(t.id, t.name(), level, write_buffer[0..len]);
         architecture.setSystemCallResult(state, len);
     } else {
         fail(state);
@@ -1729,18 +1786,35 @@ fn systemDebugWrite(state: *architecture.CpuState) void {
 /// [KlogRecordHeader][name][message] frames out of the byte stream (abi.zig).
 ///
 /// The mirror of `debug_write`: the same overflow-safe user-half bounds check,
-/// but the copy runs kernel -> user, under the log lock (inside log.readAt) so
-/// the stream can't move underneath the copy. A read-only diagnostic.
+/// but the copy runs kernel -> user. The ring is drained a chunk at a time into a
+/// kernel staging buffer (each chunk read under the log lock, so the stream can't
+/// move underneath it) and each chunk is then placed with `copyToUser` — a
+/// reader may ask for a megabyte, and the kernel stack is 16 KiB. A partial
+/// result is honest: the reader advances its cursor by what it got. A read-only
+/// diagnostic.
 fn systemKlogRead(state: *architecture.CpuState) void {
     const offset = architecture.systemCallArg(state, 0);
     const ptr = architecture.systemCallArg(state, 1);
     const len = architecture.systemCallArg(state, 2);
+    const t = scheduler.current();
     // Confine the whole destination span to the user (low) half. `len <=
     // user_half_end - ptr` bounds the length without an overflowing add.
     if (ptr < user_half_end and len <= user_half_end - ptr) {
-        const dest: [*]u8 = @ptrFromInt(ptr);
-        const n = log.readAt(offset, dest[0..len]) orelse return fail(state);
-        architecture.setSystemCallResult(state, n);
+        var chunk: [512]u8 = undefined;
+        var done: u64 = 0;
+        while (done < len) {
+            const want = @min(@as(u64, chunk.len), len - done);
+            const n = log.readAt(offset + done, chunk[0..@intCast(want)]) orelse {
+                // The cursor fell behind the ring's tail mid-drain. What was
+                // already placed stands; only a first-chunk miss fails the call.
+                if (done == 0) return fail(state);
+                break;
+            };
+            if (n == 0) break; // caught up
+            if (!user_memory.copyToUser(t.address_space, ptr + done, chunk[0..n])) return failErr(state, ipc.EFAULT);
+            done += n;
+        }
+        architecture.setSystemCallResult(state, done);
     } else {
         fail(state);
     }
@@ -1753,10 +1827,10 @@ fn systemKlogRead(state: *architecture.CpuState) void {
 fn systemKlogStatus(state: *architecture.CpuState) void {
     const ptr = architecture.systemCallArg(state, 0);
     const size = @sizeOf(abi.KlogStatus);
+    const t = scheduler.current();
     if (ptr < user_half_end and size <= user_half_end - ptr) {
         var status = log.status();
-        const dest: [*]u8 = @ptrFromInt(ptr);
-        @memcpy(dest[0..size], std.mem.asBytes(&status)[0..size]);
+        if (!user_memory.copyValueToUser(t.address_space, ptr, &status)) return failErr(state, ipc.EFAULT);
         architecture.setSystemCallResult(state, 0);
     } else {
         fail(state);
@@ -1775,10 +1849,12 @@ fn systemFsResolve(state: *architecture.CpuState) void {
     const flags = architecture.systemCallArg(state, 2);
     const out_ptr = architecture.systemCallArg(state, 3);
     const out_cap = architecture.systemCallArg(state, 4);
-    if (path_len == 0 or path_len > 224 or path_ptr >= user_half_end or path_ptr + path_len > user_half_end) return fail(state);
-    if (out_cap != 0 and (out_ptr >= user_half_end or out_ptr + out_cap > user_half_end)) return fail(state);
-    const path = @as([*]const u8, @ptrFromInt(path_ptr))[0..path_len];
+    if (path_len == 0 or path_len > maximum_resolve_path or path_ptr >= user_half_end or path_ptr + path_len > user_half_end) return fail(state);
+    if (out_cap != 0 and !user_memory.userRangeOk(out_ptr, @intCast(out_cap))) return fail(state);
     const t = scheduler.current();
+    var path_storage: [maximum_resolve_path]u8 = undefined;
+    const path = path_storage[0..@intCast(path_len)];
+    if (!user_memory.copyFromUser(t.address_space, path_ptr, path)) return failErr(state, ipc.EFAULT);
 
     const flags_lock = sync.enter();
     defer sync.leave(flags_lock);
@@ -1790,14 +1866,15 @@ fn systemFsResolve(state: *architecture.CpuState) void {
         .backend => |*backend| {
             // The rewritten path goes back in the out buffer behind a u16
             // length prefix (a third result register would collide with r8's
-            // argument role in the userspace stub).
+            // argument role in the userspace stub). Both halves are placed with
+            // the checked copy, and *before* the handle is installed, so an
+            // -EFAULT never strands a capability in the caller's table.
             if (backend.path_len + 2 > out_cap) return fail(state);
+            const prefix = [2]u8{ @intCast(backend.path_len & 0xFF), @intCast(backend.path_len >> 8) };
+            if (!user_memory.copyToUser(t.address_space, out_ptr, &prefix)) return failErr(state, ipc.EFAULT);
+            if (!user_memory.copyToUser(t.address_space, out_ptr + 2, backend.path[0..backend.path_len])) return failErr(state, ipc.EFAULT);
             const handle = ipc.installHandleDeduped(t, backend.endpoint);
             if (handle < 0) return fail(state);
-            const destination: [*]u8 = @ptrFromInt(out_ptr);
-            destination[0] = @intCast(backend.path_len & 0xFF);
-            destination[1] = @intCast(backend.path_len >> 8);
-            @memcpy(destination[2..][0..backend.path_len], backend.path[0..backend.path_len]);
             architecture.setSystemCallResult(state, abi.fs_route_backend);
             architecture.setSystemCallResult2(state, @intCast(handle));
         },
@@ -1809,6 +1886,12 @@ fn systemFsResolve(state: *architecture.CpuState) void {
 /// kernel-backed node. read copies file bytes; status copies a FileAttributes;
 /// readdir copies [DirectoryEntryHeader][name] for the `offset`th child. Reads
 /// of the immutable initrd never take the kernel lock.
+///
+/// Every result reaches the caller through `copyToUser`, never a store through
+/// the user pointer. `read` stages the file bytes a chunk at a time — a caller
+/// may ask for the 64 KiB ceiling, which no kernel stack could hold — so a
+/// mid-way -EFAULT is possible; the call fails and the already-placed prefix is
+/// meaningless, exactly as a failed read should be.
 fn systemFsNode(state: *architecture.CpuState) void {
     const operation = architecture.systemCallArg(state, 0);
     const node_token = architecture.systemCallArg(state, 1);
@@ -1817,16 +1900,24 @@ fn systemFsNode(state: *architecture.CpuState) void {
     const buf_len = architecture.systemCallArg(state, 4);
     if (buf_ptr >= user_half_end or buf_len > user_half_end - buf_ptr) return fail(state);
     const capped = @min(buf_len, 64 * 1024); // bound any single copy
-    const destination: [*]u8 = @ptrFromInt(buf_ptr);
+    const t = scheduler.current();
     switch (operation) {
         abi.fs_node_read => {
-            const n = vfs.nodeRead(node_token, offset, destination[0..capped]) orelse return fail(state);
-            architecture.setSystemCallResult(state, n);
+            var chunk: [512]u8 = undefined;
+            var done: u64 = 0;
+            while (done < capped) {
+                const want = @min(@as(u64, chunk.len), capped - done);
+                const n = vfs.nodeRead(node_token, offset + done, chunk[0..@intCast(want)]) orelse return fail(state);
+                if (n == 0) break; // end of file
+                if (!user_memory.copyToUser(t.address_space, buf_ptr + done, chunk[0..n])) return failErr(state, ipc.EFAULT);
+                done += n;
+            }
+            architecture.setSystemCallResult(state, done);
         },
         abi.fs_node_status => {
             var attributes = vfs.nodeStatus(node_token) orelse return fail(state);
             if (capped < @sizeOf(abi.FileAttributes)) return fail(state);
-            @memcpy(destination[0..@sizeOf(abi.FileAttributes)], std.mem.asBytes(&attributes));
+            if (!user_memory.copyValueToUser(t.address_space, buf_ptr, &attributes)) return failErr(state, ipc.EFAULT);
             architecture.setSystemCallResult(state, @sizeOf(abi.FileAttributes));
         },
         abi.fs_node_readdir => {
@@ -1837,10 +1928,13 @@ fn systemFsNode(state: *architecture.CpuState) void {
                 architecture.setSystemCallResult(state, 0); // past the end
                 return;
             };
-            var header = result.header;
+            // Header and name are staged contiguously so one entry is one copy.
+            var entry: [@sizeOf(abi.DirectoryEntryHeader) + name_buffer.len]u8 = undefined;
+            const header = result.header;
             const total = header_size + @min(result.name_len, capped - header_size);
-            @memcpy(destination[0..header_size], std.mem.asBytes(&header));
-            @memcpy(destination[header_size..total], name_buffer[0 .. total - header_size]);
+            @memcpy(entry[0..header_size], std.mem.asBytes(&header));
+            @memcpy(entry[header_size..total], name_buffer[0 .. total - header_size]);
+            if (!user_memory.copyToUser(t.address_space, buf_ptr, entry[0..total])) return failErr(state, ipc.EFAULT);
             architecture.setSystemCallResult(state, total);
         },
         else => fail(state),
@@ -1857,12 +1951,19 @@ fn systemFsMount(state: *architecture.CpuState) void {
     const backend_handle = architecture.systemCallArg(state, 2);
     const rewrite_ptr = architecture.systemCallArg(state, 3);
     const rewrite_len = architecture.systemCallArg(state, 4);
-    if (prefix_len == 0 or prefix_len > 64 or prefix_ptr >= user_half_end or prefix_ptr + prefix_len > user_half_end) return fail(state);
-    if (rewrite_len > 32) return fail(state);
+    if (prefix_len == 0 or prefix_len > maximum_mount_prefix or prefix_ptr >= user_half_end or prefix_ptr + prefix_len > user_half_end) return fail(state);
+    if (rewrite_len > maximum_mount_rewrite) return fail(state);
     if (rewrite_len != 0 and (rewrite_ptr >= user_half_end or rewrite_ptr + rewrite_len > user_half_end)) return fail(state);
     const t = scheduler.current();
-    const prefix = @as([*]const u8, @ptrFromInt(prefix_ptr))[0..prefix_len];
-    const rewrite = if (rewrite_len == 0) "" else @as([*]const u8, @ptrFromInt(rewrite_ptr))[0..rewrite_len];
+    // Both strings come in through the checked copy; `mountBackend` copies them
+    // again into the mount table, so these staging buffers only need to outlive
+    // this call.
+    var prefix_storage: [maximum_mount_prefix]u8 = undefined;
+    const prefix = prefix_storage[0..@intCast(prefix_len)];
+    if (!user_memory.copyFromUser(t.address_space, prefix_ptr, prefix)) return failErr(state, ipc.EFAULT);
+    var rewrite_storage: [maximum_mount_rewrite]u8 = undefined;
+    const rewrite = rewrite_storage[0..@intCast(rewrite_len)];
+    if (rewrite_len != 0 and !user_memory.copyFromUser(t.address_space, rewrite_ptr, rewrite)) return failErr(state, ipc.EFAULT);
 
     const flags = sync.enter();
     defer sync.leave(flags);
@@ -1879,8 +1980,11 @@ fn systemFsMount(state: *architecture.CpuState) void {
 fn systemFsUnmount(state: *architecture.CpuState) void {
     const prefix_ptr = architecture.systemCallArg(state, 0);
     const prefix_len = architecture.systemCallArg(state, 1);
-    if (prefix_len == 0 or prefix_len > 64 or prefix_ptr >= user_half_end or prefix_ptr + prefix_len > user_half_end) return fail(state);
-    const prefix = @as([*]const u8, @ptrFromInt(prefix_ptr))[0..prefix_len];
+    if (prefix_len == 0 or prefix_len > maximum_mount_prefix or prefix_ptr >= user_half_end or prefix_ptr + prefix_len > user_half_end) return fail(state);
+    const t = scheduler.current();
+    var prefix_storage: [maximum_mount_prefix]u8 = undefined;
+    const prefix = prefix_storage[0..@intCast(prefix_len)];
+    if (!user_memory.copyFromUser(t.address_space, prefix_ptr, prefix)) return failErr(state, ipc.EFAULT);
     const flags = sync.enter();
     defer sync.leave(flags);
     if (!vfs.unmount(prefix)) return fail(state);

system/kernel/scheduler.zig

@@ -1203,18 +1203,56 @@ pub fn destroyTaskLocked(t: *Task) void {
 /// Snapshot the task table into `out` (up to its length), returning the total
 /// number of live tasks — the kernel half of `process_enumerate`, mirroring
 /// devices_broker.enumerate. Kernel tasks are included (empty name, supervisor 0):
-/// an honest `ps` shows the idle tasks too. `out` may be user memory: the caller's
-/// address space is loaded during its system call, and the same bring-up trust
-/// applies as for device_enumerate (an unmapped user page faults the kernel).
+/// an honest `ps` shows the idle tasks too. `out` is always KERNEL memory: the
+/// system call bounces it out to the caller through the checked copy layer
+/// (system/kernel/user-memory.zig), so a bad user pointer fails the call instead
+/// of faulting ring 0.
 pub fn enumerate(out: []abi.ProcessDescriptor) u64 {
+    var total: u64 = 0;
+    var cursor: usize = 0;
+    while (true) {
+        // Past the buffer, keep walking with an empty chunk: the total is the
+        // whole live count, however few descriptors the caller had room for.
+        const room = if (total < out.len) out[@intCast(total)..] else out[out.len..];
+        const chunk = enumerateFrom(&cursor, room);
+        total += chunk.live;
+        if (chunk.done) return total;
+    }
+}
+
+/// What one chunk of the task-table walk found.
+pub const TaskChunk = struct {
+    /// Live tasks passed in this chunk, whether or not they fit in `out` — this
+    /// is what the running total (and hence `process_enumerate`'s result) counts.
+    live: usize,
+    /// How many of those were written into `out` (`@min(live, out.len)`).
+    filled: usize,
+    /// The cursor reached the end of the table: this was the last chunk.
+    done: bool,
+};
+
+/// One chunk of the task table: starting at slot `cursor` (advanced past
+/// everything scanned), describe up to `out.len` live tasks into `out` — or, with
+/// an empty `out`, just count the rest. `cursor == tasks.len` ends the walk.
+///
+/// The chunked form exists so `process_enumerate` can stage each chunk in a small
+/// kernel buffer and copy it out with `user_memory.copyToUser`, rather than
+/// handing a user pointer to the kernel's own stores. A *slot* cursor, rather
+/// than a "skip the first N live tasks" count, keeps chunks from duplicating or
+/// losing an entry when a task exits between them.
+pub fn enumerateFrom(cursor: *usize, out: []abi.ProcessDescriptor) TaskChunk {
     const flags = sync.enter();
     defer sync.leave(flags);
-    var total: u64 = 0;
-    for (&tasks) |*t| {
+    var live: usize = 0;
+    var filled: usize = 0;
+    const limit = if (out.len == 0) tasks.len else out.len; // always makes progress
+    while (cursor.* < tasks.len and live < limit) {
+        const t = &tasks[cursor.*];
+        cursor.* += 1;
         if (t.state == .free or t.state == .reaping) continue; // reaping = already exited
-        if (total < out.len) {
-            const d = &out[total];
-            d.* = .{
+        live += 1;
+        if (filled == out.len) continue;
+        out[filled] = .{
             .id = t.id,
             .supervisor = t.supervisor,
             .leader = t.leader,
@@ -1228,10 +1266,9 @@ pub fn enumerate(out: []abi.ProcessDescriptor) u64 {
             .name_length = t.name_length,
             .name = t.name_buffer,
         };
+        filled += 1;
     }
-        total += 1;
-    }
-    return total;
+    return .{ .live = live, .filled = filled, .done = cursor.* >= tasks.len };
 }
 
 /// Whether the running task is a user process (has its own address space).

system/kernel/tests.zig

@@ -29,6 +29,7 @@ const process = @import("process.zig");
 const initial_ramdisk = @import("initial-ramdisk");
 const kernel_log = @import("log.zig");
 const kernel_vfs = @import("vfs.zig");
+const user_memory = @import("user-memory.zig");
 
 /// Formatted test-marker write. Goes through the kernel log (not straight to
 /// serial): the log lock is what keeps marker lines from interleaving with
@@ -141,6 +142,8 @@ pub fn run(case: []const u8, boot_information: *const BootInformation) void {
         faultNull();
     } else if (eql(case, "usermem")) {
         userMemTest();
+    } else if (eql(case, "user-memory")) {
+        userMemoryTest(boot_information);
     } else if (eql(case, "user-pf")) {
         userPfTest();
     } else if (eql(case, "fault-recovery")) {
@@ -1023,6 +1026,103 @@ fn userMemTest() void {
     result();
 }
 
+/// The checked copy layer (system/kernel/user-memory.zig), against a scratch
+/// address space built here rather than a live process — so the refusals can be
+/// provoked exactly: a kernel-half address, an unmapped user page, and a user
+/// page mapped read-only. Then the fixture proves the same refusals reach ring 3
+/// as -errno instead of a kernel fault.
+fn userMemoryTest(boot_information: *const BootInformation) void {
+    log("DANOS-TEST-BEGIN: user-memory\n", .{});
+    const base_free = pmm.stats().free_frames;
+
+    const address_space = architecture.createAddressSpace() orelse {
+        check("created a scratch address space", false);
+        result();
+        return;
+    };
+    check("created a scratch address space", address_space != 0);
+
+    // Three consecutive pages: two writable, the third read-only — so a copy that
+    // straddles into the third proves the write check applies per page, not just
+    // to the first one the walk touches.
+    const writable_pages = 2;
+    const total_pages = 3;
+    const arena = process.heap_arena_base;
+    var frames: [total_pages]u64 = undefined;
+    var mapped: usize = 0;
+    while (mapped < total_pages) : (mapped += 1) {
+        frames[mapped] = pmm.alloc() orelse break;
+        architecture.mapUserPageInto(address_space, arena + mapped * abi.page_size, frames[mapped], mapped < writable_pages, false);
+    }
+    check("mapped two writable and one read-only user page", mapped == total_pages);
+    if (mapped == total_pages) {
+        const read_only = arena + writable_pages * abi.page_size;
+        const unmapped = arena + total_pages * abi.page_size;
+        const kernel_half: u64 = 0xFFFF_8000_0000_0000;
+
+        var out: [16]u8 = undefined;
+        const pattern = [_]u8{ 0xC0, 0xDE, 0xF0, 0x0D, 0xBA, 0xAD, 0xF0, 0x0D };
+
+        // A round trip through the writable page: what copyToUser placed is what
+        // copyFromUser brings back, and the frame really holds it.
+        const wrote = user_memory.copyToUser(address_space, arena + 32, &pattern);
+        const read_back = user_memory.copyFromUser(address_space, arena + 32, out[0..pattern.len]);
+        const frame_view: [*]const u8 = @ptrFromInt(boot_handoff.physicalToVirtual(frames[0] + 32));
+        check("copyToUser/copyFromUser round trip", wrote and read_back and
+            eql(out[0..pattern.len], &pattern) and eql(frame_view[0..pattern.len], &pattern));
+
+        // Straddling the 4 KiB boundary between the two writable pages.
+        const straddle = arena + abi.page_size - 4;
+        check("a page-straddling round trip", user_memory.copyToUser(address_space, straddle, &pattern) and
+            user_memory.copyFromUser(address_space, straddle, out[0..pattern.len]) and
+            eql(out[0..pattern.len], &pattern));
+
+        // Kernel-half addresses are refused by the range check, before any walk.
+        check("copyToUser refuses a kernel-half address", !user_memory.copyToUser(address_space, kernel_half, &pattern));
+        check("copyFromUser refuses a kernel-half address", !user_memory.copyFromUser(address_space, kernel_half, out[0..pattern.len]));
+        check("a range running off the end of the user half is refused", !user_memory.copyToUser(address_space, user_memory.user_half_end - 4, &pattern));
+
+        // An unmapped-but-in-range page: the latent kernel fault H1 exists to kill.
+        check("copyToUser refuses an unmapped user page", !user_memory.copyToUser(address_space, unmapped, &pattern));
+        check("copyFromUser refuses an unmapped user page", !user_memory.copyFromUser(address_space, unmapped, out[0..pattern.len]));
+
+        // The leaf permission bits: a read-only user page may be read, never written.
+        check("copyToUser refuses a read-only user mapping", !user_memory.copyToUser(address_space, read_only, &pattern));
+        check("copyFromUser accepts a read-only user mapping", user_memory.copyFromUser(address_space, read_only, out[0..pattern.len]));
+        check("a write straddling into a read-only page is refused", !user_memory.copyToUser(address_space, read_only - 4, &pattern));
+
+        // The kernel's own address space is not a user address space.
+        check("copyToUser refuses address space 0", !user_memory.copyToUser(0, arena, &pattern));
+        check("copyFromUser refuses address space 0", !user_memory.copyFromUser(0, arena, out[0..pattern.len]));
+    }
+
+    var i: usize = 0;
+    while (i < mapped) : (i += 1) {
+        const va = arena + i * abi.page_size;
+        architecture.unmapUserPageInto(address_space, va);
+        pmm.free(frames[i]);
+    }
+    architecture.destroyAddressSpace(address_space);
+    check("no frames leaked (free count restored)", pmm.stats().free_frames == base_free);
+
+    // Now the ring-3 half: the fixture aims bad pointers at the converted system
+    // calls and must get failures back with the machine still running.
+    if (boot_information.initial_ramdisk_len == 0) {
+        check("bootloader handed over an initial_ramdisk", false);
+        result();
+        return;
+    }
+    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.initial_ramdisk_base)))[0..boot_information.initial_ramdisk_len];
+    const rd = initial_ramdisk.Reader.init(image) orelse {
+        check("initial_ramdisk image is valid", false);
+        result();
+        return;
+    };
+    process.setInitialRamdisk(image);
+    check("user-memory-test spawned", spawnNamed(rd, "user-memory-test"));
+    result();
+}
+
 // --- synchronous IPC --------------------------------------------------------
 
 var ipc_endpoint: *ipcsync.Endpoint = undefined;
@@ -1253,11 +1353,10 @@ fn iommuTest() void {
     const pinfo = platform.platformInformation();
     check("IOMMU found in the firmware tables", pinfo.iommu_present);
     check("IOMMU unit has a register base", pinfo.iommu_base != 0);
-    // The VT-d version register is a live-unit sanity check; AMD-Vi (from IVRS) records
-    // no version, so gate it on the vendor.
-    if (!pinfo.iommu_is_amd)
-        check("VT-d version register reads back nonzero (real, mappable unit)", pinfo.iommu_version != 0);
-    log("DANOS-IOMMU: base=0x{x} version=0x{x} capabilities=0x{x}\n", .{ pinfo.iommu_base, pinfo.iommu_version, pinfo.iommu_capabilities });
+    // The live-unit sanity (the version register reading back nonzero) now
+    // gates detect itself: an unusable unit stays fail-open, so `enabled()`
+    // below subsumes the old vendor-gated register check.
+    log("DANOS-IOMMU: base=0x{x}\n", .{pinfo.iommu_base});
 
     // Translation was enabled at boot (kernel.zig: iommu.init before any driver claims
     // a device). The blanket domain keeps every device identity-mapped, so DMA still
@@ -1970,15 +2069,20 @@ fn initTest(boot_information: *const BootInformation) void {
     };
     check("init loaded and spawned as a process", spawned);
 
-    // Wait (real time) for at least two heartbeats — proving it runs, writes,
-    // and sleeps repeatedly (init sleeps ~1 s between beats).
+    // Wait (real time) until the LAST write is a heartbeat — proving init got
+    // through its boot chatter (heap ok, the /system/configuration/init.csv lookup) and settled
+    // into its beat-and-sleep loop (~1 s between beats). Waiting on the text
+    // rather than a raw write count: the boot chatter alone satisfies a count,
+    // which is exactly the too-early check that used to fail here.
     scheduler.setPriority(1);
-    const deadline = architecture.millis() + 8000;
-    while (process.write_count < 2 and architecture.millis() < deadline) scheduler.yield();
-    scheduler.setPriority(4);
-
     const prefix = "init: heartbeat";
-    const beat_ok = bufferHas(prefix);
+    const deadline = architecture.millis() + 8000;
+    var beat_ok = false;
+    while (!beat_ok and architecture.millis() < deadline) {
+        beat_ok = bufferHas(prefix);
+        scheduler.yield();
+    }
+    scheduler.setPriority(4);
     check("init produced repeated heartbeats (>=2)", process.write_count >= 2);
     check("heartbeat text arrived intact", beat_ok);
     check("heartbeats came from user mode (CPL 3)", process.write_from_user);
@@ -2216,7 +2320,7 @@ fn vfsClientDeathTest(boot_information: *const BootInformation) void {
     };
 
     process.write_count = 0;
-    // The full tree: the storage chain must come up for /mnt/usb to exist —
+    // The full tree: the storage chain must come up for /volumes/usb to exist —
     // the fat server (not a router) now owns client file state and its sweep.
     process.setInitialRamdisk(image);
     const init_ok = if (process.spawnBundled("/system/services/init")) true else |_| false;
@@ -2602,7 +2706,7 @@ fn usbStorageTest(boot_information: *const BootInformation) void {
 
 /// The FAT mount chain: boot the full tree (init spawns the fat server, which
 /// brings up the USB storage chain, mounts the FAT volume, and mounts itself into
-/// the VFS at /mnt/usb), then spawn a fat-test client that lists and reads through
+/// the VFS at /volumes/usb), then spawn a fat-test client that lists and reads through
 /// the mount. The harness attaches a usb-storage device; the expect regex requires
 /// the fat mount and the client's success.
 fn fatMountTest(boot_information: *const BootInformation) void {
@@ -2792,15 +2896,26 @@ fn initialRamdiskTest(boot_information: *const BootInformation) void {
 
     process.write_count = 0;
     process.write_from_user = false;
+    var programs: u32 = 0;
     var spawned: u32 = 0;
     var i: u32 = 0;
     while (i < rd.count) : (i += 1) {
         const item = rd.entry(i) orelse continue;
+        // The boot tree ferries data files too (/system/configuration/devices.csv,
+        // /system/configuration/init.csv — served read-only by the kernel VFS,
+        // never spawned); only the /system and /test trees hold programs, and
+        // /system/configuration holds none, so only the rest counts toward the
+        // spawn-everything sweep.
+        const is_program = (std.mem.startsWith(u8, item.name, "/system/") and
+            !std.mem.startsWith(u8, item.name, "/system/configuration/")) or
+            std.mem.startsWith(u8, item.name, "/test/");
+        if (!is_program) continue;
+        programs += 1;
         if (process.spawnProcess(item.blob, 4, &.{item.name})) spawned += 1 else |err| {
             log("DANOS-INITRD-ERR: {s}: {s}\n", .{ item.name, @errorName(err) });
         }
     }
-    check("every initial_ramdisk binary spawned", spawned == rd.count);
+    check("every initial_ramdisk program spawned", programs >= 1 and spawned == programs);
 
     // Wait for the spawned programs to run and make syscalls (they write + sleep).
     scheduler.setPriority(1);
@@ -3254,21 +3369,23 @@ fn kernelVfsTest(boot_information: *const BootInformation) void {
         check("its first bytes are an ELF magic", n == 4 and header[0] == 0x7f and header[1] == 'E' and header[2] == 'L' and header[3] == 'F');
     }
 
-    // Directories resolve and enumerate: /system lists services/drivers.
+    // Directories resolve and enumerate: /system lists services/drivers/
+    // configuration (the CSV data files ride the same initrd tree).
     const root_directory = kernel_vfs.resolvePath("/system", false);
     check("/system resolves to a directory node", root_directory == .kernel_node);
     var saw_services = false;
     var saw_drivers = false;
+    var saw_configuration = false;
     var saw_stray_in_root = false;
     var saw_files_in_services = false;
     if (root_directory == .kernel_node) {
         var cursor: u64 = 0;
         var name: [64]u8 = undefined;
         while (kernel_vfs.nodeReaddir(root_directory.kernel_node, cursor, &name)) |entry| : (cursor += 1) {
-            if (eql(name[0..entry.name_len], "services")) saw_services = true else if (eql(name[0..entry.name_len], "drivers")) saw_drivers = true else saw_stray_in_root = true;
+            if (eql(name[0..entry.name_len], "services")) saw_services = true else if (eql(name[0..entry.name_len], "drivers")) saw_drivers = true else if (eql(name[0..entry.name_len], "configuration")) saw_configuration = true else saw_stray_in_root = true;
         }
     }
-    check("readdir /system yields services and drivers", saw_services and saw_drivers);
+    check("readdir /system yields services, drivers, configuration", saw_services and saw_drivers and saw_configuration);
     check("readdir /system yields nothing else (no /test leakage)", !saw_stray_in_root);
     const services = kernel_vfs.resolvePath("/system/services", false);
     if (services == .kernel_node) {

system/kernel/user-memory.zig

@@ -0,0 +1,117 @@
+//! The single trusted door between ring 0 and a process's memory.
+//!
+//! Kernel code never dereferences a user virtual address. It walks that address
+//! space's page tables through the physmap — kernel mappings throughout — and
+//! moves the bytes there. Three properties fall out of that one decision:
+//!
+//! - **A bad pointer fails the system call.** danos has no fault-recovering
+//!   copy-in, so a raw dereference of an unmapped-but-in-range user page would
+//!   halt the machine. Here it is a `false` return and an `-EFAULT`.
+//! - **The copy is a single fetch.** A struct pulled in once cannot be changed
+//!   underneath the checks that follow it — no TOCTOU against a hostile pointer.
+//! - **It is SMAP-proof by construction.** No ring-0 access to a user-mapped
+//!   page ever happens, so the CR4.SMAP bit needs no `stac` window anywhere
+//!   (docs/os-development/smep-smap.md). There is no `stac` in this tree, and a
+//!   change that adds one is wrong by definition.
+//!
+//! The walk enforces the permissions ring 3 itself would face: a read needs the
+//! leaf user-accessible (U/S at every level), a write needs it writable too
+//! (R/W at every level). So a syscall argument cannot steer the kernel at a
+//! kernel-only mapping, nor make it write a process's own read-only text — the
+//! properties that matter once shared or copy-on-write mappings exist, and the
+//! reason the "presence only" caveat that used to sit at the top of
+//! ipc-synchronous.zig is gone.
+//!
+//! Scope: this module knows only about *user* address spaces. The kernel side of
+//! a copy (an IPC reply staged in kernel memory, a bounce buffer) is trusted and
+//! translated without permission checks — see `resolve`.
+
+const std = @import("std");
+const boot_handoff = @import("boot-handoff");
+const abi = @import("abi");
+const architecture = @import("architecture");
+
+const page_size = abi.page_size;
+
+/// End of the user (low) canonical half. Every user buffer must lie below it, so
+/// kernel addresses and non-canonical values are refused by the range check
+/// alone, before any table is read.
+pub const user_half_end: u64 = 0x0000_8000_0000_0000;
+
+/// Whether `[virtual, virtual + len)` lies wholly inside the user half. The
+/// length is compared against the remaining span rather than added to the base,
+/// so a huge `len` cannot wrap the check.
+pub fn userRangeOk(virtual: u64, len: usize) bool {
+    if (virtual >= user_half_end) return false;
+    return len <= user_half_end - virtual;
+}
+
+/// Resolve one address for a copy. `address_space == 0` means the kernel's own
+/// tables — trusted, translated as-is. A real address space is a process's, and
+/// the walk demands what ring 3 would need: user-accessible, plus writable when
+/// this side of the copy is the destination.
+///
+/// A user frame must also be reachable *through the physmap*, because that is how
+/// the copy loops touch it. The physmap covers RAM only: `paging.init` skips every
+/// `.mmio` region, while `mmio_map` hands a driver its device's BAR as an ordinary
+/// user-accessible mapping. Such a page satisfies the permission walk and would
+/// then fault ring 0 on the physmap alias — the very #PF this layer exists to make
+/// impossible — so coverage is confirmed before the address is returned, and an
+/// uncovered frame is refused like any other bad buffer. (Confirming coverage,
+/// rather than testing the `device_grant` bit, is what keeps physmap-backed RAM
+/// that merely carries that bit — a scanout surface — usable as a buffer.)
+pub fn resolve(address_space: u64, virtual: u64, for_write: bool) ?u64 {
+    if (address_space == 0) return architecture.translate(architecture.kernelPageTable(), virtual);
+    const physical = architecture.translateUser(address_space, virtual, for_write) orelse return null;
+    if (architecture.translate(architecture.kernelPageTable(), boot_handoff.physicalToVirtual(physical)) == null) return null;
+    return physical;
+}
+
+/// Copy `destination.len` bytes from `user_va` in address space `user_as` into the
+/// kernel buffer `destination`. False — never a #PF — if the range escapes the
+/// user half, or any source page is unmapped or not readable from ring 3.
+/// Handles page-straddling buffers.
+pub fn copyFromUser(user_as: u64, user_va: u64, destination: []u8) bool {
+    if (user_as == 0) return false; // not a user address space
+    if (!userRangeOk(user_va, destination.len)) return false;
+    var off: usize = 0;
+    while (off < destination.len) {
+        const physical = resolve(user_as, user_va + off, false) orelse return false;
+        const left = page_size - ((user_va + off) & (page_size - 1));
+        const n = @min(left, destination.len - off);
+        const source: [*]const u8 = @ptrFromInt(boot_handoff.physicalToVirtual(physical));
+        @memcpy(destination[off..][0..n], source[0..n]);
+        off += n;
+    }
+    return true;
+}
+
+/// The write direction: copy the kernel buffer `source` out to `user_va` in
+/// address space `user_as`. False — never a #PF, never a partial promise — if the
+/// range escapes the user half, or any destination page is unmapped, kernel-only,
+/// or read-only for ring 3. (A refusal mid-way may already have written earlier
+/// pages; the caller fails the whole system call, so the buffer's contents are
+/// meaningless either way.)
+///
+/// The mirror of `copyFromUser`, and the only way kernel data reaches a user
+/// buffer outside the IPC path's `copyAcross`.
+pub fn copyToUser(user_as: u64, user_va: u64, source: []const u8) bool {
+    if (user_as == 0) return false; // not a user address space
+    if (!userRangeOk(user_va, source.len)) return false;
+    var off: usize = 0;
+    while (off < source.len) {
+        const physical = resolve(user_as, user_va + off, true) orelse return false;
+        const left = page_size - ((user_va + off) & (page_size - 1));
+        const n = @min(left, source.len - off);
+        const destination: [*]u8 = @ptrFromInt(boot_handoff.physicalToVirtual(physical));
+        @memcpy(destination[0..n], source[off..][0..n]);
+        off += n;
+    }
+    return true;
+}
+
+/// `copyToUser` for any fixed-layout value — the shape most write-direction
+/// system calls want (a `KlogStatus`, a `FileAttributes`).
+pub fn copyValueToUser(user_as: u64, user_va: u64, value: anytype) bool {
+    return copyToUser(user_as, user_va, std.mem.asBytes(value));
+}

system/kernel/vfs.zig

@@ -7,7 +7,8 @@
 //!     mount (the initrd trees at /system and /test, the scratch ram nodes) resolves to a
 //!     stateless node TOKEN served directly by `fs_node` (read/status/readdir
 //!     with copy-out). A path under a USERSPACE mount (the fat server at
-//!     /mnt/usb and /var) resolves to the backend's ENDPOINT: the kernel
+//!     /volumes/usb, /system/configuration, and /system/logs) resolves to the
+//!     backend's ENDPOINT: the kernel
 //!     installs a (deduplicated) handle in the caller's table, rewrites the
 //!     path mount-relative, and the caller speaks the unchanged vfs-protocol
 //!     to the backend over the ordinary ipc_call rendezvous. The kernel never
@@ -21,9 +22,10 @@
 //! Mounting is `fs_mount(prefix, backend_handle, rewrite)`: possession of the
 //! backend endpoint handle is the capability, exactly the trust of the old
 //! userspace router's op-6 cap-pass. An optional REWRITE prefix maps the mount
-//! into the backend's namespace ("/var" -> fat's "/var" subtree while the same
-//! backend also serves "/mnt/usb" from its root), so FHS paths stay decoupled
-//! from which volume happens to carry them.
+//! into the backend's namespace ("/system/logs" -> the boot volume's
+//! identically-named subtree while the same backend also serves "/volumes/usb"
+//! from its root), so hierarchy paths stay decoupled from which volume happens
+//! to carry them.
 
 const std = @import("std");
 const abi = @import("abi");
@@ -99,7 +101,7 @@ var directory_count: usize = 0;
 /// If `path` lies under `mount_prefix` — equal to it, or the prefix followed by
 /// a path separator — return the path relative to the mount ("/" for an exact
 /// match, otherwise the tail beginning with '/'). Null when not under the
-/// mount, so "/mnt/usb" never captures "/mnt/usbextra".
+/// mount, so "/volumes/usb" never captures "/volumes/usbextra".
 pub fn underMount(path: []const u8, mount_prefix: []const u8) ?[]const u8 {
     if (path.len < mount_prefix.len) return null;
     if (!std.mem.eql(u8, path[0..mount_prefix.len], mount_prefix)) return null;
@@ -182,11 +184,16 @@ fn installMount(prefix: []const u8, kind: MountKind, backend: ?*ipc.Endpoint, re
 
 // --- resolve -----------------------------------------------------------------
 
+/// Longest rewritten mount-relative path a backend resolution can carry — the
+/// size `fs_resolve`'s caller has to have room for, so it is named rather than
+/// spelled out at the one place that builds it.
+pub const maximum_backend_path = maximum_rewrite + maximum_prefix + 160;
+
 pub const Resolved = union(enum) {
     /// Kernel-served: a permanent node token.
     kernel_node: u64,
     /// Backend-served: the endpoint plus the rewritten mount-relative path.
-    backend: struct { endpoint: *ipc.Endpoint, path: [maximum_rewrite + maximum_prefix + 160]u8, path_len: usize },
+    backend: struct { endpoint: *ipc.Endpoint, path: [maximum_backend_path]u8, path_len: usize },
     not_found: void,
 };
 
@@ -326,14 +333,30 @@ pub fn nodeReaddir(node_token: u64, cursor: u64, name_out: []u8) ?struct { heade
 
 // --- mount/unmount (syscall bodies; caller resolved the handle) --------------
 
+/// The writable subtrees a backend may mount beneath an initrd tree — exactly
+/// these two, nothing else. Longest-prefix resolution then routes them to the
+/// volume while every other /system and /test path stays initrd-served, so no
+/// bundled binary can ever be shadowed.
+const initrd_carve_outs = [_][]const u8{ "/system/configuration", "/system/logs" };
+
+fn isInitrdCarveOut(prefix: []const u8) bool {
+    for (initrd_carve_outs) |allowed| {
+        if (std.mem.eql(u8, prefix, allowed)) return true;
+    }
+    return false;
+}
+
 /// Mount `backend` at `prefix` with an optional backend-side `rewrite` prefix.
 /// The endpoint reference is taken by the caller (process.zig bumps it); refuses
-/// shadowing or replacing the initrd trees (/system, /test).
+/// shadowing or replacing the initrd trees (/system, /test) — except the two
+/// carve-outs in `initrd_carve_outs`, the writable configuration/log subtrees.
 pub fn mountBackend(prefix: []const u8, backend: *ipc.Endpoint, rewrite: []const u8) bool {
     if (!isAbsolute(prefix) or prefix.len < 2 or prefix.len > maximum_prefix) return false;
     if (rewrite.len > maximum_rewrite) return false;
-    for (&mounts) |*m| { // the initrd trees are not shadowable
-        if (m.used and m.kind == .kernel_initrd and underMount(prefix, m.prefixSlice()) != null) return false;
+    for (&mounts) |*m| { // the initrd trees are not shadowable (carve-outs aside)
+        if (m.used and m.kind == .kernel_initrd and underMount(prefix, m.prefixSlice()) != null) {
+            if (!isInitrdCarveOut(prefix)) return false;
+        }
     }
     installMount(prefix, .backend, backend, rewrite);
     return true;
@@ -353,12 +376,12 @@ pub fn unmount(prefix: []const u8) bool {
 // --- tests (host) ------------------------------------------------------------
 
 test "underMount matches only at path boundaries" {
-    try std.testing.expectEqualStrings("/", underMount("/mnt/usb", "/mnt/usb").?);
-    try std.testing.expectEqualStrings("/system/kernel", underMount("/mnt/usb/system/kernel", "/mnt/usb").?);
-    try std.testing.expect(underMount("/mnt/usbextra", "/mnt/usb") == null);
-    try std.testing.expect(underMount("/mnt", "/mnt/usb") == null);
-    try std.testing.expect(underMount("/other", "/mnt/usb") == null);
-    try std.testing.expect(underMount("greeting", "/mnt/usb") == null);
+    try std.testing.expectEqualStrings("/", underMount("/volumes/usb", "/volumes/usb").?);
+    try std.testing.expectEqualStrings("/system/kernel", underMount("/volumes/usb/system/kernel", "/volumes/usb").?);
+    try std.testing.expect(underMount("/volumes/usbextra", "/volumes/usb") == null);
+    try std.testing.expect(underMount("/volumes", "/volumes/usb") == null);
+    try std.testing.expect(underMount("/other", "/volumes/usb") == null);
+    try std.testing.expect(underMount("greeting", "/volumes/usb") == null);
 }
 
 test "parentOf walks toward the root" {

system/services/acpi/acpi.zig

@@ -215,7 +215,7 @@ fn onInit(endpoint: ipc.Handle) bool {
         const entry = registered[i];
         const hid = entry.hid[0..entry.hid_len];
         // The devices.csv columns (bus=acpi, hid) then the human-readable name — a
-        // would-be /etc/devices.csv row read straight off the boot log.
+        // would-be /system/configuration/devices.csv row read straight off the boot log.
         const desc = acpi_ids.description(hid);
         if (desc.len != 0)
             std.log.info("device {d}  bus=acpi hid={s}  —  {s}  ({d} resources)", .{ entry.device_id, hid, desc, entry.resource_count })

system/services/acpi/build.zig

@@ -0,0 +1,22 @@
+//! The acpi service as a binary package (docs/build-packages-plan.md):
+//! this file names the binary and EXACTLY the modules its source imports —
+//! build-support resolves each name from the domains this zon declares.
+//!
+//! The artifact is named "discovery": one swappable process per firmware
+//! fills the ramdisk's neutral `discovery` slot (docs/discovery.md); the
+//! root's -Ddiscovery picks this package or `fdt`.
+
+const std = @import("std");
+const build_support = @import("build-support");
+
+pub fn build(b: *std.Build) void {
+    const exe = build_support.userBinary(b, .{
+        .name = "discovery",
+        .root_source_file = b.path("acpi.zig"),
+        .imports = &.{
+            "acpi-ids", "aml", "device-manager-protocol", "driver", "ipc", "logging", "memory",
+            "power-protocol", "process", "service", "time",
+        },
+    });
+    b.installArtifact(exe);
+}

system/services/acpi/build.zig.zon

@@ -0,0 +1,16 @@
+.{
+    .name = .acpi,
+    .version = "0.0.0",
+    .fingerprint = 0xf31e9a0903256b64, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{
+        // build-support supplies the shared recipe; kernel is implicit in
+        // every binary (the root shim + link script live there). The rest
+        // are exactly the homes of this binary's declared imports.
+        .@"build-support" = .{ .path = "../../../build-support" },
+        .kernel = .{ .path = "../../../library/kernel" },
+        .device = .{ .path = "../../../library/device" },
+        .protocol = .{ .path = "../../../library/protocol" },
+    },
+    .paths = .{""},
+}

system/services/device-manager/build.zig

@@ -0,0 +1,18 @@
+//! The device-manager service as a binary package (docs/build-packages-plan.md):
+//! this file names the binary and EXACTLY the modules its source imports —
+//! build-support resolves each name from the domains this zon declares.
+
+const std = @import("std");
+const build_support = @import("build-support");
+
+pub fn build(b: *std.Build) void {
+    const exe = build_support.userBinary(b, .{
+        .name = "device-manager",
+        .root_source_file = b.path("device-manager.zig"),
+        .imports = &.{
+            "device-manager-protocol", "device-registry", "driver", "file-system", "ipc",
+            "logging", "memory", "process", "service", "time",
+        },
+    });
+    b.installArtifact(exe);
+}

system/services/device-manager/build.zig.zon

@@ -0,0 +1,16 @@
+.{
+    .name = .device_manager,
+    .version = "0.0.0",
+    .fingerprint = 0x7092fc24905cd147, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{
+        // build-support supplies the shared recipe; kernel is implicit in
+        // every binary (the root shim + link script live there). The rest
+        // are exactly the homes of this binary's declared imports.
+        .@"build-support" = .{ .path = "../../../build-support" },
+        .kernel = .{ .path = "../../../library/kernel" },
+        .device = .{ .path = "../../../library/device" },
+        .protocol = .{ .path = "../../../library/protocol" },
+    },
+    .paths = .{""},
+}

system/services/device-manager/device-manager.zig

@@ -28,7 +28,7 @@ const registry = @import("device-registry");
 const fs = @import("file-system");
 
 // --- the device registry ------------------------------------------------------
-// Driver matching is data-driven and authoritative: /etc/devices.csv (parsed by
+// Driver matching is data-driven and authoritative: /system/configuration/devices.csv (parsed by
 // the device-registry module) names, per bus, which driver binds a reported
 // device, the most-specific match winning. There is no compiled-in fallback — a
 // device no row matches goes unbound and is logged. This retired the hand-kept
@@ -41,12 +41,12 @@ var registry_source: [8192]u8 = undefined;
 var registry_rules: [64]registry.Rule = undefined;
 var registry_count: usize = 0;
 
-/// Read and parse /etc/devices.csv once at boot. The file lives in the initial
+/// Read and parse /system/configuration/devices.csv once at boot. The file lives in the initial
 /// ramdisk, which the kernel serves directly — no filesystem service need be up
 /// (fat is spawned after the manager), so this is a plain fs.open + read.
 fn loadRegistry() void {
-    var file = fs.open("/etc/devices.csv", .{}) orelse {
-        _ = logging.write("/system/services/device-manager: /etc/devices.csv missing — nothing will match\n");
+    var file = fs.open("/system/configuration/devices.csv", .{}) orelse {
+        _ = logging.write("/system/services/device-manager: /system/configuration/devices.csv missing — nothing will match\n");
         return;
     };
     defer file.close();
@@ -58,9 +58,9 @@ fn loadRegistry() void {
     }
     const result = registry.parse(registry_source[0..used], &registry_rules);
     registry_count = result.count;
-    if (result.malformed != 0) std.log.info("/etc/devices.csv: {d} malformed line(s) skipped", .{result.malformed});
-    if (result.truncated) _ = logging.write("/system/services/device-manager: /etc/devices.csv has more rules than the table holds\n");
-    std.log.info("/etc/devices.csv: {d} rule(s) loaded", .{registry_count});
+    if (result.malformed != 0) std.log.info("/system/configuration/devices.csv: {d} malformed line(s) skipped", .{result.malformed});
+    if (result.truncated) _ = logging.write("/system/services/device-manager: /system/configuration/devices.csv has more rules than the table holds\n");
+    std.log.info("/system/configuration/devices.csv: {d} rule(s) loaded", .{registry_count});
 }
 
 /// Build a registry Identity from a bus driver's report: the bus it named, the
@@ -443,7 +443,7 @@ fn onChildAdded(message: []const u8, reply: []u8, sender: u32) usize {
         if (!addChild(report.parent, report.bus_address, report.identity, report.device_id, sender)) status = -1;
         std.log.info("child added (device {d} port {d}, identity {d}) by {s}", .{ report.parent, report.bus_address, report.identity, driver.name() });
         if (status == 0) publishEvent(message[0..device_manager_protocol.child_added_size]);
-        // Matching from reports (M19.3), now data-driven via the /etc/devices.csv
+        // Matching from reports (M19.3), now data-driven via the /system/configuration/devices.csv
         // registry: a registered child gets the most-specific driver its identity
         // matches, once — re-reports after a bus restart dedupe on the registered
         // id, exactly like the registrations do.
@@ -451,7 +451,7 @@ fn onChildAdded(message: []const u8, reply: []u8, sender: u32) usize {
             const id = identityFromReport(report);
             if (registry.matchDriver(registry_rules[0..registry_count], id)) |match| {
                 if (match.ambiguous)
-                    std.log.info("/etc/devices.csv: multiple equally-specific rules match the device {s} reported; binding {s}", .{ driver.name(), match.driver });
+                    std.log.info("/system/configuration/devices.csv: multiple equally-specific rules match the device {s} reported; binding {s}", .{ driver.name(), match.driver });
                 if (id.bus == .acpi) {
                     // An hid-matched driver (ps2-bus) is a singleton that finds its
                     // own devices once spawned — spawn it once, no device assignment.

system/services/display-demo/build.zig

@@ -0,0 +1,15 @@
+//! The display-demo service as a binary package (docs/build-packages-plan.md):
+//! this file names the binary and EXACTLY the modules its source imports —
+//! build-support resolves each name from the domains this zon declares.
+
+const std = @import("std");
+const build_support = @import("build-support");
+
+pub fn build(b: *std.Build) void {
+    const exe = build_support.userBinary(b, .{
+        .name = "display-demo",
+        .root_source_file = b.path("display-demo.zig"),
+        .imports = &.{ "display-client", "logging", "time" },
+    });
+    b.installArtifact(exe);
+}

system/services/display-demo/build.zig.zon

@@ -0,0 +1,15 @@
+.{
+    .name = .display_demo,
+    .version = "0.0.0",
+    .fingerprint = 0x5d2832e1e2880143, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.16.0",
+    .dependencies = .{
+        // build-support supplies the shared recipe; kernel is implicit in
+        // every binary (the root shim + link script live there). The rest
+        // are exactly the homes of this binary's declared imports.
+        .@"build-support" = .{ .path = "../../../build-support" },
+        .kernel = .{ .path = "../../../library/kernel" },
+        .client = .{ .path = "../../../library/client" },
+    },
+    .paths = .{""},
+}