odem-rs-core 0.3.0

//! Provides [`Job`], a lightweight, cooperatively scheduled unit of execution
//! within the simulation framework.
//!
//! # Overview
//!
//! Jobs represent asynchronous tasks that can be dynamically created and
//! managed within the context of a simulation [`Agent`].
//! They are the primary means of expressing concurrent activities that share
//! state within a single agent's execution context.
//!
//! Unlike isolated [`Agent`]s, `Job`s are designed to easily interact with
//! variables in their lexical creation scope and with other jobs spawned by the
//! same agent, facilitating complex, stateful interactions within that agent's
//! boundary.
//!
//! # Key Concepts
//!
//! * **Unit of Execution:** A `Job` wraps a user-provided [`Future`],
//!   representing a sequence of asynchronous operations.
//! * **State Sharing:** Jobs created within the same agent share the same
//!   context, allowing access to the agent's state and simulation primitives
//!   (`Sim`). They can also directly capture and use variables from their
//!   creation environment (subject to lifetime constraints).
//! * **Cooperative Scheduling:** Jobs yield control back to the simulator
//!   scheduler via `.await` points (e.g., `sim.advance().await`). The scheduler
//!   manages the resumption of jobs based on model time, agent rank, and job
//!   precedence.
//! * **Return Values:** While the underlying [`Continuation`] mechanism only
//!   tracks success/failure, `Job` captures the actual `Output` of its future.
//!   This value can be retrieved by the creator using the [`Puck`] handle
//!   (e.g., by `.await`ing the `Puck`).
//! * **Finalization:** The [`Settle`] trait determines how a job's raw `Output`
//!   is translated into an [`ExitStatus`] (success/failure) for the underlying
//!   continuation mechanism. [`Unchecked`] treats all outcomes as success,
//!   while [`Checked`] interprets `Result`, `Option`, and `bool` meaningfully.
//! * **Lifecycle:** Jobs are created (using [`Job::new`] or
//!   [`Job::build`]), activated via [`Sim::activate`], and run until
//!   completion. They can be awaited using their [`Puck`] or prematurely
//!   terminated via [`Job::abort`] or [`Puck::abort`].
//! * **Branding:** A lifetime parameter is used internally with token witnesses
//!   to prevent accidental misuse of tokens obtained from one job instance with
//!   another. For most user interactions, this can be ignored.
//!
//! # Relationship to Agents and Continuations
//!
//! - **Agent:** An [`Agent`] is an *isolated* execution context. A `Job` runs
//!   *within* an Agent's context. An Agent acts as the root of a tree of Jobs.
//! - **Continuation:** A [`Continuation`] is the core, low-level scheduling
//!   primitive. A `Job` builds upon a `Continuation` by adding a concrete
//!   future, return value handling, and state-sharing capabilities.
//!
//! # Examples
//!
//! Creating and running a simple job that accesses a local variable:
//!
//! ```
//! # use odem_rs_core::{simulator::Sim, job::Job};
//! # use core::pin::pin;
//! async fn sim_main(sim: &Sim) {
//!     // Variable in the scope where the job is created
//!     let message = "Hello from Job!".to_string();
//!     let repeat_count = 3;
//!
//!     // Create a job (as an async block) that captures `message` and `repeat_count`
//!     let my_job = pin!(Job::new(async {
//!         println!("Job starting...");
//!         for i in 0..repeat_count {
//!             // Access captured variable
//!             println!("{}: {}", i, message);
//!             // Interact with the simulation
//!             sim.advance(1.0).await;
//!         }
//!         println!("Job finished!");
//!         // Return a value
//!         repeat_count * 10 // Job output is i32
//!     }));
//!
//!     // Activate the job using the simulation context
//!     let job_handle = sim.activate(my_job);
//!
//!     // Optionally, await the job's completion and get its return value
//!     let result: i32 = job_handle.await;
//!     assert_eq!(result, 30);
//!     println!("Job returned: {}", result);
//!
//!     // Ensure simulation runs long enough if not awaiting
//!     // sim.advance(4.0).await;
//! }
//! ```
//!
//! [`Agent`]: crate::agent::Agent

use crate::{
	Active, Dispatch, ExitStatus,
	config::Config,
	continuation::{Continuation, Label, Puck as ContPuck, Share, erased::State, token},
	error,
	fsm::*,
	ptr::{AsIrc, IntrusivelyCounted, Irc, IrcBox, IrcBoxed, Lease, LeasedMut},
	simulator::{Prec, Sim},
};

