G8l: scheduler/context-switch/TLBI runtime authority source-contract

//! Allocation-free G8l scheduler/context-switch/TLBI authority contract.
//!
//! S166 composes the S165 production authority source with the scheduler
//! handoff order.  It is intentionally a source contract: the receipts are
//! validated inputs from the eventual IRQ/TLBI implementation, not hardware
//! proof, and this module does not invoke the scheduler or context-switch
//! assembly itself.

use crate::g8l_authority_contract::{
    El0MigrationInput, G8lAuthorityError, G8lMigrationAuthority, MigrationState, MigrationTicket,
    ShootdownReceipt, Ttbr0Readback,
};
use core::sync::atomic::{AtomicU64, Ordering};

pub use crate::g8l_authority_contract::{CPU0, CPU1};
pub const ONLINE_MASK: u8 = 0b0011;

static NEXT_RUNTIME_INSTANCE_ID: AtomicU64 = AtomicU64::new(1);

fn allocate_runtime_instance_id() -> Result<u64, G8lRuntimeError> {
    let mut current = NEXT_RUNTIME_INSTANCE_ID.load(Ordering::Relaxed);
    loop {
        let next = current
            .checked_add(1)
            .ok_or(G8lRuntimeError::RuntimeInstanceIdExhausted)?;
        match NEXT_RUNTIME_INSTANCE_ID.compare_exchange_weak(
            current,
            next,
            Ordering::Relaxed,
            Ordering::Relaxed,
        ) {
            Ok(_) => return Ok(current),
            Err(observed) => current = observed,
        }
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct RuntimeMigrationInput {
    pub task_id: u64,
    pub el0: bool,
    pub asid: u16,
    pub root: u64,
    pub address_space_generation: u64,
    pub user_progress: u64,
    pub context_generation: u64,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum RuntimePhase {
    Running0,
    TicketCaptured,
    SwitchPrepared,
    Ttbr0Installed,
    ShootdownComplete,
    MappingRetired,
    ReadyPublished,
    ContextSwitched,
    Running1,
}

#[test]
fn source_contract_composes_scheduler_ttbr0_tlbi_context_switch_and_eret() {
    let mut authority = authority();
    let ticket = ready(&mut authority);
    authority
        .context_switch(CPU0, CPU1, ticket, CONTEXT_GENERATION, true, true)
        .unwrap();
    assert_eq!(authority.phase(), RuntimePhase::ContextSwitched);
    authority
        .commit_eret(CPU1, ticket, readback(ticket), CONTEXT_GENERATION)
        .unwrap();
    assert_eq!(authority.phase(), RuntimePhase::Running1);
    assert_eq!(authority.migration_state(), MigrationState::Running1);
    assert_eq!(authority.active_ticket(), None);
}

  {
    id: "g8l-s166-scheduler-tlbi-runtime-authority-contract-partial",
    date: "2026-08-24",
    sequence: 166,
    status: "passed",
    umbrella_status: "partial",
    title:
      "G8l: scheduler/context-switch/TLBI runtime authority source-contract",
    summary:
      "S166, S165 production G8l authority kaynağını scheduler handoff sırasına bağlayan 16/16 allocation-free source-contract kapısını kapattı: exact scheduler owner/task ve yalnız CPU0→CPU1 hedefi, nonzero immutable context generation, ticket/prepare/context-switch fazlarında IRQ-masked + scheduler-mutation-frozen guard'ı, production TTBR0 ticket operandı, exact online mask 0b0011/ACK TLBI receipt'i ve old-mapping retirement→READY→context switch→target ERET zinciri tek faz sözleşmesinde bağlandı. TTBR0 kurulmadan TLBI veya TLBI/retirement/READY atlanarak context switch/ERET; wrong owner/target/generation/operand, stale/foreign, duplicate completion/retirement/ERET ve overflow yolları fail-closed kaldı. Hatalı ERET sonrası retry liveness, final owner CPU0→CPU1 ve user-progress 9→10 exact commit'i doğrulandı. Gerçek scheduler/context-switch assembly, IRQ/TLBI runtime ve hardware receipt wiring açılmadı.",
    evidence: [
      "g8l_runtime_contract: 16/16 PASS; S165 production authority ile scheduler owner, context generation, TTBR0, TLBI, retirement, context-switch ve ERET fazları exact bağlandı.",
      "Başarılı zincir: RUNNING0→TicketCaptured→SwitchPrepared→Ttbr0Installed→ShootdownComplete→MappingRetired→ReadyPublished→ContextSwitched→RUNNING1.",
      "IRQ maskesi ve scheduler mutation freeze olmadan ticket, prepare veya context-switch fazı ilerlemedi; wrong owner/target/context generation/TTBR0 operandı state değiştirmeden reddedildi.",
      "TTBR0 kurulmadan TLBI completion, exact online mask 0b0011/ACK olmadan authority ilerlemesi ve TLBI→old mapping retirement→READY sırası atlanarak context switch/ERET fail-closed kaldı.",
      "Exact read-back, target CPU, stale ticket, duplicate completion/retirement/ERET ve ticket-generation overflow sınırları state/ticket yayımından önce kapandı; hatalı ERET sonrası retry final owner CPU1 ve user-progress 9→10 üretti.",
      "Production board-rpi5 source check başarıyla tamamlandı; yalnız mevcut workspace warning'leri kaldı.",
      "Kalıcı kapsam: `docs/M8.1-RPi5-G8l-S166-Scheduler-TLBI-Runtime-Authority-Contract-Proof.md`.",
      "S166 fiziksel/device operasyonu yapmadı: physical/device operations=0 ve RUNBOOK_EXECUTED_IN_S166=NO.",
    ],
    commands: [
      "cargo test --quiet --test g8l_runtime_contract -- --test-threads=1",
      "cargo check -p aselsan_kernel --no-default-features --features board-rpi5 --target aarch64-unknown-none",
    ],
    terminalSessions: [
      {
        id: "s166-g8l-scheduler-tlbi-runtime-authority-contract",
        title: "G8l scheduler/TLBI runtime authority source-contract kapısı",
        commandLines: [
          "cargo test --quiet --test g8l_runtime_contract -- --test-threads=1",
        ],
        outputLines: [
          "running 16 tests",
          "test result: ok. 16 passed; 0 failed",
        ],
        exitCode: 0,
        outputMode: "selected",
      },
      {
        id: "s166-g8l-production-board-rpi5-check",
        title: "G8l S166 board-rpi5 production source check",
        commandLines: [
          "cargo check -p aselsan_kernel --no-default-features --features board-rpi5 --target aarch64-unknown-none",
        ],
        outputLines: ["Finished successfully; existing warnings only"],
        exitCode: 0,
        outputMode: "selected",
      },
    ],
    terminalSessionsNote:
      "S166 source-contract PASS'tir; test receipt'leri bounded validated inputs'tur. Gerçek scheduler/context-switch assembly, IRQ/TLBI instruction path, hardware-derived unforgeable authority, QEMU, fiziksel RPi ve generic SMP runtime sonucu değildir.",
    limitations: [
      "S165 authority contract ve G8j/G8k fiziksel önkoşul sınırları korunur; S166 fiziksel PASS üretmez.",
      "Runtime faz zinciri production source'a bağlanmıştır, ancak gerçek scheduler çağrısı, context-switch assembly ve IRQ/TLBI receipt wiring henüz çalıştırılmadı.",
      "ShootdownReceipt ve context/readback kayıtları bounded source-contract girdileridir; hardware-derived production-unforgeable receipt kanıtı değildir.",
      "QEMU, physical/device operations, CPU2/CPU3, hotplug, generic SMP arbitration ve soak kapsam dışıdır; RUNBOOK_EXECUTED_IN_S166=NO.",
    ],
  },