Idunn/docs/guide.md

Idunn

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 no longer runs anywhere; the current binary and its idunn serve generation are what runs on Yggdrasil. This file is kept for migration history. For the current model read the README; for the route from one to the other read 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.

In plain language: Idunn is the little service whose job is to know which GameCult daemons are supposed to be alive, bring them back after a reboot or crash, watch whether they are still healthy, and raise a clear alarm when a human needs to intervene.

It is named for Idunn, the keeper of the apples that keep the gods young. The job is not glamorous. That is the point. Good infrastructure should make important things boring.

What Idunn Is For

GameCult has many daemons: Odin, Bifrost, VoidBot, Mimir, Heimdall, Eve providers, service workers, renderers, bridges, and local machine helpers. Each one owns its own work, but each one should not have to carry its own private lifecycle machinery.

Idunn centralizes that lifecycle work:

• start known daemons after machine boot;
• ensure deployed daemon artifacts match the desired target revision;
• restart daemons after crashes;
• watch health and freshness signals;
• avoid restarting services when authority is unclear;
• record every deployment/restart request and result as typed state;
• record release targets, deployment artifacts, state migrations, and rollout results as typed state;
• record operator incidents in its published incidents.cc, which Bifrost reads and delivers. Idunn never waits on delivery.

The desired shape is simple:

Odin knows what exists.
Idunn keeps it alive.
Bifrost carries operator/public crossings.
Each daemon owns its own work and health publication.

Who It Helps

Idunn is for anyone running a local GameCult swarm or operating a hosted GameCult machine.

For a developer, Idunn should mean fewer mystery services to restart by hand. For an operator, Idunn should mean health problems become visible, witnessed, and routed to the right place. For daemon authors, Idunn should mean they can publish health, transport profiles, and command boundaries over CultNet RUDP instead of building one more private watchdog.

Current State

Idunn is a Rust daemon inside Odin's Cargo workspace. Starfire and Yggdrasil run separate host-local swarm profiles. Starfire owns its local adjunct daemons and remote display/telemetry lanes. Yggdrasil owns its hosted release targets, including Odin and VoidBot. Idunn starts independently of every managed target, so an Odin outage cannot remove the organ responsible for recovering Odin. Each target declares a daemon-owned health contract and keeps its own interval and deploy/restart authority. Daemon truth comes from typed CultNet/RUDP publication and daemon-owned boundary stores. Shell scripts remain deployment, restart, and manual diagnostic lowerings only; they do not satisfy health. The scheduler and continuity witness now belong to one Rust process instead of a PowerShell-herded pile of one-daemon workers.

VoidBot deployment authority is deliberately absent from starfire-local. Pushing VoidBot's upstream main branch is the release input; Yggdrasil-local Idunn observes /srv/build/VoidBot and invokes only sudo -n /usr/local/libexec/idunn-yggdrasil deploy voidbot. The privileged actuator delegates deploy and restart to the root-owned executable /srv/odin/deploy-manifests/voidbot. A developer checkout is not a deployment target and agents must not create a local keepalive or deploy path for VoidBot. Each cycle fetches origin/main in /srv/build/VoidBot and compares it with DEPLOYED_REVISION in /srv/voidbot/deploy/deployment.env. Drift owns the deployment decision. An unavailable fetch or witness raises an operator alarm instead of guessing. The privileged manifest must atomically update that witness only after the new release is verified; Idunn rejects an otherwise successful command when the witness has not converged.

scratch/idunn/idunn.keepalive.cc

Run It

From the Idunn repository root:

cargo build --release
cargo run --release --bin idunn -- --daemon demo --rudp-health-bind <idunn-rudp-health-bind>

--rudp-health-bind is explicit. Bare one-daemon Idunn does not open a localhost health ingress.

Install the local Starfire boot watchdog:

.\scripts\install-idunn-startup.ps1

That task starts one idunn.exe swarm supervisor at user logon. The Rust runtime owns the target catalog for Odin, Stonks, Muninn, the enforced Yggdrasil source artifact lanes, and the Nightwing display services. The current Mimir dashboard is observed but not restarted until its restart authority is named.

It also starts idunn-swarm-deployment-coverage, which watches the deployment target catalog in scripts/idunn-deployment-targets.ps1. A repo/service is not allowed to vanish into shrug-space: it is either enforced by Idunn, explicitly blocked with the missing authority named, external-owned, or not a runtime.

