# Deliberation record: kido-reloc phase-3 module draft (2026-10-19)

Builder crew (micro-agent circle). Session 16. This drafts the
implementation the session-15 design named: entry-.S self-relocator
+ BSS-at-actual + report stash; linker-script manifest + probe
sections; kido-reloc.h/.c policy flip (gated) + bounds inversion +
hosted tests; the build-time completeness audit script.

Session 15 did the DESIGN deliberation; this record is the DRAFT
deliberation — the concrete decisions the code embodies, and what
this session honestly could and could not prove.

Constraining fact, stated first: the cross toolchain is ABSENT
again (VM replacement; apt main pocket unreachable — the session-13
pattern). So this session's proof posture is the session-13 one:
.S WRITTEN, NOT ASSEMBLED; audit script WRITTEN, NOT RUN; QEMU
proofs QUEUED. Stated, not hand-waved. Nothing here claims a boot.

## The equations (MEDUSA, unchanged from the design)

    delta        = runtime(probe) - linked(probe)
    loc_i        = r_offset_i + delta            (each R_AARCH64_RELATIVE)
    *loc_i       = *loc_i + delta                (apply; the word holds
                                                  the linked value until patched)
       EXCEPT r_offset_i in [probe_sec_start, probe_sec_end) — the carve-out
       EXCEPT r_offset_i == probe_literal_addr   — the .S literal guard (new, C1)
    BSS_zero     = [_bss_start + delta, _bss_end + delta)
    linked_base  = actual_base - delta           (the bounds inversion)

## Positions

- **P1 (Entry mechanic):** the .S loop as specified, with two
  hardenings the design left open. Register map: x9 cursor,
  x10 manifest end, x11 scratch, x12 loc, x13 r_info, x14/x15
  carve-out [start,end) at actual, x16 total, x17 applied,
  x18 skipped, x8 carved. x19 (DTB) and x20 (delta) untouched;
  x0-x7 unused; no SP yet so no stack use. Hardening 1:
  wrap-guarded arithmetic — loc = r_offset + delta is computed
  sign-aware (adds/b.cs for delta >= 0, compare-and-sub for
  delta < 0); any wrap spins via reloc_spin (the pre-console
  halt idiom — there is no louder before the console exists).
  The BSS-at-actual computation gets the same guard. Hardening 2:
  manifest sanity — cursor start > end spins; an empty manifest
  walks zero entries and the C policy fails it closed (total > 0
  required). The relocator runs exactly once, before SP setup;
  the counts survive in registers through the BSS loop (which
  uses only x0/x1/x11) into the five-slot BSS stash after zeroing.
- **P2 (Instrument keeper):** the finding-4 ambiguity is
  unmeasurable this session (no toolchain to dump the linked
  image), so the draft defends BOTH readings at three layers.
  (1) Runtime: the relocator skips any entry whose loc equals
  the .S's own probe-literal word — precise via `adr` of an now
  explicit `probe_literal:` label (~3 instructions; a no-op if
  finding 4 holds). (2) Build-time: the audit enumerates every
  RELATIVE's r_offset to its section and fails the build on any
  .text target except exactly probe_literal's address. (3)
  Detection: if the guard ever failed, the .S's delta would read
  0 while C reads nonzero — the existing crosscheck fires loud.
  Plus the new C-side probe-still-linked check pins the
  .rodata constant's value. Four report slots (total/applied/
  carved/skipped), not three: a derived carved count cannot
  catch a silently-unapplied entry in the hosted test; the .S
  counts carved directly on its skip branch.
- **P3 (Linker purist):** explicit `.rela.dyn` with
  __rela_dyn_start/end (8-aligned; KEEP; inside image bounds as
  law — the audit pins it), and `.rodata.kido_probe_linked`
  with __probe_sec_start/end placed BEFORE the generic .rodata
  (first-match idiom — a *(.rodata*) pattern would otherwise
  swallow the specific section). The probe constant moves there
  via a section attribute; it is the section's only occupant
  (the audit asserts exactly one OBJECT symbol).
