Idunn/docs/authority-map.md

# Idunn

Idunn is GameCult's independent deployment-admission and continuity control
plane. It decides which exact workload incarnation may run, write canonical
state, receive traffic, and be kept alive. It does not depend on Odin or any
managed workload in order to start or recover its own durable admitted state.

Systemd, container runtimes, proxies, and a future Nomad or Kubernetes driver
provide generic execution and routing. Idunn owns the GameCult-specific
decision about which source, release, runtime identity, process write lease, and
route membership are authoritative.

The detailed contract is
[`deployment-authority.md`](deployment-authority.md).

## Authority map

- **Owner:** Idunn selects exact source facts under root policy, compiles the
  repository declaration against an operator binding, seals materialized
  inputs and artifacts, admits one runtime incarnation, separately controls its
  process-bound write lease and route membership, and preserves its continuity.
- **Inputs:** the exact raw repository declaration and operator-binding blobs;
  private source-driver facts; artifact and external-input materialization
  receipts; separate deployment and lifecycle brakes; Odin's observed semantic
  topology when a graph-changing decision needs discovery; signed runtime
  presence and health; Idunn's current observed-activation projection; and
  observations from narrow execution and route drivers.
- **Outputs:** private compiled plans and sealed releases; a release-bound
  sanitized Expected projection for Odin/CultMesh, keyed by incarnation so an
  incumbent and its candidate are projected side by side; one launch-scoped
  runtime activation published only after driver observation; process
  write-lease and route decisions; continuity actions; and explicit
  disagreement or failure records.
- **Derived state:** dashboards, operator summaries, proxy displays, process
  listings, and Odin correlation views are projections. They do not establish
  deployment, write, route, presence, or readiness authority.
- **Forbidden writers:** repositories cannot grant host privileges, identities,
  trust anchors, state roots, write leases, routes, placement, or rollout
  policy. Odin cannot deploy, promote, route, or grant writes. Services cannot
  configure themselves Present or Ready. Proxies and process managers cannot
  select the admitted incarnation. Raw command strings are not deployment
  authority.
- **Shared path:** `idunn up`, scheduled deployment, operator deployment,
  restart, crash recovery, and host reboot recovery all use the same admitted
  source-to-release identity. Continuity may restart only that identity; it
  cannot fetch, rebuild, migrate, or silently change configuration.

## Repository declaration

A deployable repository publishes one strict declaration, normally
`deployment/idunn/recipe.toml`. It may contain:

- literal build, test, and package argv for named runner classes;
- generic pinned HTTPS inputs with SHA-256, runner, and relative destination;
- immutable artifact outputs, optionally pinned to an expected SHA-256;
- a constrained launch contract;
- one health-contract identity;
- an optional typed state contract with state schema generation and slots
  (kinds `cultcache-file`, `external-file` and `external-directory`; the
  external kinds are process-owned state an external runtime imposes, which
  Idunn preserves and fences but never interprets);
- provided capabilities, dependency kinds, startup requirements, capacity, and
  conflicts.

The recipe does not configure runtime health states. GameCult runtime health
uses the shared `warming`, `active`, `degraded`, and `failed` ontology. Present
and Ready are Odin correlations over independently signed runtime evidence, not
recipe fields.

Stateless services declare no state block. Their operator binding therefore has
no state root, state-transition policy, or process write-lease record.

## Foreign workloads: idunn-launch

An upstream daemon that cannot speak Idunn's runtime contract (Synapse, MAS)
runs under `idunn-launch`, the unit's own process. Idunn's two-witness rule is
unchanged: Idunn observes the unit, and the launcher, inside the unit and
supervising the child, signs presence with the provider identity and the
activation key.

- **Owner:** the launcher owns presence, config rendering and the child's
  lifetime inside the unit, and the route answers it signs for that child.
  Idunn owns admission, lease, route and continuity, as before.
- **Inputs:** the runtime bundle, the activation credential and provider
  identity descriptors, the process write lease, the systemd credentials the
  binding names, and the child's health over TCP at the member bind.
- **Outputs:** signed `gamecult.runtime_presence_health.v2` (Warming, Active
  and failed to Odin; route observations on the candidate endpoint), one child
  process, and a rendered config in the unit's private tmp that is never read
  back.
- **Route:** Idunn owns both listeners of the route: the Expected route's
  stable endpoint (presence) and, when the binding has `[route.member]`, the
  member endpoint, rendered as a second server block in the one nginx fragment
  with a `limit_conn` on one per-route zone (`max_connections`, default 128), so
  members cannot exhaust the connections the presence block shares with them.
  The launcher binds the candidate endpoint and answers Idunn's challenge there,
  one connection at a time within a one-second deadline; any other first byte
  closes the connection. The answer never waits on the child: it reports the
  lifecycle's last probe, and a failed, missing or stale probe reads `degraded`.
  The child binds the member bind Idunn sets in
  `GAMECULT_IDUNN_MEMBER_BIND`, derived from the candidate port. Member bytes
  never touch the launcher.
