G8l: target-dispatch handoff source boundary

use crate::g8l_runtime_contract::{G8lRuntimeAuthority, RuntimePhase, ONLINE_MASK};
use crate::g8l_target_aarch64_dispatch::G8lTargetAarch64DispatchRoute;

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum G8lTargetDispatchHandoffError {
    RuntimePhaseMismatch,
    RuntimeInstanceMismatch,
    ArchitecturePhaseMismatch,
    MissingArchitectureReceipt,
    WiringPhaseMismatch,
    MissingTlbiRequest,
    RequestMismatch,
    InvalidTargetCpu,
    WrongExecutionCpu,
}

#[derive(Debug, PartialEq, Eq)]
pub struct G8lTargetDispatchHandoff {
    runtime_instance_id: u64,
    ticket: MigrationTicket,
    context_generation: u64,
    architecture_receipt: ArchInstructionReceipt,
    request: TlbiRequest,
    target_route: G8lTargetAarch64DispatchRoute,
    wiring: G8lIrqTlbiWiring,
    live_cpu1_delivery_callsite_wired: bool,
}

impl G8lTargetDispatchHandoff {
    /// Bind S171 and S167 to the same active S166 runtime instance.
    pub fn from_sources(
        runtime: &G8lRuntimeAuthority,
        target_route: G8lTargetAarch64DispatchRoute,
        wiring: G8lIrqTlbiWiring,
    ) -> Result<Self, G8lTargetDispatchHandoffError> {
        if runtime.phase() != RuntimePhase::Ttbr0Installed {
            return Err(G8lTargetDispatchHandoffError::RuntimePhaseMismatch);
        }
        if target_route.architecture_phase() != ArchInstructionPhase::TlbiIssued {
            return Err(G8lTargetDispatchHandoffError::ArchitecturePhaseMismatch);
        }
        if target_route.runtime_instance_id() == 0
            || target_route.runtime_instance_id() != runtime.instance_id()
        {
            return Err(G8lTargetDispatchHandoffError::RuntimeInstanceMismatch);
        }
        if wiring.phase() != WiringPhase::TlbiRequested {
            return Err(G8lTargetDispatchHandoffError::WiringPhaseMismatch);
        }
        if wiring.runtime_instance_id() != runtime.instance_id() {
            return Err(G8lTargetDispatchHandoffError::RuntimeInstanceMismatch);
        }
        let architecture_receipt = target_route
            .source_receipt()
            .ok_or(G8lTargetDispatchHandoffError::MissingArchitectureReceipt)?;
        let request = wiring
            .request()
            .ok_or(G8lTargetDispatchHandoffError::MissingTlbiRequest)?;
        if request.source_cpu != CPU0
            || request.target_cpu != CPU1
            || request.receipt_channel != G8L_TLBI_RECEIPT_CHANNEL
            || request.online_mask != ONLINE_MASK
        {
            return Err(G8lTargetDispatchHandoffError::InvalidTargetCpu);
        }
        if request.context_generation != runtime.context_generation()
            || architecture_receipt.context_generation != runtime.context_generation()
            || target_route.ticket() != request.ticket
            || architecture_receipt.task_id != request.ticket.task_id
            || architecture_receipt.asid != request.ticket.asid
            || architecture_receipt.generation != request.ticket.generation
            || architecture_receipt.source_cpu != request.source_cpu
            || architecture_receipt.target_cpu != request.target_cpu
            || architecture_receipt.ttbr0_operand != request.ticket.ttbr0_operand
            || architecture_receipt.ttbr0_write_order != 1
            || architecture_receipt.tlbi_order != 2
            || !architecture_receipt.dsb_before_ttbr0
            || !architecture_receipt.dsb_after_tlbi
            || !architecture_receipt.isb_after_tlbi
            || runtime.active_ticket() != Some(request.ticket)
        {
            return Err(G8lTargetDispatchHandoffError::RequestMismatch);
        }
        Ok(Self {
            runtime_instance_id: runtime.instance_id(),
            ticket: request.ticket,
            context_generation: runtime.context_generation(),
            architecture_receipt,
            request,
            target_route,
            wiring,
            live_cpu1_delivery_callsite_wired: false,
        })
    }

    /// Admit the required execution identity without performing delivery.
    ///
    /// This is deliberately a source-only gate. A successful result means
    /// only that CPU1 is the required target for a future live callsite.
    pub fn validate_bounded_execution_cpu(
        &self,
        execution_cpu: usize,
    ) -> Result<(), G8lTargetDispatchHandoffError> {
        if execution_cpu != self.request.target_cpu || execution_cpu != CPU1 {
            return Err(G8lTargetDispatchHandoffError::WrongExecutionCpu);
        }
        Ok(())
    }

    /// Return the validated source authorities for a future live CPU1
    /// delivery callsite. This transfer does not itself execute or ACK them.
    pub fn into_sources(self) -> (G8lTargetAarch64DispatchRoute, G8lIrqTlbiWiring) {
        (self.target_route, self.wiring)
    }

