/*
 * kido-image.h — Kido kernel-image bounds, public interface.
 *
 * Closes sched deliberation D2 (2026-10-16): the allocator must never
 * hand out memory that the linked kernel image — or its boot stack —
 * occupies. This module is the single source of truth for
 * [image_start, image_start + size): read from the linker symbols on
 * bare metal, injected by the test on hosted.
 *
 * HONESTY LAW:
 *  - Bare metal (ARM64): bounds come from _image_start/_image_end in
 *    kido-link-arm64.ld. The module computes nothing and invents
 *    nothing. Inverted bounds (end <= start) mean a mislinked image
 *    and fail LOUD (KIDO_ERR_EARLY_ENV) — the allocator must never
 *    run on a mislinked image.
 *  - PHASE 3 (2026-10-19, the bounds inversion): the entry .S fixes
 *    up every GOT-based access before C runs, so on bare metal
 *    kido_image_bounds() reads the ACTUAL image location — the
 *    symbols resolve through the fixed GOT. The LINKED base is
 *    derived by kido-reloc as actual - delta (one query, reversed);
 *    this module never stores both. kido_image_actual_bounds() is
 *    the thin alias kept for API stability (kido_sched_init is its
 *    only consumer and is untouched).
 *  - The boot stack is part of the image (the linker script places
 *    _image_end after the 16 KiB boot stack). Reserving 16 KiB of
 *    128 MiB forever is honest waste; handing the live boot stack to
 *    a task would be silent corruption.
 *  - Hosted: there IS no linked kernel image, so there is nothing to
 *    reserve. The bounds query refuses (KIDO_ERR_STUB_REACHED) unless
 *    the test injects explicit bounds via
 *    kido_image_test_set_bounds(). kido_sched_init treats
 *    STUB_REACHED on hosted as a vacuous 0,0 reservation — declared
 *    in the design record, never invented bounds.
 *  - Link-at-load law: the symbols are absolute to the LINKED base.
 *    The image must be linked at its actual load address
 *    (kido-link-arm64.ld documents the QEMU raw-binary finding).
 *    Relocation is kido-reloc's job (image-deliberation D1, drafted
 *    2026-10-17): detect() reads the LINKED bounds here, and
 *    kido_image_actual_bounds() reports linked + last-delta for
 *    consumers that need the REAL image location (the allocator
 *    reservation). Phase 2 (2026-10-17): the environment is
 *    delta-aware; execution under relocation is still refused LOUD
 *    by kido-reloc (the image is honestly non-position-independent).
 *
 * Draft status: bounds query is REAL (linker symbols on ARM64;
 * declared-vacuous on hosted). Bare-metal execution proof is a future
 * QEMU session (assembled, not executed).
 */
#ifndef KIDO_IMAGE_H
#define KIDO_IMAGE_H

#include "kido-boot.h"  /* kido_status_t */

#if !defined(__aarch64__) && !defined(KIDO_HOSTED_TEST)
#error "kido-image: ARM64 or hosted only. Define KIDO_HOSTED_TEST for the hosted draft harness."
#endif

/* ------------------------------------------------------------------ */
/* kido_image_bounds: [image_start, image_start + size) of the linked */
/* image, boot stack included. Bare metal reads the linker symbols;  */
/* hosted returns KIDO_ERR_STUB_REACHED unless the test injected      */
/* bounds. NULL outs -> KIDO_ERR_EARLY_ENV. Mislinked image          */
/* (end <= start) -> KIDO_ERR_EARLY_ENV, loud.                        */
/* ------------------------------------------------------------------ */
kido_status_t kido_image_bounds(uint64_t *base_out, uint64_t *size_out);

/* ------------------------------------------------------------------ */
/* kido_image_actual_bounds: [actual_base, actual_base + size) — where */
/* the image REALLY runs. Phase 3: on bare metal the entry .S fixed   */
/* up every GOT-based access before C ran, so kido_image_bounds()     */
/* already reads the ACTUAL location — this is the thin alias kept    */
/* for API stability (kido_sched_init's contract is unchanged). On     */
/* hosted there is no fixup: the injected base is the linked base     */
/* and the actual base is linked + the relocation delta from          */
/* kido_reloc_last() (one query, no duplicated truth); size is        */
/* invariant under translation. A delta that would under/overflow    */
/* the base -> KIDO_ERR_EARLY_ENV (loud). kido_reloc_detect()         */
/* derives linked = actual - delta from the bare-metal query.         */
/* ------------------------------------------------------------------ */
kido_status_t kido_image_actual_bounds(uint64_t *base_out,
                                       uint64_t *size_out);

#ifdef KIDO_HOSTED_TEST
/* ------------------------------------------------------------------ */
/* kido_image_test_set_bounds: declare the fake image for the hosted  */
/* test (e.g. a slice of the scheduler's arena). size == 0, or a     */
/* base+size that overflows -> KIDO_ERR_EARLY_ENV. With no injection, */
/* the bounds query refuses. Not compiled on bare metal.              */
/* ------------------------------------------------------------------ */
kido_status_t kido_image_test_set_bounds(uint64_t base, uint64_t size);
#endif

#endif /* KIDO_IMAGE_H */
