mouse/src

PLAN.md

Mode 100644 → 100644; object f82456afd8a6 → adce7ed0c555

@@ -103,47 +103,113 @@
 MOUSE begins with source-built ports only. This difference is explicit and should
 not be blurred by calling the ports tree a binary package manager.
 
-## First implementation milestone
+## Implementation roadmap
 
-The first milestone is a QEMU-bootable base image that proves the boundary and
-service model rather than attempting a broad distribution.
+MOUSE advances in narrow, independently testable milestones. C0 through C3 are
+complete: the source tree builds a QEMU-bootable initramfs with a MOUSE-owned
+kernel configuration and static-musl userspace, runs `cheesed` as PID 1,
+translates `/etc/rc.conf` into disposable OpenRC runlevels, supervises services,
+and reaches a `tcsh` serial login. The next milestones turn that bootstrap image
+into a persistent multi-user system before adding package state.
 
-1. Build a bootable Linux image whose base includes musl, ChimeraUtils,
-   Clang/LLVM, `tcsh`, statically linked OpenRC tools, and `cheesed`.
-2. Implement `cheesed` as PID 1 with clean shutdown, early-boot logging, orphan
-   reaping, strict `rc.conf` parsing, and ephemeral OpenRC runlevel generation.
-3. Provide one required base service and one optional supervised service.
-   Enabling the optional service must require only `enable_${name}=YES` in
-   `/etc/rc.conf`; OpenRC must order its start and `supervise-daemon` must report
-   and apply its runtime restart policy.
-4. Create a minimal ports skeleton for one non-base program. Demonstrate fetching,
-   checksum verification, source build, dependency recording, installation,
-   removal, and rejection of an attempted write into a base-owned path.
-5. Publish the base release manifest and the exact ports-tree revision used for
-   the image, so a rebuilt system has an inspectable source identity.
+### C4: persistent system
 
-## Acceptance gates
+Build a bootable ext4 disk image containing the MOUSE base. The kernel mounts it
+as the real root filesystem and starts `/sbin/cheesed`; storage discovery and
+filesystem policy do not move into PID 1. The existing initramfs remains useful
+as a test and recovery artifact, but it is no longer the only runtime form.
 
-- A clean QEMU boot reaches a usable `tcsh` login without systemd.
-- Every base executable is a static musl binary with no ELF interpreter or
-  dynamic-library dependency.
-- `cheesed` is PID 1, OpenRC starts the generated runlevel in dependency order,
-  and `supervise-daemon` supervises the proof service.
-- `/etc/rc.conf` is the only persistent place that enables or disables the
-  optional service; the image does not contain `rc-update`.
-- `service`, as the `rc-service` interface, performs runtime lifecycle actions
-  without changing next-boot enablement.
-- The base manifest lists every base-owned file or package, and the ports tool
-  refuses to replace one.
-- A source-built test port installs and removes successfully without changing
-  the base manifest.
-- The image records its MOUSE release version and ports-tree revision.
+`/etc`, `/var`, `/home`, machine identity, and administrator service policy must
+survive reboot. Shutdown must stop services, flush filesystem state, and leave
+the disk cleanly mountable on the next boot.
 
-## Deliberately unresolved before implementation
+C4 is accepted when:
 
-- The base-system update mechanism.
-- The ports build sandbox, package database, installation prefix, and signing
-  format.
+- QEMU boots from a newly created MOUSE disk image into the existing supervised
+  serial login.
+- A file written under each persistent state area remains after poweroff and a
+  second boot of the same image.
+- A change to `/etc/rc.conf` affects the next boot without rebuilding the image.
+- Repeated clean shutdown and reboot cycles do not require filesystem recovery.
+- Failure to mount the real root produces a clear kernel or recovery diagnostic;
+  `cheesed` does not pretend to have booted a partial persistent system.
+
+### C5: networking
+
+Add the smallest complete IPv4 network path for QEMU VirtIO networking. A
+base-owned OpenRC service configures the interface, obtains a DHCP lease,
+installs the default route, and provides resolver configuration. Persistent
+network configuration belongs under `/etc`; service enablement continues to
+belong only in `/etc/rc.conf`.
+
+C5 is accepted when:
+
+- A clean boot acquires an address and default route without manual commands.
+- The guest reaches a test endpoint by IP address and resolves and reaches it by
+  DNS name.
+- `service` reports accurate network-service state and can stop and restart the
+  interface without changing next-boot policy.
+- A configured network-policy change survives reboot on the same disk image.
+- Shutdown stops network services cleanly before the persistent root is made
+  read-only.
+
+### C6: multi-user system
+
+Add the account and password tools required to create, modify, and remove local
+users and groups, including home-directory ownership and a documented,
+deliberately minimal privileged-administration path. Replace development root
+autologin with authenticated console login.
+
+C6 is accepted when:
+
+- An administrator can create an ordinary user and group using shipped tools.
+- The new user can authenticate through `agetty` and `login`, receives the
+  configured shell and home directory, and cannot write base-owned paths.
+- Account, password, group, and home-directory state survive reboot.
+- Failed authentication is rejected without disclosing password data.
+- The ordinary user can perform explicitly authorised administration through
+  the selected privilege mechanism; unrestricted implicit elevation is absent.
+- Root autologin is absent from the normal persistent image, while recovery
+  access remains explicit and documented.
+
+### C7: ports and source identity
+
+Only after installed system state exists, add a minimal source-built ports
+system. A port recipe records its pinned source, checksum, dependencies, build
+instructions, and installed-file manifest. Installation is transactional,
+refuses collisions with the base or another port, and removal deletes only
+files owned by that port. A port may install an OpenRC service definition but
+must not enable it.
+
+C7 also publishes the immutable base-file manifest and records the exact
+ports-tree revision in the image, so the source identity of an installed system
+is inspectable.
+
+C7 is accepted when:
+
+- The base manifest lists every base-owned path and the ports tool refuses to
+  replace one.
+- A source-built test port is fetched, checksum-verified, built, installed, and
+  removed without changing the base manifest.
+- Installed dependency and file-ownership records survive reboot.
+- Removing a port deletes only paths recorded as exclusively owned by that port
+  and does not alter base-owned or other-port files.
+- A ports-provided service starts on the next boot only after the administrator
+  adds its matching `enable_${name}=YES` assignment to `/etc/rc.conf`.
+- The running image reports its MOUSE release version and ports-tree revision.
+
+Dependency solving, binary repositories, signing, upgrades, and build sandboxing
+remain outside C7 until this ownership contract is proven.
+
+## Deliberately unresolved
+
+- The base-system installation and update mechanism beyond producing the C4 disk
+  image.
+- The persistent-disk partitioning scheme and physical-machine installer.
+- The exact network configuration file format and DHCP implementation for C5.
+- The account-management and privilege tools selected for C6.
+- The ports build sandbox, package database format, installation prefix, signing
+  format, dependency solver, binary repository, and upgrade protocol.
 - Whether Incus is supplied through the initial ports tree or deferred until the
   base and ports contracts are proven.
 - The policy for ports that cannot be made musl-compatible.