randomparity / randomparity/kdive
Runtime-mutable inventory: load systems.toml once at startup, add/remove systems & build-hosts at runtime, export running config back to file
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 1h 26m
- Merged PRs (30d)
- 311
Description
# Epic — Runtime-mutable inventory (M2.7)
`systems.toml` seeds initial inventory at startup; **runtime is authoritative**; an **export** persists running → file. This shifts the inventory reconcile model from drift-repair-from-file (ADR-0021) to seed-once + DB-authoritative, mediated by a per-identity override ledger, so operators can add/remove/modify config-declared systems and build-hosts at runtime without a restart, ConfigMap re-apply, or DB edit.
## Design
- **Spec:** [docs/design/runtime-mutable-inventory.md](../blob/main/docs/design/runtime-mutable-inventory.md)
- **ADR:** [ADR-0199 — seed-once, runtime-authoritative inventory via an override ledger](../blob/main/docs/adr/0199-seed-once-runtime-authoritative-inventory.md) (refines ADR-0021/0112)
- **Plan:** [docs/superpowers/plans/2026-06-20-runtime-mutable-inventory.md](../blob/main/docs/superpowers/plans/2026-06-20-runtime-mutable-inventory.md)
## The model
A per-identity `inventory_overrides` ledger (`(source_kind, resource_kind, name)` → `detached | removed`):
- **no entry** → reconcile behaves exactly as today (create / repair / prune) — the ADR-0021 drift-repair benefit is preserved.
- **`detached`** → runtime owns the live row; the file no longer overwrites its runtime-owned fields (`ops.set_host_capacity`).
- **`removed`** → suppress re-create; cordon a live row (ADR-0112 refuse-if-live), delete once idle.
An export tool writes running state back to the file; once committed + re-applied, reconcile GCs the now-redundant ledger entries.
## Sub-issues
- [ ] #638 — **A**: reconcile-model shift + override ledger *(foundation; gates B, C)*
- [ ] #639 — **B**: durable runtime add/remove/modify for config-owned inventory *(depends on A)*
- [ ] #640 — **C**: full inventory export `ops.export_systems_toml` *(depends on A)*
- [ ] #641 — **D**: persist export to the ConfigMap / mounted file *(depends on C; deployment-shape, opt-in)*
## Acceptance (rolls up the sub-issues)
- Add a `remote_libvirt` host at runtime → schedulable without restart, not removed by a later reconcile pass.
- Remove a system / build-host at runtime → stays removed across passes without editing `systems.toml` or the DB.
- An export writes the **full** running inventory back to `systems.toml` / the `kdive-systems` ConfigMap; a fresh start reproduces the live inventory (after completing the operator-supplied skeleton fields the DB does not carry).
- Removing a host that holds **live allocations / build leases** is refused or cordoned (ADR-0112, FK `ON DELETE RESTRICT`).
Contributor guide
Assessment
This issue has not been assessed yet.