/*
 * kido-interop.c — Kido side of the Kido <-> BUBO inter-kernel protocol.
 *
 * See kido-interop.h for the laws. Static state only; no allocator; the
 * implementation is portable C (no arch-isms) so the hosted self-test
 * exercises the real logic.
 */

#include "kido-interop.h"

/* ------------------------------------------------------------------ */
/* Static state. Explicit init; no hidden coupling.                    */
/* ------------------------------------------------------------------ */
static kido_kernel_t       s_self = KIDO_KERNEL_KIDO;
static const kido_hal_t   *s_hal  = NULL;
static const kido_link_t  *s_link = NULL;
static kido_interop_state_t s_state = KIDO_INTEROP_UNBOUND;
static uint32_t s_tx_packets        = 0u;
static uint32_t s_rx_packets        = 0u;
static uint32_t s_tx_failed         = 0u;
static uint32_t s_rx_version_reject = 0u;
static uint32_t s_announces         = 0u;
static uint8_t  s_solo_noted        = 0u;

static int valid_kernel(uint32_t k)
{
    return k == (uint32_t)KIDO_KERNEL_KIDO ||
           k == (uint32_t)KIDO_KERNEL_BUBO;
}

kido_status_t kido_interop_init(kido_kernel_t self, const kido_hal_t *hal)
{
    if (!valid_kernel((uint32_t)self) || hal == NULL)
        return KIDO_ERR_EARLY_ENV;
    s_self  = self;
    s_hal   = hal;
    s_link  = NULL;
    s_state = KIDO_INTEROP_UNBOUND;
    s_tx_packets = 0u;
    s_rx_packets = 0u;
    s_tx_failed  = 0u;
    s_rx_version_reject = 0u;
    s_announces  = 0u;
    s_solo_noted = 0u;
    return KIDO_OK;
}

kido_status_t kido_interop_bind(const kido_link_t *link)
{
    /* NULL = unbind. Any (re)bind drops the state machine to UNBOUND:
     * a new medium means a new handshake. */
    s_link  = link;
    s_state = KIDO_INTEROP_UNBOUND;
    s_solo_noted = 0u;
    return KIDO_OK;
}

kido_status_t kido_interop_announce(uint32_t max_rounds)
{
    kido_packet_t pkt, in;
    uint8_t got = 0u;
    uint32_t r;
    kido_status_t st;

    if (s_state == KIDO_INTEROP_LINKED)
        return KIDO_OK;  /* idempotent */
    if (s_hal == NULL)
        return KIDO_ERR_EARLY_ENV;
    if (s_link == NULL || s_link->send == NULL || s_link->recv == NULL)
        return KIDO_ERR_STUB_REACHED;  /* transport: declared stub */

    /* ANNOUNCE envelope. Control packets bypass band addressing — the
     * peer's interop layer consumes them by type, never by band. */
    pkt.magic       = KIDO_INTEROP_MAGIC;
    pkt.version     = KIDO_INTEROP_VERSION;
    pkt.dest_kernel = (uint32_t)KIDO_KERNEL_BUBO;
    pkt.src_kernel  = (uint32_t)s_self;
    pkt.hop_count   = 0u;
    pkt.signal.source_id        = KIDO_INTEROP_KERNEL_SOURCE;
    pkt.signal.dest_band_hz     = KIDO_BAND_UNTUNED;
    pkt.signal.type             = KIDO_TYPE_ANNOUNCE;
    pkt.signal.strength_permille = 1000u;
    pkt.signal.freq_hz          = 0u;    /* control: no resonant meaning */
    pkt.signal.arrival_ticks    = 0u;
    pkt.signal.eta              = 0.0f;

    st = s_link->send(&pkt);
    if (st != KIDO_OK) {
        s_tx_failed++;
        s_state = KIDO_INTEROP_UNBOUND;
        return st;
    }
    s_tx_packets++;
    s_announces++;
    s_state = KIDO_INTEROP_ANNOUNCED;

    for (r = 0u; r < max_rounds; r++) {
        st = kido_interop_recv(&in, &got);
        if (st != KIDO_OK)
            return st;  /* driver failure: propagate, stay ANNOUNCED */
        if (got != 0u &&
            in.signal.type   == KIDO_TYPE_ANNOUNCE_ACK &&
            in.src_kernel     == (uint32_t)KIDO_KERNEL_BUBO &&
            in.dest_kernel    == (uint32_t)s_self) {
            s_state = KIDO_INTEROP_LINKED;
            s_solo_noted = 0u;
            return KIDO_OK;
        }
        /* Anything else was validated + counted by recv and is consumed
         * here. Real traffic starts after LINKED (stated limitation). */
    }

    if (max_rounds > 0u) {
        /* Bounded wait expired: absence is a fact, not a failure. */
        s_state = KIDO_INTEROP_SOLO;
        if (s_solo_noted == 0u && s_hal->console_puts != NULL) {
            s_hal->console_puts("[Kido] interop: no BUBO answer - solo mode\n");
            s_solo_noted = 1u;
        }
    }
    return KIDO_OK;
}

