grafos_std/

grafos_worker_v0.rs

//! `grafos_worker_v0` — guest-facing WASM ABI for shared-memory tasklets.
//!
//! This module declares the import contract that a shared-memory tasklet
//! guest binary uses to talk to the worker runtime: worker identity, the
//! single tasklet-wide barrier, cancellation observation, and the linear
//! memory layout of the shared region and per-worker scratch.
//!
//! The Phase 48.3 P3 deliverable is the *SDK surface and ABI declaration
//! only* — the runtime that backs these symbols is implemented separately
//! (P1). On `wasm32` targets the externs link to host-provided imports.
//! On native targets a small mock backs them so unit tests can exercise
//! the SDK without a live runtime.
//!
//! See `docs/grafos-tasklet-abi-v1.md` for the normative spec.

#![allow(clippy::missing_safety_doc)]

// ---------------------------------------------------------------------------
// WASM ABI — real imports (only present when compiled to wasm32).
// ---------------------------------------------------------------------------

#[cfg(target_arch = "wasm32")]
#[link(wasm_import_module = "grafos_worker_v0")]
extern "C" {
    /// Returns this worker's lane index in `[0, fb_worker_count())`.
    pub fn fb_worker_index() -> i32;

    /// Returns the total number of workers participating in this tasklet.
    pub fn fb_worker_count() -> i32;

    /// Block until all workers have reached the implicit tasklet-wide barrier.
    ///
    /// Returns `0` on normal release, `-1` if the tasklet was cancelled while
    /// waiting (workers must observe and exit cooperatively).
    pub fn fb_barrier_wait() -> i32;

    /// Returns `1` if the tasklet has been cancelled (revoke / expiry /
    /// explicit cancel), `0` otherwise.
    pub fn fb_tasklet_cancelled() -> i32;

    /// Offset into linear memory of the shared region.
    pub fn fb_shared_ptr() -> i32;
    /// Length in bytes of the shared region.
    pub fn fb_shared_len() -> i32;

    /// Offset into linear memory of *this* worker's scratch region.
    pub fn fb_scratch_ptr() -> i32;
    /// Length in bytes of *this* worker's scratch region.
    pub fn fb_scratch_len() -> i32;

    /// Cooperatively reconcile fuel with the lease-wide shared fuel pool.
    ///
    /// Decrements the shared pool by `amount` and refills this Store's
    /// local fuel by `amount`. Returns 0 on success, -1 on pool exhaustion
    /// or programmer error (negative `amount`). Calling with `amount == 0`
    /// is a silent no-op returning 0.
    ///
    /// V2 (shared-pool) workers MUST call this at safe points within any
    /// compute loop that may consume more fuel than the initial precharge.
    /// On V1 (per-worker-slice) workers this hostcall is bound but always
    /// returns -1 — V1 modules should not import or call it.
    ///
    /// Phase 48.13: declared in W1; host runtime implementation lands in
    /// W2a (fabricbiosd shared-memory dispatcher, wasmtime Caller::set_fuel).
    pub fn fb_fuel_checkpoint(amount: i64) -> i32;
}

// ---------------------------------------------------------------------------
// Native shim — host-side mock used by SDK unit tests.
//
// This is NOT the runtime. It exists solely so `grafos-std` unit tests can
// instantiate `CoordinatorCtx` / `WorkerCtx` and verify that the SDK plumbing
// behaves correctly. P1 will provide the real wasmtime/wasmi-backed runtime.
// ---------------------------------------------------------------------------

#[cfg(all(feature = "std", not(target_arch = "wasm32")))]
pub use mock::*;

#[cfg(all(feature = "std", not(target_arch = "wasm32")))]
pub mod mock {
    //! Host-side mock for `grafos_worker_v0`.
    //!
    //! Backed by a thread-local `WorkerSlot`. Tests (or the SDK's
    //! `SharedTaskletBuilder` mock launch path) install a slot via
    //! [`with_worker_slot`] before calling any `fb_*` shim.

    extern crate alloc;
    use alloc::sync::Arc;
    use core::cell::RefCell;
    use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
    use std::sync::Barrier;

    /// State visible to a single worker lane (or the coordinator) inside the
    /// mock runtime.
    #[derive(Clone)]
    pub struct WorkerSlot {
        pub worker_index: i32,
        pub worker_count: i32,
        pub cancelled: Arc<AtomicBool>,
        /// Optional cross-thread barrier. `None` for single-threaded mock
        /// launches (where `barrier()` is a no-op).
        pub barrier: Option<Arc<Barrier>>,
        /// Offsets into a notional linear memory. The mock is intentionally
        /// faithful to the wasm contract: shared region first, then scratch
        /// regions in worker-index order.
        pub shared_ptr: i32,
        pub shared_len: i32,
        pub scratch_ptr: i32,
        pub scratch_len: i32,
        /// Phase 48.13 W2b — lease-wide shared fuel pool for V2
        /// shared-memory tasklets. `None` simulates a V1 worker (or any
        /// caller that hasn't installed a pool); the mock
        /// `fb_fuel_checkpoint` returns -1 in that case so V1 source
        /// observing the spec'd behavior fails closed.
        pub shared_fuel_pool: Option<Arc<AtomicU64>>,
    }