To record that a daemon has not published health, run a manual target without a matching idunn.daemon_health RUDP publication:

cargo run --release --bin idunn -- --daemon demo --restart-command "echo restart demo"

Idunn writes a non-actuating missing-publication health record and plans from that typed absence. It does not run a local health command to decide daemon truth.

To actually allow restart/deploy actuation after typed health planning decides one is needed:

cargo run --release --bin idunn -- --daemon demo --deploy-command "echo deploy demo" --restart-command "echo restart demo" --execute

To keep watching on a resident interval:

cargo run --release --bin idunn -- --daemon demo --interval-seconds 30

To run the built-in Starfire-local swarm profile directly:

cargo run --release --bin idunn -- --swarm-profile starfire-local --repo-root <repo-root> --execute

The Yggdrasil service runs the hosted profile directly:

/usr/local/bin/idunn --swarm-profile yggdrasil-local --repo-root /srv/odin/source --store /var/lib/gamecult/idunn/yggdrasil.keepalive.cc --rudp-health-bind 10.77.0.1:17870 --execute

Optional store override:

cargo run --release --bin idunn -- --daemon demo --store E:\path\to\idunn.keepalive.cc

What Daemons Should Publish

Idunn should not guess private service truth. A daemon should publish:

• its service id and Verse id;
• where its durable .cc state or witness lives;
• a health or freshness signal;
• the command boundary for deployment or artifact refresh, if one exists;
• the command boundary for restart or recovery, if one exists;
• what operator action is needed when automatic recovery is unsafe.

If that information is missing, Idunn should fail closed and create an operator alarm instead of improvising.

For the repo swarm, deployment ownership begins with catalog coverage. Use:

.\scripts\show-idunn-deployment-targets.ps1
.\scripts\health-idunn-swarm-deployment-coverage.cmd

The enforced targets are Nightwing Gjallar plus the Yggdrasil source artifact lanes whose ops runbooks can produce and verify deployment manifests. Each enforced target must declare upstream remote/branch, rollout strategy, state migration authority, and zero-downtime capability. Idunn deploys the declared declared upstream revision, not arbitrary local HEAD. Ghostlight's catalog entry remains disabled until its Linux body and signed health identity are admitted. Bifrost is blocked until its production database migration path is coherent; mobile device installs remain blocked at their physical approval boundaries; GitHub Pages remains external-owned.

Typed Records

• idunn.desired_daemon.v1
• idunn.daemon_health.v1
• idunn.signed_health_admission.v1
• idunn.keepalive_decision.v1
• idunn.deployment_request.v2
• idunn.current_deployment_request.v1
• idunn.deployment_result.v1
• idunn.release_target.v1
• idunn.deployment_artifact.v1
• idunn.state_migration_plan.v1
• idunn.state_migration_result.v1
• idunn.rollout_plan.v1
• idunn.rollout_result.v1
• idunn.restart_request.v1
• idunn.restart_result.v1
• idunn.operator_alarm.v1
• idunn.daemon_surgery_plan.v1
• idunn.daemon_transport_profile.v1
• idunn.command_boundary.v1
• idunn.runtime_transport_check.v1
• idunn.rudp_health_ingress.v1

Idunn publishes one idunn.daemon_surgery_plan.v1 record per swarm target when the swarm starts. Those records make the CultNet/RUDP migration queue explicit: owner, objective, current mechanism, intended authority, cut line, steps, blockers, severity, and status.

It also publishes one idunn.daemon_transport_profile.v1 and one idunn.command_boundary.v1 per target. The desired daemon record links to both. The transport profile names cultnet.transport.rudp.v0 as the target and marks daemon publication and daemon-owned witness stores as the health substrate. The command boundary names restart, deploy, health, and alarm authority separately; health authority belongs to daemon-published RUDP state.

At startup Idunn also publishes idunn.runtime_transport_check.v1, currently a loopback CultNet hello over cultnet.transport.rudp.v0. That proves Idunn's Rust body can use the RUDP substrate before it asks the rest of the swarm to walk through the same door.

For deploy-enforced targets, startup also publishes idunn.release_target.v1, idunn.deployment_artifact.v1, idunn.state_migration_plan.v1, and idunn.rollout_plan.v1. During deployment, Idunn runs any declared daemon-owned migration command before the deploy command; a failed migration stops the rollout and raises an operator alarm. Zero downtime is recorded only when the target declares a real in-place, blue/green, or rolling strategy; otherwise Idunn says restart-required and verifies that path honestly.

