# Deliberation record: kido-reloc — relocation detection (2026-10-17)

Builder crew (micro-agent circle). This closes the open D1 from the
kido-image deliberation (2026-10-16): "self-relocation detection
(compare linked base against the actual PC via `adr`) — overruled...
a future kido-reloc module can own detection." The future module is
this session's one solid piece: detection, a loud tripwire, and the
earliest safe wiring point. Adaptation is deliberately NOT this piece.

## The equation (MEDUSA)

    delta = runtime(probe) - linked(probe)

`runtime(probe)` is PC-relative (true wherever we run).
`linked(probe)` is a link-time absolute constant in .rodata
(R_AARCH64_ABS64, resolved by the linker). If delta != 0 the image
was not loaded at its linked address and the link-at-load law
(kido-link-arm64.ld) is broken. actual_base = linked_base + delta,
linked_base from kido_image_bounds.

## Positions

- **P1 (Linker purist):** the probe is a never-called global function
  `kido_reloc_probe`. Runtime address via `adrp`/`add :lo12:` in
  inline asm — full ±4GB range, PC-relative, always true. Linked
  address via a `static const uintptr_t` in .rodata initialized to
  `(uintptr_t)&kido_reloc_probe` — a GNU-C constant the linker
  resolves to the absolute linked address. The load-bearing
  invariant, documented in the source: NEVER take `&kido_reloc_probe`
  at runtime (with -fno-pic the compiler emits PC-relative adrp for
  that, which would hide the delta). Only the .rodata constant is
  trusted. The session verifies the invariant with `readelf -r` on
  the cross-compiled object: the constant must carry an ABS64
  relocation, not a relative one.
- **P2 (Entry realist):** the tripwire goes at the top of
  `kido_entry_c_main`, before `kido_entry_fill_bootinfo`. Every C
  symbol reference after entry assumes link-at-load; the check must
  precede all of them. `kido_reloc_verify()` returns KIDO_OK or
  KIDO_ERR_EARLY_ENV; entry halts LOUD on failure through the
  existing `kido_halt` path. The entry .S is UNTOUCHED — the proven
  boot path stays pristine. Declared exposure (not hidden): the .S
  sets SP from the absolute `_stack_top` BEFORE the tripwire runs,
  so a relocated image could crash before the check. On the
  supported path (QEMU `-kernel` raw binary) the load address always
  equals the linked base — delta is always 0 today — so the tripwire
  is a guard for future loaders (UEFI/GRUB), not for today's path.
  Delta-aware SP setup in the .S is phase 2, named not smuggled.
- **P3 (Portability auditor):** hosted has no linked image and no
  relocation concept, so the hosted path refuses with
  KIDO_ERR_STUB_REACHED unless the test injects a delta via
  `kido_reloc_test_set_delta()`. The injected delta exercises the
  pure policy (verify: 0 -> OK, != 0 -> EARLY_ENV) honestly — the
  self-test tests the tripwire logic, never a fake relocation.
  Header guard matches kido-image: ARM64 or KIDO_HOSTED_TEST only.
- **P4 (Adaptivity advocate):** Kido's spec identity is "portable and
  adaptive from the start" — failing loud on relocation is
  BUBO-posture. The module therefore REPORTS, not just refuses:
  `kido_reloc_detect()` fills `kido_reloc_info_t` {delta,
  linked_base, actual_base} and `kido_reloc_last()` keeps the last
  result in BSS for a future console to print. Detection is real
  today; the numbers it reports are exactly what a future adaptive
  phase needs (delta-aware SP, relocated image bounds, shifted
  allocator reservation). Reporting is the adaptive seed; refusing
  is the honest boundary.
- **P5 (Test keeper):** self-test under KIDO_RELOC_SELFTEST on
  hosted: NULL guard, uninjected refusal, injected-0 verify-OK,
  injected-positive and injected-negative verify-EARLY_ENV with
  exact info fields, re-injection. Bare-metal proof is the
  cross-compile (`-ffreestanding`, zero warnings) plus the
  `readelf -r` ABS64 check on the probe constant. No QEMU run this
  session: the supported QEMU path is definitionally delta-0, so a
  QEMU "proof" would prove nothing about the detector — the honest
  verification is the relocation math at the object level, stated
  here, not a theater boot.

## Challenges

- **C1 — `adr` vs `adrp`/`add` range.** `adr` is ±1MB; the probe
  lives in the same .text, so it would work — but the full-range
  `adrp`+`add :lo12:` sequence costs nothing and cannot silently
  break if .text grows past 1MB. Answered by P1's choice.
- **C2 — is the .rodata constant really link-time absolute?**
  Answered by measurement, not by trust: the session runs
  `readelf -r` on the cross-compiled object and requires an
  R_AARCH64_ABS64 relocation on the constant. If it ever shows a
  relative relocation, the technique is wrong and the module does
  not ship. (Result: ABS64 confirmed — see ledger.)
- **C3 — static vs global probe.** A static probe risks the
  compiler renaming or discarding it; the inline asm names the
  symbol textually. Answered: global function, empty body, never
  called, documented as the relocation probe. Stable by
  construction.
- **C4 — wiring point: entry shim vs `kido_boot_early`.**
  `kido_boot_early` checks stack/BSS sanity — but the relocation
  tripwire must precede even the DTB fill, because the fill reads
  firmware addresses through C that assumes link-at-load. Answered
  by P2: top of `kido_entry_c_main`.
- **C5 — why not adapt now (shift the reservation, fix up SP)?**
  Answered: adaptation touches the entry .S (proven path), the
  image-bounds semantics, and the allocator carve geometry — three
  modules for the price of one. Kido's adaptivity is served by
  detecting and reporting honestly today; half-adapting would be
  the "thin" the session law forbids.

## Convergence

P1–P5 with C1–C5 answered. Deliverables: `modules/kido-reloc.h`,
`modules/kido-reloc.c` (KIDO_RELOC_SELFTEST, hosted), wiring of
`kido_reloc_verify()` at the top of `kido_entry_c_main` (entry .S
untouched; TESTING build line gains kido-reloc.c), a one-line
comment update in kido-image.h (D1 now owned by kido-reloc),
module-map.md row. Conformance below. Image-deliberation D1
CLOSES as "owned by kido-reloc".

## Preserved dissent

- **D1 (P4):** the fail-loud policy is BUBO-posture; Kido should
  adapt to relocation, not refuse it. Overruled for this session:
  one module, one job — detection with honest reporting. Phase 2
  (delta-aware SP in entry .S, relocated image bounds in
  kido-image, delta-shifted allocator reservation) is named and
  queued, not faked.

## Conformance

- kido.json "portable and adaptive from the start": detection is
  the portable half (ARM64 inline asm, hosted-declared-vacuous);
  the reported delta is the adaptive seed. No silent invention:
  relocated images are refused LOUD, never guessed around.
- Scaffold honesty law: the pre-tripwire SP exposure in the entry
  .S is declared in this record and in the entry source comment,
  not hidden. The QEMU path's delta-0 is stated as definition, and
  no theater QEMU run is claimed as detector proof.
- MEDUSA: the behavior reduces to delta = runtime − linked, shown
  above; the readelf check is the test that can fail.
