Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0123
ADR-0123: Every host service is registered in the runtime view with its purpose and architecture component, or it is retired
| field | value |
|---|---|
| Status | Proposed |
| Date | 2026-10-22 |
| Register | factory (docs/adr, 4-digit ids) |
| Source | docs/adr/0123-every-host-service-is-registered-in-the-runtime-view-or-retired.md — recorded on branch fix/ship-sanctioned-gate-pytest at 8c7031c9a, not yet on master |
| Wiki register entry | ADR-0123 (wiki status: Proposed) |
The record
Status: Proposed · Date: 2026-10-22
Context
On 2026-10-22, ten systemd user units ran (or were scheduled) out of /opt/orchestrata: six
long-running services (miniircd, orchestrata-bot, orchestrata-kernel,
orchestrata-gateway, orchestrata-ast-live-sync, orchestrata-conversation-consumer) and
four timer-driven oneshots (orchgraph-backup, orchestrata-kg-retention,
orchestrata-history-mining, orchestrata-infra-drift). Nobody could say what turning them off
would break.
- The architecture docs describe code, not runtime.
component-dag.mdis the package DAG (contracts -> kernel -> volks -> gateway -> integration ...).architecture-ontology.mdis the graph schema for design knowledge. Neither has a deployment or runtime view. Seven of the ten units appear in neither, and kernel and gateway appear only as packages. - Every deploy enabled every unit.
deploy/systemd/install.sh, which the promote'sassetsstage runs, calledsystemctl enable --nowon every timer and every long-running service. At 14:31:15-14:31:26 it re-enabled all six services and re-armed the drift timer, after Mohamed had stopped them to cut load (machine CPU-bound, T9 btrfs pool thrashing). The drift timer then fired at once (Persistent=true) and failed the promote's verify stage. The fix to install.sh, the promoter and the installer (never enable,try-restartonly) is pending and uncommitted. - Two units have no recorded rationale at all:
orchestrata-bot, and IRC itself as the agents' bus (miniircd's commit1d9ca9fdarecords how it got a unit, not why IRC). - The evidence for every unit is now in the runtime view
(
projects/orchestrata-ultimate/runtime-services.mdin the wiki, 2026-10-22): what it runs, why it was built (commit, ADR, SPEC, plan; quoted), what uses it, what breaks while it is off, and its measured cost. Every citation was spot-checked against git.
Decision (proposed)
- The wiki page
projects/orchestrata-ultimate/runtime-services.mdis the register of host services. A unit may be installed on a host only if it has a row there naming its purpose, its architecture component (or "infrastructure layer"), what uses it, and its default state (enabled, or on demand). - Enablement and running state belong to the operator. A deploy installs unit files and restarts only units that were already running. It never enables or starts a unit. Each unit's default state is set by its disposition below.
- A unit without a purpose and an architecture home is retired: its unit file is removed from
deploy/systemd/, and so is anything whose only job is to start it. - Dispositions, one ruling per unit (recommendations; Mohamed rules each):
| Unit | Evidence (runtime view section) | Recommended disposition |
|---|---|---|
orchgraph-backup |
the only backup of orchkg; ran 03:00 today, success; produced nothing 2026-07-26 to 2026-10-05 (8b2038b92) |
keep, enabled |
orchestrata-kg-retention |
weekly; the audit exhaust was ~72% of orchkg; 4.2 s CPU per run | keep, enabled |
orchestrata-history-mining |
quarterly ruling-drift report; the 2026-10-05 run left no report and no journal lines | keep, enabled; separately, find why that run left nothing |
orchestrata-conversation-consumer |
the only standing drainer of the SPEC-021 turn queue; ~0% CPU, ~102 MB; 51 turns drained today | keep, enabled at boot |
orchestrata-infra-drift |
ADR-0077 item 4; hourly tofu plan; it failed a prod promote today on drift unrelated to the deploy |
keep the check; redesign the trigger in its own ADR (a deploy-time pre-flight, or a notifier). The timer stays disabled until then. |
orchestrata-kernel |
the agent runtime (CXP); the test suite uses the test fleet's kernel, not this one | keep the unit, on demand (disabled by default; started when the agent runtime is used) |
orchestrata-gateway |
the WS control plane; the MCP server and VizInt are its clients; the MCP path also needs GATEWAY_TOKEN, which is not set today |
keep the unit, on demand, started with the kernel. Fixing GATEWAY_TOKEN is a separate task. |
orchestrata-ast-live-sync |
file save -> orchkg in under 5 s; the PostToolUse hook already syncs Claude's own src/ edits |
keep the unit, on demand; its deploy lane is left to ADR-0118 §5 |
miniircd |
the IRC server for #agents; the session-start hook starts it, and a listener retry-loops when it is down; kimi-session and agent-mail are the agents' channels ("both off IRC") |
retire with the IRC bus (the unit, the session-start IRC hook, the listener), unless IRC is still in use |
orchestrata-bot |
keeps #orchestrata populated; no consumer found; no recorded rationale |
retire |
Alternatives rejected
- Keep every unit enabled, as the installer did. This is the state that cost CPU on a CPU-bound host, and it re-enabled units the operator had stopped.
- Retire everything that is not core. That loses the only orchkg backup and the only drainer of the conversation queue.
- Document the units without a rule. Units would again appear, and be enabled, with no record of why. That is how seven of ten ended up outside every architecture doc.
Consequences
- A change to
deploy/systemd/ships in the same change as its row in the runtime view. A mechanism is owed:scripts/health_check.py check_systemd_unitsfails when a unit indeploy/systemd/has no row in the register. Until it lands, the rule is enforced by review. - Item 2 needs the pending promoter, installer and
install.shfix (never enable,try-restart, verify skips units the operator left off). Until it lands, a prod deploy usesdeploy/install-orchestrata.sh --bootstrap-only, which touches no unit (as on 2026-10-22, 15:35). - Retiring IRC removes a session-start side effect and a 17-hour retry loop, but it also removes live task dispatch over IRC, if anyone still uses it.
Provenance
- Mohamed, 2026-10-22, verbatim:
- "find out why the services were built, what purpose they served and document that"
- "so the services must be part of the architecture, do we have an existing architecture?"
- "yes, do both" (publish the runtime view; give each unit without an architectural home a keep-or-retire decision, recorded as an ADR)
- "publish the runtime view page and mint the ADR"
- The load cuts, Mohamed 2026-10-22: "I deleted unneccessary containers my machine is cpu maxed and the t9 ssd with btrfs was thrashing". Services and drift timer stopped and disabled at 15:31. Conversation consumer started at 15:39 at his request.
- Evidence: the runtime view page (research by a Sonnet agent, citations spot-checked by the
coordinator against git:
1d9ca9fda,45d2c83d5,90883df0f,611300335,cb26d0167,8b2038b92,f2cef12cb,ea56e6057,4116a55b8);deploy/systemd/install.shat4ac0db570(theenable --nowlines); the promote log of 2026-10-22 14:31 (verify failed onorchestrata-infra-drift.service).
Related ADRs
Rulings cited
None.