diff --git a/README.md b/README.md index d96a0f5..638b8ba 100644 --- a/README.md +++ b/README.md @@ -31,31 +31,46 @@ Two binaries land in `target/release/`: | `idunn` | the daemon — keepalive supervision, deployment actuation, health | | `idunn-provision` | operator tooling — brake status, identity enrolment, provisioning | -Run one daemon locally, with no swarm and no persistence: +Idunn's CLI is **declarative**. There are three commands and no imperative +escape hatch — you cannot hand it a shell string to run: ```bash -./target/release/idunn --daemon demo --restart-command "echo restart demo" +idunn serve [runtime options] # the control plane +idunn up [--no-wait] # request a deployment +idunn status [--command ID] # read what happened ``` -Inspect a deployment brake without touching anything: +A test, `cli_exposes_only_declarative_commands`, asserts that +`--deploy-command`, `--restart-command` and `--swarm-profile` are **rejected**. +What a target is, how it is built, and what it is allowed to touch live in two +documents, never in a command line — see [Recipes and bindings](#recipes-and-bindings). + +Request a deployment and watch it: ```bash -./target/release/idunn-provision deployment-brake-status \ - --store /var/lib/gamecult/idunn-authority/deployment-brake.cc \ - --operator-anchor /etc/gamecult/idunn/deployment-brake-operator-anchor.cc \ - --runtime-id --release-id --deployment-id +idunn up ghostlight --requested-by "$USER" +idunn status --command ``` -`--rudp-health-bind` is explicit and off by default. A bare single-daemon Idunn -opens no health ingress. +`idunn up` accepts a service name or `profile:`; profiles are declared by +the bindings, so `idunn up profile:full-gamecult` brings up everything bound +into that profile. ## Authority **Owner.** Deployment admission, and the continuity of installed bodies. -**Inputs.** Its own typed state stores, its own credentials, and an -operator-provided trust anchor. Nothing else. In particular, not the state, -health, binaries or availability of anything it manages. +**Inputs.** Its own typed state stores, its own credentials, and +operator-authored trust anchors and bindings. It does not read a managed +target's binaries, health, or availability to decide anything about itself. + +The one deliberate exception, stated plainly rather than hidden: Idunn reads +Odin's published topology correlation to gate **deployment** promotion, so that +a promotion waits for semantic discovery. It is read-only, an absent store +yields `None` rather than an error, and it is structurally unreachable from the +continuity path — `validate_live_providers_for_deploy` never invokes the +provider check for `CommandKind::Continuity`. Odin being down blocks +promotions. It cannot stop daemon survival. **The invariant.** @@ -66,8 +81,9 @@ A target's brake gates mutation *of that target only*. It can neither authorize nor block Idunn's own startup, nor any other target's lifecycle. **Two brakes, not one.** Deployment and continuity are separate authorities -with separate stores, and the daemon refuses to start if the two resolve to the -same store. +with separate stores, declared per target in that target's binding. A binding +naming one store for both is rejected outright — *"deployment and lifecycle +brakes are identical"*. - *Continuity* is restarting an already-admitted installed release. Physiology. - *Deployment* is changing an artifact, revision, configuration, schema, unit, @@ -80,6 +96,58 @@ requires the separately named lifecycle brake. one merely to satisfy a deploy. If recovery would require that, the target dependency is the thing to cut. +## Recipes and bindings + +Two documents describe a target, and the split is the security model. + +The **recipe** lives in the target's own repository at +`deployment/idunn/recipe.toml` (`gamecult.idunn.target_declaration.v1`). It +declares *capability*: build and test steps, the artifacts they produce, the +service's argument shape, its health contract, its state slots, and what it +provides. It names no host paths, no images, no privileges. + +The **operator binding** lives on the host under `--bindings-dir` +(`gamecult.idunn.operator_binding.v2`). It supplies everything privileged: +which origin and ref are admitted, the pinned runner image, the workload's +roots and hardening, the runtime trust anchor, the route, the two brake +stores, rollout strategy and placement. It also declares which profiles the +target belongs to. + +```toml +# recipe — in the target's repo, capability only +[[steps]] +id = "build" +phase = "build" +runner = "rust-build" +argv = ["cargo", "build", "--locked", "--release", "-p", "thing"] + +[service] +executable_artifact = "thing" +arguments = [ + { kind = "literal", value = "--store" }, + { kind = "binding", name = "state_root" }, +] +``` + +```toml +# binding — on the host, privilege only +[repository] +origin = "https://github.com/GameCult/Thing.git" +admitted_ref = "refs/heads/main" +selection = "ref-head" +recipe_path = "deployment/idunn/recipe.toml" + +[brakes] +deployment_store = "/var/lib/gamecult/idunn-authority/thing-deployment-brake.cc" +lifecycle_store = "/var/lib/gamecult/idunn-authority/thing-lifecycle-brake.cc" +``` + +A recipe cannot grant itself an affordance: the binding must name every +affordance the recipe's runners derive, and `admit()` rejects a binding that +omits one. Unknown fields are rejected on both sides. A repository that gets +compromised can therefore change what is built, but not what it is allowed to +touch on the host. + ## Contracts Idunn's typed contracts are published by @@ -105,28 +173,29 @@ the all-seer's view, not Idunn's contract, and the two sets do not overlap. | `idunn-yggdrasil.sudoers` | the narrow sudo grant the wrapper needs | The unit runs as a dedicated `idunn` user under `ProtectSystem=full`, -`ProtectHome=yes`, `PrivateTmp=yes`, with `ReadWritePaths` enumerated per -managed target and its own authority store mounted **read-only** — -`ReadOnlyPaths=/var/lib/gamecult/idunn-authority`. +`ProtectHome=yes`, `PrivateTmp=yes`. `ReadWritePaths` is Idunn's own state plus +the build root; the operator anchor, the bindings, and Odin's correlation store +are all `ReadOnlyPaths`. Idunn admits against operator authority — it does not +author it. -Note `Wants=docker.service`, not `Requires=`. Deployment runners use Docker; -continuity actuation does not. A hard requirement would let a Docker outage -stop Idunn itself and take daemon survival down with it. This was changed from -`Requires=` during extraction — if you are copying an older installed unit, -change it. +Note `Wants=docker.service`, not `Requires=`. Only the build step is +containerized; warm, fence, promote, drain and restart run on systemd, and +worktree-tree recipes skip Docker entirely. A hard requirement would let a +Docker outage stop Idunn itself and take daemon survival down with it. -Adapt the store paths, `--swarm-profile`, and `--rudp-health-bind` for your -host. Every path in `ExecStart` is explicit on purpose; Idunn discovers no -authority implicitly. +Adapt the store paths for your host. Every path in `ExecStart` is explicit on +purpose; Idunn discovers no authority implicitly. ## Documentation | | | |---|---| -| [`docs/guide.md`](docs/guide.md) | what Idunn is for, who it helps, running it, what daemons should publish, typed records | +| [`docs/migration.md`](docs/migration.md) | **start here if you run a swarm today** — moving a target from the previous generation, in order, and cutting over the authority itself | | [`docs/authority-map.md`](docs/authority-map.md) | authority map, repository declaration, operator binding, release foundation, promotion and continuity | | [`docs/deployment-authority.md`](docs/deployment-authority.md) | the deployment transaction in depth | | [`docs/signed-daemon-health-authority.md`](docs/signed-daemon-health-authority.md) | signed health admission and trust bindings | +| [`docs/guide.md`](docs/guide.md) | the **previous** generation's keepalive daemon — still what runs on yggdrasil, kept for the migration; its commands no longer work | +| [`deploy/legacy/`](deploy/legacy/) | the shell actuator that generation used, and what replaced each part of it | ## Platform diff --git a/deploy/idunn-yggdrasil.service b/deploy/idunn-yggdrasil.service index 2f9fed0..51317fe 100644 --- a/deploy/idunn-yggdrasil.service +++ b/deploy/idunn-yggdrasil.service @@ -1,8 +1,10 @@ [Unit] -Description=Idunn Yggdrasil-local lifecycle coordinator +Description=Idunn deployment admission and daemon-survival authority After=network-online.target docker.service Wants=network-online.target -# Deployment runners use Docker, but continuity actuation does not. A hard +# Deployment runners use Docker, but continuity actuation does not. Warm, +# fence, promote, drain and restart all run on systemd; only the build step +# is containerized, and worktree-tree recipes skip even that. A hard # Requires= would let a Docker outage stop Idunn itself, killing daemon # survival for every target. Want it, order after it, and let individual # container-backed deploys fail on their own if it is absent. @@ -12,9 +14,19 @@ Wants=docker.service Type=simple User=idunn Group=idunn -# Operational cancellation ceiling only. Target daemons own readiness through -# typed health; this duration must never be interpreted as deployment success. -ExecStart=/usr/local/bin/idunn --swarm-profile yggdrasil-local --repo-root /var/lib/gamecult/idunn --store /var/lib/gamecult/idunn/yggdrasil.keepalive.cc --release-authority-store /srv/bifrost/state/repository-release-authority.cc --deployment-brake-store /var/lib/gamecult/idunn-authority/deployment-brake.cc --deployment-brake-operator-anchor /etc/gamecult/idunn/deployment-brake-operator-anchor.cc --daemon-health-trust-store /etc/gamecult/idunn/daemon-health-trust.cc --rudp-health-bind 10.77.0.1:17870 --service-identity-store /var/lib/gamecult/idunn/idunn-service-identity.cc --public-health-store /var/lib/gamecult/idunn/authenticated-provider-health.cc --public-health-query-bind 127.0.0.1:17871 --command-timeout-seconds 21600 --execute +# Idunn discovers no authority implicitly. Every store is named here, and +# every one of them is Idunn's own -- no path below belongs to a managed +# target. That is the invariant, expressed as a command line. +ExecStart=/usr/local/bin/idunn serve \ + --state-store /var/lib/gamecult/idunn/control.cc \ + --bindings-dir /etc/gamecult/idunn/bindings \ + --source-root /var/lib/gamecult/idunn/sources \ + --staging-root /var/lib/gamecult/idunn/staging \ + --topology-store /var/lib/gamecult/idunn/topology.cc \ + --idunn-identity-store /var/lib/gamecult/idunn/idunn-service-identity.cc \ + --odin-correlation-store /var/lib/gamecult/odin/idunn-runtime-topology.cc \ + --odin-trust-anchor /etc/gamecult/idunn/odin-topology-anchor.cc \ + --deployment-brake-operator-anchor /etc/gamecult/idunn/deployment-brake-operator-anchor.cc Restart=always RestartSec=5 TimeoutStopSec=20 @@ -23,8 +35,18 @@ UMask=027 PrivateTmp=yes ProtectHome=yes ProtectSystem=full -ReadWritePaths=/etc/gamecult/idunn /etc/gamecult/codex-connector /etc/gamecult/ghostlight-dungeon /etc/systemd/system/codex-connector.service /etc/systemd/system/epiphany-swarm.service /etc/systemd/system/ghostlight-dungeon.service /var/lib/gamecult/idunn /srv/build /srv/voidbot -ReadOnlyPaths=/var/lib/gamecult/idunn-authority +# Idunn's own state, and the build root it materializes releases in. +# Enumerated rather than broadened: this list is the blast radius. +ReadWritePaths=/var/lib/gamecult/idunn /var/lib/gamecult/idunn-authority /srv/build +# Everything Idunn only reads. The operator anchor and target bindings are +# operator-authored: Idunn admits against them, it does not write them. +# /var/lib/gamecult/odin is a managed target's directory and is read-only on +# purpose -- Idunn consumes Odin's published topology correlation to gate +# *deployment* promotion, and nothing else. Continuity never consults it +# (see stale_odin_provider_receipt_cannot_gate_continuity_restart), and an +# absent store returns None rather than failing, so Odin being down blocks +# promotions and leaves daemon survival untouched. +ReadOnlyPaths=/etc/gamecult/idunn /var/lib/gamecult/odin [Install] WantedBy=multi-user.target diff --git a/deploy/legacy/README.md b/deploy/legacy/README.md new file mode 100644 index 0000000..dd91a25 --- /dev/null +++ b/deploy/legacy/README.md @@ -0,0 +1,62 @@ +# Legacy actuator — the generation currently installed on yggdrasil + +**These files are superseded. Do not use them for a new installation.** They are +kept because they are what is *running*, and a migration needs both sides. + +`idunn-yggdrasil` is a root shell actuator reached through the narrow sudo grant +in `idunn-yggdrasil.sudoers`. It hardcodes eleven targets, their repositories +and their admitted refs, then delegates to executable manifests under +`/srv/odin/deploy-manifests/`. It calls `idunn validate-release-authority` +and `idunn validate-minimum-source-revision` — subcommands the current binary +does not have. + +## What replaced it + +Everything this script does by convention, the current Idunn does by contract: + +| Legacy mechanism | Current owner | +|---|---| +| `deployment_target_policy()` — a `case` over eleven target names | one operator binding per target, in `--bindings-dir` | +| `upstream_ref=refs/heads/...` in shell | `[repository] admitted_ref` | +| `minimum_source_revision_required` | `[repository] minimum_revision` | +| `requires_bifrost_authority` + `--release-authority-store` | `[repository] selection = "signed-release"`, per target | +| `/srv/odin/deploy-manifests/` shell scripts | recipe `[[steps]]` in the target's own repository | +| `run_manifest_while_holding_authority_locks` | the deployment transaction and process write-lease | +| `flock` on a brake store | `[brakes] deployment_store` and `lifecycle_store` | +| root shell with `IDUNN_ACTUATOR=1` | `systemd-transient` workload driver under `DynamicUser` | + +The structural difference is not tidiness. The legacy path admits a deployment +by *validating arguments to a root shell script*, and everything after that +validation is unverified shell running as root. The current path seals exact +source and artifacts, admits one incarnation against typed operator authority, +and hands execution to systemd — with no place to pass a command string, +enforced by `cli_exposes_only_declarative_commands`. + +## The target inventory, which is still useful + +This is the real migration scope, read out of `deployment_target_policy()`: + +| Target | Repository | Admitted ref | Notes | +|---|---|---|---| +| `odin` | GameCult/Odin | `codex/ygg-idunn-independent-bootstrap` | ref is a branch, not main | +| `codex-connector` | GameCult/CodexConnector | `codex/ghostlight-release-binding` | minimum revision enforced | +| `ghostlight` | GameCult/Ghostlight | `codex/ghostlight-dungeon-mvp` | minimum revision enforced | +| `voidbot` | GameCult/VoidBot | `main` | | +| `heimdall` | GameCult/Heimdall | `main` | restart is `docker compose restart` | +| `epiphany` | GameCult/Epiphany | `codex/epiphany-shakedown-live` | | +| `epiphany-capstone-17` | GameCult/Epiphany | `codex/epiphany-shakedown-live` | second target, same repo | +| `bifrost-persona-feedback` | GameCult/Bifrost | `main` | **only** target requiring Bifrost release authority | +| `repixelizer` | GameCult/repixelizer | `main` | | +| `streampixels` | GameCult/StreamPixels | `main` | two units, one target | +| `gjallar` | GameCult/Gjallar | `codex/yggdrasil-aggregate-daemon` | | + +Seven of eleven are pinned to a non-`main` branch. That is its own problem — the +swarm goal is everyone on `main` and current with each other — and migrating a +target is the moment to fix its ref, not to copy it forward. + +## When these files die + +When every target above has a binding and a recipe, and `idunn serve` owns +actuation on yggdrasil. At that point delete the sudoers grant first, then the +script, then `/srv/odin/deploy-manifests/`. The grant is the privileged half; it +should not outlive its consumer. diff --git a/deploy/idunn-yggdrasil b/deploy/legacy/idunn-yggdrasil similarity index 100% rename from deploy/idunn-yggdrasil rename to deploy/legacy/idunn-yggdrasil diff --git a/deploy/idunn-yggdrasil.sudoers b/deploy/legacy/idunn-yggdrasil.sudoers similarity index 100% rename from deploy/idunn-yggdrasil.sudoers rename to deploy/legacy/idunn-yggdrasil.sudoers diff --git a/docs/authority-map.md b/docs/authority-map.md index 7e26343..ea258ba 100644 --- a/docs/authority-map.md +++ b/docs/authority-map.md @@ -11,7 +11,7 @@ decision about which source, release, runtime identity, process write lease, and route membership are authoritative. The detailed contract is -[`idunn-deployment-authority.md`](idunn-deployment-authority.md). +[`deployment-authority.md`](deployment-authority.md). ## Authority map diff --git a/docs/guide.md b/docs/guide.md index 9829bdc..33613f6 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -1,10 +1,19 @@ # Idunn -> **Note.** This guide predates Idunn's extraction from Odin on 2026-09-05. -> Build and run commands have been updated from Odin's npm wrappers to direct -> cargo invocations, and paths on the lost `E:` drive have been generalised. -> Anything else describing Odin's tree may still be stale; the README is -> current, this document is the deeper reference. +> **This guide describes the previous generation and is kept for the migration.** +> +> It documents the keepalive daemon driven by `--swarm-profile`, hardcoded swarm +> targets, and a root shell actuator. Commit `330e4cd` ("Rebuild Idunn around +> typed authority ports") removed that machinery, and the current binary rejects +> every command line in this document — `idunn --swarm-profile ...` returns +> `unknown Idunn command`. +> +> That generation is still what runs on yggdrasil, which is why this is here +> rather than deleted. For the current model read the [README](../README.md); +> for the route from one to the other read [migration.md](migration.md). +> +> Its durable content — what a daemon must publish, and why keepalive is not +> deployment — remains true. Its commands do not. Idunn is the keepalive daemon for the Odin swarm. diff --git a/docs/migration.md b/docs/migration.md new file mode 100644 index 0000000..8ec6910 --- /dev/null +++ b/docs/migration.md @@ -0,0 +1,144 @@ +# Migrating a target onto the current Idunn + +Status as of 2026-09-05: **no target has been migrated.** The binary installed +on yggdrasil (`/usr/local/bin/idunn`, 2026-09-02) is the previous generation, +driven by `--swarm-profile` and a root shell actuator. The current binary +rejects that invocation outright: + +``` +$ idunn --swarm-profile yggdrasil-local --store ... +Error: unknown Idunn command "--swarm-profile" +``` + +This document is the route from one to the other. It is written per target, +because the cutover is per target — there is no flag-day. + +## What changes, in one paragraph + +The old generation kept its target list *in Rust* (`swarm_targets()`, removed by +`330e4cd`) and its actuation *in shell* (`deploy/legacy/`). The current +generation keeps capability in a **recipe** inside each target's own repository, +and privilege in an **operator binding** on the host. Idunn seals source, builds +in a runner, admits one incarnation, warms a candidate under a distinct UID and +namespaces, fences the incumbent, promotes the route, and drains. Nothing in +that path takes a command string. + +## Order + +Migrate in dependency order, and migrate the authority's own dependencies last: + +1. **`ghostlight`** — first. It is actively developed, already has a build in + `/srv/ghostlight`, and its failure blast radius is one service. +2. **`codex-connector`** — second. Same shape, and the census's dependency chain + puts it before Ghostlight's consumers. +3. **`gjallar`**, **`heimdall`**, **`repixelizer`**, **`streampixels`** — the + simple ones. `heimdall` and `repixelizer` currently restart via + `docker compose`, so they are the first real test of a compose-shaped + workload under the systemd-transient driver. +4. **`bifrost-persona-feedback`** — the only target that carries signed-release + authority. Migrate it *after* at least three ref-head targets work, because + it is the one that exercises `selection = "signed-release"`. +5. **`epiphany`** and **`epiphany-capstone-17`** — two targets sharing a + repository. Prove the binding-per-target model here. +6. **`voidbot`** — deployed, live retrieval path, 5.7 GB of state. Not early. +7. **`odin`** — last of the targets. Idunn reads Odin's topology to gate + promotion, so migrating Odin changes the thing that gates the migrations. +8. **Idunn itself** — the installed unit and binary. See *Cutting over the + authority* below. + +## Per target + +### 1. Fix the ref before you carry it forward + +Seven of eleven targets are pinned to a `codex/...` branch, not `main`. The +swarm goal is everyone on `main` and current with each other. A migration that +copies `admitted_ref = "refs/heads/codex/ghostlight-dungeon-mvp"` into a binding +has laundered a branch pin into a typed contract and made it harder to see. + +Land the branch, or record in the binding's commit message why this target +cannot be on `main` yet. + +### 2. Write the recipe, in the target's repository + +`deployment/idunn/recipe.toml`, schema `gamecult.idunn.target_declaration.v1`. +It declares capability only — steps, artifacts, service argument shape, health +contract, state slots, provides. It must name no host path, no image, and no +privilege; `TargetDeclaration::parse` rejects unknown fields, and a recipe that +reaches for host authority is rejected by `admit()` rather than honoured. + +`Odin/deployment/idunn/recipe.toml` is the only worked example in the estate. +Read it before writing the second one. + +### 3. Write the binding, on the host + +`/etc/gamecult/idunn/bindings/.toml`, schema +`gamecult.idunn.operator_binding.v2`. This is where privilege lives: origin and +admitted ref, the runner image pinned **by digest**, workload roots and +hardening, runtime trust anchor, route, brakes, rollout, placement, and the +profiles this target joins. + +Two brake stores, and they must differ: + +```toml +[brakes] +deployment_store = "/var/lib/gamecult/idunn-authority/-deployment-brake.cc" +lifecycle_store = "/var/lib/gamecult/idunn-authority/-lifecycle-brake.cc" +``` + +A binding naming one store for both is rejected — *"deployment and lifecycle +brakes are identical"*. That rejection is the doctrine the old generation could +not express: a deployment brake must not be able to suspend daemon survival. + +The binding must name every affordance the recipe's runners derive. Omitting one +fails `admit()`. This is deliberate — a compromised target repository can change +what gets built, but not what it may touch. + +### 4. Dry-run, then admit + +```bash +idunn up --requested-by "$USER" --no-wait +idunn status --command +``` + +Verify before promotion, not after: the candidate must hold a **distinct UID, +PID namespace and mount namespace** from the incumbent (`prove_isolation`), and +signed `warming` presence must be observed before the fence. If the target +cannot publish signed health yet, that is the work — not a reason to widen the +trust anchor. + +### 5. Retire the legacy path for that target + +Remove its line from the sudoers `Cmnd_Alias`, then its `case` arm, then its +manifest under `/srv/odin/deploy-manifests/`. Sudoers first: the grant is the +privileged half and must not outlive its consumer. + +## Cutting over the authority + +Idunn last, and not by deploying Idunn with Idunn. + +1. Build the current Idunn on Linux and stage it beside the running one — do not + overwrite `/usr/local/bin/idunn` while the old daemon is supervising. +2. Create `/etc/gamecult/idunn/bindings/` and the per-target brake stores. +3. Install `deploy/idunn-yggdrasil.service` from this repository. It invokes + `idunn serve` and names every store explicitly. +4. Stop the old unit, move the binary into place, `daemon-reload`, start. +5. Verify continuity actually actuates — kill a managed daemon and watch it come + back — before trusting the cutover. A control plane that starts is not a + control plane that supervises. + +**The window matters.** Between step 4's stop and a verified step 5, nothing is +supervising the swarm. Do it with the targets already migrated, so the new +daemon has bindings to load and the window is short. + +## What is not carried forward + +`Odin@ed48185` ("Supervise Bifrost Persona feedback deployment", 2026-07-18) +added a hardcoded `bifrost-persona-feedback` target with a `stale-deployment` +failure contract and `restart_on_missing_publication`. It never reached this +repository — it landed on Odin `main` after the extraction branch diverged, and +`330e4cd` deleted the machinery it was written against. + +It is preserved at the `pre-idunn-extraction-main` tag in Odin. When +`bifrost-persona-feedback` is migrated, that commit is the specification for +what its health contract must express — re-expressed as a recipe +`[service.health]` contract, not restored as Rust.