From 2eb25b6a8539c8844e50c18117861142bbf4c242 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 22 Sep 2026 15:21:11 +0200 Subject: [PATCH] Cut 0: kill the stale docs, verify transaction campaign Deletes the two stale "Current implementation boundary" sections in docs/deployment-authority.md and docs/authority-map.md; both described a pre-drivers.rs era and were wrong (drivers.rs has driven Git, runners, systemd, nginx, brakes, CultCache and CultMesh for weeks). The still-true second paragraph of the deployment-authority.md section (private plan state is never published as Odin topology) moves to the end of "Typed deployment state", reworded present tense. Fixes README.md's stale claims: the CLI has five commands (cancel and validate were missing), and docs/guide.md plus deploy/legacy/ describe a generation that no longer runs anywhere, not "still what runs on yggdrasil". Documents present truth in "Candidate promotion": advance_sealing resolves, freezes, runs every recipe step and installs before the deployment brake is consulted at all. The brake only gates the move into Starting, the first Verse-visible change. Docs only, no build required. Co-Authored-By: Claude Sonnet 5 --- README.md | 14 ++++++++------ docs/authority-map.md | 12 ------------ docs/deployment-authority.md | 34 +++++++++++++++------------------- 3 files changed, 23 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index fa3a010..2ae39ff 100644 --- a/README.md +++ b/README.md @@ -31,13 +31,15 @@ Two binaries land in `target/release/`: | `idunn` | the daemon — keepalive supervision, deployment actuation, health | | `idunn-provision` | operator tooling — brake status, identity enrolment, provisioning | -Idunn's CLI is **declarative**. There are three commands and no imperative +Idunn's CLI is **declarative**. There are five commands and no imperative escape hatch — you cannot hand it a shell string to run: ```bash -idunn serve [runtime options] # the control plane -idunn up [--no-wait] # request a deployment -idunn status [--command ID] # read what happened +idunn serve [runtime options] # the control plane +idunn up [--no-wait] # request a deployment +idunn status [--command ID] # read what happened +idunn cancel # cancel a pending command +idunn validate --recipe PATH [--binding PATH] # offline admission check ``` A test, `cli_exposes_only_declarative_commands`, asserts that @@ -194,8 +196,8 @@ purpose; Idunn discovers no authority implicitly. | [`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 | +| [`docs/guide.md`](docs/guide.md) | the **previous** generation's keepalive daemon — no longer runs anywhere, kept for migration history; its commands no longer work | +| [`deploy/legacy/`](deploy/legacy/) | the shell actuator that generation used, no longer running, and what replaced each part of it | ## Platform diff --git a/docs/authority-map.md b/docs/authority-map.md index e1c0d70..dc918fd 100644 --- a/docs/authority-map.md +++ b/docs/authority-map.md @@ -199,15 +199,3 @@ Idunn ensures one compatible Odin exists, publishes the desired fleet, resolves typed capability dependencies, admits candidates, waits for independently observed presence and readiness, and promotes routes only when the required graph conditions hold. - -## Current implementation boundary - -`crates/idunn-daemon/src/deployment.rs` and `deployment_plan.rs` implement the -deterministic declaration, binding, plan, release, and Expected contracts. -`drivers.rs` implements the narrow source resolution/freeze, runner, systemd, -write-lease, topology, and route actuator ports. The transaction engine still -must persist and sequence the compiled plan, frozen-source receipt, sealed -release, activation, lease, readiness, route, and admitted generation. Driver -ports are consequences, not a second deployment controller; runtime integration -must not recreate target catalogs, raw deployment commands, root Git inspection, -or a second admission opinion. diff --git a/docs/deployment-authority.md b/docs/deployment-authority.md index 0ccda23..0612490 100644 --- a/docs/deployment-authority.md +++ b/docs/deployment-authority.md @@ -58,25 +58,6 @@ and health. CultMesh carries typed projections between them. decide Ghostlight or CodexConnector deployment before either target is promoted through this design. -### Current implementation boundary - -`deployment.rs` and `deployment_plan.rs` are the deterministic contract -foundation only. They parse one strict source declaration and one root-admitted -operator binding from the exact raw blobs retained by the compiled plan, check -private source-selection facts, derive managed providers from validated Expected -documents, and content-address a sealed release. They do not yet -drive Git, runners, systemd, nginx, brakes, CultCache, CultMesh, or the legacy -Idunn supervisor. - -The full operator binding, compiled plan, source facts, and sealed release -are private Idunn control-plane state. They contain host paths and operational -bindings and must never be published as Odin topology. Only the sanitized -`ExpectedIncarnation` projection is shaped for later CultMesh publication. It -is derived only from a sealed release validated against its compiled plan and -names both content addresses and the executable artifact digest. Present and -Ready remain Odin-owned correlations over independently verified runtime -evidence; the deployment-plan module deliberately does not model them. - ## The three truths Odin exposes For each workload incarnation, Odin keeps three distinct observations: @@ -212,6 +193,15 @@ Idunn alone issues a fenced one-shot migration grant bound to the exact source, artifact, state schema generation, and deployment incarnation. A target migration never receives general deployment or lifecycle authority. +The full operator binding, compiled plan, source facts, and sealed release are +private Idunn control-plane state. They contain host paths and operational +bindings and are never published as Odin topology. Only the sanitized +`ExpectedIncarnation` projection is shaped for CultMesh publication. It is +derived only from a sealed release validated against its compiled plan and +names both content addresses and the executable artifact digest. Present and +Ready remain Odin-owned correlations over independently verified runtime +evidence; the deployment-plan module deliberately does not model them. + ## Initial drivers and replaceable boundary The first Yggdrasil implementation uses: @@ -272,6 +262,12 @@ For a singleton incarnation: 11. Clear the promotion fence only after route adoption is observed, then drain and stop the incumbent. +Sealing resolves the source, freezes it, runs every recipe step, and installs +the release before the deployment brake is consulted at all (`advance_sealing`). +The brake gates step 5, the first Verse-visible change: publishing the +candidate's Expected incarnation on the move into `Starting`. Build and test +already run unbraked, inside the sealing phase. + The state-write lease and route membership are distinct authorities. Fencing the incumbent does not grant the candidate or change the route. Granting the candidate permits that exact private process to write but does not route stable