From 6308489d14bf8e56a887664da428770b95078c73 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Wed, 15 Apr 2026 19:57:31 -0400 Subject: [PATCH 1/2] feat(sourceos): add initial flake scaffold for substrate control-plane work --- flake.nix | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 flake.nix diff --git a/flake.nix b/flake.nix new file mode 100644 index 0000000..acf94a3 --- /dev/null +++ b/flake.nix @@ -0,0 +1,36 @@ +{ + description = "SourceOS substrate scaffold for Fedora Asahi + Nix control-plane lanes"; + + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05"; + }; + + outputs = { self, nixpkgs }: + let + systems = [ "aarch64-linux" "x86_64-linux" ]; + forAllSystems = f: nixpkgs.lib.genAttrs systems (system: f system); + in { + formatter = forAllSystems (system: + let pkgs = import nixpkgs { inherit system; }; + in pkgs.nixfmt-rfc-style + ); + + devShells = forAllSystems (system: + let pkgs = import nixpkgs { inherit system; }; + in { + default = pkgs.mkShell { + packages = with pkgs; [ + git + jq + yq-go + nixfmt-rfc-style + ]; + shellHook = '' + echo "SourceOS substrate dev shell (${system})" + echo "This shell is the bootstrap surface for Fedora Asahi + Nix control-plane work." + ''; + }; + } + ); + }; +} From 866508281003ea33046cc45711d80a2387e26ff2 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Wed, 15 Apr 2026 20:05:42 -0400 Subject: [PATCH 2/2] docs(sourceos): add Fedora Asahi + Nix control-plane architecture --- .../fedora-asahi-nix-control-plane.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 docs/architecture/fedora-asahi-nix-control-plane.md diff --git a/docs/architecture/fedora-asahi-nix-control-plane.md b/docs/architecture/fedora-asahi-nix-control-plane.md new file mode 100644 index 0000000..4caa403 --- /dev/null +++ b/docs/architecture/fedora-asahi-nix-control-plane.md @@ -0,0 +1,215 @@ +# Fedora Asahi + Nix control plane (SourceOS substrate) + +This document defines the substrate-side architecture for running a Nix-based control plane on top of a Fedora Asahi host on Apple Silicon. + +## Scope + +This repo owns the **substrate implementation posture** for the lane: + +- Fedora Asahi host baseline +- Nix bootstrap on the host +- user-space control plane via Home Manager and service modules +- staged promotion before activation on the host +- rollback policy for config, images, and host storage snapshots +- storage/mount classes used by services and stage VMs +- operational guidance for Asahi-specific boot / EFI surfaces + +This repo does **not** own: + +- the canonical typed contract registry (`SourceOS-Linux/sourceos-spec`) +- workstation/CI contract schema (`SociOS-Linux/workstation-contracts`) +- stage execution and evidence/replay runtime (`SocioProphet/agentplane`) +- workspace orchestration (`SocioProphet/sociosphere`) + +## Design objectives + +1. Keep Fedora Asahi bootable even if Nix-managed layers fail. +2. Treat host mutation as staged, evidence-bearing work. +3. Separate immutable inputs from mutable state. +4. Make rollback explicit at every layer. +5. Respect Asahi boot constraints rather than pretending this is generic UEFI hardware. + +## Layer model + +### Layer 0 — boot / EFI surfaces + +Managed according to Asahi realities: + +- m1n1 / U-Boot / default boot path +- paired ESP assumptions per installed instance +- no fake dependency on persistent EFI variable state + +This layer is treated as sensitive substrate state, not a casual application surface. + +### Layer 1 — host OS substrate + +- Fedora Asahi host +- kernel / initramfs / device support owned by the distro lane +- snapshots and recovery policy wrapped by SourceOS operational tooling + +### Layer 2 — Nix substrate + +- `/nix/store` +- flake lock and control-plane inputs +- reproducible user-space packages and service definitions + +### Layer 3 — user / service layer + +- Home Manager profiles +- systemd user services +- rootless container runtime bindings +- rendered configs and secret-file bindings + +### Layer 4 — stage lane + +- candidate configuration +- candidate service images +- mounted data views for stage verification +- pre-promotion smoke tests + +## Boot and EFI posture + +The substrate policy here is conservative: + +1. We do not immediately replace Fedora boot ownership. +2. We treat boot assets as a separately governed surface. +3. We stage and verify user/service layers first. +4. Bare-metal NixOS convergence is a later phase after the substrate lane is stable. + +Operationally this means: + +- no unreviewed changes to boot-critical files, +- no assumption that `efibootmgr` semantics are the authority, +- explicit recovery guidance for known-good boot assets. + +## Storage and mount classes + +We distinguish four mount classes: + +### 1. Immutable rendered inputs + +Examples: + +- generated JSON/YAML config +- policy packs +- boot/stage descriptors + +Mount mode: + +- read-only in services and stage VMs + +### 2. Mutable service state + +Examples: + +- queues +- sqlite databases +- work caches +- resumable task state + +Mount mode: + +- read-write +- snapshot only with explicit intent + +### 3. Audit / evidence outputs + +Examples: + +- run receipts +- promotion evidence +- rollback evidence +- stage smoke outputs + +Mount mode: + +- append-oriented +- exportable +- strongly associated with stage/promote/rollback flows + +### 4. Host-sensitive substrate state + +Examples: + +- snapshot metadata +- boot-surface descriptors +- recovery assets + +Mount mode: + +- controlled by privileged substrate operations only + +## Promotion model + +Promotion follows this order: + +1. build candidate inputs +2. render configs +3. stage in VM or equivalent isolated lane +4. run smoke checks +5. activate the candidate generation on host +6. verify health +7. keep or roll back + +## Rollback model + +Rollback is layered. + +### Config rollback + +- Nix generation rollback +- Home Manager generation rollback + +### Image rollback + +- pinned container image digest rollback +- service restart under prior digest + +### Host rollback + +- filesystem snapshot rollback for eligible host surfaces +- boot recovery handled by substrate runbook + +We do not treat mutable application data rollback as automatic. That must be intentional and evidence-bearing. + +## Stage lane expectations + +The stage lane should validate at least: + +- config rendering succeeds +- required secret-file paths exist +- services can start +- expected mounts are present and have correct read/write posture +- health and smoke checks pass +- evidence is emitted for the stage run + +## Immediate implementation surfaces in this repo + +The initial SourceOS work for this lane should live under: + +- `flake.nix` +- `nix/` for profiles and modules +- `docs/architecture/` +- `docs/operations/` +- `tools/` for snapshot, stage, promote, and rollback helpers + +## Cross-repo dependencies + +This repo depends conceptually on: + +- `SourceOS-Linux/sourceos-spec` for typed contract shapes +- `SociOS-Linux/workstation-contracts` for workstation lane contract/conformance +- `SocioProphet/agentplane` for stage execution + evidence/replay +- `SocioProphet/prophet-platform-standards` for rollout and control standards +- `SocioProphet/socioprophet-standards-storage` for storage/mount doctrine + +Reverse dependencies from those repos into this repo should remain limited to contract consumption, integration notes, or example references. + +## Near-term work items + +- add Home Manager substrate profile for Fedora Asahi M2 +- add storage/mount class module definitions +- add stage VM module definitions +- add snapshot preflight helper tooling +- add promote/rollback helper tooling +- add operational runbook for boot-sensitive changes