# Deliberation record: kido-reloc phase 3 — self-relocation design (2026-10-19)

Builder crew (micro-agent circle). Session 15. This is the design
behind session-12's preserved dissent D1, explicitly named in the
session-14 remains as "phase-3 PI build + self-relocation
deliberation (dissent D1, named — the .rela.dyn manifest is now
confirmed real)."

Where we stand: phase 2 (sessions 12–14) made the boot
*environment* delta-aware — SP = _stack_top + delta, bounds and
the allocator carve describe the real image — while execution
under relocation still refuses LOUD, because the image is
honestly non-position-independent. Session 14's empirical
addressing model is this design's foundation, restated because
phase 3 lives or dies on it:

  1. Same-TU globals compile to direct PC-relative adrp/add —
     relocation-TRUE (the C crosscheck reads the ACTUAL BSS slot).
  2. Cross-TU globals compile GOT-relative (R_AARCH64_ADR_GOT);
     the static EXEC link leaves R_AARCH64_RELATIVE in .rela.dyn,
     never applied on bare metal — every GOT-based access
     resolves to the LINKED address, permanently.
  3. The .rodata probe constant: ABS64 at object level, unapplied
     RELATIVE holding the correct linked value (0x400036c0) in
     the linked image. Manifest-VISIBLE.
  4. The .S literal-pool probe (`ldr x10, =kido_reloc_probe`):
     ABS64 at object level, resolved with NO reloc entry in the
     linked image. Manifest-INvisible — stays linked forever.
  5. Ten R_AARCH64_RELATIVE entries in .rela.dyn — phase 3's
     self-relocation manifest, sitting in the image already.
  6. Known exposure (session 14, P3): the BSS loop zeroes the
     LINKED region while the PC-relative stash lands in actual
     BSS. Harmless today (execution refused); phase 3's problem
     to fix — named here.

Scope of this record: the DESIGN only. No code is written this
session; the module draft (entry .S relocator + linker-script
manifest section + probe carve-out) is the named next session.
The full build plan still queues for N8toriousAi's review; first boot
is his to witness.

## The equations (MEDUSA)

    delta        = runtime(probe) - linked(probe)   (unchanged)
    loc_i        = r_offset_i + delta               (each RELATIVE entry)
    *loc_i       = *loc_i + delta                   (apply; linked value + delta)
       EXCEPT r_offset_i in [probe_sec_start, probe_sec_end) — the carve-out
    BSS_zero     = [_bss_start + delta, _bss_end + delta)   (the session-14 fix)
    linked_base  = actual_base - delta              (the bounds inversion)

## Positions

- **P1 (Relocation mechanic):** the self-relocator lives in the
  entry .S, in registers, between the EL drop and SP setup. New
  sequence: measure delta (x20, as today) → EL drop (as today) →
  RELOCATE: walk the manifest — manifest bounds from the linker
  script as linked symbols + delta (actual manifest), for each
  R_AARCH64_RELATIVE entry compute loc = r_offset + delta and
  add delta to the word there — → SP = _stack_top + delta
  (as today) → zero BSS at ACTUAL bounds (the session-14
  exposure, fixed) → stash delta/valid/report via PC-relative
  adrp (as today, now landing in the actually-zeroed BSS) →
  `bl kido_entry_c_main`. After the relocator runs, every
  GOT-based access in C resolves to the ACTUAL address — the C
  world becomes relocation-true by construction, not by
  per-module delta arithmetic. The relocator uses only
  x9/x10/x11 temporaries; x20 (delta) and x19 (DTB) are
  untouched — register discipline stated, not assumed.
- **P2 (Instrument keeper):** the probe constant MUST stay
  linked — it is the linked instrument of the C detector. It is
  manifest-visible (finding 3), so a blind manifest walk would
  "fix" it to actual and the detector would measure delta = 0
  forever: a silent instrument death, the exact failure mode
  this scaffold exists to prevent. Design: the linker script
  places the probe constant in its own named section
  (.rodata.kido_probe_linked) with __probe_sec_start/end
  symbols; the relocator skips any r_offset inside that range.
  The .S literal instrument (finding 4) needs no carve-out —
  no reloc entry exists for it, it stays linked by the absence
  of a manifest entry. One probe, two instruments, both still
  honest after relocation: the C instrument compares against
  the carved-out linked constant; the .S instrument against the
  manifest-invisible literal.
