G8l: target-only final callsite source path

use crate::g8l_target_dispatch_callsite::G8lTargetDispatchCallsitePermit;
use crate::g8l_target_dispatch_preflight::G8lTargetDispatchPreflight;

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum G8lTargetDispatchFinalCallsitePhase {
    Ready,
    Executing,
    Executed,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum G8lTargetDispatchFinalCallsiteError {
    RuntimeInstanceMismatch,
    RuntimePhaseMismatch,
    ActiveTicketMismatch,
    ContextGenerationMismatch,
    RuntimeInputMismatch,
    PreflightMpidrMismatch,
    InvalidPhase,
    MissingPermit,
    WrongHardwareCpu,
    Architecture(G8lTargetAarch64DispatchError),
}

impl From<G8lTargetAarch64DispatchError> for G8lTargetDispatchFinalCallsiteError {
    fn from(error: G8lTargetAarch64DispatchError) -> Self {
        Self::Architecture(error)
    }
}

#[derive(Debug, PartialEq, Eq)]
pub struct G8lTargetDispatchFinalCallsite {
    runtime_instance_id: u64,
    ticket: MigrationTicket,
    context_generation: u64,
    permit: Option<G8lTargetDispatchCallsitePermit>,
    executed_route: Option<G8lTargetAarch64DispatchRoute>,
    wiring: Option<G8lIrqTlbiWiring>,
    receipt: Option<ArchInstructionReceipt>,
    phase: G8lTargetDispatchFinalCallsitePhase,
}

impl G8lTargetDispatchFinalCallsite {
    /// Consume the typed S175 preflight. No caller-supplied CPU or MPIDR value
    /// is accepted at this boundary; hardware identity is resolved only in
    /// the target-only execution method.
    pub fn from_preflight(
        runtime: &G8lRuntimeAuthority,
        preflight: G8lTargetDispatchPreflight,
    ) -> Result<Self, G8lTargetDispatchFinalCallsiteError> {
        if !preflight.mpidr_contract_validated()
            || preflight.mpidr_affinity() != crate::g8_contract::TARGET_MPIDR
            || preflight.logical_cpu() != CPU1
        {
            return Err(G8lTargetDispatchFinalCallsiteError::PreflightMpidrMismatch);
        }
        let permit = preflight.into_permit();
        let callsite = Self {
            runtime_instance_id: permit.runtime_instance_id(),
            ticket: permit.ticket(),
            context_generation: permit.context_generation(),
            permit: Some(permit),
            executed_route: None,
            wiring: None,
            receipt: None,
            phase: G8lTargetDispatchFinalCallsitePhase::Ready,
        };
        callsite.exact_runtime(runtime)?;
        Ok(callsite)
    }

    fn exact_runtime(
        &self,
        runtime: &G8lRuntimeAuthority,
    ) -> Result<(), G8lTargetDispatchFinalCallsiteError> {
        if self.runtime_instance_id == 0 || runtime.instance_id() != self.runtime_instance_id {
            return Err(G8lTargetDispatchFinalCallsiteError::RuntimeInstanceMismatch);
        }
        if runtime.phase() != RuntimePhase::Ttbr0Installed {
            return Err(G8lTargetDispatchFinalCallsiteError::RuntimePhaseMismatch);
        }
        if runtime.active_ticket() != Some(self.ticket) {
            return Err(G8lTargetDispatchFinalCallsiteError::ActiveTicketMismatch);
        }
        if runtime.context_generation() != self.context_generation {
            return Err(G8lTargetDispatchFinalCallsiteError::ContextGenerationMismatch);
        }
        let input = runtime.migration_input();
        if input.task_id != self.ticket.task_id
            || input.owner_cpu != CPU0
            || input.asid != self.ticket.asid
            || input.root != self.ticket.root
            || input.address_space_generation != self.ticket.address_space_generation
            || input.user_progress != self.ticket.user_progress_before
        {
            return Err(G8lTargetDispatchFinalCallsiteError::RuntimeInputMismatch);
        }
        Ok(())
    }

    /// Host-visible proof hook used by focused tests and by the target method.
    /// It returns no authority and performs no instruction.
    pub fn revalidate_ready_runtime(
        &self,
        runtime: &G8lRuntimeAuthority,
    ) -> Result<(), G8lTargetDispatchFinalCallsiteError> {
        if self.phase != G8lTargetDispatchFinalCallsitePhase::Ready {
            return Err(G8lTargetDispatchFinalCallsiteError::InvalidPhase);
        }
        self.exact_runtime(runtime)
    }

    /// Execute the retained S171 route on the real bare-metal CPU1 path.
    ///
    /// The phase is consumed before hardware identity resolution, so a wrong
    /// CPU or architecture error cannot leave a replayable Ready token.
    ///
    /// # Safety
    /// The caller must own the scheduler mutation boundary for `ticket` and
    /// ensure the retained TTBR0 root remains mapped and valid. S176 does not
    /// establish that global scheduler exclusion itself.
    #[cfg(all(target_arch = "aarch64", target_os = "none"))]
    pub unsafe fn execute_target_aarch64(
        &mut self,
        runtime: &G8lRuntimeAuthority,
    ) -> Result<ArchInstructionReceipt, G8lTargetDispatchFinalCallsiteError> {
        if self.phase != G8lTargetDispatchFinalCallsitePhase::Ready {
            return Err(G8lTargetDispatchFinalCallsiteError::InvalidPhase);
        }
        let _irq_guard = crate::arch::aarch64::IrqGuard::new();
        self.exact_runtime(runtime)?;
        self.phase = G8lTargetDispatchFinalCallsitePhase::Executing;
        if crate::percpu::try_current_cpu_id() != Some(CPU1) {
            return Err(G8lTargetDispatchFinalCallsiteError::WrongHardwareCpu);
        }
        let permit = self
            .permit
            .take()
            .ok_or(G8lTargetDispatchFinalCallsiteError::MissingPermit)?;
        let (mut route, wiring) = permit.into_sources();
        let receipt = unsafe { route.dispatch_target_aarch64()? };
        self.executed_route = Some(route);
        self.wiring = Some(wiring);
        self.receipt = Some(receipt);
        self.phase = G8lTargetDispatchFinalCallsitePhase::Executed;
        Ok(receipt)
    }

    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 phase(&self) -> G8lTargetDispatchFinalCallsitePhase {
        self.phase
    }

    pub const fn hardware_mpidr_read_wired(&self) -> bool {
        true
    }

    pub const fn local_irq_guard_wired(&self) -> bool {
        true
    }

    pub const fn target_instruction_path_wired(&self) -> bool {
        true
    }

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

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

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

    pub const fn executed_sources_retained(&self) -> bool {
        self.executed_route.is_some() && self.wiring.is_some() && self.receipt.is_some()
    }

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

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

#[test]
fn final_callsite_consumes_s175_without_another_caller_mpidr() {
    let (runtime, preflight) = final_preflight();
    let callsite = G8lTargetDispatchFinalCallsite::from_preflight(&runtime, preflight).unwrap();
    assert_eq!(callsite.runtime_instance_id(), runtime.instance_id());
    assert_eq!(callsite.context_generation(), CONTEXT_GENERATION);
    assert_eq!(callsite.phase(), G8lTargetDispatchFinalCallsitePhase::Ready);
    assert!(callsite.hardware_mpidr_read_wired());
    assert!(callsite.local_irq_guard_wired());
    assert!(callsite.target_instruction_path_wired());
    assert!(!callsite.hardware_execution_proven());
    assert!(!callsite.global_scheduler_exclusion_proven());
    assert!(!callsite.executed_sources_retained());
}

  {
    id: "g8l-s176-target-dispatch-final-callsite-partial",
    date: "2026-08-24",
    sequence: 176,
    status: "passed",
    umbrella_status: "partial",
    title: "G8l: target-only final callsite source path",
    summary:
      "S176, exact S175 preflight'i tüketip yeni caller CPU/MPIDR girdisi almayan target-only final çağrı yolunu 7/7 doğruladı. Canlı S166 runtime instance/Ttbr0Installed/active-ticket/context/migration-input zarfı inşa ve target sınırında yeniden doğrulanır; local IRQ guard altında production MPIDR_EL1 ile CPU1 çözülür ve mevcut S171 → S168 TTBR0/TLBI instruction yolu çağrılır. Yol AArch64 için derlendi fakat QEMU veya donanımda çalıştırılmadı.",
    evidence: [
      "g8l_target_dispatch_final_callsite: 7/7 PASS; exact S175 consumption, no new caller CPU/MPIDR input, construction/target-boundary runtime revalidation and foreign/stale-after-construction rejection.",
      "Target-only source path: IrqGuard → live runtime recheck → Ready→Executing consumption → percpu::try_current_cpu_id()/mrs mpidr_el1 CPU1 gate → S171 dispatch_target_aarch64() → S168 TTBR0/TLBI instruction seam.",
      "RPi5 AArch64 compile PASS. hardware_mpidr_read_wired=true ve target_instruction_path_wired=true; hardware_execution_proven=false, global_scheduler_exclusion_proven=false ve global_source_linearity_proven=false.",
      "Kalıcı kapsam: `docs/M8.1-RPi5-G8l-S176-Final-Target-Callsite-Proof.md`.",
      "S176 fiziksel/device operasyonu yapmadı: physical/device operations=0 ve RUNBOOK_EXECUTED_IN_S176=NO.",
    ],
    commands: [
      "cargo test --quiet --test g8l_target_dispatch_final_callsite -- --test-threads=1",
      "cargo check -p aselsan_kernel --no-default-features --features board-rpi5 --target aarch64-unknown-none",
    ],
    terminalSessions: [
      {
        id: "s176-g8l-final-target-dispatch-callsite",
        title: "G8l S176 target-only final callsite source path",
        commandLines: [
          "cargo test --quiet --test g8l_target_dispatch_final_callsite -- --test-threads=1",
        ],
        outputLines: ["running 7 tests", "test result: ok; 7 passed; 0 failed"],
        exitCode: 0,
        outputMode: "selected",
      },
    ],
    terminalSessionsNote:
      "S176 dar kaynak kabulü PASS'tir: target-only hardware MPIDR ve S171→S168 instruction yolu bağlı/AArch64-compile edilmiştir; yolun gerçekten çalıştırıldığı, cross-CPU scheduler exclusion ve production caller kanıtlanmış değildir.",
    limitations: [
      "S176 target-only MPIDR_EL1 ve TTBR0/TLBI yolunu bağlar/derler; QEMU veya fiziksel donanımda çalıştırmaz.",
      "Local IRQ masking, cross-CPU scheduler mutation exclusion kanıtı değildir.",
      "Underlying S171/S167 kayıtları Copy kaldığı için global source linearity kanıtı yoktur.",
      "Production scheduler caller, SGI/GIC delivery ve context-switch assembly callsite bağlı değildir.",
      "QEMU, fiziksel RPi, CPU2/CPU3, hotplug, soak ve generic SMP açık kalır.",
      "S176 fiziksel/device operasyonu yapmadı; RUNBOOK_EXECUTED_IN_S176=NO.",
    ],
  },