- **P4 (Honesty auditor):** the policy flip is gated on a
  GENERATED stamp and defaults CLOSED. scripts/
  kido-audit-abs-refs.sh --stamp is the ONLY writer of
  modules/kido-reloc-audit-stamp.h (which defines
  KIDO_RELOC_AUDIT_PASS); kido-reloc.c picks it up via
  __has_include — no Makefile flag juggling, no hand-written
  stamp (documented in the header, the script, and here). The
  .S mechanism runs UNCONDITIONALLY even with the gate closed:
  fixups only make GOT accesses correct; the refusal still
  fires. That is deliberate — a relocated image under the
  closed gate gets correct addresses AND a loud refusal,
  never correct addresses silently. The stamp records the
  audited image's sha256 + counts + date; the build flow is
  audit -> stamp -> rebuild -> re-audit -> QEMU.
- **P5 (Portability auditor):** the bounds inversion is
  bare-metal-only. Hosted keeps the declared fiction (injected
  base IS the linked base; actual = linked + delta) — the
  hosted harness has no .S and no fixup, and must not pretend
  otherwise. kido_image_actual_bounds() becomes a thin alias
  of kido_image_bounds() on bare metal (post-fixup the GOT
  reads actual); on hosted it keeps its old injected+delta
  body. kido_sched_init is untouched — the alias preserves its
  contract. The flip-engaged hosted test passes -DKIDO_RELOC_
  AUDIT_PASS on the TEST COMPILE LINE ONLY (declared
  comparator testing — the same precedent as delta injection);
  the gate-closed hosted build keeps all 21 existing checks
  passing unchanged, which pins "no flip without the audit."
- **P6 (Test keeper):** hosted matrix in two flavors.
  Gate-closed: nonzero delta + a PERFECT report still refuses
  (EARLY_ENV) — the gate does its job; delta-0 proceeds.
  Flip-engaged: proceed on {delta +/-0x80000, report
  10/9/1/0, probe-ok, instruments agreeing}; loud on
  applied+carved+skipped != total, skipped != 0, total == 0,
  carved == 0 (the carve-out pin), probe-ok == 0, crosscheck
  disagreement (which precedes the policy), and a bad report at
  delta 0 (the walk validates even when it adds nothing).
  Audit script: parsing/decision logic fixture-tested (one
  positive fixture -> PASS with exact counts; two negative
  fixtures -> FAIL) — real pass/fail on the logic; the thin
  tool-invocation layer (readelf calls) is untested by
  construction and stated so.

## Challenges

- **C1 — the finding-4 ambiguity: guard in the .S, or trust
  the audit?** Answered (P2): both, plus detection. The
  dissent (D2) wanted the audit alone; overruled — the audit
  cannot run today, and a latent instrument-killer is the
  exact failure this scaffold exists to prevent. If a future
  audit proves finding 4, the guard is a documented no-op.
- **C2 — four slots vs three?** Answered (P2): the .S counts
  carved on its skip branch; the hosted test's "applied !=
  expected -> loud" case is only meaningful with an
  independent carved count.
- **C3 — the .S fixup runs with the gate closed: does that
  weaken the refusal?** Answered (P4): no — the fixup is
  address-correctness, the refusal is policy. A relocated
  image under the closed gate now refuses with correct
  addresses instead of refusing with stale ones. Strictly
  safer.
- **C4 — stamp staleness (audited image != shipped image)?**
  Answered (P4): the stamp records sha256 + counts + date;
  the documented flow re-audits the final image before any
  QEMU claim. A stale stamp is a human-auditable fact, not a
  silent one.
- **C5 — is a spin "loud"?** Answered: pre-console there is
  no louder; it is the established idiom (EL0/EL3 spin). The
  C side re-validates everything the .S guarded and halts
  with a code. Spin-then-code, never silent corruption.
- **C6 — kido_image_actual_bounds as an alias: does any
  consumer break?** Answered: no. kido_sched_init is the only
  consumer; its contract (reserve the real image) is
  preserved — on bare metal the real image IS what bounds()
  now returns. Hosted keeps the old body. Its self-test is
  unaffected.
