No description
  • Rust 99.2%
  • Shell 0.8%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Meta Vens 95016e817d Land F2: freeze writes blobs raw, per Self's ruling on the Eve survey finding
Self reviewed the F2 survey finding (Eve's gitlink under Ghostlight carries
`packages/*/dist/** text eol=lf`) and ruled it is not a real dependency on an
archive transform: Git stores text blobs as LF, `eol=lf` checks them out as
LF, so no conversion happens. Self verified this directly at Ghostlight's
pinned Eve gitlink revision `672c0c1e9fc828b63752345385727b06c50491d0` — all
26 files under `packages/*/dist/` hash identically between `git archive` and
`git hash-object --no-filters`, and none contains a CR. Stopping for the
survey was correct; the ruling is to proceed.

Survey table (repo, attributes found, verdict), recorded here as ruled:

| Repo (deploy target) | Binding source | .gitattributes findings | Verdict |
|---|---|---|---|
| Ghostlight | idunn/yggdrasil/bindings/ghostlight.toml.in | none | clean |
| Ghostlight's gitlink vendor/eve -> Eve | same binding | packages/*/dist/** text eol=lf | transform present, but a no-op on stored LF content (Self's evidence above) |
| Odin | idunn/yggdrasil/bindings/odin.toml.in | none | clean |
| CodexConnector | idunn/yggdrasil/bindings/codex-connector.toml.in | none | clean |
| Muninn (raven-muninn) | idunn/yggdrasil/bindings/raven-muninn.toml.in | none | clean |
| Heimdall | deployment/idunn-bindings/heimdall.toml.template (a second, previously unlisted binding directory, installed live 2026-09-06) | none | clean |
| Heimdall's gitlink -> CultLib | same binding | * text=auto only (F12) | clean |

`freeze_exact` now writes every tree entry raw from the object store:
`git ls-tree -r -z` for the manifest, `git cat-file --batch` for content, with
no `git archive` anywhere in the path and so no attribute-driven transform of
any kind. Modes and symlinks are preserved exactly as the tree records them.
Gitlinks are frozen the same raw way, through the same primitive, at their
own path. LFS content is never fetched; `freeze_exact` now also returns
whether any materialized file is an LFS pointer (recorded in the frozen
result's own return value — not yet plumbed into `FrozenSourceReceipt`, which
has no field for it; that is follow-up scope, not this fix).

Deleted: `git_archive_into`, `materialize_gitlink_archive`, and the
now-unused `tar_program` field — the archive-and-extract path they built has
no remaining caller. `GitSourceDriver::new` no longer takes a tar program.

Tests:
- `freeze_exact_is_byte_exact_across_every_attribute_transform`: a fixture
  with `eol=crlf`, `export-ignore`, `export-subst`, `ident`, a symlink, the
  executable bit, and a Gitlink. Every frozen file's bytes are asserted equal
  to `git cat-file blob` at the selected revision.
- `freeze_exact_matches_archive_when_untransformed_and_diverges_when_transformed`:
  the deploy-equivalence test Self's ruling asked for. An `eol=lf` file over
  already-LF content matches today's independently-reconstructed `git archive`
  tree exactly; a second file with `eol=crlf` over the same LF content
  diverges from it, so the equivalence check has teeth rather than trivially
  passing for every fixture.
- `exact_git_blobs_become_root_owned_immutable_source_without_git_metadata`
  (renamed from the git-archive-era test) now exercises `materialize_tree_raw`.
- `tools/verify-mutations/cut1.psd1`: `cut1-fix-freeze-skips-gitlinks`
  retargeted at the new call, and a new `cut1-fix-f2-revert-to-git-archive`
  entry that reverts `materialize_tree_raw` to a `git archive | tar` pipeline;
  it must die against the byte-exact test.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-22 16:48:17 +02:00
