Placeholder discovery services and the -Ddiscovery build option

system/services/acpi and system/services/fdt exist as documented
placeholders (silent clean-exit mains; the headers say exactly what each
becomes and why). The build's -Ddiscovery=acpi|fdt option fills the
ramdisk's neutral 'discovery' slot — the device manager will spawn
"discovery" by that name in M20.3 and never learn which firmware it is
on (m19-m20-plan.md decision 7). x86 defaults to acpi; the aarch64
target flips the default when it lands.

build.zig

@@ -343,6 +343,20 @@ pub fn build(b: *std.Build) void {
     // what the driver-restart scenario drives the crash-loop cap with.
     const crash_test_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "crash-test", "system/services/crash-test/crash-test.zig");
     const device_list_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "device-list", "system/services/device-list/device-list.zig");
+    // The discovery service: one swappable process per firmware
+    // (docs/m19-m20-plan.md decision 7), bundled under the neutral ramdisk name
+    // "discovery" so the device manager never learns which firmware it is on.
+    // x86 boots describe hardware with ACPI; the Raspberry Pis hand over a
+    // flattened device tree — the aarch64 target flips the default when it
+    // lands (docs/arm.md). Both are placeholders until M20.1 (acpi) and the
+    // ARM bring-up (fdt).
+    const Discovery = enum { acpi, fdt };
+    const discovery = b.option(Discovery, "discovery", "Which discovery service fills the ramdisk's 'discovery' slot (default: acpi)") orelse Discovery.acpi;
+    const discovery_source: []const u8 = switch (discovery) {
+        .acpi => "system/services/acpi/acpi.zig",
+        .fdt => "system/services/fdt/fdt.zig",
+    };
+    const discovery_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "discovery", discovery_source);
     const device_manager_exe = addUserBinary(b, kernel_target, runtime_module, posix_module, mmio_module, xkeyboard_config_module, acpi_ids_module, "device-manager", "system/services/device-manager/device-manager.zig");
     // The input service and its exercisers: the fan-out server, a hardware-free synthetic
     // source, and a subscriber that doubles as the `input` test's oracle. See docs/input.md.
@@ -378,6 +392,8 @@ pub fn build(b: *std.Build) void {
     mk_run.addFileArg(crash_test_exe.getEmittedBin());
     mk_run.addArg("device-list");
     mk_run.addFileArg(device_list_exe.getEmittedBin());
+    mk_run.addArg("discovery");
+    mk_run.addFileArg(discovery_exe.getEmittedBin());
     mk_run.addArg("device-manager");
     mk_run.addFileArg(device_manager_exe.getEmittedBin());
     mk_run.addArg("input");

docs/m19-m20-plan.md

@@ -71,7 +71,11 @@ branch is green; keep branches; push everything.
    ("brcm,bcm2835-aux-uart") — identity widens before the fdt service exists;
    and cross-firmware surfaces are named by **domain, not firmware** (M21
    defines a *power* protocol, not an "ACPI events" protocol — PSCI/mailbox
-   sources feed the same subscribers on ARM).
+   sources feed the same subscribers on ARM). **Landed early (2026-07-13):**
+   both services exist as placeholders (system/services/acpi, system/services/
+   fdt) and the build's `-Ddiscovery=acpi|fdt` option fills the ramdisk's
+   neutral `discovery` slot — the manager will spawn "discovery" by that name
+   in M20.3 and never learn which firmware it is on.
 
 ## Status
 
@@ -94,7 +98,8 @@ branch is green; keep branches; push everything.
       are the assertion — xhci must come up spawned off a pci-bus report, and
       the suite must not be able to tell the difference. discovery.md updated.
 - [ ] **merge** `feat/pci-bus` → main, push.
-- [ ] **M20.1** — acpi service, parse only: kernel publishes `acpi-tables`
+- [ ] **M20.1** — acpi service, parse only (fills the existing placeholder at
+      system/services/acpi/acpi.zig): kernel publishes `acpi-tables`
       (decision 5) — memory over the table blobs, the broad io_port grant, and
       **the SCI as an irq resource** (from the FADT; unused until M21 but free
       to record now). The service claims it, maps the blobs, runs the shared

system/services/acpi/acpi.zig

@@ -0,0 +1,30 @@
+//! /system/services/acpi — the ACPI discovery service: the x86 firmware
+//! interpreter, moved out of ring 0 (docs/m19-m20-plan.md, M20). **Placeholder:
+//! not implemented until M20.1** — it exists so the build's `-Ddiscovery`
+//! option has both of its values and the ramdisk's neutral `discovery` slot is
+//! wired before the implementation lands.
+//!
+//! What it becomes (the plan's decisions 5 and 7): claim the `acpi-tables`
+//! node the kernel publishes (table blobs + the broad io_port grant + the SCI),
+//! map the tables, and run the **shared AML module** in ring 3 behind a `Hal`
+//! backed by `mmio_map` and `io_read`/`io_write` — the interpreter cannot tell
+//! it moved. Then the bus-driver shape: `device_register` the namespace
+//! devices (`_HID`, `_CRS` resources, containment against the node's
+//! apertures), report each to the device manager, stay resident under its
+//! supervision. M21 grows the event side on the same claim: the SCI, PM1 fixed
+//! events, GPEs, Notify — published through the domain-named power protocol,
+//! never an "ACPI events" protocol.
+
+const runtime = @import("runtime");
+
+pub fn main() void {
+    // Not implemented: exit cleanly and silently (a bare spawn by the
+    // initial-ramdisk sweep must not derange other tests' markers). The
+    // supervisor reads a clean exit as "meant to stop" — correct for a
+    // placeholder.
+}
+
+pub const panic = runtime.panic;
+comptime {
+    _ = &runtime.start._start; // pull the runtime entry shim into the image
+}

system/services/fdt/fdt.zig

@@ -0,0 +1,34 @@
+//! /system/services/fdt — the devicetree discovery service: the ARM twin of the
+//! acpi service (docs/m19-m20-plan.md decision 7). **Placeholder: not
+//! implemented.** It exists so the build's `-Ddiscovery` option has both of its
+//! values from day one; the implementation lands with the Raspberry Pi
+//! bring-up (docs/arm.md).
+//!
+//! What it becomes: the per-firmware discoverer for boots that hand over a
+//! flattened device tree instead of ACPI tables. It claims the
+//! `devicetree-blob` node the kernel publishes (the FDT the loader received),
+//! walks the tree — pure data, no bytecode, so unlike the acpi service it
+//! needs no port grant and no interpreter — and, like any bus-shaped driver:
+//! `device_register`s what it finds (containment against the blob node's
+//! recorded apertures), reports each child to the device manager
+//! (`child_added`, identity = the node's `compatible` string), and stays
+//! resident under the manager's supervision (hello, restart, the usual
+//! contract).
+//!
+//! Known prerequisite recorded in the plan: `DeviceDescriptor`'s 8-byte `hid`
+//! cannot hold an FDT `compatible` string ("brcm,bcm2835-aux-uart") — identity
+//! widens before this file grows a body.
+
+const runtime = @import("runtime");
+
+pub fn main() void {
+    // Not implemented: exit cleanly and silently (a bare spawn by the
+    // initial-ramdisk sweep must not derange other tests' markers). The
+    // supervisor reads a clean exit as "meant to stop" — correct for a
+    // placeholder.
+}
+
+pub const panic = runtime.panic;
+comptime {
+    _ = &runtime.start._start; // pull the runtime entry shim into the image
+}