- **C7 — the audit script cannot run: is it a real
  deliverable?** Answered (P6): the parsing/decision core is
  fixture-tested with real pass/fail; the readelf-invocation
  layer is thin and its exact commands are documented in the
  script header for the toolchain's return. Marked WRITTEN
  NOT RUN, like the .S.

## Convergence

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

- This deliberation record.
- `modules/kido-entry-arm64.S` — rewritten: delta measure
  (unchanged) -> EL drop (unchanged) -> RELOCATE (new,
  register map + wrap guards + literal guard as above) ->
  SP = _stack_top + delta -> BSS zero at ACTUAL (wrap-guarded)
  -> five-slot BSS stash (delta/valid/total/applied/carved/
  skipped) -> kido_entry_c_main. Explicit probe_literal label.
  PROOF STATUS: written, not assembled (toolchain absent).
- `modules/kido-link-arm64.ld` — explicit .rela.dyn
  (__rela_dyn_start/end, 8-aligned, KEEP, inside image as law)
  + .rodata.kido_probe_linked (__probe_sec_start/end, before
  generic .rodata). Canonical RAM_BASE untouched.
- `modules/kido-reloc.h` — phase-3 honesty law; four new
  BSS-slot externs; kido_reloc_test_set_probe_ok (hosted);
  the stamp-gate documentation; verify()'s gated contract;
  linked_base now DERIVED (actual - delta) on bare metal.
- `modules/kido-reloc.c` — probe constant moved to the
  probe section; stamp include via __has_include; detect()
  bare-metal inversion (wrap-guarded); kido_reloc_report_
  check() + kido_reloc_probe_still_linked() (static);
  verify() gated flip; self-test rewritten (flavor-
  independent base + gate-closed pin + flip-engaged matrix).
- `modules/kido-image.h/.c` — bare-metal actual_bounds is
  now the thin alias (documented); hosted body unchanged.
- `modules/kido-entry-arm64.c` — comment-only: WHAT IS REAL
  updated to phase 3 (wiring line unchanged).
- `scripts/kido-audit-abs-refs.sh` — the gate (checks A–E
  in its header); fixture-tested parsing; WRITTEN NOT RUN.
- `scripts/fixtures/` + `scripts/test-audit-fixtures.sh` —
  the fixture test (real pass/fail).
- `architecture/module-map.md` — reloc row: phase-3 draft.
- `README.md` — layout gains scripts/.
- Ledger entry (session 16).

NOT this draft (stated so phase 3 doesn't sprawl): assembling
the .S, running the audit on a real image, the QEMU
relocated-proceed proofs (+0x80000 / -0x80000 — the design's
proof plan, queued on the toolchain), -fPIE (D1), MMU,
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 with zero exceptions — it
does not end with a bootable kernel claim. First boot is
N8toriousAi's to witness.

## Preserved dissent

- **D1 (inherited, P3/P4):** flip the whole image to -fPIE
  for completeness-by-construction instead of -fno-pic +
  audit. Still overruled for phase 3 (session-15 reasoning
  stands). The audit measures the manifest on every build,
  so the dissent keeps its tripwire: if the image outgrows
  auditing, the dissent is the named fallback.
- **D2 (P2 minority):** ship the .S without the probe-literal
  guard; let the build-time audit catch a wrong finding-4.
  Overruled: fail-closed. The audit cannot run today; a
  latent silent-instrument-death is not shippable on a
  promise. Revisit only with a measured linked image in hand.

## Conformance

- kido.json "portable and adaptive from the start": phase 3
  is the adaptivity payoff — execution adapts by measurement
  and fixup, never by assumption. The hosted harness keeps
  its declared fictions; nothing is pretended onto bare metal.
- Scaffold honesty law: the .S is written-not-assembled, the
  audit written-not-run, the QEMU proofs queued — each stated
  in the file that carries it. The policy flip defaults
  CLOSED; no relocated execution is claimed anywhere.
- MEDUSA: loc_i = r_offset_i + delta, *loc_i += delta (minus
  the two carve-outs), BSS_zero at actual, linked = actual -
  delta. The hosted matrix and the fixture-tested audit are
  the tests that can fail; the QEMU relocated runs are the
  tests that will fail or pass when the toolchain returns.
