The migration procedure told operators to dry-run a target, and no dry-run existed. `up` needs a running daemon and a state store, so the only way to find out whether a binding was well-formed was to install it and see whether `serve` refused to start -- on the host, with the authority down. `idunn validate --recipe PATH [--binding PATH]` runs the same TargetDeclaration::parse and OperatorBinding::admit the daemon runs at load. It opens no store, contacts no host, and actuates nothing. Owner: the existing control-plane CLI, no new module or target. Consumer: whoever authors a binding, starting with this migration. Invariant: a binding installed on the host admits against its target's recipe. It replaces the install-and-see loop rather than adding a layer. Verified against the real estate: Odin, CodexConnector and Ghostlight recipes all parse. Negative paths checked too, because a validator that only ever passes is worse than none -- an unknown recipe field (the privilege-escalation shape), a missing --recipe, and an unreadable file all fail with the reason. A test asserts validate stays declarative and refuses --deploy-command, matching the guarantee cli_exposes_only_declarative_commands makes for the rest of the surface. 64 passed / 18 failed, against a 63/18 baseline: one added pass, no new failures, and the 18 remain the known Windows absolute-path cases. cargo check for x86_64-unknown-linux-gnu is clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
283 lines
15 KiB
Markdown
283 lines
15 KiB
Markdown
# 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:
|
|
|
|
0. **`codex-connector` — do not migrate. Retire it.** The operator is not
|
|
returning to Codex, so a credential-isolated transport for Codex subscription
|
|
inference has nothing left to isolate. It is already dead in practice: the
|
|
deployed daemon has been failing every three minutes with
|
|
`401 ... token_expired` against `chatgpt.com/backend-api/codex/models`, with
|
|
no established connections on its port. Migrating it would mean writing a
|
|
binding for a corpse. See *Retiring Codex* below.
|
|
0b. **`gjallar` — do not migrate. Retired 2026-09-06.** Had a brief useful life
|
|
on Nightwing's framebuffer, then broke and was never fixed. The Yggdrasil
|
|
incarnation ran `--headless --refresh-hz 2` for eleven days: a compositor
|
|
with no display, recomposing twice a second, 55 minutes of CPU and 125 MB
|
|
resident to produce frames nothing rendered. The only reference to
|
|
`gjallar.overview` in the estate is one Odin test file. Stopped and disabled;
|
|
420 MB under `/srv/gjallar` is reclaimable.
|
|
1. **`heimdall`** — first. It is the only target already shaped like a release:
|
|
`node /srv/heimdall/app/current/dist/src/index.js`, with a `current` symlink
|
|
over a built `dist/`. That is what `release_root` and the workload driver
|
|
expect, so it is the shortest distance between what runs and what a recipe
|
|
describes.
|
|
2. **`repixelizer`** — second. Unit is `repixelizer-gui` (the target name and
|
|
the unit name differ). Runs `/srv/repixelizer/.venv/bin/python` against a
|
|
source checkout at `/srv/repixelizer/app`, so the recipe needs a real build
|
|
step producing an artifact rather than a checkout to point at.
|
|
3. **`streampixels`** — third, and the hardest of the three despite looking
|
|
simple. It is **two units** under one target name, `streampixels-service` and
|
|
`streampixels-web`, and the service one runs
|
|
`node node_modules/tsx/dist/cli.mjs apps/service/src/index.ts` — raw
|
|
TypeScript transpiled at startup, from a checkout, with no build artifact to
|
|
seal. Idunn's model is sealed exact source *and* artifacts; this target has
|
|
to grow a build before it can have a recipe.
|
|
|
|
**Their continuity is already broken, and has been.** The legacy actuator
|
|
restarts all three with
|
|
`docker compose -f /srv/compose/yggdrasil-apps.yaml restart <name>`, and that
|
|
file **does not exist** — `/srv/compose` holds only `odin`, `voidbot` and
|
|
`voidbot-retrieval`. The path is guarded by `require_root_owned_regular_path`,
|
|
so every restart of these three has been failing at the guard. They are
|
|
running only because nothing has asked them to restart. This is the
|
|
difference between a supervised service and a service that happens to be up.
|
|
4. **`ghostlight`** — **blocked, not merely later.** A world-elaboration and
|
|
ontology rebuild is running in it right now: commits landed 2026-09-05 across
|
|
178 branches, with work parked on `codex/ghostlight-dungeon-mvp`. Adding
|
|
`deployment/idunn/recipe.toml` to that tree collides with live work. Migrate
|
|
it when the rebuild lands, and coordinate rather than assuming.
|
|
5. **`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"`.
|
|
6. **`epiphany`** and **`epiphany-capstone-17`** — two targets sharing a
|
|
repository. Prove the binding-per-target model here.
|
|
7. **`voidbot`** — deployed, live retrieval path, 5.7 GB of state. Not early.
|
|
8. **`odin`** — last of the targets. Idunn reads Odin's topology to gate
|
|
promotion, so migrating Odin changes the thing that gates the migrations.
|
|
9. **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.
|
|
|
|
**Several targets already have one.** Recipes exist in `Odin`, `Ghostlight`,
|
|
`Ghostlight-interruptfu`, `CodexConnector`, and the four `Ghostlight-worlds`
|
|
variants — eight in total. So recipe authoring is *not* the bottleneck for those
|
|
targets; the missing halves are the operator bindings and the daemon cutover.
|
|
|
|
Read `CodexConnector/deployment/idunn/recipe.toml` before writing a new one. It
|
|
is the richest worked example — it carries `[[external_inputs]]` pinned by
|
|
sha256, a non-Rust runner, and a typed credential-store schema — and since that
|
|
target is being retired rather than migrated, it is a reference with no live
|
|
claim on it. `Odin`'s is the minimal example.
|
|
|
|
### 3. Write the binding, on the host
|
|
|
|
`/etc/gamecult/idunn/bindings/<target>.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/<target>-deployment-brake.cc"
|
|
lifecycle_store = "/var/lib/gamecult/idunn-authority/<target>-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 <target> --requested-by "$USER" --no-wait
|
|
idunn status --command <id>
|
|
```
|
|
|
|
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.
|
|
|
|
Validate with `visudo -c -f` **before** installing, and diff the resulting grant
|
|
set against a backup afterwards. Removing the last entry from a `Cmnd_Alias`
|
|
leaves a dangling `\` continuation, and repairing that by hand is how you
|
|
silently drop a `*` from a neighbouring grant and break a live target's deploy
|
|
path — as happened here on 2026-09-06 to `deploy streampixels`, caught by
|
|
diffing and not by reading.
|
|
|
|
## Why retirement forces the migration
|
|
|
|
The previous generation **cannot express that a target is retired.** Its target
|
|
list is compiled into the binary; `idunn --help` on the installed daemon offers
|
|
`restart` and `redeploy` and no way to remove a daemon from supervision. So when
|
|
`codex-connector` was stopped on 2026-09-05, the supervisor immediately began
|
|
deciding:
|
|
|
|
```
|
|
Idunn decision for yggdrasil-codex-connector: restart
|
|
(health is failed; restart authority is available)
|
|
```
|
|
|
|
— eighty log lines in ten minutes, against a service deliberately retired. The
|
|
only brake that generation has is the **deployment** brake, and doctrine forbids
|
|
using it here: a deployment brake must not suspend continuity. Retiring a target
|
|
means suspending continuity *for that target only*, which is exactly what the
|
|
current generation's **lifecycle brake** is, and exactly what the old one lacks.
|
|
|
|
Until cutover, the available mitigation is to remove the sudo grant, so the
|
|
restart attempts fail at the privilege boundary rather than half-succeeding.
|
|
That is a compensator, not an owner, and it is worth noticing that the estate
|
|
found the argument for its own migration by trying to throw something away.
|
|
|
|
Gjallar, by contrast, was handled correctly, because its failure classified as
|
|
`dependency-unavailable` rather than `failed`:
|
|
|
|
```
|
|
Idunn decision for yggdrasil-gjallar: alarm
|
|
(local restart/deploy is not the owner of this failure)
|
|
```
|
|
|
|
Alarm, not resurrection. The distinction the old generation *can* draw is
|
|
between failures it owns and failures it does not — not between a target that
|
|
is broken and a target that is finished.
|
|
|
|
## 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.
|
|
|
|
## Retiring Codex
|
|
|
|
Decided by the operator 2026-09-05: the estate is not going back to Codex.
|
|
Generic token capacity comes from elsewhere, and anything *served* to third
|
|
parties needs an EU supplier with a DPA — `together.ai` is the current
|
|
direction. That makes the Codex integration a maintenance liability with no
|
|
consumer, and it is deep enough to be worth naming before anyone starts pulling.
|
|
|
|
**Live state.** `codex-connector.service` was `active (running)` and failing
|
|
`401 token_expired` on a three-minute loop against
|
|
`https://chatgpt.com/backend-api/codex/models`, with nothing connected to port
|
|
`4103`. **Stopped and disabled 2026-09-05**; the port is closed and the loop has
|
|
ended. It had consumed 1min 30s of CPU and peaked at 1.2 GB doing nothing but
|
|
retrying expired credentials.
|
|
|
|
Two loose ends that stop left behind:
|
|
|
|
- `ghostlight-dungeon.service` carries
|
|
`Environment=GHOSTLIGHT_MODEL_CONNECTOR=127.0.0.1:4103`, which now points at
|
|
nothing. It had logged nothing for 24 hours before the stop, so this broke
|
|
no working path — but it is where the provider replacement lands first.
|
|
- `epiphany-model-connector.service` binds **the same port** with
|
|
`--model gpt-5.4 --codex-home ...`. It is inactive and disabled. Two Codex
|
|
connectors were competing for one endpoint, which is duplicate authority of
|
|
exactly the kind the census was looking for; both are now off, and only one
|
|
of them has a repository.
|
|
|
|
**Blast radius**, in the order it should come out:
|
|
|
|
| Surface | What it is |
|
|
|---|---|
|
|
| `codex-connector.service` on yggdrasil | running, 401-looping, no consumers |
|
|
| the sudoers `deploy`/`restart codex-connector` grants | privileged half — remove before the script |
|
|
| `GameCult/CodexConnector` | the whole repo; a transport for a provider we no longer buy |
|
|
| `Epiphany/epiphany-openai-codex-spine` | an OpenAI/Codex adapter crate |
|
|
| `Epiphany/epiphany-codex-bridge` + vendored `app-server` | Codex JSON-RPC protocol edge |
|
|
| `VoidBot` config | `turnCodexModel`, `mindCodexModel`, `imaginationCodexModel`, `codexModelReasoningEffort` and their model lists |
|
|
| `~/.codex/AGENTS.md` and per-repo `AGENTS.md` | doctrine maintained for a second agent runtime |
|
|
|
|
**Do not simply delete the Epiphany and Ghostlight side.** Those are minds that
|
|
need *an* inference transport; CodexConnector was one implementation of that
|
|
seam, and the seam is worth keeping. The correct shape is to replace the
|
|
provider behind it, not to remove the boundary and let each mind grow its own
|
|
HTTP client — that would be re-forking the wire law CodexConnector's README
|
|
exists to prevent. Retire the Codex-specific backend; decide deliberately
|
|
whether the transport daemon is rebuilt against the new supplier or whether
|
|
CultNet already covers it.
|
|
|
|
Sequencing note: `epiphany` and `epiphany-capstone-17` are on this migration
|
|
list. Do not write bindings for them until the provider question is settled —
|
|
their deployment shape depends on whether they still front a transport daemon.
|
|
|
|
## 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.
|