# Deliberation record: kido-reloc phase 2 — relocation adaptation (2026-10-17)

Builder crew (micro-agent circle). This is the named phase 2 from the
session-12 deliberation's preserved dissent D1: "delta-aware SP in the
entry .S, relocated image bounds, delta-shifted allocator reservation."
One solid piece: the relocation *environment* becomes delta-aware.
Execution under relocation is deliberately NOT this piece (see P3/P4).

## The equations (MEDUSA)

    delta       = runtime(probe) - linked(probe)   (unchanged, session 12)
    SP          = _stack_top + delta               (entry .S, registers only)
    actual_base = linked_base + delta              (kido_image_actual_bounds)
    size        = _image_end - _image_start        (invariant under translation)

## Positions

- **P1 (Entry realist):** the .S measures delta in registers BEFORE
  touching SP — the only point where memory is unsafe. Sequence:
  `adrp`/`add :lo12:` on `kido_reloc_probe` (runtime address, full
  ±4GB range per session-12 C1 — not `adr`'s ±1MB), minus
  `ldr x10, =kido_reloc_probe` (linked address from the literal pool,
  the linker's absolute truth). Delta lives in x20 (callee-saved;
  `eret` restores PSTATE/PC only, GPRs untouched — x20 survives the
  EL2->EL1 drop). SP = literal `_stack_top` + delta. After the BSS
  zero loop, the .S stashes delta + a valid flag into BSS via
  `adrp` stores — PC-relative, hence correct wherever the image
  runs. x0 (DTB) is stashed in x19 first, as today; the delta
  computation uses only x9/x10/x20.
- **P2 (Linker purist):** one probe, two instruments. The C
  instrument (session 12: adrp/add vs .rodata ABS64 constant) stays
  authoritative for the report. The .S instrument (adrp/add vs
  literal-pool ABS64) is the same linker's truth in a different
  encoding. The readelf proof gate extends: the .S object's literal
  entry for the probe MUST carry R_AARCH64_ABS64 — a relative
  relocation there means the technique is wrong and the .S does not
  ship. `kido_image_bounds()` keeps its LINKED semantics (the
  detector needs the unshifted base); the new
  `kido_image_actual_bounds()` reports linked + last-delta. No
  duplicated truth: reloc owns the delta, image queries it.
- **P3 (Honesty auditor):** execution still REFUSES loud on
  delta != 0. The image is non-position-independent by the
  session-12 load-bearing invariant (-fno-pic); absolute references
  would corrupt under relocation, and phase 2 does not fake around
  that. What phase 2 honestly delivers: (1) the refusal path runs
  on a valid stack — safe failure, closing session-12's declared
  exposure (a relocated image with a garbage SP is a crash lottery,
  not a tripwire); (2) bounds and the allocator carve describe the
  REAL image location — truthful bookkeeping; (3) detector
  crosscheck: two independent measurements of one physical fact.
  Disagreement = instrument fault = KIDO_ERR_EARLY_ENV, loud.
  Bare-metal valid==0 = stale .S (the slot the C expects was never
  written) = build inconsistency = loud. Phase 3 (PI build +
  self-relocation pass) is NAMED, not smuggled.
- **P4 (Adaptivity advocate):** CONVERGES with P3. Kido adapts what
  it can honestly adapt today — the environment (SP, bounds,
  carve). Refusing *execution* under relocation is the honest
  boundary until the position-independent build exists. Kido's
  adaptive identity is served, not betrayed: every number the
  kernel acts on is now relocation-true.
- **P5 (Portability auditor):** hosted has no .S, so entry_valid==0
  -> crosscheck is vacuously OK there (distinguished by
  KIDO_HOSTED_TEST, not by guessing). The hosted test MAY write the
  BSS slots to exercise the comparator — declared as comparator
  testing, never a fake .S. `kido_image_actual_bounds` on hosted =
  injected bounds + last-delta (0 unless the reloc test injected a
  delta). Header arch guard unchanged.
- **P6 (Test keeper):** hosted matrix, all real: reloc crosscheck
  (match -> OK, mismatch -> EARLY_ENV, bare-metal-stale valid==0 ->
  EARLY_ENV, hosted-vacuous -> OK); image actual bounds (+delta
  exact, -delta exact, overflow -> loud, underflow -> loud);
  scheduler shifted-carve (injected image + injected delta ->
  created stacks avoid [base+delta, base+delta+size), pinned like
  session 10's carve test). .S object proof (assemble + readelf
  ABS64 on the literal + disassembly adrp/add) is QUEUED: the
  cross toolchain is absent this session (apt mirror unreachable
  for main; only security pocket reachable) — stated as unproven,
  session-7 precedent, not hand-waved.

## Challenges

- **C1 — detect() calls kido_image_bounds() for linked_base; image
  now shifts by last-delta. Circularity / double-shift?**
  Answered by the split (P2): `kido_image_bounds()` stays LINKED
  forever — the detector's input. `kido_image_actual_bounds()` is
  the phase-2 query — the scheduler's input. First detect() call
  reads last==zero -> correct; later calls never re-shift the
  linked query.
- **C2 — does x20 survive `eret`?** Answered: `eret` restores only
  PSTATE and PC (from SPSR_EL2/ELR_EL2); general registers are
  untouched. x20 is callee-saved and no call occurs before the BSS
  stash. The DTB in x19 was already relying on exactly this.
- **C3 — is `ldr =probe` really the linked address under the
  custom linker script?** Answered: identical mechanism to the
  session-12 .rodata constant — static link, literal-pool entry
  resolved absolute by the linker. Proof gate is readelf ABS64 on
  the .S object (queued, P6).
- **C4 — why delta-aware SP if execution refuses anyway?**
  Answered (P3): the refusal must be *safe*. Session-12's declared
  exposure was a relocated image crashing before the tripwire —
  the tripwire is only a tripwire if the stack it runs on is real.
  Phase 3 (PI execution) also needs this exact line.
- **C5 — bare-metal valid==0: vacuous or loud?** Answered: loud
  (P3). On bare metal the current .S always writes the slot; zero
  means a half-upgraded image. Hosted valid==0 is vacuously OK —
  no .S exists there. The two are distinguished at compile time.
- **C6 — does the shifted carve protect anything while execution
  refuses?** Answered: it makes the *bookkeeping* truthful — the
  exact mechanism phase 3 consumes — and it is proven today by the
  hosted shifted-carve test running the same kido-alloc.c that
  runs on bare metal. Truthful books, loud refusal: both honest.

## Convergence

P1–P6 with C1–C6 answered. Deliverables:

- `modules/kido-entry-arm64.S` — delta-aware SP (registers only),
  BSS stash of delta + valid flag (adrp stores).
- `modules/kido-reloc.h` — `kido_reloc_crosscheck()` API; BSS slot
  contract; honesty law updated (phase 2 = safe environment, loud
  execution refusal; phase 3 named).
- `modules/kido-reloc.c` — BSS slot definitions, crosscheck,
  verify() now detect + crosscheck + refuse-if-relocated;
  self-test extended (13 -> 21 checks).
- `modules/kido-image.h` — `kido_image_actual_bounds()` API.
- `modules/kido-image.c` — actual = linked + last-delta, overflow
  guards; self-test extended (9 -> 15 checks).
- `modules/kido-sched.c` — init consumes `kido_image_actual_bounds`
  (the reservation shifts with the image; zero allocator changes);
  self-test gains the shifted-carve section (64 -> 72 checks).
- `modules/kido-entry-arm64.c` — comment updates only; the wiring
  line `kido_reloc_verify()` is UNCHANGED (verify's contract is
  unchanged: OK or EARLY_ENV).
- `architecture/module-map.md` — reloc row: phase 2 landed.

Session-12's declared exposure CLOSES. Session-12 dissent D1
CLOSES as built.

## Preserved dissent

- **D1 (P4):** execution should adapt NOW — build the image
  position-independent (-fPIE) with a self-relocation pass over
  .rela, instead of refusing. Overruled for this session: that
  touches every module's absolute-address assumptions and the
  linker script's load law — a different-sized piece. Named as
  phase 3 (kido-reloc phase 3: PI build + self-relocation), not
  faked here.

## Conformance

- kido.json "portable and adaptive from the start": the boot
  *environment* is now relocation-adaptive (SP, bounds, carve all
  delta-true); the *execution* refusal stays loud because the code
  is honestly non-PI. No silent invention anywhere: every
  relocation fact is measured twice and reported.
- Scaffold honesty law: the .S change is written but UNASSEMBLED
  this session (no cross toolchain) — marked unproven in the
  ledger and in the .S header, queued for the toolchain's return.
  The C logic it feeds is fully proven on hosted.
- MEDUSA: the behavior reduces to SP = _stack_top + delta and
  actual_base = linked_base + delta, shown above; the hosted
  shifted-carve test is the test that can fail.
