harn-vm 0.10.168

Async bytecode virtual machine for the Harn programming language
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

//! Native pipeline settlement and finish-hook policy.

use crate::{
    value::{VmError, VmValue},
    vm::Vm,
};

pub(super) trait NativeVmLifecycle {
    fn run_pipeline_finish_lifecycle(
        &mut self,
        value: VmValue,
    ) -> impl std::future::Future<Output = Result<VmValue, VmError>> + Send;
    fn fire_finish_lifecycle_event(
        &mut self,
        event: crate::orchestration::HookEvent,
        payload: &serde_json::Value,
    ) -> impl std::future::Future<Output = Result<(), VmError>> + Send;
}

impl NativeVmLifecycle for Vm {
    /// Finish hooks run on this VM so their final output reaches the host.
    async fn run_pipeline_finish_lifecycle(&mut self, value: VmValue) -> Result<VmValue, VmError> {
        use crate::orchestration::{
            take_pipeline_on_finish, unsettled_state_snapshot_async, HookEvent,
        };
        let _tape_phase =
            crate::testbench::tape::enter_phase(crate::testbench::tape::TapePhase::RuntimeFinalize);
        let on_finish = take_pipeline_on_finish();
        let unsettled = unsettled_state_snapshot_async().await;
        let pre_payload = serde_json::json!({
            "event": HookEvent::PreFinish.as_str(),
            "return_value": crate::value::json::vm_value_to_json(&value),
            "unsettled": unsettled.to_json(),
            "has_on_finish": on_finish.is_some(),
        });
        self.fire_finish_lifecycle_event(HookEvent::PreFinish, &pre_payload)
            .await?;
        if !unsettled.is_empty() {
            let payload = serde_json::json!({
                "event": HookEvent::OnUnsettledDetected.as_str(),
                "unsettled": unsettled.to_json(),
            });
            self.fire_finish_lifecycle_event(HookEvent::OnUnsettledDetected, &payload)
                .await?;
        }
        let final_value = if let Some(closure) = on_finish {
            let harness_value = self.root_harness_value().ok_or_else(|| {
                VmError::Runtime(
                    "pipeline finish callback requires Harness, but no root Harness is installed"
                        .to_string(),
                )
            })?;
            self.call_closure_pub(&closure, &[harness_value, value])
                .await?
        } else {
            value
        };
        let post_payload = serde_json::json!({
            "event": HookEvent::PostFinish.as_str(),
            "return_value": crate::value::json::vm_value_to_json(&final_value),
            "unsettled": unsettled.to_json(),
        });
        self.fire_finish_lifecycle_event(HookEvent::PostFinish, &post_payload)
            .await?;
        Ok(final_value)
    }

    /// PreFinish rejects Block; PostFinish is advisory; unsettled work can block.
    async fn fire_finish_lifecycle_event(
        &mut self,
        event: crate::orchestration::HookEvent,
        payload: &serde_json::Value,
    ) -> Result<(), VmError> {
        use crate::orchestration::{HookControl, HookEvent};
        let invocations = crate::orchestration::matching_vm_lifecycle_hooks(event, payload);
        if invocations.is_empty() {
            return Ok(());
        }
        let harness = self.root_harness_value().ok_or_else(|| {
            VmError::Runtime(
                "pipeline lifecycle hook requires Harness, but no root Harness is installed"
                    .to_string(),
            )
        })?;
        let mut current_payload = payload.clone();
        for invocation in invocations {
            let arg = crate::value::json::json_to_vm_value(&current_payload);
            let closure = invocation.resolve(self).await?;
            let raw = self
                .call_closure_pub(&closure, &[harness.clone(), arg])
                .await?;
            let (action, effects) =
                crate::orchestration::collect_hook_effects_and_action(event, raw, VmValue::Nil)?;
            crate::orchestration::inject_hook_effects_into_current_session(effects)?;
            let control = crate::orchestration::parse_hook_control_for_finish(event, &action)?;
            match control {
                HookControl::Allow => {}
                HookControl::Block { reason } => {
                    if matches!(event, HookEvent::PreFinish) {
                        return Err(VmError::Runtime(format!(
                            "PreFinish hook returned block, which is not a valid control: {reason}. \
                             To delay pipeline finish until unsettled work clears, use \
                             OnFinish.block_until_settled (std/lifecycle) or return Modify/Allow \
                             from PreFinish."
                        )));
                    }
                    if matches!(event, HookEvent::PostFinish) {
                        continue;
                    }
                    return Err(VmError::Runtime(format!(
                        "{} hook blocked pipeline finish: {reason}",
                        event.as_str()
                    )));
                }
                HookControl::Modify { payload: modified } => current_payload = modified,
                HookControl::Decision { .. } => {}
            }
        }
        Ok(())
    }
}