AdaWorldAPI
diff --git a/‎crates/ogar-from-schema/src/action_ws.rs‎
Lines changed: 379 additions & 0 deletions b/‎crates/ogar-from-schema/src/action_ws.rs‎
Lines changed: 379 additions & 0 deletions
diff --git a/‎crates/ogar-from-schema/src/lib.rs‎
Lines changed: 1 addition & 0 deletions b/‎crates/ogar-from-schema/src/lib.rs‎
Lines changed: 1 addition & 0 deletions
@@ -0,0 +1,379 @@
+//! HIRO **Action API** (`action-ws`) protocol core — the testable runtime
+//! binding for an OGAR-native ActionHandler (parity brick **B2**).
+//!
+//! This is the *protocol core* of the action-ws adapter — the typed messages
+//! plus the binding `submitAction → ActionInvocation → sendActionResult` — with
+//! **no live WebSocket and no command execution**. It is the deterministic,
+//! unit-tested heart that an outer transport (the live `tokio-tungstenite` loop)
+//! and the executor (parity brick **B1**, the `ExecTarget` runner) wrap.
+//!
+//! Source: the HIRO 7 Action API tutorial (`tutorial-action-handler-action-api`),
+//! transcribed verbatim in `docs/ARAGO-ACTIONHANDLER-PARITY.md` §2. The lifecycle
+//!
+//! ```text
+//!   engine ──submitAction──► handler ──acknowledged{200}──► engine
+//!                            handler  (execute)
+//!                            handler ──sendActionResult──►   engine ──acknowledged──►
+//! ```
+//!
+//! maps field-for-field onto OGAR's [`ActionInvocation`] Rubicon lifecycle
+//! (`Pending → Committed`): `submitAction` builds a `Pending` invocation
+//! ([`submit_to_invocation`]); the engine's final ack is the Lance commit; a
+//! `Committed` invocation yields the `sendActionResult` ([`invocation_to_result`]).
+//! Parameter binding ([`bind_parameters`]) validates the engine's `parameters`
+//! against the capability's [`ActionParam`] signature — the same check arago's
+//! Python handler performs before executing.
+
+#[cfg(feature = "serde")]
+use serde::{Deserialize, Serialize};
+
+use ogar_vocab::{
+    ActionDef, ActionInvocation, ActionState, ActionSubject, LokalSpec, ModalSpec, TemporalSpec,
+};
+
+use crate::do_arm::ActionParam;
+
+/// A `submitAction` message (engine → handler). The engine asks the handler to
+/// run `capability` on a target with the supplied `parameters`.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct SubmitAction {
+    /// Correlation id — `"$appId:$requestId"`. Carried through to the result.
+    pub id: String,
+    /// The capability requested (e.g. `"ExecuteCommand"`) — must match an
+    /// [`ActionDef::predicate`].
+    pub capability: String,
+    /// The handler id this action is routed to.
+    pub handler: String,
+    /// The instance scope (tenant).
+    pub scope: Option<String>,
+    /// The action inputs (`{host, command, user, …}`), as `(key, value)` pairs.
+    pub parameters: Vec<(String, String)>,
+    /// Per-action SLA in milliseconds.
+    pub timeout_millis: Option<i64>,
+}
+
+/// An `acknowledged` message (either direction): receipt confirmation.
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct Acknowledged {
+    /// The id of the message being acknowledged.
+    pub id: String,
+    /// Status code (`200` on success).
+    pub code: u16,
+    /// Human-readable note.
+    pub message: String,
+}
+
+/// A `sendActionResult` message (handler → engine): the outcome payload — the
+/// capability's `resultParameters` as `(key, value)` pairs.
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct SendActionResult {
+    /// The same correlation id as the originating [`SubmitAction`].
+    pub id: String,
+    /// The result fields (the `resultParameters` output signature, bound).
+    pub result: Vec<(String, String)>,
+}
+
+/// Errors in the protocol binding (the pure core — no I/O errors here).
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum ActionWsError {
+    /// `submitAction.capability` does not match the [`ActionDef`] it was routed to.
+    CapabilityMismatch {
+        /// The def's predicate.
+        expected: String,
+        /// The submitAction's capability.
+        got: String,
+    },
+    /// A mandatory parameter of the capability signature was not supplied and
+    /// has no default.
+    MissingMandatoryParam(String),
+    /// A result was requested from an invocation that has not reached
+    /// [`ActionState::Committed`] (the Rubicon crossing).
+    NotCommitted(ActionState),
+}
+
+impl core::fmt::Display for ActionWsError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            Self::CapabilityMismatch { expected, got } => {
+                write!(
+                    f,
+                    "capability mismatch: def expects `{expected}`, got `{got}`"
+                )
+            }
+            Self::MissingMandatoryParam(p) => write!(f, "missing mandatory parameter `{p}`"),
+            Self::NotCommitted(s) => write!(f, "invocation not committed (state = {s:?})"),
+        }
+    }
+}
+
+impl std::error::Error for ActionWsError {}
+
+/// The handler's immediate receipt acknowledgement (code 200), echoing the
+/// action's `id`. Sent before execution; the engine re-sends `submitAction`
+/// until this arrives (at-least-once → idempotency).
+#[must_use]
+pub fn acknowledge(msg: &SubmitAction) -> Acknowledged {
+    Acknowledged {
+        id: msg.id.clone(),
+        code: 200,
+        message: "Received the action".to_owned(),
+    }
+}
+
+/// Bind the engine-supplied `parameters` to the capability's [`ActionParam`]
+/// signature: every mandatory param must be supplied (or have a default);
+/// optional params fall back to their default when present, and are dropped
+/// when absent. Returns the bound `(name, value)` set in signature order — the
+/// same validation arago's handler runs before executing the `Command`.
+///
+/// # Errors
+///
+/// [`ActionWsError::MissingMandatoryParam`] if a mandatory param is neither
+/// supplied nor defaulted.
+pub fn bind_parameters(
+    supplied: &[(String, String)],
+    signature: &[ActionParam],
+) -> Result<Vec<(String, String)>, ActionWsError> {
+    let mut bound = Vec::with_capacity(signature.len());
+    for p in signature {
+        if let Some((_, v)) = supplied.iter().find(|(k, _)| k == &p.name) {
+            bound.push((p.name.clone(), v.clone()));
+        } else if let Some(default) = &p.default {
+            bound.push((p.name.clone(), default.clone()));
+        } else if p.mandatory {
+            return Err(ActionWsError::MissingMandatoryParam(p.name.clone()));
+        }
+        // optional + absent + no default → omitted
+    }
+    Ok(bound)
+}
+
+/// The target node an action acts on — arago routes by the `host` parameter
+/// (the MARS node); fall back to the handler id when absent.
+fn target_node(msg: &SubmitAction) -> String {
+    msg.parameters
+        .iter()
+        .find(|(k, _)| k == "host" || k == "node")
+        .map(|(_, v)| v.clone())
+        .unwrap_or_else(|| msg.handler.clone())
+}
+
+/// Build a **`Pending`** [`ActionInvocation`] from a `submitAction`, realizing
+/// `def` (whose [`predicate`](ActionDef::predicate) must equal the action's
+/// `capability`). This is the `submitAction → ActionInvocation` half of the
+/// lifecycle; the invocation then passes through the RBAC/guard/MUL gate
+/// (`commit_via` in `lance-graph-contract`) before reaching `Committed`.
+///
+/// Field mapping (`docs/ARAGO-ACTIONHANDLER-PARITY.md` §2):
+/// `capability`→`def.predicate`, `id`→`idempotency_key`, `handler`→`lokal.actor`,
+/// `scope`→`lokal.tenant`, target node→`object_instance`. Automation defaults:
+/// `subject = System`, `temporal = Deferred`, `modal = Idempotent` (at-least-once).
+///
+/// # Errors
+///
+/// [`ActionWsError::CapabilityMismatch`] if `msg.capability != def.predicate`.
+pub fn submit_to_invocation(
+    msg: &SubmitAction,
+    def: &ActionDef,
+) -> Result<ActionInvocation, ActionWsError> {
+    if msg.capability != def.predicate {
+        return Err(ActionWsError::CapabilityMismatch {
+            expected: def.predicate.clone(),
+            got: msg.capability.clone(),
+        });
+    }
+    let object_instance = target_node(msg);
+    let identity = format!("{}::invocation::{}", def.object_class, msg.id);
+    let mut inv = ActionInvocation::new(identity, def.identity.clone(), object_instance);
+    inv.subject = ActionSubject::System;
+    inv.temporal = TemporalSpec::Deferred;
+    inv.modal = ModalSpec::Idempotent;
+    inv.state = ActionState::Pending;
+    inv.idempotency_key = Some(msg.id.clone());
+    // LokalSpec is #[non_exhaustive] — build via Default + field set, not a literal.
+    let mut lokal = LokalSpec::default();
+    lokal.actor = Some(msg.handler.clone());
+    lokal.tenant = msg.scope.clone();
+    inv.lokal = lokal;
+    Ok(inv)
+}
+
+/// Build the `sendActionResult` from a **`Committed`** invocation plus the
+/// executor's result payload (the bound `resultParameters`). Only a committed
+/// invocation (the Rubicon crossing) yields a result — a `Pending` / `Failed` /
+/// `Cancelled` invocation has nothing to report on the success path.
+///
+/// # Errors
+///
+/// [`ActionWsError::NotCommitted`] if the invocation has not reached
+/// [`ActionState::Committed`].
+pub fn invocation_to_result(
+    inv: &ActionInvocation,
+    result: Vec<(String, String)>,
+) -> Result<SendActionResult, ActionWsError> {
+    if inv.state != ActionState::Committed {
+        return Err(ActionWsError::NotCommitted(inv.state));
+    }
+    Ok(SendActionResult {
+        id: inv.idempotency_key.clone().unwrap_or_default(),
+        result,
+    })
+}
+
+// ───────────────────────────────────────────────────────────── tests ──
+//
+// The pure protocol core: the full submitAction → bind → invocation(Pending)
+// → (Committed) → sendActionResult flow, deterministic and socket-free.
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// An ExecuteCommand-shaped capability signature (the arago SSH handler):
+    /// mandatory `command`, optional `timeout` defaulting to `60000`.
+    fn execute_command_signature() -> Vec<ActionParam> {
+        vec![
+            ActionParam {
+                name: "command".to_owned(),
+                mandatory: true,
+                default: None,
+            },
+            ActionParam {
+                name: "timeout".to_owned(),
+                mandatory: false,
+                default: Some("60000".to_owned()),
+            },
+        ]
+    }
+
+    fn execute_command_def() -> ActionDef {
+        ActionDef::new(
+            "ogit-automation/action_capability::action_def::ExecuteCommand",
+            "ExecuteCommand",
+            "ogit-automation/mars_machine",
+        )
+    }
+
+    fn submit() -> SubmitAction {
+        SubmitAction {
+            id: "app1:req42".to_owned(),
+            capability: "ExecuteCommand".to_owned(),
+            handler: "handler-7".to_owned(),
+            scope: Some("tenant-A".to_owned()),
+            parameters: vec![
+                ("host".to_owned(), "node-9".to_owned()),
+                ("command".to_owned(), "uptime".to_owned()),
+            ],
+            timeout_millis: Some(60_000),
+        }
+    }
+
+    #[test]
+    fn acknowledge_echoes_id_with_200() {
+        let ack = acknowledge(&submit());
+        assert_eq!(ack.id, "app1:req42");
+        assert_eq!(ack.code, 200);
+    }
+
+    #[test]
+    fn bind_parameters_fills_default_and_keeps_supplied() {
+        let bound =
+            bind_parameters(&submit().parameters, &execute_command_signature()).expect("binds");
+        // `command` supplied, `timeout` defaulted; signature order preserved.
+        assert_eq!(
+            bound,
+            vec![
+                ("command".to_owned(), "uptime".to_owned()),
+                ("timeout".to_owned(), "60000".to_owned()),
+            ]
+        );
+    }
+
+    #[test]
+    fn bind_parameters_rejects_missing_mandatory() {
+        let supplied = vec![("timeout".to_owned(), "5".to_owned())];
+        let err = bind_parameters(&supplied, &execute_command_signature()).unwrap_err();
+        assert_eq!(
+            err,
+            ActionWsError::MissingMandatoryParam("command".to_owned())
+        );
+    }
+
+    #[test]
+    fn submit_builds_pending_invocation_with_provenance() {
+        let inv = submit_to_invocation(&submit(), &execute_command_def()).expect("builds");
+        assert_eq!(inv.state, ActionState::Pending);
+        assert_eq!(inv.object_instance, "node-9"); // routed by the `host` param
+        assert_eq!(inv.idempotency_key.as_deref(), Some("app1:req42"));
+        assert_eq!(inv.action_def, execute_command_def().identity);
+        assert_eq!(inv.lokal.actor.as_deref(), Some("handler-7"));
+        assert_eq!(inv.lokal.tenant.as_deref(), Some("tenant-A"));
+        assert!(matches!(inv.modal, ModalSpec::Idempotent));
+    }
+
+    #[test]
+    fn submit_rejects_capability_mismatch() {
+        let mut bad = submit();
+        bad.capability = "RunScript".to_owned();
+        let err = submit_to_invocation(&bad, &execute_command_def()).unwrap_err();
+        assert_eq!(
+            err,
+            ActionWsError::CapabilityMismatch {
+                expected: "ExecuteCommand".to_owned(),
+                got: "RunScript".to_owned(),
+            }
+        );
+    }
+
+    #[test]
+    fn committed_invocation_yields_result_pending_does_not() {
+        let mut inv = submit_to_invocation(&submit(), &execute_command_def()).expect("builds");
+
+        // Pending → no result on the success path.
+        let pending = invocation_to_result(&inv, vec![]);
+        assert_eq!(
+            pending.unwrap_err(),
+            ActionWsError::NotCommitted(ActionState::Pending)
+        );
+
+        // The Rubicon crossing (the gate would set this) → result emitted.
+        inv.state = ActionState::Committed;
+        let result = invocation_to_result(
+            &inv,
+            vec![("output".to_owned(), "12:00 up 3 days".to_owned())],
+        )
+        .expect("committed → result");
+        assert_eq!(result.id, "app1:req42"); // correlation id round-trips
+        assert_eq!(
+            result.result,
+            vec![("output".to_owned(), "12:00 up 3 days".to_owned())]
+        );
+    }
+
+    /// The whole loop, end-to-end (socket-free): submit → ack → bind → invoke
+    /// → commit → result, with the `id` correlating throughout.
+    #[test]
+    fn full_action_ws_roundtrip() {
+        let msg = submit();
+        let def = execute_command_def();
+
+        let ack = acknowledge(&msg);
+        assert_eq!(ack.code, 200);
+
+        let _bound = bind_parameters(&msg.parameters, &execute_command_signature()).expect("bind");
+
+        let mut inv = submit_to_invocation(&msg, &def).expect("invoke");
+        assert_eq!(inv.state, ActionState::Pending);
+
+        // (the executor + commit_via gate run here; we simulate the crossing)
+        inv.state = ActionState::Committed;
+
+        let result = invocation_to_result(&inv, vec![("exitcode".to_owned(), "0".to_owned())])
+            .expect("result");
+        assert_eq!(result.id, msg.id);
+    }
+}
@@ -57,6 +57,7 @@
 
 use ogar_vocab::{Attribute, Class, EnumDecl, EnumSource, Language};
 
+pub mod action_ws;
 pub mod do_arm;
 pub mod sgo;
 pub mod ttl;