Module host_mock 

Shared-memory tasklet SDK surface — host mock (Phase 48.3 P3, Phase 48.14).

This module exposes the programmer-facing types for the shared-memory tasklet execution mode: a builder, a coordinator context, a worker context, typed views over the shared region and per-worker scratch, and partition helpers.

Source portability (Phase 48.14)

The host mock and the wasm32 guest ([super::guest]) deliberately do NOT present a single source-portable surface. They present three levels of parity, documented in detail in docs/grafos/shared-memory-tasklet-programming-model.md:

1. Behavioral portability is the primary promise. The fidelity test shared_memory_host_wasm_fidelity_e2e guarantees that the same logical workload produces byte-identical output on both targets.
2. Source portability is a narrower documented subset. Methods on the safe-list compile and behave identically on both targets. The cfg-list and behavior-divergent sub-list do NOT.
3. #[cfg] is the honest tool outside that subset. Methods tagged with **Target-specific.** below require per-target source when used portably.

Methods carrying the **Target-specific.** rustdoc tag are on the cfg-list. Methods carrying **Behavior diverges across targets.** compile on both targets but mean different things (see CoordinatorCtx::barrier and WorkerCtx::barrier).

Coordinator-lane programming model

Phase 48.3 — the host mock implements the same coordinator-lane model as the wasm32 guest path in [super::guest]: worker 0 is the coordinator lane and runs only the coordinator closure; CoordinatorCtx::parallel_for_workers spawns the worker body on data worker lanes 1..worker_count() (skipping worker 0). Source compiled for either target produces identical observable behavior under the SharedMemory execution mode, so a programmer can prototype against the host mock and deploy unchanged on a real fabricBIOS runtime. The data_worker_index() / data_worker_count() / data_scratch(i) helpers expose the data-plane lane space for partitioning, while the raw worker_index() / worker_count() / scratch(i) accessors keep “raw wasm worker space” semantics for advanced cases.

What this is

• The types developers will use to write a shared-memory tasklet.
• A host-mock launch path so the SDK is unit-testable without a runtime.
• The companion ABI declaration lives in crate::grafos_worker_v0.

What this is NOT

• This is not the runtime. The wasmtime/wasmi-backed runtime that actually executes shared-memory tasklets is delivered as part of the P1 track. Here, launch() runs the coordinator and worker closures directly on the host using a std::thread::scope plus a real std::sync::Barrier, purely so the SDK abstractions can be exercised in unit tests.
• The programmer-facing API never mentions wasmi, wasmtime, or “threads”. The abstraction is coordinator + workers with explicit shared and per-worker state.

Programming model

use grafos_std::cpu::{CpuBuilder, CoordinatorCtx, WorkerCtx};
use std::sync::atomic::{AtomicU32, Ordering};

#[derive(Default)]
struct Shared {
    counter: AtomicU32,
}
#[derive(Default, Clone)]
struct Scratch {
    local: u32,
}

let lease = CpuBuilder::new().cores(4).acquire().unwrap();
let _ = lease.cpu().shared_memory_tasklet::<Shared, Scratch>()
    .cores(4)
    .workers(4)
    .shared_bytes(1024)
    .scratch_bytes_per_worker(64)
    .fuel(1_000_000)
    .launch(|coord: &mut CoordinatorCtx<Shared, Scratch>| {
        // Coordinator: load input, orchestrate phases, emit output.
        coord.parallel_for_workers(|w| {
            w.scratch_mut().local = w.worker_index() as u32;
            w.shared().counter.fetch_add(1, Ordering::SeqCst);
        }).unwrap();
        let n = coord.shared().counter.load(Ordering::SeqCst);
        coord.set_output(&n.to_le_bytes());
        Ok(())
    });

Structs

Cancelled

Returned by WorkerCtx::barrier / CoordinatorCtx::barrier when the tasklet is cancelled while waiting on the barrier.

CoordinatorCtx

Programmer-facing coordinator context.

FuelExhausted

Returned by WorkerCtx::fuel_checkpoint / CoordinatorCtx::fuel_checkpoint when the lease-wide shared fuel pool is exhausted (or, defensively, when called by a V1 worker that has no shared pool installed).

SharedRegion

Typed wrapper over the shared region of a tasklet.

SharedTaskletBuilder

Builder for a shared-memory tasklet.

SharedTaskletResult

Result of a completed shared-memory tasklet.

WorkerCtx

Programmer-facing worker context.

WorkerScratch

Typed wrapper over a single worker’s scratch region.

Enums

TaskletError

Errors produced by the shared-memory tasklet SDK surface.