§6. Repository layout

planarian @ a924e09 · Spec v4.6 · snapshot main · all versions

planarian/
  Cargo.toml                 workspace
  crates/
    schema/                  types; no I/O (§8). Verus subset.
    policy/                  decision function (§11). Verus subset.
    txn/                     transaction kernel: journal states, recovery (§12). Verus subset.
    state/                   desired/observed/health/graph assembly; probe runner (§10)
    exec/                    executor protocol around txn (§12)
    incident/                incident lifecycle, budgets, cooldowns (§13)
    diagnose/                deterministic search (§13)
    changes/                 change catalog: typed handlers (§9)
    intent/                  phrase → transition or desired-state override (§14)
    backends/
      linux/                 systemd, logind, sysfs/udev, nixos-rebuild, probes, processes behind the §8 traits (one crate in A; snapshot-btrfs in C)
    fake/                    the in-memory backends the kernel is tested against (§18 rule 12): a second real implementation
    ipc/                     request and response types shared by daemon, CLI, console and tray
    watchdog/                planarian-recovery: separate binary (§12)
    daemon/                  planariad: wiring, IPC, systemd units
    cli/                     `planarian`, `ask`
    console/                 iced read-only console (§16a)
    tray/                    status indicator (StatusNotifierItem); ships with the console
    gym/                     catalog, VM harness (NixOS VM, Firecracker, Asterinas NixOS), scoring, metrics, verification accounting, the guarantees site generator (§15, §17a, §17b, §17c)
    sandbox/                 (B) dry-run and Firecracker-from-snapshot tier (§12g); not present in A
    model/                   (B) not present in A
  nix/
    module.nix               services.planarian, including the unit manifest options (§9)
    posture.nix              planarian-ready.target and failure-posture targets (§12d)
    reference.nix            personal profile in A: COSMIC + greeter + console autostart; wires the shipped change catalog (§9)
    package.nix, console.nix, verus.nix, firecracker.nix
    profiles/                (C) agent-host.nix, server.nix, personal.nix (§9a)
    template/                `nix flake init -t` starting point, including planarian/overrides.nix
    vm/, live/, installer/, demo/   the demo VM, live image and installer (docs/planarian-os.md)
    tests/                   NixOS VM tests: the gym's VM harness, runtime/generations/posture/installer tests, the boundaries check, the Verus check
    gym/                     run-vm.sh (the by-hand VM catalog runner)
  share/canonical.json       canonical probes (§9)
  docs/                      SPEC.md (this), AGENTS.md (§18), deviations.md, pins.md, assumptions.md (§17a), bypasses.md (§17b), spec-history.md (changes through v4.4), verification.md and verification-ratio.toml (§17a), guarantees.md, ga-status.md, catalog-review.md, planarian-os.md, why.md (public design essay), future-work.md (non-normative)

The layout above is descriptive of the repository at v4.6; it replaces the aspirational v4.5 layout (separate backend crates, nix/manifest.nix, nix/changes/, stub sandbox/model crates), which docs/deviations.md recorded only in part.

Dependency rule, enforced in CI: schema, policy, txn, exec, diagnose, incident, state MUST NOT depend on backends/*, std::process, or read /proc, /sys, /nix. Backends are passed as generic type parameters; in Phase A a single enum Backends wraps the concrete set. No dyn Trait in schema, policy, txn, exec.