use core::{
	any::Any,
	cell::{RefCell, RefMut},
	fmt,
	future::{Future, IntoFuture, Pending},
	marker::PhantomData,
	panic::Location,
	pin::Pin,
	task::{Context, Poll},
};

/* ******************************************************************** Job */

/// A cooperatively scheduled, lightweight execution unit (job) within a
/// simulation [`Agent`].
///
/// `Job` combines a [`Future`] (representing the job's logic) with a
/// [`Continuation`] (providing the scheduling context). It allows asynchronous
/// tasks to run within the simulation, share state with their parent [`Agent`]
/// and sibling jobs, and capture variables from their lexical scope.
///
/// Unlike the base [`Continuation`] which only tracks success/failure, `Job`
/// captures the actual `Output` of its future `F`. This output can be retrieved
/// upon completion via the [`Puck`] handle. The interpretation of completion
/// (success vs. failure) for scheduling purposes is controlled by the
/// [`Settle`] strategy `S`.
///
/// Jobs must be pinned before activation. They are typically created using
/// [`Job::new`] or [`Job::build`].
///
/// # Type Parameters
///
/// * `C`: The simulation configuration type ([`Config`]).
/// * `F`: The [`Future`] type defining the job's asynchronous logic.
/// * `S`: The [`Settle`] strategy (default: [`Unchecked`]) determining how
///   `F::Output` translates to an [`ExitStatus`].
///
/// # Examples
///
/// ```
/// # use odem_rs_core::{simulator::Sim, job::Job};
/// # use core::pin::pin;
/// async fn sim_main(sim: &Sim) {
///     let local_data = 10;
///
///     // Create a job using an async block, capturing `local_data`
///     let job = pin!(Job::new(async move {
///         println!("Job started with data: {}", local_data);
///         sim.advance(5.0).await;
///         println!("Job finishing.");
///         local_data * 2 // The job returns an i32
///     }));
///
///     // Activate and await the result
///     let result: i32 = sim.activate(job).await;
///     assert_eq!(result, 20);
/// }
/// ```
///
/// [`Agent`]: crate::agent::Agent
pub type Job<C, F, S = Unchecked> = BrandedJob<'static, C, F, S>;

/// Branded version of the user-facing [`Job`] type.
///
/// This is the type underlying the `Job` type-alias and exposes branding
/// methods to safely manipulate the state of the underlying [`Continuation`].
#[pin_project::pin_project(PinnedDrop, !Unpin)]
pub struct BrandedJob<'brand, C: ?Sized + Config, F: Future, S> {
	/// The underlying continuation providing the scheduling context and state.
	#[pin]
	cont: Continuation<'brand, C>,
	/// Internal state holding either the pending future or the final result.
	#[pin]
	state: RefCell<Inner<F, S>>,
}

impl<C: ?Sized + Config, F: Future> Job<C, F> {
	/// Creates a new `Job` wrapping the given asynchronous action.
	///
	/// The `actions` argument can be any type that implements `IntoFuture`,
	/// typically an `async` block or function.
	///
	/// Uses the default [`Unchecked`] settle strategy and default precedence.
	/// For more configuration options, use [`Job::build`].
	///
	/// Returns a [`Lease`], which must be pinned before activation.
	#[track_caller]
	pub fn new<'p, A>(actions: A) -> Lease<'p, Self>
	where
		A: IntoFuture<IntoFuture = F>,
	{
		Job::build().with_actions(actions).finish()
	}
}

impl Job<(), Pending<()>> {
	/// Creates a [`Builder`] for constructing `Job` instances with custom
	/// configurations.
	///
	/// Use the builder to set options like a custom [`Settle`] strategy,
	/// initial scheduling [precedence], and explicit source code [`Location`].
	///
	/// [precedence]: Prec
	pub const fn build() -> Builder {
		Builder::new()
	}
}