kido_status_t kido_interop_send(kido_kernel_t dest, const kido_signal_t *sig)
{
    kido_packet_t pkt;
    kido_status_t st;

    if (!valid_kernel((uint32_t)dest) || sig == NULL ||
        sig->strength_permille > 1000u)
        return KIDO_ERR_EARLY_ENV;
    if (s_hal == NULL || s_state == KIDO_INTEROP_UNBOUND)
        return KIDO_ERR_EARLY_ENV;
    if (s_state != KIDO_INTEROP_LINKED)
        return KIDO_ERR_STUB_REACHED;  /* ANNOUNCED/SOLO: no peer — loud */
    if (s_link == NULL || s_link->send == NULL)
        return KIDO_ERR_STUB_REACHED;  /* defensive; announce guards this */

    pkt.magic       = KIDO_INTEROP_MAGIC;
    pkt.version     = KIDO_INTEROP_VERSION;
    pkt.dest_kernel = (uint32_t)dest;
    pkt.src_kernel  = (uint32_t)s_self;
    pkt.hop_count   = 0u;
    pkt.signal      = *sig;  /* the wire shape, carried whole */

    st = s_link->send(&pkt);
    if (st != KIDO_OK) {
        s_tx_failed++;
        return st;
    }
    s_tx_packets++;
    return KIDO_OK;
}

kido_status_t kido_interop_recv(kido_packet_t *out, uint8_t *got_out)
{
    kido_packet_t pkt;
    uint8_t got = 0u;
    kido_status_t st;

    if (out == NULL || got_out == NULL)
        return KIDO_ERR_EARLY_ENV;
    if (s_hal == NULL || s_state == KIDO_INTEROP_UNBOUND ||
        s_link == NULL || s_link->recv == NULL)
        return KIDO_ERR_EARLY_ENV;

    st = s_link->recv(&pkt, &got);
    if (st != KIDO_OK)
        return st;
    if (got == 0u) {
        *got_out = 0u;  /* SOLO polls land here: absence is a fact */
        return KIDO_OK;
    }

    if (pkt.magic != KIDO_INTEROP_MAGIC ||
        pkt.version != KIDO_INTEROP_VERSION) {
        s_rx_version_reject++;
        *got_out = 0u;
        return KIDO_OK;  /* counted result, not an error */
    }

    /* Ingress accounting. Decay is receiver-measured; the wire stays
     * honest about what was sent. */
    pkt.signal.strength_permille =
        (pkt.signal.strength_permille *
         (1000u - KIDO_INTEROP_HOP_LOSS_PERMILLE)) / 1000u;
    pkt.hop_count++;
    s_rx_packets++;

    *out = pkt;
    *got_out = 1u;
    return KIDO_OK;
}

kido_status_t kido_interop_stats(kido_interop_stats_t *out)
{
    if (out == NULL)
        return KIDO_ERR_EARLY_ENV;
    out->state             = (uint32_t)s_state;
    out->self_kernel       = (uint32_t)s_self;
    out->tx_packets        = s_tx_packets;
    out->rx_packets        = s_rx_packets;
    out->tx_failed         = s_tx_failed;
    out->rx_version_reject = s_rx_version_reject;
    out->announces         = s_announces;
    return KIDO_OK;
}

/* ================================================================== */
/* Hosted self-test. A two-queue loopback pipe stands in for the      */
/* transport; a SIMULATED BUBO peer (test-authored packets) proves    */
/* Kido's side of the protocol. The peer is declared simulation —     */
/* this test proves Kido's envelope, handshake, decay, and loudness,  */
/* not BUBO's existence.                                              */
/* ================================================================== */
#ifdef KIDO_INTEROP_SELFTEST
#ifndef KIDO_HOSTED_TEST
#error "KIDO_INTEROP_SELFTEST needs KIDO_HOSTED_TEST."
#endif

