# Deliberation circle — kido-sched destroy API (2026-10-21)

Module: the teardown piece queued since session 6 (2026-10-14 alloc/sched
integration, D1: "When a destroy API is specified, it will free — and be
tested then") and carried as "Remains" through sessions 18 and 19. This is
the moment the queued item is specified. kido_free has been test-only since
day one; destroy is the API that makes it live in production code.

The fork: the steady state has no teardown moment — tasks run to DONE, the
queue halts, tests re-init. So the destroy API must be a load-bearing
teardown that can only ever run at rest, over a table whose live tasks are
gone, and it must leave the allocator in the same honest state it found it.

## Positions

- **P1 — Teardown realist.** Destroy is the exact inverse of what init+create
  built: free every scheduler-owned stack through kido_free, return every
  TCB to EMPTY, and drop the initialized flag. It is the one production
  caller of kido_free, which closes session-6's open wound ("free has no
  steady-state caller") without inventing churn in the steady state —
  destroy is not a steady-state path, so D1's no-churn verdict stands.
- **P2 — Refusal purist.** Destroy over live (READY or RUNNING) tasks would
  strand the round-robin cursor, the current-task pointer, and — worst —
  the stack the running task is standing on. There is no safe default, so
  refusal is the only honest posture: LOUD (KIDO_ERR_EARLY_ENV, the
  codebase's misuse code) when any task is READY or RUNNING. Destroying
  from inside a task is refused by the same rule — self-destruction by
  construction. No new header code: D1's KIDO_ERR_NO_TASKS stays N8toriousAi's
  call, and this session does not touch the approved header's code list.
- **P3 — Ownership accountant.** Destroy frees only what the scheduler OWNS:
  task stacks. The allocator's image carve-out is NOT sched's property —
  destroy must not reset, re-init, or otherwise disturb kido-alloc. On bare
  metal the image is still in RAM while destroy runs; tearing down its
  reservation would be a foot-gun the steady state can't survive. Proof
  shape: after destroy, kido_alloc_stats shows allocs == frees and
  allocated_bytes == 0, while total_bytes still reflects the carve-out.
  DONE slots' stacks are freed here — session-6's keep-on-recycle (C3) is
  steady-state behavior, untouched; teardown is a different moment.
- **P4 — State-law keeper.** After a successful destroy the scheduler is back
  to never-initialized: sched_hal NULL, current NULL, cursor zero, idle ctx
  zeroed, all TCBs EMPTY. Create fails LOUD until init runs again, and init
  keeps its existing re-init law (resets table + allocator; image
  injections survive like the arena). Destroy-before-init and
  destroy-twice both refuse LOUD — teardown of nothing is a caller bug.
- **P5 — Fence keeper.** kido-sched.c/h are stability-critical (sessions
  5/6/7 proof chain, session 20's reiterated fence). Destroy is ADDITIVE:
  one new function, zero changes to existing signatures or semantics. No
  asm is touched, so no new QEMU proof is owed — hosted self-test is the
  evidence. A conformance doc is written because this session alters the
  scheduler's public surface; the fence's demand is proof, not paperwork.

## Challenges and resolutions

- **C1 — What counts as "live"?** READY or RUNNING. DONE slots are teardown-
  eligible by construction (never scheduled again — session-6 C3). EMPTY
  slots hold no stack. After the refusal gate the table is DONE/EMPTY, so
  destroy frees every slot with a non-EMPTY state and zeroes it.
- **C2 — Free-then-memset order.** Free first, THEN memset the TCB:
  kido_free needs the stack_base pointer the slot holds. A failed free is
  fail-stop: propagate the allocator's status unchanged and abort WITHOUT
  zeroing that slot. Continuing past a failed free would report KIDO_OK
  while a stack is still accounted-allocated — a lie about completeness.
  Post-abort the scheduler is still "initialized" (partial teardown is
  caller-visible, retryable, and never misreported as done).
- **C3 — Why not reset the allocator too?** P3. The image reservation is the
  allocator's contract with the linker; destroy is teardown, not a boot
  path. kido_sched_init's re-init resets the allocator because init IS a
  fresh start. The split is deliberate: destroy = free what I own; init =
  rebuild the world.
- **C4 — How is "never initialized" tracked?** The existing convention:
  sched_hal == NULL means init was never called (create already uses it as
  the guard). Destroy sets it NULL on success, so the post-destroy guard
  falls out of existing code — no new flag, no new convention.
- **C5 — Does the idle ctx need zeroing?** Yes, with the rest: sched_idle_ctx
  is module state like the cursor. Zeroed on destroy, rebuilt implicitly
  by the next run. Hosted test-double's switch counter is test state;
  untouched (it belongs to the test, not the module).
- **C6 — What do the self-tests pin?** (a) destroy before init -> EARLY_ENV;
  (b) happy path: init, create N, DONE them, destroy -> OK, every slot
  EMPTY, sched_hal/current NULL, stats allocs==frees and
  allocated_bytes==0 with total_bytes still carved; (c) create after
  destroy -> EARLY_ENV; (d) destroy twice -> EARLY_ENV; (e) re-init after
  destroy -> OK, create works; (f) destroy with a READY task -> EARLY_ENV,
  table and stats untouched; (g) destroy with a RUNNING task (+ current
  set, the self-destruction shape) -> EARLY_ENV, untouched. The (f)/(g)
  "untouched" assertions are the refusal contract made checkable.

## Convergence

- Additive API: `kido_status_t kido_sched_destroy(void)`.
- Refusal rule: EARLY_ENV unless the scheduler is initialized AND no task
  is READY or RUNNING. DONE/EMPTY only -> proceed.
- Free-then-zero per slot, fail-stop on a failed free with the allocator's
  status propagated and partial state left visible.
- Ownership split: scheduler-owned stacks freed; allocator (and its image
  carve-out) untouched. Post-destroy = never-initialized; re-init is the
  only way back.
- No new header codes, no asm changes, no QEMU proof owed. Hosted
  self-test sections 50-59 carry the evidence; conformance doc written
  per the fence.

## Preserved dissent

- **D1 — Force-teardown variant.** Mark live tasks DONE and free their
  stacks regardless. Overruled (P2). Freeing the stack of the RUNNING
  task — or of a READY task that may be re-entered before the caller
  notices — is a use-after-free waiting for a witness. Refusal is the
  safe default that exists; forcing is a N8toriousAi decision, and he is not
  here.
- **D2 — Destroy resets the allocator to pristine.** Overruled (P3). The
  reservation protects the image that is still executing the caller.
  Pristine-allocator destroy would need the image bounds re-carved before
  any further create — a call-order trap identical to the one session 10
  closed for trim. The ownership split avoids it entirely.
