# Deliberation circle — kido-sched design (2026-10-14)

**Question:** What is the honest first scheduler for Kido — the first module
where the kernel becomes multi-tasking?

**Context:** Gate-approved foundation: kido-boot (wired to the real ARM64
HAL this session), kido-hal-arm64 (PL011 + generic timer real; GIC/timer
IRQ loud stubs), kido-mem (DTB region seed list real; allocator NOT
written), kido-entry-arm64 (boots under QEMU). No prior scheduling
deliberations exist — this circle is the first.

## Positions

- **P1 — Cooperative round-robin, no fake preemption.** Preemptive
  scheduling needs timer interrupts + a GIC driver; both are loud stubs
  in the HAL. The honest first scheduler is cooperative: tasks run until
  they voluntarily yield. Say so explicitly in the header.
- **P2 — Bounded static TCB table, zero allocation.** The allocator does
  not exist; the scheduler must never allocate. `KIDO_SCHED_MAX_TASKS`
  (16) static TCBs. Creation fails `KIDO_ERR_NO_MEMORY` when full —
  loud, not silent.
- **P3 — Explicit stack carving from kido-mem's seed list.** Each task
  gets a fixed 16 KiB stack carved top-down from the largest discovered
  region, watermarked and bounds-checked. This is explicitly the
  allocator's future job; the scheduler borrows the seed list and says so.
  On hosted, stacks come from a static array (the firmware addresses in
  the hosted caps are test values, not real memory).
- **P4 — Minimal callee-saved context on ARM64.** `kido_ctx_switch`
  saves/restores x19–x28, FP, SP, LR only. Caller-saved regs are the
  compiler's responsibility across the `kido_sched_yield()` call
  (AAPCS64) — the switch is a normal function call from the task's
  perspective. First-run contexts are crafted so the restore lands in a
  trampoline with the entry/arg in x19/x20. Written as a separate .S
  file: inline asm inside a compiled function cannot reliably capture
  the caller's callee-saved registers (the compiler may spill/reuse them
  in the prologue).
- **P5 — Timer ticks for accounting, never preemption.** The HAL's
  `timer_ticks()` is sampled at each switch; per-task `ticks_run` is
  accounting data. A NULL timer is tolerated (accounting stays 0) —
  documented, not faked.
- **P6 — Empty run queue halts LOUD.** A scheduler with nothing runnable
  is a kernel misconfiguration. No status code fits (the header enum is
  Gate-approved and this builder may not extend it), so the halt uses
  `KIDO_ERR_STUB_REACHED` with the mapping documented here and a
  dedicated `KIDO_ERR_NO_TASKS` code queued for N8toriousAi's approval.

## Challenges

- **C1 — Cooperative scheduling starves:** a task that never yields hangs
  the kernel. *Answer:* honest for v1 and documented; a watchdog is
  future work. Starvation-by-design is stated, not hidden.
- **C2 — Stack carving duplicates the future allocator.** *Answer:*
  explicit, bounded, and marked replaceable; it consumes the same seed
  list the allocator will own. Duplication is temporary and declared.
- **C3 — Hosted cannot execute the ARM64 switch.** *Answer:* the hosted
  self-test exercises the portable core for real (creation, pick-next
  order, states, carving bounds, guards, halt code, accounting with a
  fake timer). The .S is verified by the real cross-assembler (encoding
  check), not merely parsed. QEMU task-switch execution is queued for
  the kido_main wiring — the designed integration seam.
- **C4 — UP-only, no locking.** *Answer:* QEMU virt boots one CPU; the
  scheduler asserts the UP assumption in its header. SMP locking is a
  future module, not a silent omission.

## Convergence

P1–P6 adopted. The scheduler is cooperative round-robin over a static
TCB table with explicit stack carving, ARM64 callee-saved context
switch in .S, tick accounting, and loud halts.

## Preserved dissent

- **D1 (halt-code mapping):** `KIDO_ERR_STUB_REACHED` for "run queue
  empty" is semantically wrong — no stub was reached. The circle kept it
  because inventing a code means touching the Gate-approved header, and
  a loud wrong-ish code beats a silent right one. Queued for the Gate:
  approve a `KIDO_ERR_NO_TASKS` header extension.
- **D2 (carve direction):** top-down carving does not know the kernel
  image bounds (image sits at the region's base on QEMU). Safe while
  total carve stays far below region size; the allocator will own precise
  bounds. Recorded as a known limitation, not a bug.