#include <stdio.h>

static int s_checks = 0;
static int s_failures = 0;

#define CHECK(cond) do { \
    s_checks++; \
    if (!(cond)) { s_failures++; \
        printf("[FAIL] line %d: %s\n", __LINE__, #cond); } \
} while (0)

/* Fake HAL: counts console notes so the SOLO loudness is observable. */
static int s_solo_notes = 0;
static void fake_putc(char c) { (void)c; }
static void fake_puts(const char *s) { (void)s; s_solo_notes++; }
static uint64_t fake_ticks(void) { return 42u; }
static uint32_t fake_hz(void)    { return 1000u; }

/* Loopback pipe: kido_out = packets FROM kido; kido_in = packets TO kido
 * (peer-authored). Depth-bounded; overflow is a loud test-harness error. */
#define LB_DEPTH 16u
static kido_packet_t s_kido_in[LB_DEPTH];
static uint8_t s_kido_in_n = 0u;
static kido_packet_t s_kido_out[LB_DEPTH];
static uint8_t s_kido_out_n = 0u;

static kido_status_t lb_send(const kido_packet_t *pkt)
{
    if (pkt == NULL || s_kido_out_n >= LB_DEPTH)
        return KIDO_ERR_EARLY_ENV;
    s_kido_out[s_kido_out_n++] = *pkt;
    return KIDO_OK;
}

static kido_status_t lb_recv(kido_packet_t *pkt, uint8_t *got_out)
{
    uint8_t i;
    if (pkt == NULL || got_out == NULL)
        return KIDO_ERR_EARLY_ENV;
    if (s_kido_in_n == 0u) {
        *got_out = 0u;
        return KIDO_OK;
    }
    *pkt = s_kido_in[0];
    for (i = 1u; i < s_kido_in_n; i++)
        s_kido_in[i - 1u] = s_kido_in[i];
    s_kido_in_n--;
    *got_out = 1u;
    return KIDO_OK;
}

static const kido_link_t s_lb_link   = { lb_send, lb_recv };
static const kido_link_t s_half_link = { NULL, lb_recv };  /* half table */

/* Simulated BUBO: the test authors peer-side packets. Declared
 * simulation — proves Kido's side only. */
static void peer_inject(const kido_packet_t *pkt)
{
    if (s_kido_in_n < LB_DEPTH)
        s_kido_in[s_kido_in_n++] = *pkt;
}

static uint8_t peer_drain(kido_packet_t *pkt)
{
    uint8_t i;
    if (s_kido_out_n == 0u)
        return 0u;
    *pkt = s_kido_out[0];
    for (i = 1u; i < s_kido_out_n; i++)
        s_kido_out[i - 1u] = s_kido_out[i];
    s_kido_out_n--;
    return 1u;
}

static void peer_make(kido_packet_t *p, uint32_t type, uint32_t strength)
{
    p->magic       = KIDO_INTEROP_MAGIC;
    p->version     = KIDO_INTEROP_VERSION;
    p->dest_kernel = (uint32_t)KIDO_KERNEL_KIDO;
    p->src_kernel  = (uint32_t)KIDO_KERNEL_BUBO;
    p->hop_count   = 0u;
    p->signal.source_id         = 3u;
    p->signal.dest_band_hz      = 515u;
    p->signal.type              = type;
    p->signal.strength_permille = strength;
    p->signal.freq_hz           = 515u;
    p->signal.arrival_ticks     = 0u;
    p->signal.eta               = 0.0f;
}

int main(void)
{
    kido_hal_t hal;
    kido_packet_t pkt, ack;
    kido_signal_t sig, bad;
    kido_interop_stats_t st;
    uint8_t got = 0u;

    hal.console_putc = fake_putc;
    hal.console_puts = fake_puts;
    hal.timer_ticks  = fake_ticks;
    hal.timer_hz     = fake_hz;

    /* 1. init guards */
    CHECK(kido_interop_init((kido_kernel_t)99u, &hal) == KIDO_ERR_EARLY_ENV);
    CHECK(kido_interop_init(KIDO_KERNEL_KIDO, NULL) == KIDO_ERR_EARLY_ENV);
    CHECK(kido_interop_init(KIDO_KERNEL_KIDO, &hal) == KIDO_OK);
    CHECK(kido_interop_stats(&st) == KIDO_OK);
    CHECK(st.state == (uint32_t)KIDO_INTEROP_UNBOUND);
    CHECK(st.self_kernel == (uint32_t)KIDO_KERNEL_KIDO);

    /* 2. unbound link is loud */
    CHECK(kido_interop_send(KIDO_KERNEL_BUBO, &sig) == KIDO_ERR_EARLY_ENV);
    CHECK(kido_interop_recv(&pkt, &got) == KIDO_ERR_EARLY_ENV);
    CHECK(kido_interop_announce(4u) == KIDO_ERR_STUB_REACHED); /* no driver */
    CHECK(kido_interop_stats(&st) == KIDO_OK && st.announces == 0u);

    /* 3. half-filled driver table fails loud on announce */
    CHECK(kido_interop_bind(&s_half_link) == KIDO_OK);
    CHECK(kido_interop_announce(1u) == KIDO_ERR_STUB_REACHED);
    CHECK(kido_interop_stats(&st) == KIDO_OK && st.announces == 0u);

    /* 4. bind loopback; peer silent -> SOLO, loud note exactly once */
    CHECK(kido_interop_bind(&s_lb_link) == KIDO_OK);
    CHECK(kido_interop_announce(4u) == KIDO_OK);
    CHECK(kido_interop_stats(&st) == KIDO_OK);
    CHECK(st.state == (uint32_t)KIDO_INTEROP_SOLO);
    CHECK(st.announces == 1u && st.tx_packets == 1u);
    CHECK(s_solo_notes == 1);
    /* the ANNOUNCE envelope is well-formed */
    CHECK(peer_drain(&pkt) == 1u);
    CHECK(pkt.magic == KIDO_INTEROP_MAGIC);
    CHECK(pkt.version == KIDO_INTEROP_VERSION);
    CHECK(pkt.dest_kernel == (uint32_t)KIDO_KERNEL_BUBO);
    CHECK(pkt.src_kernel == (uint32_t)KIDO_KERNEL_KIDO);
    CHECK(pkt.hop_count == 0u);
    CHECK(pkt.signal.type == KIDO_TYPE_ANNOUNCE);
    CHECK(pkt.signal.source_id == KIDO_INTEROP_KERNEL_SOURCE);

    /* 5. SOLO: sends loud, polls quiet */
    sig.source_id = 7u; sig.dest_band_hz = 515u; sig.type = KIDO_TYPE_LANG;
    sig.strength_permille = 800u; sig.freq_hz = 515u;
    sig.arrival_ticks = 1234u; sig.eta = 0.75f;
    CHECK(kido_interop_send(KIDO_KERNEL_BUBO, &sig) == KIDO_ERR_STUB_REACHED);
    CHECK(kido_interop_recv(&pkt, &got) == KIDO_OK && got == 0u);
    CHECK(kido_interop_stats(&st) == KIDO_OK && st.tx_packets == 1u);

    /* 6. peer answers: re-announce -> LINKED (simulated BUBO ACK) */
    peer_make(&ack, KIDO_TYPE_ANNOUNCE_ACK, 1000u);
    peer_inject(&ack);
    CHECK(kido_interop_announce(8u) == KIDO_OK);
    CHECK(kido_interop_stats(&st) == KIDO_OK);
    CHECK(st.state == (uint32_t)KIDO_INTEROP_LINKED);
    CHECK(st.announces == 2u && st.tx_packets == 2u && st.rx_packets == 1u);
    CHECK(peer_drain(&pkt) == 1u);  /* the second ANNOUNCE */
    CHECK(pkt.signal.type == KIDO_TYPE_ANNOUNCE);

    /* 7. re-announce while LINKED: idempotent, no new traffic */
    CHECK(kido_interop_announce(8u) == KIDO_OK);
    CHECK(kido_interop_stats(&st) == KIDO_OK);
    CHECK(st.state == (uint32_t)KIDO_INTEROP_LINKED);
    CHECK(st.announces == 2u && st.tx_packets == 2u);

    /* 8. LANG send: envelope wraps the wire shape whole; the wire stays
     * honest (no sender-side decay — decay is receiver-measured). */
    CHECK(kido_interop_send(KIDO_KERNEL_BUBO, &sig) == KIDO_OK);
    CHECK(peer_drain(&pkt) == 1u);
    CHECK(pkt.magic == KIDO_INTEROP_MAGIC && pkt.version == KIDO_INTEROP_VERSION);
    CHECK(pkt.dest_kernel == (uint32_t)KIDO_KERNEL_BUBO);
    CHECK(pkt.src_kernel == (uint32_t)KIDO_KERNEL_KIDO);
    CHECK(pkt.hop_count == 0u);
    CHECK(pkt.signal.source_id == 7u && pkt.signal.dest_band_hz == 515u);
    CHECK(pkt.signal.type == KIDO_TYPE_LANG);
    CHECK(pkt.signal.strength_permille == 800u);  /* wire honest */
    CHECK(pkt.signal.freq_hz == 515u && pkt.signal.arrival_ticks == 1234u);
    CHECK(pkt.signal.eta == 0.75f);
    CHECK(kido_interop_stats(&st) == KIDO_OK && st.tx_packets == 3u);

    /* 9. ingress: hop counted, decay applied by the receiver.
     * 1000 -> 1000*950/1000 = 950. */
    peer_make(&pkt, KIDO_TYPE_SYS, 1000u);
    peer_inject(&pkt);
    CHECK(kido_interop_recv(&pkt, &got) == KIDO_OK && got == 1u);
    CHECK(pkt.hop_count == 1u);
    CHECK(pkt.signal.strength_permille == 950u);
    CHECK(pkt.signal.type == KIDO_TYPE_SYS);
    CHECK(pkt.src_kernel == (uint32_t)KIDO_KERNEL_BUBO);
    CHECK(pkt.dest_kernel == (uint32_t)KIDO_KERNEL_KIDO);

    /* 10. decay equation pinned: 800 -> 800*950/1000 = 760, exact. */
    peer_make(&pkt, KIDO_TYPE_LANG, 800u);
    peer_inject(&pkt);
    CHECK(kido_interop_recv(&pkt, &got) == KIDO_OK && got == 1u);
    CHECK(pkt.signal.strength_permille == 760u && pkt.hop_count == 1u);

    /* 11. version/magic mismatch: counted, not errors */
    peer_make(&pkt, KIDO_TYPE_SYS, 500u);
    pkt.version = 99u;
    peer_inject(&pkt);
    CHECK(kido_interop_recv(&pkt, &got) == KIDO_OK && got == 0u);
    peer_make(&pkt, KIDO_TYPE_SYS, 500u);
    pkt.magic = 0xDEADu;
    peer_inject(&pkt);
    CHECK(kido_interop_recv(&pkt, &got) == KIDO_OK && got == 0u);
    CHECK(kido_interop_stats(&st) == KIDO_OK);
    CHECK(st.rx_version_reject == 2u && st.rx_packets == 3u);

    /* 12. arg validation is loud */
    bad = sig; bad.strength_permille = 1001u;
    CHECK(kido_interop_send((kido_kernel_t)99u, &sig) == KIDO_ERR_EARLY_ENV);
    CHECK(kido_interop_send(KIDO_KERNEL_BUBO, NULL) == KIDO_ERR_EARLY_ENV);
    CHECK(kido_interop_send(KIDO_KERNEL_BUBO, &bad) == KIDO_ERR_EARLY_ENV);
    CHECK(kido_interop_recv(NULL, &got) == KIDO_ERR_EARLY_ENV);
    CHECK(kido_interop_recv(&pkt, NULL) == KIDO_ERR_EARLY_ENV);
    CHECK(kido_interop_stats(NULL) == KIDO_ERR_EARLY_ENV);

    /* 13. final accounting */
    CHECK(kido_interop_stats(&st) == KIDO_OK);
    CHECK(st.state == (uint32_t)KIDO_INTEROP_LINKED);
    CHECK(st.tx_packets == 3u && st.rx_packets == 3u);
    CHECK(st.tx_failed == 0u && st.announces == 2u);
    CHECK(s_solo_notes == 1);  /* noted once; LINKED reset the flag */

    printf("[test] kido-interop: %d checks, %d failures\n",
           s_checks, s_failures);
    return s_failures == 0 ? 0 : 1;
}
#endif /* KIDO_INTEROP_SELFTEST */