    pub const fn bounded_execution_cpu_hardware_derived(&self) -> bool {
        false
    }

    pub const fn runtime_instance_id(&self) -> u64 {
        self.runtime_instance_id
    }

    pub const fn ticket(&self) -> MigrationTicket {
        self.ticket
    }

    pub const fn context_generation(&self) -> u64 {
        self.context_generation
    }

    pub const fn architecture_receipt(&self) -> ArchInstructionReceipt {
        self.architecture_receipt
    }

    pub const fn request(&self) -> TlbiRequest {
        self.request
    }

    pub const fn live_cpu1_delivery_callsite_wired(&self) -> bool {
        self.live_cpu1_delivery_callsite_wired
    }

    pub const fn gic_delivery_wired(&self) -> bool {
        false
    }

    pub const fn scheduler_runtime_wired(&self) -> bool {
        false
    }
}

#[test]
fn handoff_rejects_value_equal_foreign_runtime() {
    let (runtime, route, wiring) = sources();
    let (foreign, _, _) = sources();
    assert_ne!(runtime.instance_id(), foreign.instance_id());
    assert_eq!(
        G8lTargetDispatchHandoff::from_sources(&foreign, route, wiring),
        Err(G8lTargetDispatchHandoffError::RuntimeInstanceMismatch)
    );
}

  {
    id: "g8l-s172-target-dispatch-handoff-partial",
    date: "2026-08-24",
    sequence: 172,
    status: "passed",
    umbrella_status: "partial",
    title: "G8l: target-dispatch handoff source boundary",
    summary:
      "S172, S171 target-only dispatch route ile S167 TlbiRequested wiring authority'sini aynı aktif nonzero S166 runtime-instance üzerinde birleştirdi ve ikisini gelecek callsite için handoff içinde korudu. S168 TlbiIssued architecture receipt'in exact full ticket, task/ASID/generation/context/source/target/TTBR0, instruction order ve barrier alanları request ile yeniden eşleştirilir. Caller-provided CPU1 değeri yalnız bounded girdidir, hardware-derived değildir; CPU0 ve value-equal foreign runtime fail-closed reddedilir. Live CPU1 delivery callsite, GIC/SGI, scheduler ownership, target assembly, QEMU ve fiziksel runtime açılmadı.",
    evidence: [
      "g8l_target_dispatch_handoff: 4/4 PASS; exact S171 route + S167 request + S166 runtime binding, CPU0 reject, foreign-runtime reject and source audit.",
      "Architecture phase TlbiIssued ve wiring phase TlbiRequested zorunlu; exact full ticket ile architecture receipt/request zarfı task, ASID, generation, context generation, CPU, TTBR0 operand, order ve barrier alanlarında yeniden doğrulanıyor.",
      "Validated S171 route ve S167 wiring `into_sources` için kayıpsız korunuyor; bounded CPU1 validation hardware-derived değildir. live_cpu1_delivery_callsite_wired, GIC delivery ve scheduler runtime false kalıyor.",
      "Kalıcı kapsam: `docs/M8.1-RPi5-G8l-S172-Target-Dispatch-Handoff-Proof.md`.",
      "S172 fiziksel/device operasyonu yapmadı: physical/device operations=0 ve RUNBOOK_EXECUTED_IN_S172=NO.",
    ],
    commands: [
      "cargo test --quiet --test g8l_target_dispatch_handoff -- --test-threads=1",
      "cargo check -p aselsan_kernel --no-default-features --features board-rpi5 --target aarch64-unknown-none",
    ],
    terminalSessions: [
      {
        id: "s172-g8l-target-dispatch-handoff",
        title: "G8l S172 target-dispatch handoff source boundary",
        commandLines: [
          "cargo test --quiet --test g8l_target_dispatch_handoff -- --test-threads=1",
        ],
        outputLines: ["running 4 tests", "test result: ok; 4 passed; 0 failed"],
        exitCode: 0,
        outputMode: "selected",
      },
    ],
    terminalSessionsNote:
      "S172 source handoff PASS'tir; source authority'leri korur fakat bounded CPU girdisi live CPU1 delivery, GIC/SGI veya scheduler-owned migration runtime kanıtı değildir.",
    limitations: [
      "S172 host'ta target-only unsafe AArch64 instruction veya live CPU1 delivery callsite çalıştırmaz.",
      "Caller-provided CPU1 yalnız bounded validation girdisidir; production execution kimliği S171 içindeki MPIDR guard ile doğrulanmalıdır.",
      "Handoff SGI/GIC'e dokunmaz, scheduler ownership/context-switch assembly mutasyonu yapmaz.",
      "S172 fiziksel/device operasyonu yapmadı; RUNBOOK_EXECUTED_IN_S172=NO.",
    ],
  },