impl<C: ?Sized + Config, F: Future, S: Settle<F::Output>> Job<C, F, S> {
	/// Used during startup of a simulation run to initialize the root job.
	pub(crate) fn boot<'p>(
		this: Pin<LeasedMut<'p, Self>>,
		share: Pin<&'p Share<C>>,
	) -> Puck<'p, C, F, S> {
		// create a reference-counted type
		let mut this = Irc::new(this);

		// set the most-specialized vptr for the continuation
		unsafe {
			let vptr = Irc::into_raw(this);
			this = Irc::from_raw(vptr);
			this.cont.set_vptr(vptr);
		}

		this.get_pin_mut().unwrap().brand(move |job, once| {
			let born = job.token(once).into_born().unwrap();

			// bind the shared agent data to it
			unsafe { job.bind(born, share.get_ref()) };
		});

		// initialize the pinned job reference
		Puck(this, PhantomData)
	}
}

impl<'brand, C: ?Sized + Config, F: Future, S> BrandedJob<'brand, C, F, S> {
	/// Sets the scheduling precedence for this job.
	/// Higher precedence jobs run before lower precedence jobs at the same
	/// simulation time.
	pub fn set_prec(&self, prec: Prec) {
		self.cont.set_prec(prec);
	}

	/// Returns the current execution state of the job's underlying
	/// continuation.
	pub fn state(&self) -> State {
		self.cont.state().borrow().erased()
	}

	/// Attempts to retrieve the job's return value if it has completed
	/// successfully.
	///
	/// Returns `Ok(value)` if the job is finished and the value hasn't been
	/// taken. Returns `Err(NotDone)` if the job is still running, was aborted,
	/// panicked, or the value was already retrieved.
	pub fn result(&self) -> Result<F::Output, error::NotDone> {
		self.brand(|job, once| Ok(job.inner_result(job.token(once).into_done()?).1))
	}

	/// Aborts the execution of this job immediately.
	///
	/// - Removes the job from the event calendar or `active` slot.
	/// - Drops the internal future, releasing its resources.
	/// - Sets the job's `ExitStatus` to `Failure`.
	/// - The job's return value (if any) is discarded.
	///
	/// This operation is idempotent; aborting an already aborted or completed
	/// job has no effect.
	pub fn abort(self: Pin<&Self>) {
		self.brand(|job, once| {
			job.inner_abort(job.token(once));
		});
	}

	/// Special abort method for use in drop implementations.
	///
	/// Does everything [`Self::abort`] does, but clears the vtable pointer
	/// before aborting in order to prevent `reclaim` from running.
	pub(crate) fn abort_on_drop(self: Pin<&Self>) {
		// Clear the vtable pointer *before* aborting. This prevents `reclaim`
		// (part of Continuation drop) from being called if `abort` causes the
		// ref-count to hit zero, as accessing `self` during `reclaim` after
		// starting the drop would be undefined due to the active mut reference.
		self.cont.clear_vptr();

		// Now we can abort.
		self.abort();
	}

