GameCult/Idunn
Watch
9
0
Fork
You've already forked Idunn
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Cut 0: kill the stale docs, verify transaction campaign

Browse source 
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 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-09-22 15:21:11 +02:00
commit 2eb25b6a85
3 changed files with 23 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

14
README.md
View file

@ -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 <service|profile:name> [--no-wait] # request a deployment
idunn status [--command ID] # read what happened
idunn serve [runtime options] # the control plane
idunn up <service|profile:name> [--no-wait] # request a deployment
idunn status [--command ID] # read what happened
idunn cancel <command-id> # 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

12
docs/authority-map.md
View file

@ -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.

34
docs/deployment-authority.md
View file

@ -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