lash_lashlang_runtime/
lib.rs

1use std::sync::{Arc, Mutex};
2
3use sha2::{Digest, Sha256};
4
5#[cfg(feature = "testing")]
6pub mod testing;
7
8pub use lash_trace::{
9    TraceLashlangChildExecution, TraceLashlangEdgeSelection, TraceLashlangExecutionEvent,
10    TraceLashlangExecutionIdentity, TraceLashlangGraph, TraceLashlangGraphChildLink,
11    TraceLashlangGraphEdge, TraceLashlangGraphNode, TraceLashlangGraphStore, TraceLashlangMap,
12    TraceLashlangMapEdge, TraceLashlangMapNode, TraceLashlangNodeStatus, TraceLashlangStatus,
13};
14pub use lashlang::{
15    CompiledProcessCache, InMemoryLashlangArtifactStore, LASH_TYPE_KEY, LashlangAbilities,
16    LashlangArtifactStore, LashlangHostCatalog, LashlangHostEnvironment, LashlangLanguageFeatures,
17};
18
19/// Map the lashlang language crate's durability tier onto the runtime's
20/// [`lash_core::DurabilityTier`]. The two enums are parallel; this is the single
21/// bridge point between them (the parallel `LashlangDurabilityTier` alias is
22/// gone — process engines self-describe their tier via `lash_core::DurabilityTier`).
23pub fn lashlang_durability_tier(tier: lashlang::DurabilityTier) -> lash_core::DurabilityTier {
24    match tier {
25        lashlang::DurabilityTier::Inline => lash_core::DurabilityTier::Inline,
26        lashlang::DurabilityTier::Durable => lash_core::DurabilityTier::Durable,
27    }
28}
29
30pub const LASHLANG_ENGINE_KIND: &str = "lashlang";
31pub const LASHLANG_TOOL_BINDING_KEY: &str = "lashlang.tool";
32pub const LASHLANG_SURFACE_EXTENSION_ID: &str = "lashlang.surface";
33
34#[derive(Clone, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
35#[serde(default)]
36pub struct LashlangSurfaceContribution {
37    pub abilities: LashlangAbilities,
38    pub language_features: LashlangLanguageFeatures,
39    pub resources: LashlangHostCatalog,
40}
41
42impl LashlangSurfaceContribution {
43    pub fn new(
44        abilities: LashlangAbilities,
45        language_features: LashlangLanguageFeatures,
46        resources: LashlangHostCatalog,
47    ) -> Self {
48        Self {
49            abilities,
50            language_features,
51            resources,
52        }
53    }
54
55    pub fn from_surface(surface: LashlangSurface) -> Self {
56        Self {
57            abilities: surface.abilities,
58            language_features: surface.language_features,
59            resources: surface.resources,
60        }
61    }
62}
63
64#[derive(Clone, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
65pub struct LashlangToolBinding {
66    #[serde(default, skip_serializing_if = "Vec::is_empty")]
67    pub module_path: Vec<String>,
68    #[serde(default, skip_serializing_if = "Option::is_none")]
69    pub operation: Option<String>,
70    #[serde(default, skip_serializing_if = "Option::is_none")]
71    pub authority_type: Option<String>,
72    #[serde(default, skip_serializing_if = "Vec::is_empty")]
73    pub aliases: Vec<String>,
74}
75
76impl LashlangToolBinding {
77    pub fn new(
78        module_path: impl IntoIterator<Item = impl Into<String>>,
79        operation: impl Into<String>,
80    ) -> Self {
81        Self {
82            module_path: module_path.into_iter().map(Into::into).collect(),
83            operation: Some(operation.into()),
84            authority_type: None,
85            aliases: Vec::new(),
86        }
87    }
88
89    pub fn with_authority_type(mut self, authority_type: impl Into<String>) -> Self {
90        self.authority_type = Some(authority_type.into());
91        self
92    }
93
94    pub fn with_aliases(mut self, aliases: impl IntoIterator<Item = impl Into<String>>) -> Self {
95        self.aliases = aliases.into_iter().map(Into::into).collect();
96        self
97    }
98
99    pub fn executable_for(&self, tool_name: &str) -> Result<ResolvedLashlangToolBinding, String> {
100        if self.module_path.is_empty() {
101            return Err(format!(
102                "tool `{tool_name}` is missing an explicit Lashlang module path"
103            ));
104        }
105        for segment in &self.module_path {
106            validate_lashlang_identifier(tool_name, "module path segment", segment)?;
107        }
108        let operation = self
109            .operation
110            .as_deref()
111            .filter(|operation| !operation.trim().is_empty())
112            .ok_or_else(|| {
113                format!("tool `{tool_name}` is missing an explicit Lashlang operation name")
114            })?;
115        validate_lashlang_identifier(tool_name, "operation name", operation)?;
116        let authority_type = self
117            .authority_type
118            .as_deref()
119            .filter(|authority_type| !authority_type.trim().is_empty())
120            .map(ToOwned::to_owned)
121            .unwrap_or_else(|| default_authority_type(&self.module_path));
122        Ok(ResolvedLashlangToolBinding {
123            module_path: self.module_path.clone(),
124            operation: operation.to_string(),
125            authority_type,
126            aliases: self.aliases.clone(),
127        })
128    }
129
130    pub fn required_for_remote(
131        manifest: &lash_core::ToolManifest,
132    ) -> Result<ResolvedLashlangToolBinding, String> {
133        required_tool_lashlang_executable(manifest)
134    }
135
136    pub fn required_executable_for_remote(
137        &self,
138        tool_name: &str,
139    ) -> Result<ResolvedLashlangToolBinding, String> {
140        self.executable_for(tool_name)
141    }
142}
143
144#[derive(Clone, Debug, PartialEq, Eq)]
145pub struct ResolvedLashlangToolBinding {
146    pub module_path: Vec<String>,
147    pub operation: String,
148    pub authority_type: String,
149    pub aliases: Vec<String>,
150}
151
152impl ResolvedLashlangToolBinding {
153    pub fn module_path_string(&self) -> String {
154        self.module_path.join(".")
155    }
156
157    pub fn call_path(&self) -> String {
158        format!("{}.{}", self.module_path_string(), self.operation)
159    }
160}
161
162fn default_authority_type(module_path: &[String]) -> String {
163    module_path
164        .last()
165        .map(|segment| {
166            let mut chars = segment.chars();
167            match chars.next() {
168                Some(first) => first.to_uppercase().collect::<String>() + chars.as_str(),
169                None => "Tool".to_string(),
170            }
171        })
172        .unwrap_or_else(|| "Tool".to_string())
173}
174
175fn validate_lashlang_identifier(tool_name: &str, label: &str, value: &str) -> Result<(), String> {
176    let value = value.trim();
177    let mut chars = value.chars();
178    let Some(first) = chars.next() else {
179        return Err(format!("tool `{tool_name}` has an empty Lashlang {label}"));
180    };
181    if !(first == '_' || first.is_ascii_alphabetic()) {
182        return Err(format!(
183            "tool `{tool_name}` has invalid Lashlang {label} `{value}`"
184        ));
185    }
186    if !chars.all(|ch| ch == '_' || ch.is_ascii_alphanumeric()) {
187        return Err(format!(
188            "tool `{tool_name}` has invalid Lashlang {label} `{value}`"
189        ));
190    }
191    Ok(())
192}
193
194pub fn tool_lashlang_binding(
195    manifest: &lash_core::ToolManifest,
196) -> Result<Option<LashlangToolBinding>, String> {
197    manifest
198        .bindings
199        .get(LASHLANG_TOOL_BINDING_KEY)
200        .cloned()
201        .map(serde_json::from_value)
202        .transpose()
203        .map_err(|err| {
204            format!(
205                "tool `{}` has invalid `{LASHLANG_TOOL_BINDING_KEY}` binding: {err}",
206                manifest.name
207            )
208        })
209}
210
211pub fn required_tool_lashlang_binding(
212    manifest: &lash_core::ToolManifest,
213) -> Result<LashlangToolBinding, String> {
214    tool_lashlang_binding(manifest)?.ok_or_else(|| {
215        format!(
216            "tool `{}` is missing an explicit `{LASHLANG_TOOL_BINDING_KEY}` binding",
217            manifest.name
218        )
219    })
220}
221
222pub fn required_tool_lashlang_executable(
223    manifest: &lash_core::ToolManifest,
224) -> Result<ResolvedLashlangToolBinding, String> {
225    required_tool_lashlang_binding(manifest)?.executable_for(&manifest.name)
226}
227
228pub trait ToolManifestLashlangExt {
229    fn lashlang_binding(&self) -> Result<Option<LashlangToolBinding>, serde_json::Error>;
230}
231
232impl ToolManifestLashlangExt for lash_core::ToolManifest {
233    fn lashlang_binding(&self) -> Result<Option<LashlangToolBinding>, serde_json::Error> {
234        self.bindings
235            .get(LASHLANG_TOOL_BINDING_KEY)
236            .cloned()
237            .map(serde_json::from_value)
238            .transpose()
239    }
240}
241
242pub trait ToolDefinitionLashlangExt {
243    fn with_lashlang_binding(self, lashlang_binding: LashlangToolBinding) -> Self;
244}
245
246impl ToolDefinitionLashlangExt for lash_core::ToolDefinition {
247    fn with_lashlang_binding(mut self, lashlang_binding: LashlangToolBinding) -> Self {
248        let value = serde_json::to_value(lashlang_binding)
249            .expect("lashlang tool binding must serialize to JSON");
250        self.manifest
251            .bindings
252            .insert(LASHLANG_TOOL_BINDING_KEY.to_string(), value);
253        self
254    }
255}
256
257pub trait RemoteToolGrantLashlangExt {
258    fn with_lashlang_binding(self, lashlang_binding: LashlangToolBinding) -> Self;
259    fn lashlang_binding(&self) -> Result<Option<LashlangToolBinding>, serde_json::Error>;
260}
261
262impl RemoteToolGrantLashlangExt for lash_remote_protocol::RemoteToolGrant {
263    fn with_lashlang_binding(mut self, lashlang_binding: LashlangToolBinding) -> Self {
264        let value = serde_json::to_value(lashlang_binding)
265            .expect("lashlang tool binding must serialize to JSON");
266        self.bindings
267            .insert(LASHLANG_TOOL_BINDING_KEY.to_string(), value);
268        self
269    }
270
271    fn lashlang_binding(&self) -> Result<Option<LashlangToolBinding>, serde_json::Error> {
272        self.bindings
273            .get(LASHLANG_TOOL_BINDING_KEY)
274            .cloned()
275            .map(serde_json::from_value)
276            .transpose()
277    }
278}
279
280#[derive(Clone, Debug)]
281pub struct LashlangSurface {
282    pub abilities: LashlangAbilities,
283    pub language_features: LashlangLanguageFeatures,
284    pub resources: LashlangHostCatalog,
285}
286
287impl Default for LashlangSurface {
288    fn default() -> Self {
289        Self {
290            abilities: LashlangAbilities::default().with_sleep(),
291            language_features: LashlangLanguageFeatures::default(),
292            resources: LashlangHostCatalog::new(),
293        }
294    }
295}
296
297impl LashlangSurface {
298    pub fn new(
299        abilities: LashlangAbilities,
300        language_features: LashlangLanguageFeatures,
301        resources: LashlangHostCatalog,
302    ) -> Self {
303        Self {
304            abilities,
305            language_features,
306            resources,
307        }
308    }
309
310    pub fn for_process_registry(mut self, process_registry_available: bool) -> Self {
311        self.abilities = self.abilities.with_sleep();
312        if process_registry_available {
313            self.abilities = self.abilities.with_processes().with_process_signals();
314        } else {
315            self.abilities.processes = false;
316            self.abilities.process_signals = false;
317        }
318        self
319    }
320
321    pub fn with_resources(mut self, resources: LashlangHostCatalog) -> Self {
322        self.resources.extend(resources);
323        self
324    }
325
326    pub fn with_plugin_extensions(
327        mut self,
328        extensions: &lash_core::PluginExtensions,
329    ) -> Result<Self, String> {
330        for payload in extensions.payloads(LASHLANG_SURFACE_EXTENSION_ID) {
331            let contribution: LashlangSurfaceContribution = serde_json::from_value(payload.clone())
332                .map_err(|err| {
333                    format!("invalid `{LASHLANG_SURFACE_EXTENSION_ID}` extension payload: {err}")
334                })?;
335            self.abilities = self.abilities.union(contribution.abilities);
336            self.language_features = self.language_features.union(contribution.language_features);
337            self.resources.extend(contribution.resources);
338        }
339        Ok(self)
340    }
341
342    pub fn host_environment(
343        &self,
344        catalog: &lash_core::ToolCatalog,
345    ) -> Result<LashlangHostEnvironment, String> {
346        lashlang_host_environment_from_tool_catalog(
347            catalog,
348            self.abilities,
349            self.language_features,
350            self.resources.clone(),
351        )
352    }
353}
354
355pub fn lashlang_host_environment_from_tool_catalog(
356    catalog: &lash_core::ToolCatalog,
357    abilities: LashlangAbilities,
358    language_features: LashlangLanguageFeatures,
359    host_resources: LashlangHostCatalog,
360) -> Result<LashlangHostEnvironment, String> {
361    let mut resources = lashlang_resources_from_tool_catalog(catalog)?;
362    resources.extend(host_resources);
363    if abilities.triggers {
364        lashlang::add_trigger_resource_operations(&mut resources);
365    }
366    Ok(
367        LashlangHostEnvironment::new(resources, abilities)
368            .with_language_features(language_features),
369    )
370}
371
372pub fn lashlang_resources_from_tool_catalog(
373    catalog: &lash_core::ToolCatalog,
374) -> Result<LashlangHostCatalog, String> {
375    let mut host_catalog = LashlangHostCatalog::new();
376    // Every catalog member is callable; membership is the execution gate.
377    for entry in catalog.tools.iter() {
378        let lashlang_binding = required_tool_lashlang_executable(&entry.manifest)?;
379        host_catalog.add_module_operation(
380            lashlang_binding.module_path.iter().map(String::as_str),
381            lashlang_binding.authority_type.clone(),
382            lashlang_binding.operation.clone(),
383            entry.manifest.id.to_string(),
384            lashlang::TypeExpr::Any,
385            lashlang::TypeExpr::Any,
386        );
387    }
388    Ok(host_catalog)
389}
390
391pub fn lashlang_host_environment_satisfies_requirements(
392    required: &lashlang::HostRequirements,
393    current: &LashlangHostEnvironment,
394) -> Result<(), String> {
395    let abilities = required.abilities;
396    let current_abilities = current.abilities;
397    if abilities.processes && !current_abilities.processes {
398        return Err("processes are not available".to_string());
399    }
400    if abilities.sleep && !current_abilities.sleep {
401        return Err("sleep is not available".to_string());
402    }
403    if abilities.process_signals && !current_abilities.process_signals {
404        return Err("process signals are not available".to_string());
405    }
406    if abilities.triggers && !current_abilities.triggers {
407        return Err("triggers are not available".to_string());
408    }
409    if required.language_features.label_annotations && !current.language_features.label_annotations
410    {
411        return Err("label annotations are not available".to_string());
412    }
413
414    for (_, module) in required.resources.module_instances() {
415        let current_module = current
416            .resources
417            .resolve_module_path(&module.path)
418            .ok_or_else(|| format!("module `{}` is not available", module.alias))?;
419        if current_module.resource_type != module.resource_type {
420            return Err(format!(
421                "module `{}` has type `{}`, expected `{}`",
422                module.alias, current_module.resource_type, module.resource_type
423            ));
424        }
425        for (operation, required_binding) in &module.operations {
426            match current.resources.resolve_module_operation(
427                &module.resource_type,
428                &module.alias,
429                operation,
430            ) {
431                Some(current_binding) if current_binding == required_binding => {}
432                Some(current_binding) => {
433                    return Err(format!(
434                        "module `{}` operation `{operation}` resolves to `{}`, expected `{}`",
435                        module.alias,
436                        current_binding.host_operation,
437                        required_binding.host_operation
438                    ));
439                }
440                None => {
441                    return Err(format!(
442                        "module `{}` does not expose operation `{operation}`",
443                        module.alias
444                    ));
445                }
446            }
447        }
448    }
449
450    for (resource_type, required_type) in required.resources.resource_types() {
451        if !current.resources.has_resource_type(resource_type) {
452            return Err(format!("resource type `{resource_type}` is not available"));
453        }
454        for (operation, required_binding) in &required_type.operations {
455            let current_binding = current
456                .resources
457                .resolve_operation(resource_type, operation)
458                .ok_or_else(|| {
459                    format!(
460                        "resource type `{resource_type}` does not expose operation `{operation}`"
461                    )
462                })?;
463            if current_binding.input_ty != required_binding.input_ty {
464                return Err(format!(
465                    "resource type `{resource_type}` operation `{operation}` has incompatible input type"
466                ));
467            }
468            if current_binding.output_ty != required_binding.output_ty {
469                return Err(format!(
470                    "resource type `{resource_type}` operation `{operation}` has incompatible output type"
471                ));
472            }
473        }
474    }
475    for (name, required_data_type) in required.resources.named_data_types() {
476        let current_data_type = current
477            .resources
478            .resolve_named_data_type(name)
479            .ok_or_else(|| format!("host data type `{name}` is not available"))?;
480        if current_data_type != required_data_type {
481            return Err(format!(
482                "host data type `{name}` has incompatible structure"
483            ));
484        }
485    }
486    for (path, required_binding) in required.resources.value_constructors() {
487        let current_binding = current
488            .resources
489            .resolve_value_constructor(&path.split('.').collect::<Vec<_>>())
490            .ok_or_else(|| format!("value constructor `{path}` is not available"))?;
491        if current_binding.input_ty != required_binding.input_ty {
492            return Err(format!(
493                "value constructor `{path}` has incompatible input type"
494            ));
495        }
496        if current_binding.output_ty != required_binding.output_ty {
497            return Err(format!(
498                "value constructor `{path}` has incompatible output type"
499            ));
500        }
501    }
502    for (source_ty, required_binding) in required.resources.trigger_sources() {
503        let current_binding = current
504            .resources
505            .resolve_trigger_source(source_ty)
506            .ok_or_else(|| format!("trigger source type `{source_ty}` is not available"))?;
507        if current_binding != required_binding {
508            return Err(format!(
509                "trigger source type `{source_ty}` has incompatible event type"
510            ));
511        }
512    }
513
514    Ok(())
515}
516
517#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
518pub struct LashlangProcessInput {
519    pub module_ref: lashlang::ModuleRef,
520    pub process_ref: lashlang::ProcessRef,
521    pub host_requirements_ref: lashlang::HostRequirementsRef,
522    pub process_name: String,
523    #[serde(default)]
524    pub args: serde_json::Map<String, serde_json::Value>,
525}
526
527impl LashlangProcessInput {
528    pub fn process_identity(&self) -> lash_core::ProcessIdentity {
529        lashlang_process_identity(self)
530    }
531
532    pub fn remote_identity(&self) -> lash_remote_protocol::RemoteProcessIdentity {
533        lash_remote_protocol::RemoteProcessIdentity {
534            kind: LASHLANG_ENGINE_KIND.to_string(),
535            label: Some(self.process_name.clone()),
536            definition: Some(lash_remote_protocol::RemoteProcessDefinitionIdentity {
537                value: self.definition(),
538            }),
539        }
540    }
541
542    pub fn to_process_input(&self) -> Result<lash_core::ProcessInput, serde_json::Error> {
543        Ok(lash_core::ProcessInput::Engine {
544            kind: LASHLANG_ENGINE_KIND.to_string(),
545            payload: serde_json::to_value(self)?,
546        })
547    }
548
549    pub fn into_process_input(self) -> Result<lash_core::ProcessInput, serde_json::Error> {
550        self.to_process_input()
551    }
552
553    pub fn remote_trigger_subscription_draft(
554        &self,
555        registrant: lash_remote_protocol::RemoteProcessOriginator,
556        env_ref: lash_remote_protocol::RemoteProcessExecutionEnvRef,
557        source_type: impl Into<String>,
558        source_key: impl Into<String>,
559    ) -> Result<lash_remote_protocol::RemoteTriggerSubscriptionDraft, serde_json::Error> {
560        Ok(
561            lash_remote_protocol::RemoteTriggerSubscriptionDraft::for_process(
562                registrant,
563                env_ref,
564                source_type,
565                source_key,
566                self.clone().try_into()?,
567                self.remote_identity(),
568            ),
569        )
570    }
571
572    pub fn from_payload(payload: serde_json::Value) -> Result<Self, serde_json::Error> {
573        serde_json::from_value(payload)
574    }
575
576    pub fn definition(&self) -> serde_json::Value {
577        serde_json::json!({
578            "module_ref": self.module_ref,
579            "process_ref": self.process_ref,
580            "host_requirements_ref": self.host_requirements_ref,
581            "process_name": self.process_name,
582        })
583    }
584}
585
586impl TryFrom<LashlangProcessInput> for lash_remote_protocol::RemoteProcessInput {
587    type Error = serde_json::Error;
588
589    fn try_from(value: LashlangProcessInput) -> Result<Self, Self::Error> {
590        Ok(Self::Engine {
591            kind: LASHLANG_ENGINE_KIND.to_string(),
592            payload: serde_json::to_value(value)?,
593        })
594    }
595}
596
597#[derive(Clone, Debug)]
598pub struct PreparedLashlangProcessStart {
599    pub registration: lash_core::ProcessRegistration,
600    pub label: Option<String>,
601}
602
603pub async fn prepare_lashlang_process_start(
604    artifact_store: Arc<dyn LashlangArtifactStore>,
605    parent_start_seed: &str,
606    start: lashlang::ProcessStart,
607) -> Result<PreparedLashlangProcessStart, String> {
608    let display_name = Some(start.process_name.clone());
609    let artifact = artifact_store
610        .get_module_artifact(&start.module_ref)
611        .await
612        .map_err(|err| format!("failed to load lashlang module artifact: {err}"))?
613        .ok_or_else(|| {
614            format!(
615                "missing lashlang module artifact `{}` for process `{}`",
616                start.module_ref, start.process_name
617            )
618        })?;
619    if artifact.host_requirements_ref != start.host_requirements_ref {
620        return Err(format!(
621            "lashlang module artifact `{}` host requirements mismatch: process requested {}, artifact has {}",
622            start.module_ref, start.host_requirements_ref, artifact.host_requirements_ref
623        ));
624    }
625    if artifact.process_ref(&start.process_name) != Some(&start.process_ref) {
626        return Err(format!(
627            "lashlang module artifact `{}` does not export process `{}` as requested ref {:?}",
628            start.module_ref, start.process_name, start.process_ref
629        ));
630    }
631    let args = match serde_json::to_value(lashlang::Value::Record(Arc::new(start.args)))
632        .map_err(|err| format!("failed to serialize process args: {err}"))?
633    {
634        serde_json::Value::Object(map) => map,
635        _ => return Err("process args must serialize as a record".to_string()),
636    };
637    let signal_event_types = artifact
638        .canonical_ir
639        .process(&start.process_name)
640        .map(lashlang_process_signal_event_types)
641        .unwrap_or_default();
642    let process_input = LashlangProcessInput {
643        module_ref: start.module_ref,
644        process_ref: start.process_ref,
645        host_requirements_ref: start.host_requirements_ref,
646        process_name: start.process_name,
647        args,
648    };
649    let identity = lashlang_process_identity(&process_input);
650    let process_id =
651        deterministic_lashlang_process_id(parent_start_seed, &start.start_site, &process_input)
652            .map_err(|err| format!("failed to derive deterministic process id: {err}"))?;
653    let process_input = process_input
654        .into_process_input()
655        .map_err(|err| format!("failed to encode process input: {err}"))?;
656    let registration = lash_core::ProcessRegistration::new(
657        process_id,
658        process_input,
659        // Lashlang engine rows are journaled and idempotent by process id, so
660        // recovery may re-execute them (ADR 0019).
661        lash_core::RecoveryDisposition::Rerunnable,
662        lash_core::ProcessProvenance::host(),
663    )
664    .with_identity(identity)
665    .with_extra_event_types(
666        lashlang_process_event_types()
667            .into_iter()
668            .chain(signal_event_types),
669    );
670    Ok(PreparedLashlangProcessStart {
671        registration,
672        label: display_name,
673    })
674}
675
676pub fn deterministic_lashlang_process_id(
677    parent_start_seed: &str,
678    start_site: &lashlang::LashlangExecutionCallSite,
679    input: &LashlangProcessInput,
680) -> Result<String, serde_json::Error> {
681    let args = serde_json::to_string(&input.args)?;
682    let occurrence = start_site.occurrence.to_string();
683    let process_ref = lashlang::process_ref_key(&input.process_ref);
684    let mut hasher = Sha256::new();
685    for part in [
686        "lashlang-process-start:v1",
687        parent_start_seed,
688        start_site.site.node_id.as_str(),
689        occurrence.as_str(),
690        input.module_ref.as_str(),
691        process_ref.as_str(),
692        input.host_requirements_ref.as_str(),
693        input.process_name.as_str(),
694        args.as_str(),
695    ] {
696        hasher.update(part.as_bytes());
697        hasher.update([0]);
698    }
699    let hash = format!("{:x}", hasher.finalize());
700    Ok(format!("process:lashlang:sha256:{hash}"))
701}
702
703pub fn resolve_lashlang_module_operation(
704    host_environment: &lashlang::LashlangHostEnvironment,
705    receiver: &lashlang::ResourceHandle,
706    operation: &str,
707) -> Result<String, lashlang::ExecutionHostError> {
708    host_environment
709        .resources
710        .resolve_module_operation(&receiver.resource_type, &receiver.alias, operation)
711        .map(|binding| binding.host_operation.clone())
712        .ok_or_else(|| {
713            lashlang::ExecutionHostError::new(format!(
714                "module `{}` of type `{}` does not expose operation `{operation}`",
715                receiver.alias, receiver.resource_type
716            ))
717        })
718}
719
720fn lashlang_process_identity(input: &LashlangProcessInput) -> lash_core::ProcessIdentity {
721    lash_core::ProcessIdentity::new(LASHLANG_ENGINE_KIND)
722        .with_label(Some(input.process_name.clone()))
723        .with_definition(Some(input.definition()))
724}
725
726#[derive(Clone)]
727pub struct LashlangProcessEngine {
728    artifact_store: Arc<dyn LashlangArtifactStore>,
729    process_cache: Arc<Mutex<CompiledProcessCache>>,
730    surface: LashlangSurface,
731    execution_sink: Option<Arc<dyn lash_trace::TraceSink>>,
732    trace_context: lash_trace::TraceContext,
733}
734
735impl LashlangProcessEngine {
736    pub fn new(artifact_store: Arc<dyn LashlangArtifactStore>, surface: LashlangSurface) -> Self {
737        Self {
738            artifact_store,
739            process_cache: Arc::new(Mutex::new(CompiledProcessCache::new())),
740            surface,
741            execution_sink: None,
742            trace_context: lash_trace::TraceContext::default(),
743        }
744    }
745
746    pub fn in_memory(surface: LashlangSurface) -> Self {
747        Self::new(
748            lashlang::global_in_memory_lashlang_artifact_store(),
749            surface,
750        )
751    }
752
753    pub fn with_execution_trace(
754        mut self,
755        sink: Option<Arc<dyn lash_trace::TraceSink>>,
756        trace_context: lash_trace::TraceContext,
757    ) -> Self {
758        self.execution_sink = sink;
759        self.trace_context = trace_context;
760        self
761    }
762
763    pub fn artifact_store(&self) -> Arc<dyn LashlangArtifactStore> {
764        Arc::clone(&self.artifact_store)
765    }
766}
767
768#[async_trait::async_trait]
769impl lash_core::ProcessEngine for LashlangProcessEngine {
770    fn kind(&self) -> &'static str {
771        LASHLANG_ENGINE_KIND
772    }
773
774    async fn validate_start(
775        &self,
776        context: lash_core::ProcessEngineValidationContext<'_>,
777        payload: &serde_json::Value,
778        _env_spec: Option<&lash_core::ProcessExecutionEnvSpec>,
779    ) -> Result<(), lash_core::PluginError> {
780        let input: LashlangProcessInput =
781            serde_json::from_value(payload.clone()).map_err(|err| {
782                lash_core::PluginError::Session(format!("invalid lashlang process payload: {err}"))
783            })?;
784        let artifact = self
785            .artifact_store
786            .get_module_artifact(&input.module_ref)
787            .await
788            .map_err(|err| lash_core::PluginError::Session(format!("load module artifact: {err}")))?
789            .ok_or_else(|| {
790                lash_core::PluginError::Session(format!(
791                    "missing lashlang module artifact `{}`",
792                    input.module_ref
793                ))
794            })?;
795        if artifact.host_requirements_ref != input.host_requirements_ref {
796            return Err(lash_core::PluginError::Session(format!(
797                "lashlang process `{}` requested surface {}, artifact has {}",
798                input.process_name, input.host_requirements_ref, artifact.host_requirements_ref
799            )));
800        }
801        if artifact.process_ref(&input.process_name) != Some(&input.process_ref) {
802            return Err(lash_core::PluginError::Session(format!(
803                "lashlang module `{}` does not export process `{}` as requested ref {:?}",
804                input.module_ref, input.process_name, input.process_ref
805            )));
806        }
807        let surface = self
808            .surface
809            .clone()
810            .for_process_registry(context.process_registry_available());
811        let host_environment = surface
812            .host_environment(context.tool_catalog())
813            .map_err(lash_core::PluginError::Session)?;
814        if let Err(err) = lashlang_host_environment_satisfies_requirements(
815            &artifact.host_requirements,
816            &host_environment,
817        ) {
818            return Err(lash_core::PluginError::Session(format!(
819                "lashlang process `{}` is incompatible with this host surface: {err}",
820                input.process_name
821            )));
822        }
823        Ok(())
824    }
825
826    async fn run(
827        &self,
828        context: lash_core::ProcessEngineRunContext<'_>,
829        payload: serde_json::Value,
830    ) -> lash_core::ProcessAwaitOutput {
831        process::run_lashlang_process(self.clone(), context, payload).await
832    }
833
834    fn identity(&self, payload: &serde_json::Value) -> lash_core::ProcessIdentity {
835        match LashlangProcessInput::from_payload(payload.clone()) {
836            Ok(input) => lashlang_process_identity(&input),
837            Err(_) => lash_core::ProcessIdentity::new(LASHLANG_ENGINE_KIND),
838        }
839    }
840
841    fn durability_tier(&self) -> lash_core::DurabilityTier {
842        lashlang_durability_tier(self.artifact_store.durability_tier())
843    }
844}
845
846mod bridge;
847mod catalogue_preview;
848mod deferred;
849mod process;
850mod typed_output;
851
852pub use bridge::{
853    lashlang_value_to_json, process_event_payload, protocol_tool_output_to_lashlang_value,
854    protocol_tool_reply_to_lashlang_value, sleep_duration_ms,
855};
856pub use catalogue_preview::{
857    CataloguePreviewEntry, CataloguePreviewOptions, DEFAULT_CATALOGUE_PREVIEW_CALL_NAME_LIMIT,
858    DEFAULT_CATALOGUE_PREVIEW_MODULE_LIMIT, catalogue_preview_contribution,
859    catalogue_preview_contribution_for_entries,
860    catalogue_preview_contribution_for_entries_with_options,
861    catalogue_preview_contribution_for_manifests, catalogue_preview_contribution_with_options,
862    catalogue_preview_entries_from_catalog_records, catalogue_preview_entries_from_manifests,
863    catalogue_preview_entry_from_catalog_record, catalogue_preview_entry_from_manifest,
864};
865pub use deferred::{
866    DeferredResolutionRecord, DeferredToolResolver, Resolution, SharedDeferredToolResolver,
867    ToolGrant, link_with_deferred_resolution, resolve_and_fold_deferred,
868};
869pub use process::{
870    lashlang_process_event_types, lashlang_process_signal_event_types, lashlang_type_expr_schema,
871};
872pub use typed_output::parse_output_schema;
873
874#[cfg(test)]
875mod tests {
876    use super::*;
877
878    #[test]
879    fn process_input_serializes_as_generic_engine_payload() {
880        let hash = lashlang::ContentHash::new("abc123");
881        let input = LashlangProcessInput {
882            module_ref: lashlang::ModuleRef::new(&hash),
883            process_ref: lashlang::ProcessRef::new(hash.clone(), 7),
884            host_requirements_ref: lashlang::HostRequirementsRef::new(&hash),
885            process_name: "main".to_string(),
886            args: serde_json::Map::from_iter([("prompt".to_string(), serde_json::json!("go"))]),
887        };
888
889        let process_input = input
890            .clone()
891            .into_process_input()
892            .expect("lashlang process input serializes");
893
894        let lash_core::ProcessInput::Engine { kind, payload } = process_input else {
895            panic!("lashlang runtime must use the generic engine process input");
896        };
897        assert_eq!(kind, LASHLANG_ENGINE_KIND);
898        assert_eq!(
899            LashlangProcessInput::from_payload(payload)
900                .expect("engine payload decodes")
901                .process_name,
902            input.process_name
903        );
904    }
905
906    #[test]
907    fn process_input_remote_helpers_use_generic_engine_and_identity() {
908        let hash = lashlang::ContentHash::new("abc123");
909        let input = LashlangProcessInput {
910            module_ref: lashlang::ModuleRef::new(&hash),
911            process_ref: lashlang::ProcessRef::new(hash.clone(), 7),
912            host_requirements_ref: lashlang::HostRequirementsRef::new(&hash),
913            process_name: "main".to_string(),
914            args: serde_json::Map::from_iter([("prompt".to_string(), serde_json::json!("go"))]),
915        };
916
917        let remote_input: lash_remote_protocol::RemoteProcessInput = input
918            .clone()
919            .try_into()
920            .expect("lashlang process input serializes remotely");
921        let lash_remote_protocol::RemoteProcessInput::Engine { kind, payload } = remote_input
922        else {
923            panic!("lashlang runtime must use the generic remote engine process input");
924        };
925        assert_eq!(kind, LASHLANG_ENGINE_KIND);
926        assert_eq!(
927            LashlangProcessInput::from_payload(payload)
928                .expect("remote payload decodes")
929                .process_name,
930            "main"
931        );
932
933        let identity = input.process_identity();
934        assert_eq!(identity.kind, LASHLANG_ENGINE_KIND);
935        assert_eq!(identity.label.as_deref(), Some("main"));
936        assert_eq!(input.remote_identity().label.as_deref(), Some("main"));
937
938        let draft = input
939            .remote_trigger_subscription_draft(
940                lash_remote_protocol::RemoteProcessOriginator::Host,
941                "process-env:sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
942                    .parse()
943                    .expect("canonical env ref"),
944                "ui.button.pressed",
945                "source-key",
946            )
947            .expect("remote trigger draft");
948        draft.validate().expect("draft validates");
949        assert_eq!(draft.target_label.as_deref(), Some("main"));
950        assert_eq!(draft.target_identity.label.as_deref(), Some("main"));
951    }
952
953    #[test]
954    fn missing_tool_binding_is_not_fabricated() {
955        let tool = lash_core::ToolDefinition::raw(
956            "tool:test/read_file",
957            "read_file",
958            "read a file",
959            lash_core::ToolDefinition::default_input_schema(),
960            serde_json::Value::Null,
961        );
962
963        let err = required_tool_lashlang_executable(&tool.manifest)
964            .expect_err("missing explicit binding should fail");
965
966        assert!(err.contains("missing an explicit `lashlang.tool` binding"));
967    }
968
969    #[test]
970    fn explicit_tool_binding_attaches_lashlang_metadata() {
971        let tool = lash_core::ToolDefinition::raw(
972            "tool:test/read_file",
973            "read_file",
974            "read a file",
975            lash_core::ToolDefinition::default_input_schema(),
976            serde_json::Value::Null,
977        )
978        .with_lashlang_binding(
979            LashlangToolBinding::new(["fs"], "read")
980                .with_authority_type("Filesystem")
981                .with_aliases(["cat"]),
982        );
983
984        let binding =
985            required_tool_lashlang_executable(&tool.manifest).expect("explicit binding resolves");
986
987        assert_eq!(binding.module_path, vec!["fs"]);
988        assert_eq!(binding.operation, "read");
989        assert_eq!(binding.authority_type, "Filesystem");
990        assert_eq!(binding.aliases, vec!["cat"]);
991    }
992
993    #[test]
994    fn dotted_operation_names_are_rejected() {
995        let tool = lash_core::ToolDefinition::raw(
996            "tool:test/update_plan",
997            "update_plan",
998            "update a plan",
999            lash_core::ToolDefinition::default_input_schema(),
1000            serde_json::Value::Null,
1001        )
1002        .with_lashlang_binding(LashlangToolBinding::new(["tools"], "update.plan"));
1003
1004        let err = required_tool_lashlang_executable(&tool.manifest)
1005            .expect_err("dotted operation cannot compile as one Lashlang operation");
1006
1007        assert!(err.contains("invalid Lashlang operation name `update.plan`"));
1008    }
1009
1010    #[test]
1011    fn manifest_lashlang_binding_accessor_reports_absent_valid_and_malformed() {
1012        let mut manifest = lash_core::ToolDefinition::raw(
1013            "tool:test/read_file",
1014            "read_file",
1015            "read a file",
1016            lash_core::ToolDefinition::default_input_schema(),
1017            serde_json::Value::Null,
1018        )
1019        .manifest;
1020        assert_eq!(manifest.lashlang_binding().expect("absent binding"), None);
1021
1022        manifest.bindings.insert(
1023            LASHLANG_TOOL_BINDING_KEY.to_string(),
1024            serde_json::json!({
1025                "module_path": ["fs"],
1026                "operation": "read"
1027            }),
1028        );
1029        let binding = manifest
1030            .lashlang_binding()
1031            .expect("valid binding")
1032            .expect("present binding");
1033        assert_eq!(binding.module_path, vec!["fs"]);
1034        assert_eq!(binding.operation.as_deref(), Some("read"));
1035
1036        manifest.bindings.insert(
1037            LASHLANG_TOOL_BINDING_KEY.to_string(),
1038            serde_json::json!({ "module_path": "fs" }),
1039        );
1040        assert!(manifest.lashlang_binding().is_err());
1041    }
1042
1043    #[test]
1044    fn remote_grant_lashlang_binding_accessor_reports_absent_valid_and_malformed() {
1045        let grant = remote_tool_grant("read_file");
1046        assert_eq!(grant.lashlang_binding().expect("absent binding"), None);
1047
1048        let grant = grant.with_lashlang_binding(LashlangToolBinding::new(["fs"], "read"));
1049        let binding = grant
1050            .lashlang_binding()
1051            .expect("valid binding")
1052            .expect("present binding");
1053        assert_eq!(binding.module_path, vec!["fs"]);
1054        assert_eq!(binding.operation.as_deref(), Some("read"));
1055
1056        let mut malformed = grant;
1057        malformed.bindings.insert(
1058            LASHLANG_TOOL_BINDING_KEY.to_string(),
1059            serde_json::json!({ "module_path": "fs" }),
1060        );
1061        assert!(malformed.lashlang_binding().is_err());
1062    }
1063
1064    #[test]
1065    fn deterministic_process_id_reuses_replayed_start_site_and_args() {
1066        let input = test_process_input(serde_json::json!({ "root": "." }));
1067        let site = test_start_site("child_process:scan", 1);
1068
1069        let first = deterministic_lashlang_process_id("parent:root", &site, &input)
1070            .expect("process id derives");
1071        let second = deterministic_lashlang_process_id("parent:root", &site, &input)
1072            .expect("process id derives");
1073
1074        assert_eq!(first, second);
1075        assert!(first.starts_with("process:lashlang:sha256:"));
1076    }
1077
1078    #[test]
1079    fn deterministic_process_id_separates_parallel_sites_ordinals_and_parents() {
1080        let input = test_process_input(serde_json::json!({ "root": "." }));
1081        let left = deterministic_lashlang_process_id(
1082            "parent:root",
1083            &test_start_site("child_process:left", 1),
1084            &input,
1085        )
1086        .expect("left id derives");
1087        let right = deterministic_lashlang_process_id(
1088            "parent:root",
1089            &test_start_site("child_process:right", 1),
1090            &input,
1091        )
1092        .expect("right id derives");
1093        let second_ordinal = deterministic_lashlang_process_id(
1094            "parent:root",
1095            &test_start_site("child_process:left", 2),
1096            &input,
1097        )
1098        .expect("second ordinal id derives");
1099        let nested_parent = deterministic_lashlang_process_id(
1100            "parent:nested",
1101            &test_start_site("child_process:left", 1),
1102            &input,
1103        )
1104        .expect("nested parent id derives");
1105
1106        assert_ne!(left, right);
1107        assert_ne!(left, second_ordinal);
1108        assert_ne!(left, nested_parent);
1109    }
1110
1111    #[tokio::test(flavor = "current_thread")]
1112    async fn prepared_start_replays_same_registration_id_without_duplicate_child_identity() {
1113        let store = Arc::new(InMemoryLashlangArtifactStore::new());
1114        let environment = LashlangHostEnvironment::new(
1115            lashlang::LashlangHostCatalog::new(),
1116            LashlangAbilities::default().with_processes(),
1117        );
1118        let output = lashlang::compile_module(lashlang::ModuleCompileRequest {
1119            source: r#"process scan(root: str) -> str { finish root }"#,
1120            environment: &environment,
1121            artifact_store: Some(store.as_ref()),
1122        })
1123        .await
1124        .expect("module compiles and persists");
1125        let artifact_store: Arc<dyn LashlangArtifactStore> = store;
1126        let site = test_start_site("child_process:scan", 1);
1127
1128        let first = prepare_lashlang_process_start(
1129            Arc::clone(&artifact_store),
1130            "parent:root",
1131            test_process_start(&output, site.clone(), "."),
1132        )
1133        .await
1134        .expect("first start prepares");
1135        let replayed = prepare_lashlang_process_start(
1136            Arc::clone(&artifact_store),
1137            "parent:root",
1138            test_process_start(&output, site.clone(), "."),
1139        )
1140        .await
1141        .expect("replayed start prepares");
1142        let sibling = prepare_lashlang_process_start(
1143            Arc::clone(&artifact_store),
1144            "parent:root",
1145            test_process_start(&output, test_start_site("child_process:scan", 2), "."),
1146        )
1147        .await
1148        .expect("sibling start prepares");
1149
1150        assert_eq!(first.registration.id, replayed.registration.id);
1151        assert_eq!(first.registration.identity, replayed.registration.identity);
1152        assert_ne!(first.registration.id, sibling.registration.id);
1153    }
1154
1155    #[test]
1156    fn surface_merges_plugin_extensions() {
1157        let contribution = LashlangSurfaceContribution::new(
1158            LashlangAbilities::default().with_processes(),
1159            LashlangLanguageFeatures::default().with_label_annotations(),
1160            LashlangHostCatalog::tool_default(["lookup"]),
1161        );
1162        let extensions = lash_core::PluginExtensions::from_contributions([
1163            lash_core::PluginExtensionContribution::new(
1164                LASHLANG_SURFACE_EXTENSION_ID,
1165                contribution,
1166            )
1167            .expect("extension payload serializes"),
1168        ]);
1169
1170        let surface = LashlangSurface::default()
1171            .with_plugin_extensions(&extensions)
1172            .expect("lashlang surface extension merges");
1173        let environment = surface
1174            .host_environment(&lash_core::ToolCatalog::default())
1175            .expect("empty tool catalog has no Lashlang bindings to validate");
1176
1177        assert!(environment.abilities.sleep);
1178        assert!(environment.abilities.processes);
1179        assert!(environment.language_features.label_annotations);
1180        assert!(
1181            environment
1182                .resources
1183                .resolve_module_operation("Tools", "tools", "lookup")
1184                .is_some()
1185        );
1186    }
1187
1188    fn remote_tool_grant(name: &str) -> lash_remote_protocol::RemoteToolGrant {
1189        lash_remote_protocol::RemoteToolGrant {
1190            protocol_version: lash_remote_protocol::REMOTE_PROTOCOL_VERSION,
1191            id: format!("remote-tool:{name}"),
1192            name: name.to_string(),
1193            description: String::new(),
1194            input_schema: lash_remote_protocol::RemoteSchemaContract {
1195                canonical: lash_core::ToolDefinition::default_input_schema(),
1196                projection: lash_remote_protocol::RemoteSchemaProjectionPolicy::default(),
1197            },
1198            output_schema: lash_remote_protocol::RemoteSchemaContract::default(),
1199            output_contract: lash_remote_protocol::RemoteToolOutputContract::Static,
1200            examples: Vec::new(),
1201            activation: None,
1202            argument_projection: None,
1203            scheduling: None,
1204            retry_policy: None,
1205            bindings: Default::default(),
1206        }
1207    }
1208
1209    fn test_process_input(args: serde_json::Value) -> LashlangProcessInput {
1210        let hash = lashlang::ContentHash::new("abc123");
1211        let args = args
1212            .as_object()
1213            .expect("test args must be an object")
1214            .clone();
1215        LashlangProcessInput {
1216            module_ref: lashlang::ModuleRef::new(&hash),
1217            process_ref: lashlang::ProcessRef::new(hash.clone(), 7),
1218            host_requirements_ref: lashlang::HostRequirementsRef::new(&hash),
1219            process_name: "scan".to_string(),
1220            args,
1221        }
1222    }
1223
1224    fn test_start_site(node_id: &str, occurrence: u64) -> lashlang::LashlangExecutionCallSite {
1225        lashlang::LashlangExecutionCallSite {
1226            site: lashlang::LashlangExecutionSite {
1227                node_id: node_id.to_string(),
1228                node_kind: "child_process".to_string(),
1229                label: "start scan".to_string(),
1230                branch: None,
1231            },
1232            occurrence,
1233        }
1234    }
1235
1236    fn test_process_start(
1237        output: &lashlang::ModuleCompileOutput,
1238        start_site: lashlang::LashlangExecutionCallSite,
1239        root: &str,
1240    ) -> lashlang::ProcessStart {
1241        let mut args = lashlang::Record::new();
1242        args.insert("root".to_string(), lashlang::Value::String(root.into()));
1243        lashlang::ProcessStart {
1244            module_ref: output.module_ref.clone(),
1245            process_ref: output
1246                .artifact
1247                .process_ref("scan")
1248                .expect("scan process export")
1249                .clone(),
1250            host_requirements_ref: output.host_requirements_ref.clone(),
1251            start_site,
1252            process_name: "scan".to_string(),
1253            args,
1254        }
1255    }
1256}
lash_lashlang_runtime/lib.rs

lash_lashlang_runtime/
lib.rs