	/// Returns the current state of the job as a lifetime-branded token.
	///
	/// Tokens ([`token::State`]) are used to prove the job's state at a
	/// specific moment, enabling safe state transitions and operations.
	/// Requires an [`Ephemeral`] token tied to the job's `'brand`.
	pub fn token(&self, once: Ephemeral<'brand>) -> token::State<'brand> {
		self.cont.token(once)
	}

	/// Returns an exclusive reference to the job's finalizer if the job is in
	/// the `Born` state (i.e., before activation).
	///
	/// Requires a [`token::Born`] to prove the job's state. Allows modifying
	/// the `Settle` strategy before the job starts running.
	pub fn finalizer(self: Pin<&mut Self>, born: &token::Born<'brand>) -> &mut S {
		let _ = born; // Ensure the Born token is provided

		match self.inner_state_mut().project() {
			InnerProject::Pending(_, settle) => settle,

			// SAFETY: We are `Pending` due to being in the Born state.
			// Mutable access is safe before activation.
			// We need to pin the mutable reference to the finalizer S.
			_ => unsafe { core::hint::unreachable_unchecked() },
		}
	}

	/// Core logic for aborting the job based on its current state token.
	fn inner_abort(self: Pin<&Self>, state: token::State<'brand>) -> token::Gone<'brand> {
		use scopeguard::{ScopeGuard, guard};
		use token::State::*;

		// Handle abort based on the current state proved by the token.
		match state {
			// Already aborted/finished, return Gone token.
			Gone(gone) => return gone,
			// Finished, drop result, return Gone.
			Done(done) => return self.inner_result(done).0,
			// Need to drop the future before transitioning.
			_ => {}
		};

		// Perform the actual transition into the `Gone` state.
		let to_gone = |state: token::State<'brand>| -> token::Gone<'brand> {
			let sm = self.cont.state();
			let rc = Err(crate::Failure);

			let gone = match state {
				// Nothing to do, other than transition for `Born` and `Idle`.
				Born(born) => sm.transition(born, rc),
				Idle(idle) => sm.transition(idle, rc),

				// Scheduled, remove from calendar.
				Next(next) => sm.transition(self.cont.deschedule(next), rc),
				// Currently running, deactivate.
				Busy(busy) => sm.transition(self.cont.deactivate(busy), rc),

				// This is not reachable due to the logic above.
				_ => unsafe { core::hint::unreachable_unchecked() },
			};

			// Wake up any other continuations that might have been waiting.
			self.cont.wake_pending();
			gone
		};

		// Secure the transition to `Gone(Failure)` using a scope guard.
		let guard = guard(state, |state| {
			to_gone(state);
		});

		// Enter the job's tracing span if tracing is enabled.
		let _span = self.cont.enter_span();

		// Drop the future payload; this may panic, invoking the scope guard.
		// User `drop` impls cannot be used to transition, since the current
		// state is frozen by this scope.
		self.inner_state().as_mut().abort();

		// Perform the transition on the happy path and return the `Gone` token.
		to_gone(ScopeGuard::into_inner(guard))
	}

	/// Core logic for extracting the result after completion.
	/// Returns the `Gone` token and the `Output`.
	fn inner_result(&self, done: token::Done<'brand>) -> (token::Gone<'brand>, F::Output) {
		let task = &self.cont;
		// Get the ExitStatus determined by the Settle strategy.
		let exit_status = task.branded_result(&done);

		// Extract the result.
		let output = self
			.state
			.borrow_mut()
			.result()
			.expect("Job::result: Result missing in Done state");

		// Enter the job's tracing span.
		let _span = task.enter_span();

		// Transition the Continuation state to Gone(exit_status).
		let gone = task.state().transition(done, exit_status);

		// Wake pending continuations now that this one is truly gone.
		task.wake_pending();

		(gone, output)
	}

	/// Performs a pin projection from the pinned job to a pinned `RefMut`
	/// of the inner state.
	///
	/// This realizes structural pinning of a `RefCell`, which is otherwise
	/// not possible.
	fn inner_state(self: Pin<&Self>) -> Pin<RefMut<'_, Inner<F, S>>> {
		unsafe { Pin::new_unchecked(self.get_ref().state.borrow_mut()) }
	}

	/// Performs a pin projection from a mutably pinned job to a mutably
	/// pinned reference of the inner state.
	fn inner_state_mut(self: Pin<&mut Self>) -> Pin<&mut Inner<F, S>> {
		unsafe { self.map_unchecked_mut(|job| job.state.get_mut()) }
	}

	/// Binds the shared agent context (`Share`) to a `Born` job.
	/// Transitions the job from `Born` to `Idle`.
	///
	/// # Safety
	/// Caller must ensure the `share` reference outlives the job's execution.
	/// This is typically guaranteed by the agent activation logic.
	pub(crate) unsafe fn bind(
		self: Pin<&mut Self>,
		born: token::Born<'brand>,
		share: &Share<C>,
	) -> token::Idle<'brand> {
		unsafe { self.project().cont.bind(born, share) }
	}
}

impl<'b, C, F, S> Stateful for BrandedJob<'b, C, F, S>
where
	C: ?Sized + Config,
	F: Future,
{
	type Brand = &'b ();

	unsafe fn enter(&self) {
		unsafe {
			self.cont.enter();
		}
	}

	unsafe fn leave(&self) {
		unsafe {
			self.cont.leave();
		}
	}
}

impl<'b, C, F, S> Rebrand<'b> for BrandedJob<'b, C, F, S>
where
	C: ?Sized + Config,
	F: Future,
{
	type Kind<'a> = BrandedJob<'a, C, F, S>;
}

impl<C, F, S> fmt::Debug for BrandedJob<'_, C, F, S>
where
	C: ?Sized + Config,
	F: Future,
{
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		use core::any::type_name;
		f.debug_struct("Job")
			.field("cont", &self.cont)
			.field("future_type", &type_name::<F>())
			.field("settle_type", &type_name::<S>())
			.finish()
	}
}