- **Lease:** with `write_lease_required` the launcher starts the child only
  after it holds the lease (bound to this Expected, this activation and one of
  its own Warming proofs) and keeps the lease store share-locked while the
  child lives. Losing the lease stops the child.
- **Config:** one template from the release is rendered with the closed
  placeholder set `{{child.listen}}`, `{{child.listen_host}}`,
  `{{child.listen_port}}` (all three the member bind), `{{credential:NAME}}`,
  `{{credential_path:NAME}}` and `{{state_root}}`. Any other placeholder
  refuses to start.
- **Forbidden:** member traffic through the launcher; the child binding the
  candidate endpoint; a child of a lease-requiring target running without a held lease; any presence not signed
  by both keys.
- **State kind `external-directory`:** a process-owned directory imposed by an
  external runtime contract. Same writer, recovery and startup rules as
  `external-file`: it is lease-gated, preserved and fenced, never interpreted.

## Operator binding

The root-admitted operator binding supplies the physical policy a repository
cannot grant itself:

- source origin, admitted ref, selection policy, checkout, and Gitlink origins;
- pinned runner images, literal-program allowlists, resources, mounts, secrets,
  and preconfigured network profiles;
- workload driver, identity, isolation, release root, and runtime root;
- runtime ID, expected signer identity, and trust-anchor store;
- optional state root and state-transition policy;
- an optional process write-lease record exactly when a state slot is
  process-bound writable; its sibling `<filename>.lock` path is derived;
- optional route driver and stable/private endpoint binding;
- independent deployment and lifecycle brakes;
- one replica on one admitted node in the v1 foundation.

Route membership is not a write lease. A write lease is not route membership.
Neither may be inferred from a PID, unit, socket, symlink, or health message.

## Deterministic release foundation

The compiled plan retains the exact raw declaration and binding blobs and
parses those exact bytes again during validation. Its content address therefore
covers the real inputs rather than caller-supplied digests beside mutable parsed
copies.

Source-selection facts currently preserve the private driver output: the
exact commit, source tree, recipe blob, admitted ref, and Gitlink tree entries.
The contract does not claim that shape validation proves ancestry, signatures,
or object custody. Those proofs belong to the narrow source driver that will
produce the facts.

A sealed release binds the plan ID to sorted full artifact receipts and sorted
full external-input materialization receipts. Only a sealed release validated
against its exact plan can derive Expected. Expected includes the plan and
release IDs, runtime and signer identities, health contract, node, route,
executable artifact digest, capabilities, selected dependencies, and the
optional canonical state-contract digest computed from the typed
`StateDeclaration` MessagePack encoding.

Expected is stable release and topology intent. Each actuator launch receives a
separate tiny `idunn.runtime_activation.v1` containing the Expected digest and
one Idunn-issued opaque runtime-instance ID. Idunn publishes that activation as
current only after the workload driver observes the matching native process and
artifact. Present requires both that Idunn observation and the service's
independent signed presence; either document alone is insufficient.

Managed dependency candidates are derived from validated Expected documents.
External operator bindings remain expected configuration only; they cannot
impersonate signed presence or readiness.

### Source resolution and actuation map

- **Owner:** the Idunn deployment transaction owns the transition from one
  observation of a moving admitted ref to runner-readable immutable source.
  The source driver resolves through a transaction-unique fetched-ref witness;
  the control loop must compile and durably persist the complete
  `CompiledDeploymentPlan` before any source freeze or runner actuation.
- **Inputs:** the root-admitted raw operator-binding bytes; the exact repository
  declaration blob read from the selected Git tree; one unique source-resolution
  ID; the fetched admitted-ref revision; the selected commit and tree; and the
  complete Gitlink path, origin, and revision set admitted by that binding.
- **Outputs:** private `ResolvedSource` facts used to compile the plan; a
  plan-only exact archive in root-owned transaction storage; and a
  `FrozenSourceReceipt` binding the transaction ID, plan ID, and snapshot digest.
  The receipt is embedded in the observed `FrozenSource` and must validate
  against the plan before a runner may consume the tree.
- **Derived state:** the source-identity checkout, unique fetched ref, temporary
  Gitlink checkouts, extracted runner workspaces, and in-memory `FrozenSource`
  view are disposable projections. None may replace the persisted plan,
  receipt, or sealed release as transaction authority.
