mustardscript 0.1.0

package/crates/mustard/src/runtime/api.rs

@@ -0,0 +1,192 @@
+use indexmap::IndexMap;
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+
+use crate::{
+    cancellation::CancellationToken,
+    diagnostic::{DiagnosticKind, MustardError, MustardResult},
+    ir::CompiledProgram,
+    limits::RuntimeLimits,
+    structured::StructuredValue,
+};
+
+use super::{
+    Runtime,
+    bytecode::BytecodeProgram,
+    lower_to_bytecode,
+    validation::{validate_bytecode_program, validate_snapshot},
+};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ExecutionOptions {
+    pub inputs: IndexMap<String, StructuredValue>,
+    pub capabilities: Vec<String>,
+    pub limits: RuntimeLimits,
+    #[serde(skip, default)]
+    pub cancellation_token: Option<CancellationToken>,
+}
+
+impl Default for ExecutionOptions {
+    fn default() -> Self {
+        Self {
+            inputs: IndexMap::new(),
+            capabilities: Vec::new(),
+            limits: RuntimeLimits::default(),
+            cancellation_token: None,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct HostError {
+    pub name: String,
+    pub message: String,
+    pub code: Option<String>,
+    pub details: Option<StructuredValue>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum ResumePayload {
+    Value(StructuredValue),
+    Error(HostError),
+    Cancelled,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SnapshotPolicy {
+    pub capabilities: Vec<String>,
+    pub limits: RuntimeLimits,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SnapshotInspection {
+    pub capability: String,
+    pub args: Vec<StructuredValue>,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct ResumeOptions {
+    pub cancellation_token: Option<CancellationToken>,
+    pub snapshot_policy: Option<SnapshotPolicy>,
+}
+
+#[derive(Debug, Clone)]
+pub struct ExecutionSnapshot {
+    pub(super) runtime: Runtime,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Suspension {
+    pub capability: String,
+    pub args: Vec<StructuredValue>,
+    pub snapshot: ExecutionSnapshot,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum ExecutionStep {
+    Completed(StructuredValue),
+    Suspended(Box<Suspension>),
+}
+
+#[derive(Serialize)]
+struct SerializableExecutionSnapshot<'a> {
+    runtime: &'a Runtime,
+}
+
+#[derive(Deserialize)]
+struct DeserializableExecutionSnapshot {
+    runtime: Runtime,
+}
+
+impl ExecutionSnapshot {
+    pub(in crate::runtime) fn restore_loaded_runtime(runtime: Runtime) -> MustardResult<Self> {
+        let mut snapshot = Self { runtime };
+        validate_snapshot(&snapshot)?;
+        snapshot.runtime.recompute_accounting_after_load()?;
+        snapshot.runtime.snapshot_policy_required = true;
+        Ok(snapshot)
+    }
+}
+
+impl Serialize for ExecutionSnapshot {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        SerializableExecutionSnapshot {
+            runtime: &self.runtime,
+        }
+        .serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for ExecutionSnapshot {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let decoded = DeserializableExecutionSnapshot::deserialize(deserializer)?;
+        Self::restore_loaded_runtime(decoded.runtime).map_err(serde::de::Error::custom)
+    }
+}
+
+pub fn execute(
+    program: &CompiledProgram,
+    options: ExecutionOptions,
+) -> MustardResult<StructuredValue> {
+    match start(program, options)? {
+        ExecutionStep::Completed(value) => Ok(value),
+        ExecutionStep::Suspended(suspension) => Err(MustardError::runtime(format!(
+            "execution suspended on capability `{}`; use start()/resume() for iterative execution",
+            suspension.capability
+        ))),
+    }
+}
+
+pub fn start(program: &CompiledProgram, options: ExecutionOptions) -> MustardResult<ExecutionStep> {
+    let bytecode = lower_to_bytecode(program)?;
+    start_bytecode(&bytecode, options)
+}
+
+pub fn start_bytecode(
+    program: &BytecodeProgram,
+    options: ExecutionOptions,
+) -> MustardResult<ExecutionStep> {
+    validate_bytecode_program(program)?;
+    let mut runtime = Runtime::new(program.clone(), options)?;
+    runtime.run_root()
+}
+
+pub fn resume(snapshot: ExecutionSnapshot, payload: ResumePayload) -> MustardResult<ExecutionStep> {
+    resume_with_options(snapshot, payload, ResumeOptions::default())
+}
+
+pub fn resume_with_options(
+    snapshot: ExecutionSnapshot,
+    payload: ResumePayload,
+    options: ResumeOptions,
+) -> MustardResult<ExecutionStep> {
+    let mut runtime = snapshot.runtime;
+    runtime.apply_resume_options(options)?;
+    runtime.resume(payload)
+}
+
+pub fn inspect_snapshot(
+    snapshot: &mut ExecutionSnapshot,
+    policy: SnapshotPolicy,
+) -> MustardResult<SnapshotInspection> {
+    snapshot.runtime.apply_snapshot_policy(policy)?;
+    let request = snapshot
+        .runtime
+        .suspended_host_call
+        .as_ref()
+        .ok_or_else(|| MustardError::Message {
+            kind: DiagnosticKind::Serialization,
+            message: "snapshot is not suspended on a host capability".to_string(),
+            span: None,
+            traceback: Vec::new(),
+        })?;
+    Ok(SnapshotInspection {
+        capability: request.capability.clone(),
+        args: request.args.clone(),
+    })
+}

package/crates/mustard/src/runtime/async_runtime/mod.rs

@@ -0,0 +1,5 @@
+use super::*;
+
+mod promises;
+mod reactions;
+mod scheduler;

package/crates/mustard/src/runtime/async_runtime/promises.rs

@@ -0,0 +1,246 @@
+use crate::runtime::builtins::PromiseSetupPolicy;
+
+use super::*;
+
+impl Runtime {
+    pub(in crate::runtime) fn current_async_boundary_index(&self) -> Option<usize> {
+        self.frames
+            .iter()
+            .rposition(|frame| frame.async_promise.is_some())
+    }
+
+    pub(in crate::runtime) fn promise_outcome(
+        &self,
+        promise: PromiseKey,
+    ) -> MustardResult<Option<PromiseOutcome>> {
+        let promise = self
+            .promises
+            .get(promise)
+            .ok_or_else(|| MustardError::runtime("promise missing"))?;
+        Ok(match &promise.state {
+            PromiseState::Pending => None,
+            PromiseState::Fulfilled(value) => Some(PromiseOutcome::Fulfilled(value.clone())),
+            PromiseState::Rejected(rejection) => Some(PromiseOutcome::Rejected(rejection.clone())),
+        })
+    }
+
+    pub(in crate::runtime) fn coerce_to_promise(
+        &mut self,
+        value: Value,
+    ) -> MustardResult<PromiseKey> {
+        match value {
+            Value::Promise(promise) => Ok(promise),
+            other => {
+                let promise = self.insert_promise(PromiseState::Pending)?;
+                self.resolve_promise(promise, other)?;
+                Ok(promise)
+            }
+        }
+    }
+
+    pub(in crate::runtime) fn attach_awaiter(
+        &mut self,
+        promise: PromiseKey,
+        continuation: AsyncContinuation,
+    ) -> MustardResult<()> {
+        self.promises
+            .get_mut(promise)
+            .ok_or_else(|| MustardError::runtime("promise missing"))?
+            .awaiters
+            .push(continuation);
+        self.refresh_promise_accounting(promise)
+    }
+
+    pub(in crate::runtime) fn attach_dependent(
+        &mut self,
+        promise: PromiseKey,
+        dependent: PromiseKey,
+    ) -> MustardResult<()> {
+        self.promises
+            .get_mut(promise)
+            .ok_or_else(|| MustardError::runtime("promise missing"))?
+            .dependents
+            .push(dependent);
+        self.refresh_promise_accounting(promise)
+    }
+
+    pub(in crate::runtime) fn attach_promise_reaction(
+        &mut self,
+        promise: PromiseKey,
+        reaction: PromiseReaction,
+    ) -> MustardResult<()> {
+        match self.promise_outcome(promise)? {
+            Some(outcome) => self.schedule_promise_reaction(reaction, outcome),
+            None => {
+                self.promises
+                    .get_mut(promise)
+                    .ok_or_else(|| MustardError::runtime("promise missing"))?
+                    .reactions
+                    .push(reaction);
+                self.refresh_promise_accounting(promise)
+            }
+        }
+    }
+
+    pub(in crate::runtime) fn schedule_promise_reaction(
+        &mut self,
+        reaction: PromiseReaction,
+        outcome: PromiseOutcome,
+    ) -> MustardResult<()> {
+        self.microtasks
+            .push_back(MicrotaskJob::PromiseReaction { reaction, outcome });
+        Ok(())
+    }
+
+    pub(in crate::runtime) fn settle_promise_with_outcome(
+        &mut self,
+        promise: PromiseKey,
+        outcome: PromiseOutcome,
+    ) -> MustardResult<()> {
+        let (awaiters, dependents, reactions) = {
+            let promise_ref = self
+                .promises
+                .get_mut(promise)
+                .ok_or_else(|| MustardError::runtime("promise missing"))?;
+            if !matches!(promise_ref.state, PromiseState::Pending) {
+                return Ok(());
+            }
+            promise_ref.state = match &outcome {
+                PromiseOutcome::Fulfilled(value) => PromiseState::Fulfilled(value.clone()),
+                PromiseOutcome::Rejected(rejection) => PromiseState::Rejected(rejection.clone()),
+            };
+            promise_ref.driver = None;
+            (
+                std::mem::take(&mut promise_ref.awaiters),
+                std::mem::take(&mut promise_ref.dependents),
+                std::mem::take(&mut promise_ref.reactions),
+            )
+        };
+        self.refresh_promise_accounting(promise)?;
+        for continuation in awaiters {
+            self.microtasks.push_back(MicrotaskJob::ResumeAsync {
+                continuation,
+                outcome: outcome.clone(),
+            });
+        }
+        for dependent in dependents {
+            self.resolve_promise_with_outcome(dependent, outcome.clone())?;
+        }
+        for reaction in reactions {
+            self.schedule_promise_reaction(reaction, outcome.clone())?;
+        }
+        Ok(())
+    }
+
+    pub(in crate::runtime) fn resolve_promise_with_outcome(
+        &mut self,
+        promise: PromiseKey,
+        outcome: PromiseOutcome,
+    ) -> MustardResult<()> {
+        match outcome {
+            PromiseOutcome::Fulfilled(value) => self.resolve_promise(promise, value),
+            PromiseOutcome::Rejected(rejection) => self.reject_promise(promise, rejection),
+        }
+    }
+
+    pub(in crate::runtime) fn resolve_promise(
+        &mut self,
+        promise: PromiseKey,
+        value: Value,
+    ) -> MustardResult<()> {
+        if self.promise_outcome(promise)?.is_some() {
+            return Ok(());
+        }
+        if let Value::Promise(source) = value {
+            if source == promise {
+                let error_value =
+                    self.value_from_runtime_message("TypeError: promise cannot resolve to itself")?;
+                return self.reject_promise(
+                    promise,
+                    PromiseRejection {
+                        value: error_value,
+                        span: None,
+                        traceback: self.traceback_snapshots(),
+                    },
+                );
+            }
+            match self.promise_outcome(source)? {
+                Some(outcome) => self.resolve_promise_with_outcome(promise, outcome),
+                None => self.attach_dependent(source, promise),
+            }
+        } else if let Some(then) = self.promise_thenable_handler(&value)? {
+            let tracked_thenable = self
+                .promises
+                .get(promise)
+                .ok_or_else(|| MustardError::runtime("promise missing"))?
+                .driver
+                .as_ref()
+                .and_then(|driver| match driver {
+                    PromiseDriver::Thenable { value } => Some(value),
+                    _ => None,
+                });
+            if tracked_thenable.is_some_and(|tracked| strict_equal(tracked, &value)) {
+                let error_value = self
+                    .value_from_runtime_message("TypeError: thenable cannot resolve to itself")?;
+                return self.reject_promise(
+                    promise,
+                    PromiseRejection {
+                        value: error_value,
+                        span: None,
+                        traceback: self.traceback_snapshots(),
+                    },
+                );
+            }
+            self.promises
+                .get_mut(promise)
+                .ok_or_else(|| MustardError::runtime("promise missing"))?
+                .driver = Some(PromiseDriver::Thenable {
+                value: value.clone(),
+            });
+            self.refresh_promise_accounting(promise)?;
+            let resolve = self.promise_settler(promise, false);
+            let reject = self.promise_settler(promise, true);
+            self.call_promise_setup_callback(
+                promise,
+                then,
+                value,
+                &[resolve, reject],
+                PromiseSetupPolicy {
+                    non_callable_message: "TypeError: adopted thenable `.then` must be callable",
+                    host_suspension_message:
+                        "TypeError: adopted thenables do not support synchronous host suspensions",
+                    async_message:
+                        "TypeError: adopted thenables must use synchronous `.then` handlers",
+                },
+            )
+        } else {
+            self.settle_promise_with_outcome(promise, PromiseOutcome::Fulfilled(value))
+        }
+    }
+
+    pub(in crate::runtime) fn reject_promise(
+        &mut self,
+        promise: PromiseKey,
+        rejection: PromiseRejection,
+    ) -> MustardResult<()> {
+        self.settle_promise_with_outcome(promise, PromiseOutcome::Rejected(rejection))
+    }
+
+    pub(in crate::runtime) fn suspend_async_await(&mut self, value: Value) -> MustardResult<()> {
+        let boundary = self.current_async_boundary_index().ok_or_else(|| {
+            MustardError::runtime("await is only supported inside async functions")
+        })?;
+        let promise = self.coerce_to_promise(value)?;
+        let continuation = AsyncContinuation {
+            frames: self.frames.split_off(boundary),
+        };
+        match self.promise_outcome(promise)? {
+            Some(outcome) => self.microtasks.push_back(MicrotaskJob::ResumeAsync {
+                continuation,
+                outcome,
+            }),
+            None => self.attach_awaiter(promise, continuation)?,
+        }
+        Ok(())
+    }
+}