impl<C, F, S> Dispatch for BrandedJob<'_, C, F, S>
where
	C: ?Sized + Config,
	F: Future,
	S: Settle<F::Output>,
{
	fn poll(self: Pin<&Self>, cx: &mut Context<'_>) -> Poll<ExitStatus> {
		// Borrow the internal state.
		let mut inner = self.inner_state();

		// Poll the inner future.
		inner
			.as_mut()
			.poll(cx)
			.map(|value| inner.as_mut().ready(value))
	}
}

impl<C, F, S> Active<C> for Job<C, F, S>
where
	C: ?Sized + Config,
	F: Future,
	S: Settle<F::Output>,
{
	type Output = F::Output;
	type Puck<'p>
		= Puck<'p, C, F, S>
	where
		Self: 'p;

	/// Activates a `Born` job by binding it to a simulation context.
	///
	/// This is called by [`Sim::activate`]. It wraps the job in an `Irc`, sets
	/// up the vtable pointer for dispatch, binds the shared context, and
	/// returns a [`Puck`].
	fn bind<'p>(this: Pin<LeasedMut<'p, Self>>, sctx: &'p Share<C>) -> Self::Puck<'p> {
		// Wrap the leased mutable reference in an Irc.
		let mut irc = Irc::new(this);

		// Set the vtable pointer in the Continuation part for dispatch.
		// SAFETY: Similar to Job::boot, setting up the Irc dispatch mechanism.
		unsafe {
			let vptr = Irc::into_raw(irc);
			irc = Irc::from_raw(vptr);
			irc.cont.set_vptr(vptr);
		}

		// Use branding to safely transition state and bind the context.
		irc.get_pin_mut().unwrap().brand(move |mut job, once| {
			// Get a 'Born' token, proving the job is in the initial state.
			let born_token = job
				.token(once)
				.into_born()
				.expect("Job::bind called on non-Born job");

			// Bind the provided shared context of the active agent.
			// SAFETY: `Sim::activate` ensures `sctx` outlives the activated job
			// `this`. Lifetime 'p connects `this` and `sctx`.
			unsafe {
				job.as_mut().bind(born_token, sctx);
			}
			// Job is now Idle.
		});

		// Return the Puck handle, containing the Irc and PhantomData for
		// lifetime 'p.
		Puck(irc, PhantomData)
	}
}

// SAFETY: the `IrcBox`-method points to an inner `IrcBox`.
unsafe impl<C, F, S> IntrusivelyCounted for BrandedJob<'_, C, F, S>
where
	C: ?Sized + Config,
	F: Future,
{
	fn irc_box(&self) -> &IrcBox<dyn IrcBoxed> {
		self.cont.irc_box()
	}
}

impl<'brand, C, F, S> AsRef<Continuation<'brand, C>> for BrandedJob<'brand, C, F, S>
where
	C: ?Sized + Config,
	F: Future,
{
	fn as_ref(&self) -> &Continuation<'brand, C> {
		&self.cont
	}
}

#[pin_project::pinned_drop]
impl<C: ?Sized + Config, F: Future, T> PinnedDrop for BrandedJob<'_, C, F, T> {
	fn drop(self: Pin<&mut Self>) {
		// Abort the job's execution cleanly (removes from schedule, drops future).
		self.into_ref().abort_on_drop();
	}
}

/* ********************************************************************* Puck */

/// An owned handle to an activated [`Job`], providing interaction capabilities.
///
/// A `Puck` represents an active instance of a `Job` within the simulation. It
/// holds an intrusive reference to the `Job`.
///
/// `Puck` allows you to:
/// - Await the job's completion and retrieve its `Output`.
/// - Check the job's state ([`Puck::state`]).
/// - Access shared context information ([`Puck::share`], [`Puck::sim`], etc.).
/// - Abort the job prematurely ([`Puck::abort`]).
///
/// The `'p` lifetime ensures the `Puck` doesn't outlive the job bound to during
/// activation. `PhantomDrop` ensures correct diagnostics related to temporary
/// lifetimes during activation.
///
/// [`Puck::state`]: crate::Puck::state
/// [`Puck::sim`]: crate::Puck::sim
pub struct Puck<'p, C: ?Sized + Config, F: Future, S = Unchecked>(
	/// Intrusive reference counter holding the Job instance.
	Irc<Job<C, F, S>>,
	/// Signals to the borrow checker that the Puck may not outlive the Job
	/// that spawned it.
	PhantomDrop<Pin<&'p mut Job<C, F, S>>>,
);