- **P3 (Linker purist):** name the manifest in the linker
  script. Today .rela.dyn arrives by orphan-section placement
  (finding 5) — phase 3 must not depend on orphan luck. The
  script gains an explicit `.rela.dyn` input section with
  PROVIDE __rela_dyn_start/__rela_dyn_end, placed inside the
  image bounds (it already is; naming makes it law). On
  -fPIE: NOT this phase (see D1). The manifest already exists
  under the current flags; flipping codegen changes every
  module's addressing assumptions at once — the opposite of
  one solid piece.
- **P4 (Honesty auditor):** the policy flip is gated, and the
  tripwire is NOT deleted. New verify() contract: detect +
  crosscheck as today, then — if delta != 0 — confirm the .S
  relocation report (manifest count applied == manifest count
  expected, both stashed in BSS by the .S; probe constant
  still reads linked, pinned by test) → OK, proceed. Any
  check fails → KIDO_ERR_EARLY_ENV, loud, exactly as today.
  Phase 2's refusal becomes the fallback, not the policy.
  The completeness audit (C6) is the gate for the policy flip:
  the flip does not land until every absolute reference in the
  image is proven covered (manifest, carve-out, or manual
  delta). A flip without the audit would be phase-2's refusal
  replaced by wishful thinking.
- **P5 (Portability auditor):** hosted has no .S and no
  relocation — the hosted harness keeps today's semantics
  (injected delta exercises policy, never a fake relocation).
  The relocator ALGORITHM gets a hosted unit test on a synthetic
  manifest + synthetic GOT (declared simulation of the
  algorithm — precedent: interop's simulated peer, declared,
  never a fake relocation). Bare-metal proof plan on QEMU:
  the session-14 relocated recipe (link 0x40000000, load
  0x40080000, delta +0x80000) must now PROCEED — breath →
  kido_main → ABCABCABCABC, zero exceptions — where it
  refused before. Plus the negative-delta run session-14's D1
  named for this plan (link 0x41000000, load 0x40080000,
  delta −0x80000): the negative path finally gets bare-metal
  evidence. Register trace remains the evidence standard.
- **P6 (Test keeper):** hosted matrix for the new policy, all
  real: relocated-OK via injected delta + synthetic applied/
  expected counts (match → OK); applied != expected → loud;
  probe-constant-moved (carve-out violated) → loud; delta-0
  unchanged (relocator runs, adds 0, count validates the walk).
  The completeness audit ships as a build-time check: a script
  that enumerates absolute references in the linked image and
  fails the build on any uncovered one — MEDUSA's "a test that
  cannot fail is a painting" applied to the linker output.

## Challenges

- **C1 — does the relocator corrupt its own manifest walk?**
  Answered: the walk reads the manifest at actual addresses
  (linked bounds + delta) and patches loc = r_offset + delta.
  The word at loc holds the linked value (verbatim image copy)
  until patched — read-then-add is correct. Double application
  would double-add; guarded by design: the relocator runs
  exactly once per boot, before BSS zero, with no re-entry
  path. Stated in the .S header, not left implicit.
- **C2 — how does the .S know the probe carve-out range?**
  Answered (P2/P3): linker-script section
  .rodata.kido_probe_linked with __probe_sec_start/end. The .S
  loads them as linked literals + delta (same mechanism as
  _stack_top today) and skips r_offset in range. The C side
  keeps its `static const uintptr_t` probe constant — the
  script change only re-sections it.
- **C3 — what happens to the linked/actual bounds split?**
  Answered: it INVERTS. Post-relocation the C world only ever
  sees actual (GOT fixed), so kido_image_bounds() — read via
  the fixed GOT — returns ACTUAL. The detector's linked input
  becomes linked_base = actual_base − delta (reloc owns the
  delta; image queries it — the same one-query law, reversed).
  Phase-2's C1 circularity concern dissolves: no consumer
  re-shifts, because bounds() is single-semantics (actual)
  and the linked value is derived, never stored twice.
  kido_image_actual_bounds() becomes a thin alias kept for
  API stability — or removed; the module session decides,
  this record names both options honestly.
- **C4 — the allocator carve under relocation?**
  Answered: sched_init runs after the fixup, reads actual
  bounds via GOT, carves actual — phase 2's shifted-carve
  machinery becomes the normal path, and the phase-2
  injection test already proves it on the same kido-alloc.c.
  No allocator changes (the session-10 law holds).
- **C5 — why not just -fPIE for completeness by construction?**
  Answered (P3, dissent preserved D1): the manifest exists
  without it; the image is small enough that every absolute
  reference is enumerable (10 RELATIVEs + the known .S
  literals + the probe constant). -fPIE changes codegen in
  every TU at once — a different-sized piece with its own
  audit burden. Audit-over-flag-flip, for this phase.
