# MOUSE Plan ## Project definition **MOUSE** means **Monolithic Opinionated Unix-like System Environment**. It is a Linux distribution with a FreeBSD-style release model: a deliberately integrated, versioned base system and a distinct source-based ports collection for third-party software. MOUSE is opinionated by design. The goal is a coherent system with clear defaults and boundaries, not a framework for assembling an arbitrary Linux installation. ## System contract ### Base system The MOUSE base system is built, tested, versioned, and released as one unit. It contains the Linux kernel; musl libc; ChimeraUtils; the C/C++ toolchain based on Clang and LLVM; the default login environment; essential system configuration; and the service framework. Every executable in the MOUSE base system is statically linked against musl. Base-image validation must reject an ELF interpreter or dynamic `NEEDED` entries. This policy does not automatically apply to third-party ports, whose linkage contract will be specified separately. Base components are not installed, upgraded, or removed through the ports tree. A base-system update changes the whole release in a controlled, compatible way. ### Ports The MOUSE ports tree contains third-party software outside the base system. A port describes how to fetch, verify, patch, build, install, and remove a piece of software from source, including its dependencies. The first release treats ports as source-built software; it does not promise a public binary-package repository. If binary packages are added later, they must be generated from the same ports revision and remain an acceleration layer, not a second package definition system. The ports tree installs outside the base-owned paths. The precise prefix and package database format are implementation decisions, but both must preserve the rule that a port cannot overwrite a file owned by the base system. ## Component choices | Component | MOUSE choice | Rationale | | --- | --- | --- | | Identity | MOUSE: Monolithic Opinionated Unix-like System Environment | States the integrated release model and deliberate system conventions. | | Init and supervision | `cheesed`, OpenRC, and `supervise-daemon` | `cheesed` remains PID 1 and owns early boot, signal handling, orphan reaping, and final shutdown. OpenRC orders service lifecycle actions, while one `supervise-daemon` process owns the restart policy and runtime state of each supervised service. | | Service policy | `/etc/rc.conf` | Persistent enablement lives only in `rc.conf`, for example `enable_sshd=YES`. `cheesed` translates that policy into disposable OpenRC runlevel state at boot. Service definitions and generated runlevels must not become a second persistent policy store. | | Service definitions | OpenRC service scripts | Definitions declare dependencies and lifecycle actions using OpenRC's service interface. Supervised services use `supervise-daemon`; system scripts use the base POSIX shell. | | Release engineering | Versioned base releases | Kernel, libc, base utilities, toolchain, and init framework are released together. | | Base build | Multi-stage OCI Containerfile | A digest-pinned Linux builder fetches checksum-pinned sources, builds both `mouse-src` and `cheesed`, and exports only release artifacts. Apple Container, Docker BuildKit, and Podman are interchangeable frontends. | | Kernel | Linux 6.18 with a MOUSE-owned config | The kernel is built from checksum-pinned kernel.org source. The initial `kernel/x86_64.config` targets QEMU's x86_64 serial-console, initramfs, ACPI, VirtIO, and ext4 path; it is versioned with the rest of the base rather than inherited from a host distribution. | | C library | musl | Chosen for a compact, consistent base. Port maintainers must treat musl compatibility as a first-class constraint; glibc assumptions require explicit fixes or exclusions. | | Base utilities | ChimeraUtils | Core command-line utilities are part of the MOUSE base, rather than a GNU coreutils package selected from ports. | | Default desktop | None | MOUSE starts as a text-oriented system. Desktop environments, display stacks, and related applications belong in ports. | | Default login shell | `tcsh` | This is an intentional interactive default inspired by historical BSD practice. System scripts must use a POSIX shell, not `tcsh`. | | Toolchain | Clang/LLVM | The compiler and linker toolchain are base components and are tested with each base release. | | Workload isolation | Incus | Incus provides containers and virtual machines as an optional, ports-provided operational layer; it is not represented as a FreeBSD-jail equivalent. | ## FreeBSD influence, accurately scoped MOUSE borrows FreeBSD's separation between base and third-party software, its release discipline, and its `rc.conf`-centred service policy. It does not claim to be FreeBSD or to reproduce every FreeBSD component. In FreeBSD terminology, `rc(8)` and the scripts in `/etc/rc.d` execute service startup, while `/etc/rc.conf` records local policy. MOUSE should preserve that separation: `cheesed` translates local policy and coordinates boot, OpenRC executes the service graph, and `/etc/rc.conf` is the sole persistent enablement interface. MOUSE uses OpenRC as the execution engine for that model without adopting OpenRC's usual persistent runlevel administration. During boot, `cheesed` strictly parses `enable_${name}=YES|NO` entries and generates ephemeral OpenRC runlevel membership under `/run`. OpenRC starts services in dependency order and then exits; service definitions which require supervision use `supervise-daemon`. MOUSE does not ship `rc-update`, because persistent runlevel symlinks would compete with `/etc/rc.conf` as the enablement database. The effective runlevel tree is a complete generation below `/run/openrc/runlevels/generations`, exposed through an atomically replaced `/run/openrc/runlevels/current` link and an immutable `/etc/runlevels` link to that runtime path. `cheesed` rebuilds the whole tree on every boot from versioned base templates under `/usr/lib/mouse/runlevels` and optional `enable_${name}=YES` assignments. OpenRC itself is not patched to use a MOUSE-specific runlevel path. For the first release, `rc.conf` accepts only comments, empty lines, and unique `enable_${name}=YES|NO` assignments. Service names match `[a-z][a-z0-9_]*`; missing values mean `NO` for optional services, and required base services cannot be disabled through `rc.conf`. Unknown keys, duplicate assignments, shell syntax, and names which do not resolve to exactly one service definition are errors. OpenRC global settings and include files are deferred until they have an explicit allowlisted grammar. The administrator-facing `service` command is a symlink to `rc-service`. `service foo start`, `stop`, `restart`, and `status` are runtime operations and do not change whether `foo` starts on the next boot. FreeBSD Ports and `pkg` are complementary source and binary installation paths. 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. ## Implementation roadmap 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. ### C4: persistent system 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. `/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. C4 is accepted when: - 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.