impl<C: ?Sized + Config, F: Future, S> Puck<'_, C, F, S> {
	/// Returns a reference to the [`Share`]d context associated with this job's
	/// agent.
	///
	/// Provides access to the agent's state, simulation context, label, rank,
	/// etc.
	pub fn share(&self) -> &Share<C> {
		self.0
			.cont
			.share()
			.expect("Puck::share called on unbound Job")
	}

	/// Aborts the referenced job prematurely.
	///
	/// Consumes the `Puck` to prevent further interaction (like awaiting the
	/// result) after aborting. See [`Job::abort`] for details on the abort
	/// process.
	pub fn abort(self) {
		self.0.get_pin().abort();
	}
}

impl<C, F, S> fmt::Debug for Puck<'_, C, F, S>
where
	C: ?Sized + Config,
	F: Future,
{
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		f.debug_tuple("Puck").field(&self.0).finish()
	}
}

impl<C, F, S> IntoFuture for Puck<'_, C, F, S>
where
	C: ?Sized + Config,
	F: Future,
{
	type Output = F::Output;
	type IntoFuture = crate::ops::Join<C, Self>;

	#[inline]
	fn into_future(self) -> Self::IntoFuture {
		crate::ops::join(self)
	}
}

impl<C, F, S> crate::Puck<C> for Puck<'_, C, F, S>
where
	C: ?Sized + Config,
	F: Future,
{
	fn result(&mut self) -> Option<Self::Output> {
		self.0.result().ok()
	}

	fn subject(&self) -> &dyn Any {
		self.share().subject()
	}

	fn sim(&self) -> &Sim<C> {
		self.share().sim()
	}

	fn label(&self) -> Label {
		self.share().label()
	}

	fn time(&self) -> Option<C::Time> {
		self.0.cont.time()
	}

	fn rank(&self) -> C::Rank {
		self.share().rank()
	}

	fn prec(&self) -> Prec {
		self.0.cont.prec()
	}

	fn state(&self) -> State {
		self.0.cont.state().borrow().erased()
	}

	fn location(&self) -> &'static Location<'static> {
		self.0.cont.location()
	}

	fn puck(&self) -> ContPuck<C> {
		ContPuck::checked(self.as_irc()).expect("Puck::puck called on unbound Job")
	}
}

impl<C, F, S> From<Puck<'_, C, F, S>> for Irc<Job<C, F, S>>
where
	C: ?Sized + Config,
	F: Future,
{
	fn from(value: Puck<'_, C, F, S>) -> Self {
		value.0
	}
}

impl<C, F, S> AsRef<Continuation<'static, C>> for Puck<'_, C, F, S>
where
	C: ?Sized + Config,
	F: Future,
{
	fn as_ref(&self) -> &Continuation<'static, C> {
		&self.0.cont
	}
}

impl<C, F, S> AsIrc<Continuation<'static, C>> for Puck<'_, C, F, S>
where
	C: ?Sized + Config,
	F: Future,
{
	fn as_irc(&self) -> Irc<Continuation<'static, C>> {
		Irc::map(self.0.clone(), |inner| &inner.cont)
	}
}

/* **************************************** Return-Type-Erased Future Adapter */

/// Enumeration managing the state of the job's future.
///
/// This `enum` efficiently stores either the pending `Future` and its
/// associated [`Settle`] strategy or the `Option<F::Output>` once the future
/// completes.
#[pin_project::pin_project(
	project = InnerProject,
	project_replace = InnerOwn,
)]
enum Inner<F: Future, S> {
	/// Variant containing a pending `Future` and its `Settle`.
	Pending(#[pin] F, S),

	/// Variant containing the result of the `Future` or `None` in case of an
	/// aborted or terminated job where the result has already been retrieved.
	Ready(Option<F::Output>),
}

impl<F: Future, S> Inner<F, S> {
	/// Initializes a new return-type-erased instance from a future returning
	/// a `Result`.
	const fn new(actions: F, settle: S) -> Self {
		Inner::Pending(actions, settle)
	}

	/// Polls the inner future, panicking if it already terminated.
	fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<F::Output> {
		match self.project() {
			InnerProject::Pending(future, _) => future.poll(cx),
			_ => panic!("attempted to poll a terminated job"),
		}
	}

	/// Drops the jobs future `F` and settler `S`.
	fn abort(mut self: Pin<&mut Self>) {
		self.set(Inner::Ready(None));
	}

