# KNELPerf scheduler — breakout from Ultix (#826)

The scheduling subsystem of the Ultix workstation repo (`~/projects/ultix`)
was broken out here on 2026-09-06 and redesigned for fleet use. Ultix remains
the live workstation deployment; this module is the going-forward home.

## What was ported and what changed

| Ultix source | KNELPerf destination | Redesign delta |
|---|---|---|
| `staged/ukrrs-daynight.sh` | `daynight/knelperf-daynight.sh` | Slice targets, devices, and every knob are conf-driven lists (was: hardcoded `reachableceo-*` slices, `/dev/sdb`, user 1001). Slice specs are `slice:weight:cpus:memhigh` so any host participates. |
| `staged/etc-ukrrs-daynight.conf` | `daynight/knelperf-daynight.conf.example` | Self-documenting example; post-upgrade values live per-host, not in comments of the engine. |
| `staged/systemd/reachableceo-{day,night}profile.*` | `daynight/systemd/knelperf-*` | Generic units; the conf — never a sed-edit of a live timer — is the only value source. |
| `staged/reachableceo-perfsnap.sh` | `collectors/knelperf-perfsnap.sh` | Watched cgroups/interfaces are env-driven lists; no baked-in uids/NICs. Same pipe-delimited log format. |
| `staged/ukrrs-psi-textfile.sh` | `collectors/knelperf-psi-textfile.sh` | Cgroup glob + metric prefix env-driven; emits for any slice namespace. |
| `staged/proxmox-ctl.sh` | `proxmox/proxmox-ctl.sh` | Ported as-is (was already generic + guarded: PROTECTED vmids, graceful shutdown only, pvesh local-or-token). |

Not ported (stay workstation-local in ultix): `mkacct.sh` account tiers,
`21-priority-ladder.sh` GUI-first cgroup ladder (host-specific by design),
`gateway-ensure.sh`, RTMP stack.

## Lessons learned carried forward (from ultix REPORT.md / TRACKING.md)

1. `Slice=` is create-time only — `set-property` cannot set it; caps go in unit
   drop-ins AND live via `set-property --runtime`.
2. `CPUWeight` on user-manager units is inert until `cpu` is in the parent's
   `cgroup.subtree_control` — enable it explicitly.
3. IOWeight is inert under the `none` I/O scheduler (virtio) — don't bother.
4. Guests have no cpufreq driver — governor tuning is PVE-host-side only.
5. Reboot must land in DAY mode: slice unit files carry day defaults; the
   profile engine only does runtime mutations. Non-negotiable invariant.
6. `Persistent=true` timers replay missed flips at boot (intentional).
7. Duplicated truth is the failure mode: one conf file per host is the only
   place values live (the 07:00 sed-edit of a live timer was the wart that
   motivated this redesign).
8. Measure before touching; collectors install data, they tune nothing.

## Fleet rollout model

- Workstation (ultix-streaming): stays on its live ultix units until this
  module is UAT'd, then converges onto knelperf-* units.
- PVE nodes: daynight engine applies to host-level services + VM cgroup
  scopes (`qemu.slice` children) via the same conf mechanism; timers install
  from `daynight/systemd/`.
- Everything deploys through AWX job templates (KNELIAC) per the 100%-IaC
  mandate; this repo supplies the scripts, not ad-hoc ssh.

See `docs/ARCHITECTURE.md` for the full baseline → audit → tweak → re-baseline
program this module feeds.

> **Docs live on Discourse — this repo is the executable source of truth.** Perf topic: https://community.turnsys.com/t/328