- **Forbidden writers:** a repository identity may perform Git and network
  reads but cannot write the root-owned frozen tree. A moving ref, mutable
  checkout, caller-supplied parsed binding, fresh recipe read, or incomplete
  Gitlink subset cannot revise a compiled transaction. Resume may not resolve a
  fresh binding or ref, and runner actuation may not accept source without its
  plan-bound receipt.
- **Shared path:** initial execution resolves once, compiles and persists the
  full plan, freezes only from that plan, persists the receipt, re-observes the
  immutable snapshot, and runs the bound builders. Retry and crash recovery use
  the same persisted plan and receipt; if freeze must be repeated, it fetches
  only the exact planned revisions and never observes the moving ref again.
  Transaction source storage is cleaned only after the sealed release has been
  durably persisted.
- **Deletion line:** source-owned worktrees and Git metadata do not cross into
  actuation storage; source selection does not return a runner-usable mutable
  checkout; and no resume path is permitted to reconstruct authority from the
  current repository binding or branch head.
- **Verification layer:** focused source-driver tests observe the unique
  admitted-ref witness, exact Gitlink-set equality, root ownership, canonical
  read-only modes, bounded symlinks, snapshot digest, and plan/receipt binding.
  Transaction crash tests must additionally prove that every boundary after
  plan persistence resumes without ref resolution and that cleanup cannot run
  before sealed-release persistence.

## Promotion and continuity

For a routed stateful singleton, Idunn starts the candidate privately, observes
the exact actuator launch, publishes its current activation, and observes its
signed warming presence. It then fences the incumbent writer, grants the
candidate its exact process-bound write lease, and waits for signed active
health plus Ready correlation. It changes and observes route membership only
afterward. Only after the proxy has adopted the candidate may Idunn clear the
promotion fence and drain the incumbent.

A target has two slots: the incumbent (the admitted generation) and a
transaction's candidate. Continuity owns the incumbent slot and keeps the
admitted generation alive; it never stops. A live `DeploymentTransaction` owns
its private candidate before Fencing and takes the target itself at Fencing (a
stop-then-start rollout, at Starting) through one `take_target` CAS, so of two
transactions entering from one view exactly one succeeds. A continuity
restart is itself a transaction and takes the target the same way.

Phases from Warming through Committing carry deadlines, as do aborts and
drains; an expired deadline never waits silently. A stateless deployment
aborts to its incumbent. A deployment whose candidate was issued a write lease
is left to the operator (`operator-required` incident, the second incident
condition beside `continuity-exhausted`; its subject is the transaction id and
it closes when the record ends or its step goes on). A continuity after
Fencing retries its phase forward on a capped backoff and never stops its live
candidate, since that is the only running copy of the admitted body; the
deadline opens the same incident. The one exception is yielding: a continuity
whose route proof has not succeeded gives way, through its own post-fencing
abort, to a deployment the deployment brake has released and that awaits the
handover; a continuity that has proven its route never yields. The
`ContinuityExhausted` incident (six charged attempts in an hour,
`restarts_page`) pages and gates nothing. When continuity next acts is derived
only from its own record in `TargetSupervision` (schema v2): the attempt
streak, the backoff anchor (written by the dead-and-free pass, the only
writer), and the once-per-admission re-materialization bound. The workload
driver alone answers whether a lost unit was a host reboot
(`WorkloadPort::lost_to_host_reboot`). Operator-facing incidents and
`idunn status` are projections that decide nothing. A boot lift returns a
continuity abort left by an older Idunn, one that had not stopped its running
candidate, to forward retry; if it cannot decide, every continuity abort is
held until a lift succeeds. It is a migration with a deletion line (follow-up
`c2c-delete-boot-lift`). Cut line: cuts 3 and 4 of `reincarnation-map.md`
still owe dependency failures not growing the streak and the dead-generation
route refresh.

The deployment brake gates changes to source, release, configuration, schema,
unit, or authority binding. The lifecycle brake separately gates restart of an
already-admitted incarnation. Neither target brake may gate Idunn itself or an
unrelated service.

If Odin is unavailable, Idunn preserves existing routes and continuity for
already-admitted incarnations. It starts no graph-changing deployment or
promotion. A merely sealed candidate waits. An already-fenced transaction may
promote only when its frozen evidence already contains the exact Odin Ready
receipt for this runtime instance and presence digest; otherwise it waits,
rolls back through the same fence when reversible, or fails closed.

## Operator surface

The intended entry points are small:

```text
idunn up ghostlight
idunn up profile:aetheria
idunn up profile:full-gamecult
```

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.