	/// Returns the result of the inner future.
	fn result(&mut self) -> Option<F::Output> {
		if let Inner::Ready(result) = self {
			result.take()
		} else {
			None
		}
	}

	/// Drops the inner future and writes out the result.
	///
	/// Panics if the job has already terminated.
	fn ready(mut self: Pin<&mut Self>, result: F::Output) -> ExitStatus
	where
		S: Settle<F::Output>,
	{
		match self.as_mut().project_replace(Inner::Ready(Some(result))) {
			InnerOwn::Pending(_, settle) => match self.project() {
				InnerProject::Ready(Some(result)) => settle.settle(result),
				_ => unsafe { core::hint::unreachable_unchecked() },
			},

			_ => panic!("terminating an already terminated job"),
		}
	}
}

/* ************************************************ Canonical Future Adapters */

/// Trait for defining how a [`Job`]'s return value (`R`) maps to an
/// [`ExitStatus`].
///
/// When a job's future completes, its `Settle` strategy is invoked with a
/// mutable reference to the return value. The `settle` method determines the
/// final `ExitStatus` (success or failure) that the underlying [`Continuation`]
/// records. This allows decoupling the job's actual output type from the
/// simulation's success/failure tracking.
pub trait Settle<R> {
	/// Called once when the job's future completes.
	fn settle(self, result: &mut R) -> ExitStatus;
}

// blanket implementation for closures
impl<R, F> Settle<R> for F
where
	F: FnOnce(&mut R) -> ExitStatus,
{
	fn settle(self, result: &mut R) -> ExitStatus {
		self(result)
	}
}

/// A [`Settle`] strategy where job completion *always* results in `Ok(Success)`.
///
/// This is the default strategy. The job's actual return value `R` is ignored
/// when determining the `ExitStatus`.
pub struct Unchecked;

impl<R> Settle<R> for Unchecked {
	fn settle(self, _result: &mut R) -> ExitStatus {
		Ok(crate::Success)
	}
}

/// A [`Settle`] strategy that interprets common types (`bool`, `Option`,
/// `Result`) to determine the [`ExitStatus`].
///
/// - `bool`: `true` -> `Ok(Success)`, `false` -> `Err(Failure)`.
/// - `Option<T>`: `Some(_)` -> `Ok(Success)`, `None` -> `Err(Failure)`.
/// - `Result<T, E>`: `Ok(_)` -> `Ok(Success)`, `Err(_)` -> `Err(Failure)`.
///
/// For other types `R`, using `Checked` will result in a compile error unless
/// a specific `Settle<R> for Checked` implementation is provided.
pub struct Checked;

impl Settle<bool> for Checked {
	fn settle(self, result: &mut bool) -> ExitStatus {
		if *result {
			Ok(crate::Success)
		} else {
			Err(crate::Failure)
		}
	}
}

impl<R, T> Settle<Result<R, T>> for Checked {
	fn settle(self, result: &mut Result<R, T>) -> ExitStatus {
		if result.is_ok() {
			Ok(crate::Success)
		} else {
			Err(crate::Failure)
		}
	}
}

impl<T> Settle<Option<T>> for Checked {
	fn settle(self, result: &mut Option<T>) -> ExitStatus {
		if result.is_some() {
			Ok(crate::Success)
		} else {
			Err(crate::Failure)
		}
	}
}

/* ************************************************************ Job Builder */

/// A builder for configuring and creating [`Job`] instances.
///
/// Provides methods to customize the job's future, settle strategy, precedence,
/// and source location before instantiation.
///
/// Start with [`Job::build()`], chain configuration methods, and finish with
/// [`finish()`](Builder::finish).
///
/// # Type Parameters
/// * `R`: `bool` indicating if this builder is for a root job (internal use).
/// * `F`: The type holding the future definition. Initially `()`.
/// * `S`: The [`Settle`] strategy type. Initially [`Unchecked`].
pub struct Builder<const R: bool = false, F = (), S = Unchecked> {
	/// The future or future provider. Set by `with_actions`.
	future: F,
	/// Optional source code location. Set by `with_location` or `with_actions`.
	location: Option<&'static Location<'static>>,
	/// The settle strategy instance. Set by `with_finalizer` or `checked`.
	finalizer: S,
	/// The initial scheduling precedence. Set by `with_precedence`.
	precedence: Prec,
}

impl Builder {
	/// Creates a new builder with default settings.
	pub const fn new() -> Self {
		Builder {
			future: (),
			location: None,
			finalizer: Unchecked,
			precedence: Prec::new(),
		}
	}