Deploy scripts are Idunn actuators. Agents should configure the target catalog, release target, command boundary, migration command, and daemon publication surface, then let Idunn run the rollout. Direct script execution without IDUNN_ACTUATOR=1 fails on purpose; the little hand reaching for the deploy button has been removed from the machine.

scripts/start-idunn-local.ps1 launches the local swarm with --rudp-health-bind 0.0.0.0:17870 so host-local and explicitly configured peers can publish to the configured Idunn health endpoint. It accepts raw idunn.daemon_health document puts on the canonical CNR0 RUDP schema channel and writes them into the keepalive store. That is daemon-owned health publication, not restart/deploy authority. On Windows, UDP reset reports from closed one-shot publishers are treated as nonfatal ingress noise so one accepted health frame cannot kill the listener.

Epiphany uses a separate signed runtime-health schema. Idunn joins that document to the exact latest Bifrost-authorized deployment request and persists idunn.signed_health_admission.v1. The privileged admission verifier reads only that fresh, current, request-bound record; generic health remains observation.

When a fresh daemon-published RUDP health record exists for a target, Idunn uses that record for keepalive planning. The record must match the daemon id, health contract, RUDP transport, and freshness window. If it is absent or stale, Idunn publishes a missing-publication observation and raises/plans from that typed absence instead of running a local health probe.

The active transport cut is no longer "make the daemons speak RUDP at all." Nightwing Gjallar now consumes Odin's accepted surface:gamecult.network.status snapshot over CultNet/RUDP, so every active Starfire-local daemon target now publishes daemon-owned RUDP health plus typed boundary state. The remaining debt is deleting bridge-only lowerings and xenos-boundary ingestion shims without letting them reclaim ownership. Odin still owes removal of hashed-store/C# witness shims once direct interoperable witness publication is ready.

Muninn media uses a codec-owned prediction model, not a custom visual-delta codec. The canonical LAN profile is muninn.rudp.low_latency_h264_lan.v1: NVENC H.264 owns inter-frame prediction, motion search, residuals, keyframe production, and the actual lossy visual encoding; CultNet/RUDP owns bounded delivery of typed video access units, audio packets, receiver feedback, retransmit pressure, expiry, and keyframe requests. Late media is dropped when it misses the fixed latency budget. Optical flow, foveation, ROI maps, or stochastic patch experiments may become future Muninn profiles only after this hardware-codec RUDP path is measured and proven insufficient.

Raven Muninn task actions are also an explicit ops invariant: Task Scheduler must execute wscript.exe //B //Nologo hidden launcher actions directly for GameCult-Muninn, GameCult-Muninn-Activate, and GameCult-Muninn-VideoProof, never raw .cmd wrappers, and the hidden VBS layer must call .ps1 launchers directly instead of cmdPath trampolines. Those three live Raven tasks have been repaired and verified. The repair actuator now uploads its Raven PowerShell body with sftp and runs a tiny cleanup wrapper, so the hidden-task repair does not hit Windows command-line limits before it can run. The Muninn serve bodies no longer publish a daemon-health document: --idunn-rudp-health, --idunn-daemon and --idunn-health-contract are retired flags that the binary rejects. Raven's liveness is Odin-correlated runtime presence; Starfire and Nightwing are checked by their scripts/health-*-muninn.ps1 witness scripts.

From here on out, the work is not "teach another daemon to speak." It is "delete the witness masks and keep ownership where it belongs."

Rust no longer gets to claim the transport is imaginary: CultLib's cultnet-rs carries the canonical CNR0 cultnet.transport.rudp.v0 session path for acknowledged CultNet messages over UDP. That is substrate only. Idunn still marks daemon profiles as migration-required until each daemon actually publishes health and command boundary records through that path.

Boundaries

Idunn is not Odin. It does not decide which Verses exist.

Idunn is not Bifrost. It does not own public crossings, Discord delivery, owner DMs, or governance transport.

Idunn is not Eve. It does not own presentation.

Idunn is the keeper of continuity. If a daemon should be alive, Idunn should know that, check it, help it recover, and leave a witness trail sharp enough that nobody has to guess what happened.