- **C6 — enumerate the absolute references (the audit's
  input list)?** Answered, from session-14 findings + the
  current sources: (i) the 10 .rela.dyn RELATIVEs → applied
  by the relocator; (ii) the .S literal-pool entries
  (_stack_top, _bss_start/_bss_end, =kido_reloc_probe) →
  manual +delta at each use, audited in disassembly;
  (iii) the .rodata probe constant → carve-out, stays linked;
  (iv) same-TU PC-relative accesses → relocation-true by
  construction (finding 1). The build-time check (P6) pins
  this list: any new absolute outside it fails the build.
- **C7 — relocator in pure .S vs C-with-args?** Answered:
  pure .S. A C relocator in the entry TU would be PC-relative
  safe TODAY (finding 1, direct bl), but its safety would rest
  on "no cross-TU access ever" — a property one future edit
  silently breaks, with no compiler warning. The .S loop is
  ~15 instructions, fully auditable in disassembly, and keeps
  the no-C-before-fixup invariant absolute. C owns the policy
  (verify reads the .S's report); .S owns the mechanism.

## Convergence

P1–P6 with C1–C7 answered. Deliverables of THIS session:

- This deliberation record (the design behind D1, as named).
- `architecture/module-map.md` — reloc row: phase-3 design
  deliberated (session 15); implementation named next.

Named next session (module draft, one solid piece):

- `modules/kido-entry-arm64.S` — the self-relocation loop
  (register discipline x9/x10/x11; x19/x20 preserved),
  BSS zero at actual bounds, relocation report stash
  (applied count + expected count) in BSS.
- `modules/kido-link-arm64.ld` — named .rela.dyn section
  with __rela_dyn_start/end; .rodata.kido_probe_linked
  section with __probe_sec_start/end; manifest inside image
  bounds as law.
- `modules/kido-reloc.h/.c` — verify() policy flip (gated on
  the completeness audit + QEMU proof); the bounds inversion
  (C3); hosted self-test for the new policy; synthetic
  relocator-algorithm test (declared simulation).
- Build-time completeness audit script (P6/C6) — the gate the
  policy flip waits on.

NOT this design (stated so phase 3 doesn't sprawl): -fPIE
(D1), MMU bring-up, the destroy API, resonate deferred
delivery-at-yield, real BUBO peer + bare-metal transport,
UEFI/RPi4. Phase 3 ends when a relocated image PROCEEDS on
QEMU (+0x80000 and −0x80000) with zero exceptions — it does
not end with a bootable kernel claim. First boot is N8toriousAi's
to witness.

## Preserved dissent

- **D1 (P3/P4):** flip the whole image to -fPIE/-pie for
  completeness-by-construction instead of -fno-pic + audit.
  Overruled for phase 3: blast radius (every TU's codegen
  changes at once) vs an enumerable 10-entry manifest on a
  small image. Named as the fallback if the image outgrows
  auditing — the audit script measures that, so the dissent
  has a tripwire of its own.
- **D2 (P1):** a C relocator (entry TU, args passed from .S)
  would be more readable than the .S loop. Overruled (C7):
  readability bought with a fragile cross-TU-access invariant
  that no compiler checks. The .S loop is short enough to
  audit instruction-for-instruction.
- **D3 (inherited):** session-14 D1's negative-delta bare-metal
  run — ADOPTED into the phase-3 proof plan (P5), not
  overruled. It finally gets its run.

## Conformance

- kido.json "portable and adaptive from the start": phase 3
  is the adaptivity payoff the spec names — the environment
  adapted in phase 2; execution adapts here, by measurement
  and fixup, never by assumption. BUBO's flaw (x86-bound,
  untestable-until-hardware) stays compensated: the
  relocator is unit-tested on hosted (synthetic manifest)
  and proven on QEMU before any hardware claim.
- Scaffold honesty law: this record designs but builds
  nothing — no code, no proof claims, no boot. The
  completeness audit is specified as the gate the policy
  flip waits on; the flip is not pre-claimed. The .S loop's
  register discipline and the probe carve-out are stated
  precisely so the module session can be checked against
  them.
- MEDUSA: the behavior reduces to loc_i = r_offset_i +
  delta, *loc_i += delta (minus the carve-out), BSS_zero at
  actual, linked = actual − delta, shown above. The QEMU
  relocated runs (+0x80000, −0x80000) proceeding to
  ABCABCABCABC with zero exceptions are the tests that can
  fail.