    impl Default for WorkerSlot {
        fn default() -> Self {
            Self {
                worker_index: 0,
                worker_count: 1,
                cancelled: Arc::new(AtomicBool::new(false)),
                barrier: None,
                shared_ptr: 0,
                shared_len: 0,
                scratch_ptr: 0,
                scratch_len: 0,
                shared_fuel_pool: None,
            }
        }
    }

    thread_local! {
        static SLOT: RefCell<Option<WorkerSlot>> = const { RefCell::new(None) };
    }

    /// Install `slot` for the duration of `f` (this thread only).
    pub fn with_worker_slot<R>(slot: WorkerSlot, f: impl FnOnce() -> R) -> R {
        let prev = SLOT.with(|s| s.borrow_mut().replace(slot));
        let out = f();
        SLOT.with(|s| *s.borrow_mut() = prev);
        out
    }

    fn slot<R>(f: impl FnOnce(&WorkerSlot) -> R) -> R {
        SLOT.with(|s| {
            let b = s.borrow();
            let slot = b
                .as_ref()
                .expect("grafos_worker_v0 mock: no WorkerSlot installed on this thread");
            f(slot)
        })
    }

    pub fn fb_worker_index() -> i32 {
        slot(|s| s.worker_index)
    }
    pub fn fb_worker_count() -> i32 {
        slot(|s| s.worker_count)
    }
    pub fn fb_tasklet_cancelled() -> i32 {
        slot(|s| {
            if s.cancelled.load(Ordering::SeqCst) {
                1
            } else {
                0
            }
        })
    }
    pub fn fb_barrier_wait() -> i32 {
        let (barrier, cancelled) = slot(|s| (s.barrier.clone(), s.cancelled.clone()));
        if cancelled.load(Ordering::SeqCst) {
            return -1;
        }
        if let Some(b) = barrier {
            b.wait();
        }
        if cancelled.load(Ordering::SeqCst) {
            -1
        } else {
            0
        }
    }
    pub fn fb_shared_ptr() -> i32 {
        slot(|s| s.shared_ptr)
    }
    pub fn fb_shared_len() -> i32 {
        slot(|s| s.shared_len)
    }
    pub fn fb_scratch_ptr() -> i32 {
        slot(|s| s.scratch_ptr)
    }
    pub fn fb_scratch_len() -> i32 {
        slot(|s| s.scratch_len)
    }

    /// Phase 48.13 W2b mock implementation of `fb_fuel_checkpoint`.
    ///
    /// Consults the per-thread [`WorkerSlot`]'s `shared_fuel_pool` and
    /// performs a CAS-loop decrement that mirrors the wasmtime runtime
    /// behavior in `fabricbiosd`'s shared-memory dispatcher. The mock does
    /// not actually consume host-side native fuel — it only tracks the
    /// logical pool state — but the success/failure semantics match the
    /// real runtime so SDK and program tests can exercise pool exhaustion
    /// deterministically.
    ///
    /// Returns:
    /// * `amount == 0` → `0` (silent no-op, matches spec)
    /// * `amount < 0`  → `-1` (programmer error, matches spec)
    /// * No pool installed (V1 worker simulation, or no slot) → `-1`
    /// * Pool exhausted (`pool < amount`) → `-1`
    /// * Successful debit → `0`
    pub fn fb_fuel_checkpoint(amount: i64) -> i32 {
        if amount == 0 {
            return 0;
        }
        if amount < 0 {
            return -1;
        }
        let amount = amount as u64;
        let pool = SLOT.with(|s| {
            s.borrow()
                .as_ref()
                .and_then(|slot| slot.shared_fuel_pool.clone())
        });
        let pool = match pool {
            Some(p) => p,
            None => return -1,
        };
        let mut current = pool.load(Ordering::SeqCst);
        loop {
            if current < amount {
                return -1;
            }
            match pool.compare_exchange_weak(
                current,
                current - amount,
                Ordering::SeqCst,
                Ordering::SeqCst,
            ) {
                Ok(_) => return 0,
                Err(observed) => current = observed,
            }
        }
    }

    /// Test helper: install a single-thread slot, run `f`, restore.
    pub fn mock_set_single_worker(worker_count: u16) {
        let slot = WorkerSlot {
            worker_index: 0,
            worker_count: worker_count as i32,
            ..WorkerSlot::default()
        };
        SLOT.with(|s| *s.borrow_mut() = Some(slot));
    }

    /// Test helper: clear any installed slot.
    pub fn mock_clear() {
        SLOT.with(|s| *s.borrow_mut() = None);
    }
}