Split the system contract into boot-handoff / abi / device-abi

The `system` module (formerly `danos`) had become a grab-bag: it held the
loader<->kernel handoff *and* the kernel<->user ABI *and* the device wire types, in
one module three different audiences imported. Usage proved the seam — the
bootloader never touched the syscall/device ABI, and user space never touched the
boot handoff — so split it by audience, one module per contract:

  system/boot-handoff.zig       loader <-> kernel: BootInformation, Framebuffer,
                                MemoryMap, the VM layout + physicalToVirtual, kernel_abi
  system/abi.zig                kernel <-> user, core: SystemCall, mmap prot flags,
                                page_size, notify_badge_bit, ServiceId
  system/devices/device-abi.zig kernel <-> user, devices: DeviceDescriptor,
                                DeviceClass, ResourceDescriptor, ResourceKind, ...

device-abi is the devices sub-project's public interface, exposed as its own module
the way vfs exposes vfs-protocol — importable by user space, unlike the
kernel-internal device model it also feeds. That collapses a real duplication:
DeviceClass and ResourceKind were defined twice (device-model.zig and the contract,
kept "in sync by hand"); device-model now re-exports them from device-abi, so the
enum a driver matches on and the one the kernel classifies with are one type.

Each import now declares which contract it speaks: the bootloader imports only
boot-handoff; a driver only abi + device-abi (via the runtime); the kernel all
three. This also retires the `system` / `runtime.system` name overlap. page_size
lands in abi (it's part of the mmap contract user space aligns to); the bootloader
keeps its own local 4 KiB constant so it depends on nothing but the handoff.

All 21 importers rewired, docs updated to keep /system mapping to source. Build,
host tests, and the QEMU suite (36/36) all green.

system/devices/acpi.zig

@@ -15,7 +15,8 @@
 //! the `Hal.mapMmio` callback the caller supplies (the architecture VMM's map primitive).
 
 const std = @import("std");
-const system = @import("system");
+const boot_handoff = @import("boot-handoff");
+const abi = @import("abi");
 const parameters = @import("parameters");
 const device_model = @import("device-model.zig");
 const aml = @import("aml/aml.zig");
@@ -147,7 +148,7 @@ var aml_block_count: usize = 0;
 
 fn addAmlBlock(sdt_physical: u64) void {
     if (aml_block_count >= aml_block_physical.len or sdt_physical == 0) return;
-    const h: *const SystemDescriptorTableHeader = @ptrFromInt(system.physicalToVirtual(sdt_physical));
+    const h: *const SystemDescriptorTableHeader = @ptrFromInt(boot_handoff.physicalToVirtual(sdt_physical));
     if (h.length <= @sizeOf(SystemDescriptorTableHeader)) return;
     aml_block_physical[aml_block_count] = sdt_physical + @sizeOf(SystemDescriptorTableHeader);
     aml_block_len[aml_block_count] = h.length - @sizeOf(SystemDescriptorTableHeader);
@@ -376,14 +377,14 @@ pub fn discover(rsdp_physical: u64, device_tree: *DeviceTree, hal: Hal) !void {
     dsdt_physical = 0;
     aml_block_count = 0;
 
-    const rsdp: *const RootSystemDescriptionPointer = @ptrFromInt(system.physicalToVirtual(rsdp_physical));
+    const rsdp: *const RootSystemDescriptionPointer = @ptrFromInt(boot_handoff.physicalToVirtual(rsdp_physical));
     if (!std.mem.eql(u8, &rsdp.signature, "RSD PTR ")) return error.BadRsdpSignature;
     // Revision 0 checksums only the first 20 bytes (the v1.0 RSDP).
-    if (!checksumOk(@ptrFromInt(system.physicalToVirtual(rsdp_physical)), 20)) return error.BadRsdpChecksum;
+    if (!checksumOk(@ptrFromInt(boot_handoff.physicalToVirtual(rsdp_physical)), 20)) return error.BadRsdpChecksum;
 
     if (rsdp.revision >= 2) {
-        const xsdp: *const ExtendedSystemDescriptorPointer = @ptrFromInt(system.physicalToVirtual(rsdp_physical));
-        if (!checksumOk(@ptrFromInt(system.physicalToVirtual(rsdp_physical)), xsdp.length)) return error.BadXsdpChecksum;
+        const xsdp: *const ExtendedSystemDescriptorPointer = @ptrFromInt(boot_handoff.physicalToVirtual(rsdp_physical));
+        if (!checksumOk(@ptrFromInt(boot_handoff.physicalToVirtual(rsdp_physical)), xsdp.length)) return error.BadXsdpChecksum;
         try walkRoot(u64, xsdp.extended_system_descriptor_table_address, device_tree, hal);
     } else {
         try walkRoot(u32, rsdp.root_system_description_table_address, device_tree, hal);
@@ -393,7 +394,7 @@ pub fn discover(rsdp_physical: u64, device_tree: *DeviceTree, hal: Hal) !void {
     // read the sleep types from it.
     var blocks: [aml_block_physical.len][]const u8 = undefined;
     for (0..aml_block_count) |i| {
-        blocks[i] = @as([*]const u8, @ptrFromInt(system.physicalToVirtual(aml_block_physical[i])))[0..aml_block_len[i]];
+        blocks[i] = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(aml_block_physical[i])))[0..aml_block_len[i]];
     }
     const active = blocks[0..aml_block_count];
     if (aml.parse(device_tree.allocator, active)) |pr| {
@@ -412,11 +413,11 @@ pub fn discover(rsdp_physical: u64, device_tree: *DeviceTree, hal: Hal) !void {
 /// Walk the RSDT (Entry = u32) or XSDT (Entry = u64): validate it, then dispatch
 /// each SDT it points at. A bad individual table is skipped, not fatal.
 fn walkRoot(comptime Entry: type, root_physical: u64, device_tree: *DeviceTree, hal: Hal) !void {
-    const header: *const SystemDescriptorTableHeader = @ptrFromInt(system.physicalToVirtual(root_physical));
-    if (!checksumOk(@ptrFromInt(system.physicalToVirtual(root_physical)), header.length)) return error.BadRootChecksum;
+    const header: *const SystemDescriptorTableHeader = @ptrFromInt(boot_handoff.physicalToVirtual(root_physical));
+    if (!checksumOk(@ptrFromInt(boot_handoff.physicalToVirtual(root_physical)), header.length)) return error.BadRootChecksum;
 
     const count = (header.length - @sizeOf(SystemDescriptorTableHeader)) / @sizeOf(Entry);
-    const base: [*]const u8 = @ptrFromInt(system.physicalToVirtual(root_physical));
+    const base: [*]const u8 = @ptrFromInt(boot_handoff.physicalToVirtual(root_physical));
     const entries: [*]align(1) const Entry = @ptrCast(base + @sizeOf(SystemDescriptorTableHeader));
 
     for (entries[0..count]) |ent| {
@@ -427,7 +428,7 @@ fn walkRoot(comptime Entry: type, root_physical: u64, device_tree: *DeviceTree,
 
 /// Dispatch a single SDT on its signature.
 fn handleTable(device_tree: *DeviceTree, hal: Hal, sdt_physical: u64) !void {
-    const header: *const SystemDescriptorTableHeader = @ptrFromInt(system.physicalToVirtual(sdt_physical));
+    const header: *const SystemDescriptorTableHeader = @ptrFromInt(boot_handoff.physicalToVirtual(sdt_physical));
     const sig = header.signature;
     if (std.mem.eql(u8, &sig, &APIC)) {
         try parseMadt(device_tree, header);
@@ -1120,7 +1121,7 @@ fn pciConfigurationPtr(alloc: McfgAllocation, hal: Hal, bus: u8, device: u8, fun
         (@as(u64, function) << 12);
     // Map the configuration page (writable, for BAR sizing) and use the virtual
     // address the HAL hands back.
-    return @ptrFromInt(hal.mapMmio(physical, system.page_size, true));
+    return @ptrFromInt(hal.mapMmio(physical, abi.page_size, true));
 }
 
 /// Read a little-endian integer at `off` from a (possibly unaligned) byte pointer.

system/devices/device-abi.zig

@@ -0,0 +1,76 @@
+//! The **device ABI**: the flat, `extern` device types that cross the system_call
+//! boundary — what `device_enumerate` hands a user-space driver, what
+//! `device_register` takes back. This is the devices sub-project's *public
+//! interface*, exposed as its own `device-abi` module the same way the VFS server
+//! exposes `vfs-protocol` — so both the kernel and user space depend on the contract
+//! by name, and neither reaches into the other's files.
+//!
+//! It is also the **single source of truth** for `DeviceClass` and `ResourceKind`:
+//! the kernel's rich, pointer-based device tree (system/devices/device-model.zig,
+//! which user space must never import) re-exports these, so the enum that a driver
+//! matches on and the enum the kernel classifies with are the *same* type — no
+//! hand-kept "mirror in order" to drift. The core kernel↔user ABI is [[abi]]; the
+//! loader↔kernel handoff is [[boot-handoff]].
+
+/// A coarse classification of a device, independent of the describing firmware.
+/// Kept small on purpose; refine as real drivers arrive. `enum(u32)` because the
+/// `@intFromEnum` value crosses the system_call boundary in `DeviceDescriptor.class`.
+pub const DeviceClass = enum(u32) {
+    /// The synthetic root every discovered device hangs beneath.
+    root,
+    processor,
+    interrupt_controller,
+    timer,
+    /// A PCI(e) host bridge — the root of a PCI segment (owns an ECAM window).
+    pci_host_bridge,
+    /// A single PCI function.
+    pci_device,
+    /// A device named in the ACPI namespace (from the DSDT/SSDT), carrying a
+    /// hardware ID (`_HID`) and, where static, current resource settings (`_CRS`).
+    acpi_device,
+    unknown,
+};
+
+/// The kind of hardware resource a device occupies. `enum(u32)` for the same
+/// boundary-crossing reason as `DeviceClass` (see `ResourceDescriptor.kind`).
+pub const ResourceKind = enum(u32) {
+    /// A memory-mapped I/O window: `start` is the physical base, `len` its size.
+    memory,
+    /// A legacy I/O-port range: `start` is the first port, `len` the count.
+    io_port,
+    /// An interrupt: `start` is the global system interrupt (GSI), `len` is 1.
+    irq,
+    /// A range of bus numbers owned by a bridge: `start`..`start+len`.
+    bus_range,
+};
+
+/// One device resource, as handed to a user-space driver (flat, extern).
+pub const ResourceDescriptor = extern struct {
+    kind: u64, // a ResourceKind value
+    start: u64,
+    len: u64,
+};
+
+pub const maximum_device_resources = 8;
+
+/// `DeviceDescriptor.parent` for a device with no parent — a root of the device tree.
+pub const no_parent: u64 = ~@as(u64, 0);
+
+/// A device, as snapshotted for user space by `device_enumerate`. A driver scans
+/// these to find the hardware it owns, claims it, and maps its MMIO.
+///
+/// `parent` makes the table a tree rather than a list, which is what a **bus driver**
+/// needs: it claims the bus, finds the devices below it, and publishes any it
+/// discovers itself with `device_register`. A registered child's resources must lie
+/// within its parent's (the kernel enforces this) — that containment is what makes
+/// delegation safe, since a device descriptor is otherwise a licence to map physical
+/// memory.
+pub const DeviceDescriptor = extern struct {
+    id: u64,
+    parent: u64, // a device id, or `no_parent`
+    class: u64, // a DeviceClass value
+    hid_len: u64,
+    resource_count: u64,
+    hid: [8]u8,
+    resources: [maximum_device_resources]ResourceDescriptor,
+};

system/devices/device-model.zig

@@ -12,6 +12,7 @@
 //! on top of this — nothing here presumes them.
 
 const std = @import("std");
+const device_abi = @import("device-abi");
 
 /// The hardware primitives a discovery backend needs but can't express portably.
 /// The kernel injects an implementation (the architecture VMM + port I/O), so the device
@@ -26,17 +27,10 @@ pub const Hal = struct {
     pioWrite: *const fn (width: u8, port: u16, value: u32) void,
 };
 
-/// The kind of hardware resource a device occupies.
-pub const ResourceKind = enum {
-    /// A memory-mapped I/O window: `start` is the physical base, `len` its size.
-    memory,
-    /// A legacy I/O-port range: `start` is the first port, `len` the count.
-    io_port,
-    /// An interrupt: `start` is the global system interrupt (GSI), `len` is 1.
-    irq,
-    /// A range of bus numbers owned by a bridge: `start`..`start+len`.
-    bus_range,
-};
+/// The kind of hardware resource a device occupies. Canonically defined by the
+/// device ABI (system/devices/device-abi.zig) and re-exported here, so the kernel's
+/// internal tree and the descriptors it hands user space share one enum.
+pub const ResourceKind = device_abi.ResourceKind;
 
 /// One hardware resource claimed by a device.
 pub const Resource = struct {
@@ -46,22 +40,10 @@ pub const Resource = struct {
 };
 
 /// A coarse classification of a device, independent of the describing firmware.
-/// Kept small on purpose; refine as real drivers arrive.
-pub const DeviceClass = enum {
-    /// The synthetic root every discovered device hangs beneath.
-    root,
-    processor,
-    interrupt_controller,
-    timer,
-    /// A PCI(e) host bridge — the root of a PCI segment (owns an ECAM window).
-    pci_host_bridge,
-    /// A single PCI function.
-    pci_device,
-    /// A device named in the ACPI namespace (from the DSDT/SSDT), carrying a
-    /// hardware ID (`_HID`) and, where static, current resource settings (`_CRS`).
-    acpi_device,
-    unknown,
-};
+/// Canonically defined by the device ABI (system/devices/device-abi.zig) and
+/// re-exported here — the enum a driver matches on and the one the kernel classifies
+/// with are the same type. Kept small on purpose; refine as real drivers arrive.
+pub const DeviceClass = device_abi.DeviceClass;
 
 /// Firmware-independent identity. Each backend fills only the fields it knows;
 /// the rest stay null. The generic layer never branches on *how* an id was

system/devices/platform.zig

@@ -9,7 +9,7 @@
 //! compile-time choice.
 
 const std = @import("std");
-const system = @import("system");
+const boot_handoff = @import("boot-handoff");
 const device_model = @import("device-model.zig");
 const acpi = @import("acpi.zig");
 const power = @import("power.zig");
@@ -65,7 +65,7 @@ pub fn cpusDropped() usize {
 /// ACPI registers); pass the architecture implementation. Errors leave nothing to clean up
 /// beyond the tree's own allocations.
 pub fn discover(
-    boot_information: *const system.BootInformation,
+    boot_information: *const boot_handoff.BootInformation,
     allocator: std.mem.Allocator,
     hal: Hal,
 ) !DeviceTree {