Struct RunRequest 

pub struct RunRequest<'a, K> { /* private fields */ }

A run about to start — see Runtime::start.

The answer’s type follows the key. Unkeyed, a run answers with its RunOutcome and a spawn with its RunId; under once, with an Admission or a Spawned, because a key already held is answered by the run that holds it, and a caller must say what it does then.

let _: agentplane::runtime::RunOutcome = rt.start("c", input).once("k").run().await.unwrap();

rt.start("c", input).once("a").once("b");

let _: agentplane::runtime::RunOutcome = rt.start("c", input.clone()).run().await.unwrap();
let _: agentplane::runtime::Admission = rt.start("c", input).once("k").run().await.unwrap();

Implementations

impl<K> RunRequest<'_, K>

pub fn terms(self, terms: RunTerms) -> Self

Bind the run: a case, a caller’s chain, who asked, a pinned declaration. A second call replaces the first, as one value.

impl<'a> RunRequest<'a, Unkeyed>

pub fn once(self, key: impl Into<String>) -> RunRequest<'a, Keyed>

Admit at most once per tenant under this key.

The door for an at-least-once emitter: a bus that retries until it sees a 2xx, a webhook fan-out, a queue with redelivery. The store claims the key in the same transaction that writes the run’s first record, so a second request under it cannot admit a second run — not on a retry, not across a restart, not from another instance sharing the store.

The key must carry its producer. An id is unique only within one emitter, so a bare message id lets two counterparties swallow each other’s messages as apparent retries. InboundEvent::dedup_key is the ready-made spelling.

Not the event buffer: an event nobody subscribes to is dead-lettered by sweep, so using the buffer as a ledger would spend that signal to buy deduplication.

pub async fn run(self) -> Result<RunOutcome, RuntimeError>

Run, and wait until it rests.

Errors

RuntimeError::NoProvider when no skill provides the capability, and whatever admission refuses — policy, quota, a halted tenant, an instance draining, a chain this plane may not act under.

pub async fn spawn(self) -> Result<RunId, RuntimeError>

Admit, and let the run proceed in the background, returning its id.

Admission happens before this returns. The policy gate, the lease and the admission records are written first, so a refusal is an error here and not a task that never appears, and the id can be read at once. The run is durable: a process that dies mid-flight leaves a journal another instance resumes.

Panics

Outside a Tokio runtime, as the rest of this crate’s timing does.

Errors

As run.

impl RunRequest<'_, Keyed>

pub async fn run(self) -> Result<Admission, RuntimeError>

Run under the key. A key already held comes back as Admission::Replayed or Admission::InFlight, not an error.

Errors

As RunRequest::run, and RuntimeError::PlanContract for an empty key or one over MAX_ADMISSION_KEY_BYTES.

pub async fn spawn(self) -> Result<Spawned, RuntimeError>

Spawn under the key. A key already held names its run, with fresh false.

Panics

Outside a Tokio runtime.

Errors

As run.

pub async fn settle(self) -> Result<RunOutcome, RuntimeError>

Run under the key until the run it admitted rests, whoever admitted it, and answer with its outcome.

The shape a process that may have been killed mid-run wants on restart: the same request again. An unused key runs. A key whose run has rested answers with that run, its value re-derived by strict replay, which performs nothing. A key whose run is still working is resumed when nobody holds its lease — its holder has gone — and otherwise followed on the journal until it rests or its lease lapses.

Errors

As run, and whatever resuming or replaying the held run refuses.

Trait Implementations

impl<'a, K: Debug> Debug for RunRequest<'a, K>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.