deploy Host actuator: Idunn manages a workload on a Windows host it cannot touch 2026-09-11 13:49:25 +02:00
docs Land the Cut 1 fix batch: pin every argv branch, one fetch, dead StepPort gone 2026-09-22 16:15:38 +02:00
src Land F2: freeze writes blobs raw, per Self's ruling on the Eve survey finding 2026-09-22 16:48:17 +02:00
tests/fixtures Gate Yggdrasil releases through Bifrost 2026-07-16 18:34:26 +01:00
tools/verify-mutations Land F2: freeze writes blobs raw, per Self's ruling on the Eve survey finding 2026-09-22 16:48:17 +02:00
.gitignore Stand Idunn up as its own repository 2026-09-05 17:53:29 +02:00
Cargo.lock Bump CultLib pin to 61549aa: anchor-export permission fix 2026-09-13 19:25:50 +02:00
Cargo.toml Bump CultLib pin to 61549aa: anchor-export permission fix 2026-09-13 19:25:50 +02:00
LICENSE Add the MIT license file the manifest already declares 2026-09-05 22:02:45 +02:00
README.md Cut 0: kill the stale docs, verify transaction campaign 2026-09-22 15:21:11 +02:00

Idunn

Deployment admission and daemon-survival authority for the GameCult swarm.

Idunn decides two things and nothing else: whether an artifact may be installed, and whether an already-installed body may be restarted. It keeps daemons alive across a fleet, admits releases against operator-signed authority, and reports typed health — while depending on none of the services it manages.

Extracted from Odin on 2026-09-05 with its full 136-commit history. Idunn had lived as a crate inside the repository of a service it manages, which inverted the authority it exists to hold.


Quick start

Requires Rust 1.95+. Idunn is a Linux daemon; see Platform.

git clone https://github.com/GameCult/Idunn.git
cd Idunn
cargo build --release

Two binaries land in target/release/:

Binary Purpose
idunn the daemon — keepalive supervision, deployment actuation, health
idunn-provision operator tooling — brake status, identity enrolment, provisioning

Idunn's CLI is declarative. There are five commands and no imperative escape hatch — you cannot hand it a shell string to run:

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

Request a deployment and watch it:

idunn up ghostlight --requested-by "$USER"
idunn status --command <id>

idunn up accepts a service name or profile:<name>; 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 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.

Idunn must be able to start, recover, observe and report while any managed target is absent, broken, or deliberately braked.

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, 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, or authority binding.

A deployment brake does not own the former. Suspending restart actuation requires the separately named lifecycle brake.

Forbidden. Idunn does not depend on a managed target, and does not repair 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.

# 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" },
]
# 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 CultLib in cultnet-rs — deployment and lifecycle brakes, service identity, runtime activation, expected incarnation, and the provider-health family. Idunn consumes them and defines no private copies.

State is CultCache (.cc typed documents) throughout. Health is published over CultNet RUDP.

Odin keeps its own separate projection of Idunn state for aggregation. That is the all-seer's view, not Idunn's contract, and the two sets do not overlap.

Running as a service

deploy/ carries a worked systemd installation:

File
idunn-yggdrasil.service the unit
idunn-yggdrasil operator wrapper
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. 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=. 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 for your host. Every path in ExecStart is explicit on purpose; Idunn discovers no authority implicitly.

Documentation

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 authority map, repository declaration, operator binding, release foundation, promotion and continuity
docs/deployment-authority.md the deployment transaction in depth
docs/signed-daemon-health-authority.md signed health admission and trust bindings
docs/guide.md the previous generation's keepalive daemon — no longer runs anywhere, kept for migration history; its commands no longer work
deploy/legacy/ the shell actuator that generation used, no longer running, and what replaced each part of it

Platform

Idunn targets Linux and does not compile on Windows (drivers.rs uses std::os::unix unconditionally). A local cargo check on a Windows workstation proves nothing. Test and build where it runs, in the same image Odin uses, with the working tree shipped to the host's build root:

git ls-files -z | tar --null -T - -cf - | ssh ygg 'sudo rm -rf /srv/build/idunn && sudo mkdir -p /srv/build/idunn && sudo tar -x -C /srv/build/idunn && sudo chown -R gamecultadmin:gamecultadmin /srv/build/idunn'
ssh ygg 'sudo docker run --rm -v /srv/build/idunn:/w -v /etc/machine-id:/etc/machine-id:ro -v /srv/build/cargo-registry:/usr/local/cargo/registry -v /srv/build/cargo-git:/usr/local/cargo/git -w /w rust:1.95-bookworm sh -c "cargo test --lib && cargo build --release"'

/etc/machine-id must be mounted or every identity-enrolling test fails. --lib because the tests under tests/ assume the host layout. The release binary lands in /srv/build/idunn/target/release/idunn; install it over /usr/local/bin/idunn and restart idunn-yggdrasil.service.

Licence

MIT.