	/// Creates a new builder marked for a root job (internal use by Agent).
	pub const fn root() -> Builder<true> {
		Builder {
			future: (),
			location: None,
			finalizer: Unchecked,
			precedence: Prec::new(),
		}
	}
}

// Methods available before the future is set
impl<const R: bool, S> Builder<R, (), S> {
	/// Sets the asynchronous action (future) for the job.
	///
	/// Accepts any type implementing `IntoFuture`, typically an `async` block
	/// or function. Also captures the caller's location as the default source
	/// location unless explicitly set via `with_location`.
	#[track_caller]
	pub fn with_actions<F: IntoFuture>(self, future: F) -> Builder<R, F, S> {
		let Builder {
			location,
			finalizer,
			precedence,
			..
		} = self;

		Builder {
			future,
			location: Some(location.unwrap_or(Location::caller())),
			finalizer,
			precedence,
		}
	}
}

// Methods available before Settle is set (assuming default Unchecked)
impl<const R: bool, F> Builder<R, F> {
	/// Sets a custom [`Settle`] strategy for the job.
	pub fn with_finalizer<S>(self, finalizer: S) -> Builder<R, F, S> {
		let Builder {
			future,
			location,
			precedence,
			..
		} = self;

		Builder {
			future,
			location,
			finalizer,
			precedence,
		}
	}

	/// Sets the [`Settle`] strategy to [`Checked`], interpreting `bool`,
	/// `Option`, and `Result` outputs to determine success or failure.
	/// Shortcut for `with_finalizer(Checked)`.
	pub fn checked(self) -> Builder<R, F, Checked> {
		self.with_finalizer(Checked)
	}
}

// Methods always available
impl<const R: bool, F, S> Builder<R, F, S> {
	/// Sets the initial scheduling precedence for the job.
	/// Higher precedence jobs run before lower precedence jobs at the same
	/// simulation time.
	pub const fn with_precedence(mut self, precedence: Prec) -> Self {
		self.precedence = precedence;
		self
	}

	/// Explicitly sets the source code [`Location`] associated with the job.
	/// Overrides the location captured by `with_actions`.
	pub const fn with_location(mut self, location: &'static Location<'static>) -> Self {
		self.location = Some(location);
		self
	}
}

impl<const R: bool, F: IntoFuture, S: Settle<F::Output>> Builder<R, F, S> {
	/// Creates the [`Job`] instance from the builder configuration.
	///
	/// Consumes the builder and returns the configured `Job` wrapped in a
	/// [`Lease`].
	pub fn finish<'p, C>(self) -> Lease<'p, Job<C, F::IntoFuture, S>>
	where
		C: ?Sized + Config,
	{
		let location = self.location.unwrap();

		// create a new span if it's not a root fiber
		#[cfg(feature = "tracing")]
		let _span = if R {
			tracing::Span::current()
		} else {
			tracing::error_span!("Job", line = location.line()).or_current()
		}
		.entered();

		Lease::new(Job {
			cont: Continuation::new(self.precedence, location),
			state: RefCell::new(Inner::new(self.future.into_future(), self.finalizer)),
		})
	}
}

impl Default for Builder {
	fn default() -> Self {
		Self::new()
	}
}

/* ******************************************************* PhantomDrop helper */

/// This type-alias combines [`PhantomData`] with a Drop-check, ensuring that
/// even phantom types that don't implement the Drop traits themselves present
/// like they would. This is necessary to prevent code like in the following
/// example to compile which would lead to a runtime error due to increased
/// reference counts during destruction.
///
/// ```compile_fail
/// # use odem_rs_core::{simulator::Sim, job::Job};
/// # use core::pin::pin;
///
/// async fn sim_main(sim: &Sim) {
///     let puck = sim.activate(pin!(Job::new(async {})));
/// }
/// ```
type PhantomDrop<T> = PhantomData<PhantomDropInner<T>>;

/// Newtype wrapping a `T` and explicitly implementing the [Drop]-trait.
struct PhantomDropInner<T: ?Sized>(T);

impl<T: ?Sized> Drop for PhantomDropInner<T> {
	fn drop(&mut self) {}
}