action_ws: harvest the HIRO 7.0 dev-portal specs — spec-faithful protocol core

Harvested the authoritative machine-readable contract from the HIRO 7.0 dev
portal (core.engine.datagroup.de/help/specs/definitions/{action-ws,action}.yaml)
and folded the corrections into the action-ws core, so it now matches the spec
rather than the tutorial-only first pass.

Corrections the spec forced:
- result is a SINGLE STRING (<= 1048576 chars), not an object: SendActionResult.result
  is now String; invocation_to_result JSON-encodes the bound resultParameters via
  a new minimal escaping json_object(); MAX_RESULT_LEN + ResultTooLarge guard.
- id is 12-256 chars: validate_id() + InvalidId.
- three missing message types added: NegativeAcknowledged {id,code,message},
  ConfigChanged (re-fetch capabilities), InboundError {code,message}.

New connection facts captured (for B2-transport):
- ACTION_WS_PATH = "/api/action-ws/1.0/connect"
- auth_subprotocol(token) = "token-$TOKEN" (the sec-websocket-protocol header)
- registration is REST (GET /capabilities, /applicabilities), NOT a WS handshake;
  configChanged just signals a re-fetch. The REST view lifts straight into
  do_arm::assemble_action_handler's ActionHandlerSpec (the B2-lift brick).

38 do_arm/action_ws tests green (4 new: nack, validate_id, json_object escaping,
auth_subprotocol) under default AND serde features; action_ws clippy-clean.

Docs: ARAGO-ACTIONHANDLER-PARITY §2a (the full harvested contract + the
corrections) + §6 spec URLs; D-ACTIONHANDLER-PARITY row updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EYvNjD8M8LMNYbRy3gq2FP

Author: claude

crates/ogar-from-schema/src/action_ws.rs

@@ -33,6 +33,23 @@ use ogar_vocab::{
 
 use crate::do_arm::ActionParam;
 
+/// The `action-ws` WebSocket connect path (HIRO Action API 1.0). The full URL is
+/// `wss://<host>/api/action-ws/1.0/connect`.
+pub const ACTION_WS_PATH: &str = "/api/action-ws/1.0/connect";
+
+/// The WebSocket subprotocol header value carrying the auth token — HIRO passes
+/// the token as `sec-websocket-protocol: token-$TOKEN`.
+#[must_use]
+pub fn auth_subprotocol(token: &str) -> String {
+    format!("token-{token}")
+}
+
+/// Spec bounds on a `submitAction` / `sendActionResult` correlation `id`
+/// (12–256 chars). [`validate_id`] enforces it.
+pub const ID_MIN_LEN: usize = 12;
+/// Upper bound on the correlation `id` length (spec).
+pub const ID_MAX_LEN: usize = 256;
+
 /// 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)]
@@ -65,15 +82,55 @@ pub struct Acknowledged {
     pub message: String,
 }
 
-/// A `sendActionResult` message (handler → engine): the outcome payload — the
-/// capability's `resultParameters` as `(key, value)` pairs.
+/// A `sendActionResult` message (handler → engine): the outcome payload.
+///
+/// Per the `action-ws` spec the `result` is a **single string** (max
+/// `1048576` chars) — the capability's `resultParameters` JSON-encoded into one
+/// field (build it with [`json_object`]). The engine replies `acknowledged` /
+/// `negativeAcknowledged`.
 #[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)>,
+    /// The result value — a JSON object string of the bound `resultParameters`
+    /// (spec: `string`, max 1 MiB).
+    pub result: String,
+}
+
+/// Max length of the [`SendActionResult::result`] string (spec: `1048576`).
+pub const MAX_RESULT_LEN: usize = 1_048_576;
+
+/// A `negativeAcknowledged` message (engine ↔ handler): receipt *rejection*
+/// (e.g. `code = 400`). The negative twin of [`Acknowledged`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct NegativeAcknowledged {
+    /// The id of the message being rejected.
+    pub id: String,
+    /// Error code (e.g. `400`).
+    pub code: u16,
+    /// Error description.
+    pub message: String,
+}
+
+/// A `configChanged` notification (engine → handler): the handler's
+/// capabilities / applicabilities changed; the handler must re-fetch them from
+/// the REST Action API (`GET /capabilities`, `GET /applicabilities`). Carries
+/// no payload beyond `type`; the handler replies `acknowledged`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct ConfigChanged;
+
+/// An asynchronous `error` message (engine → handler) — not tied to a specific
+/// request id.
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct InboundError {
+    /// Error code.
+    pub code: u16,
+    /// Error details.
+    pub message: String,
 }
 
 /// Errors in the protocol binding (the pure core — no I/O errors here).
@@ -93,6 +150,12 @@ pub enum ActionWsError {
     /// A result was requested from an invocation that has not reached
     /// [`ActionState::Committed`] (the Rubicon crossing).
     NotCommitted(ActionState),
+    /// A correlation `id` outside the spec bounds (12–256 chars); carries the
+    /// offending length.
+    InvalidId(usize),
+    /// The encoded `result` exceeds [`MAX_RESULT_LEN`] (spec: 1 MiB); carries the
+    /// offending length.
+    ResultTooLarge(usize),
 }
 
 impl core::fmt::Display for ActionWsError {
@@ -106,6 +169,8 @@ impl core::fmt::Display for ActionWsError {
             }
             Self::MissingMandatoryParam(p) => write!(f, "missing mandatory parameter `{p}`"),
             Self::NotCommitted(s) => write!(f, "invocation not committed (state = {s:?})"),
+            Self::InvalidId(n) => write!(f, "correlation id length {n} out of bounds (12..=256)"),
+            Self::ResultTooLarge(n) => write!(f, "result length {n} exceeds 1 MiB"),
         }
     }
 }
@@ -124,6 +189,70 @@ pub fn acknowledge(msg: &SubmitAction) -> Acknowledged {
     }
 }
 
+/// Reject a message by id (the `negativeAcknowledged` twin of [`acknowledge`]).
+#[must_use]
+pub fn negative_acknowledge(
+    id: &str,
+    code: u16,
+    message: impl Into<String>,
+) -> NegativeAcknowledged {
+    NegativeAcknowledged {
+        id: id.to_owned(),
+        code,
+        message: message.into(),
+    }
+}
+
+/// Validate a correlation `id` against the spec bounds (12–256 chars).
+///
+/// # Errors
+///
+/// [`ActionWsError::InvalidId`] when the length is out of range.
+pub fn validate_id(id: &str) -> Result<(), ActionWsError> {
+    if (ID_MIN_LEN..=ID_MAX_LEN).contains(&id.len()) {
+        Ok(())
+    } else {
+        Err(ActionWsError::InvalidId(id.len()))
+    }
+}
+
+/// Encode `(key, value)` pairs as a JSON object string — the wire form of the
+/// [`SendActionResult::result`] field (the bound `resultParameters`). A minimal,
+/// correctly-escaping encoder; the live transport may use `serde_json` instead.
+#[must_use]
+pub fn json_object(pairs: &[(String, String)]) -> String {
+    let mut s = String::from("{");
+    for (i, (k, v)) in pairs.iter().enumerate() {
+        if i > 0 {
+            s.push(',');
+        }
+        json_string(k, &mut s);
+        s.push(':');
+        json_string(v, &mut s);
+    }
+    s.push('}');
+    s
+}
+
+/// Append `raw` as a JSON string literal (RFC 8259 escaping) to `out`.
+fn json_string(raw: &str, out: &mut String) {
+    out.push('"');
+    for c in raw.chars() {
+        match c {
+            '"' => out.push_str("\\\""),
+            '\\' => out.push_str("\\\\"),
+            '\n' => out.push_str("\\n"),
+            '\r' => out.push_str("\\r"),
+            '\t' => out.push_str("\\t"),
+            c if (c as u32) < 0x20 => {
+                out.push_str(&format!("\\u{:04x}", c as u32));
+            }
+            c => out.push(c),
+        }
+    }
+    out.push('"');
+}
+
 /// 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
@@ -213,11 +342,17 @@ pub fn submit_to_invocation(
 /// [`ActionState::Committed`].
 pub fn invocation_to_result(
     inv: &ActionInvocation,
-    result: Vec<(String, String)>,
+    result_params: &[(String, String)],
 ) -> Result<SendActionResult, ActionWsError> {
     if inv.state != ActionState::Committed {
         return Err(ActionWsError::NotCommitted(inv.state));
     }
+    // The spec's `result` is a single string (max 1 MiB) — JSON-encode the bound
+    // resultParameters into it.
+    let result = json_object(result_params);
+    if result.len() > MAX_RESULT_LEN {
+        return Err(ActionWsError::ResultTooLarge(result.len()));
+    }
     Ok(SendActionResult {
         id: inv.idempotency_key.clone().unwrap_or_default(),
         result,
@@ -334,26 +469,64 @@ mod tests {
         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![]);
+        let pending = invocation_to_result(&inv, &[]);
         assert_eq!(
             pending.unwrap_err(),
             ActionWsError::NotCommitted(ActionState::Pending)
         );
 
-        // The Rubicon crossing (the gate would set this) → result emitted.
+        // The Rubicon crossing (the gate would set this) → result emitted as a
+        // JSON object string (the spec's single `result` field).
         inv.state = ActionState::Committed;
-        let result = invocation_to_result(
-            &inv,
-            vec![("output".to_owned(), "12:00 up 3 days".to_owned())],
-        )
-        .expect("committed → result");
+        let result =
+            invocation_to_result(&inv, &[("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, r#"{"output":"12:00 up 3 days"}"#);
+    }
+
+    #[test]
+    fn negative_acknowledge_carries_code_and_message() {
+        let nack = negative_acknowledge("app1:req42", 400, "bad capability");
+        assert_eq!(nack.id, "app1:req42");
+        assert_eq!(nack.code, 400);
+        assert_eq!(nack.message, "bad capability");
+    }
+
+    #[test]
+    fn validate_id_enforces_spec_bounds() {
+        assert!(validate_id("123456789012").is_ok()); // 12 chars (min)
+        assert_eq!(
+            validate_id("short").unwrap_err(),
+            ActionWsError::InvalidId(5)
+        );
+        let too_long = "x".repeat(257);
         assert_eq!(
-            result.result,
-            vec![("output".to_owned(), "12:00 up 3 days".to_owned())]
+            validate_id(&too_long).unwrap_err(),
+            ActionWsError::InvalidId(257)
         );
     }
 
+    #[test]
+    fn json_object_escapes_correctly() {
+        // Empty, simple, and escape-needing values.
+        assert_eq!(json_object(&[]), "{}");
+        assert_eq!(
+            json_object(&[("k".to_owned(), "v".to_owned())]),
+            r#"{"k":"v"}"#
+        );
+        assert_eq!(
+            json_object(&[("out".to_owned(), "a\"b\\c\nd".to_owned())]),
+            r#"{"out":"a\"b\\c\nd"}"#
+        );
+    }
+
+    #[test]
+    fn auth_subprotocol_prefixes_the_token() {
+        assert_eq!(auth_subprotocol("abc123"), "token-abc123");
+        assert_eq!(ACTION_WS_PATH, "/api/action-ws/1.0/connect");
+    }
+
     /// The whole loop, end-to-end (socket-free): submit → ack → bind → invoke
     /// → commit → result, with the `id` correlating throughout.
     #[test]
@@ -372,8 +545,9 @@ mod tests {
         // (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");
+        let result =
+            invocation_to_result(&inv, &[("exitcode".to_owned(), "0".to_owned())]).expect("result");
         assert_eq!(result.id, msg.id);
+        assert_eq!(result.result, r#"{"exitcode":"0"}"#);
     }
 }

docs/ARAGO-ACTIONHANDLER-PARITY.md

@@ -104,6 +104,47 @@ needs a type OGAR lacks — only the *glue* (§3) is unbuilt.
 
 ---
 
+## 2a. The harvested authoritative contract (`action-ws.yaml` + `action.yaml`)
+
+Harvested from the HIRO 7.0 dev-portal machine-readable specs
+(`core.engine.datagroup.de/help/specs/definitions/{action-ws,action}.yaml`).
+This is the **complete** message set + connection + registration model the OGAR
+`action_ws` module is built to (corrections folded in — the earlier `result{…}`
+object framing from the tutorial is superseded by the spec's `result: string`).
+
+**Connection.** `wss://<host>/api/action-ws/1.0/connect` — token passed as the
+WebSocket subprotocol `sec-websocket-protocol: token-$TOKEN`. (`action_ws::{ACTION_WS_PATH,
+auth_subprotocol}`.)
+
+**The six message types** (✓ = modelled in `action_ws`):
+
+| type | dir | fields | OGAR type |
+|---|---|---|---|
+| `submitAction` | engine → handler | `id` (12–256), `handler`, `capability`, `parameters` (obj), `timeout` (ms) | `SubmitAction` ✓ |
+| `sendActionResult` | handler → engine | `id`, `result` (**string**, ≤ `1048576`) | `SendActionResult` ✓ (`result` = `json_object(resultParams)`) |
+| `acknowledged` | both | `id`, `code` (200), `message` | `Acknowledged` ✓ (`acknowledge`) |
+| `negativeAcknowledged` | both | `id`, `code` (e.g. 400), `message` | `NegativeAcknowledged` ✓ (`negative_acknowledge`) |
+| `configChanged` | engine → handler | `type` only → re-fetch capabilities | `ConfigChanged` ✓ |
+| `error` | engine → handler | `code`, `message` (no `id`) | `InboundError` ✓ |
+
+**Corrections the spec forced** (vs the tutorial-only first pass): `result` is a
+**single string** (≤ 1 MiB), not an object — `invocation_to_result` JSON-encodes
+the bound `resultParameters` into it (`MAX_RESULT_LEN`, `ResultTooLarge`); `id`
+is **12–256 chars** (`validate_id`, `InvalidId`); the nack / configChanged /
+error message types now exist.
+
+**Registration is REST, not a WS handshake.** A handler's capabilities and
+applicabilities live in the graph and are read via the REST **Action API**
+(`/api/action/1.0/`, Bearer token): `GET /capabilities` →
+`MapOfCapabilities` (each `{description, mandatoryParameters, optionalParameters}`),
+`GET /applicabilities` → `MapOfApplicabilities` (keyed by handler id). The
+`action-ws` socket has **no registration message** — `configChanged` just tells
+the handler to re-`GET` them. This is exactly the `do_arm::assemble_action_handler`
+shape (handler → applicabilities → capabilities), so the REST registration view
+lifts straight into `ActionHandlerSpec` (the B2-lift brick).
+
+---
+
 ## 3. The switch path — replacing the Python daemon with OGAR
 
 To "switch from Python to OGAR running it here," one OGAR-side component
@@ -210,3 +251,8 @@ is replaceable; the parity claim is certified, not argued.
 - `rs-graph-llm/graph-flow-action` — the `ActionHandler` executor trait (B1 home).
 - arago: `github.com/arago/ActionHandlers`,
   `arago/python-hiro-stonebranch-actionhandler`, HIRO 7 Action API tutorial.
+- **HIRO 7.0 dev-portal specs (the authoritative harvest, §2a):**
+  `core.engine.datagroup.de/help/specs/definitions/action-ws.yaml` (the
+  WebSocket message contract), `…/action.yaml` (the REST registration API),
+  `…/auth.yaml` (the token endpoint). Indexed at
+  `dev-portal.engine.datagroup.de/7.0/api/`.

docs/DISCOVERY-MAP.md

@@ -210,7 +210,7 @@ two halves of a cell. ADR‑026 names the cascade that ties them.
 | D‑ELIXIR | Elixir/HIRO SchemaSource scaffold (`gen_statem`→Rubicon) | G | CODED (scaffold) | `ogar-from-elixir/` | D‑VOCAB |
 | D‑HIRO‑DO | OGIT Automation → DO arm: `into_action_def` lifts `KnowledgeItem`→`ActionDef` (object_class←`relates`, kausal←`contains Trigger`, body **pointed‑to** not inlined — lossless‑DO §1); schema half of `PROBE‑OGAR‑DO‑ARM‑LIFT` green; lift→`emit_action_def`→SPO triples proven end‑to‑end (`tests/do_arm_emit.rs`, lossless‑DO holds across emit) | G | CODED (schema half) | `ogar-from-schema/src/do_arm.rs` | D‑VOCAB, D‑TTL, D‑ELIXIR, D‑EMIT |
 | D‑MARS‑CLASSID | MARS/Automation classids MINTED: `ConceptDomain::Automation` (0x0C), 9 concepts (`mars_application/resource/software/machine` 0x0C01‑04, `knowledge_item` 05, `mars_node_template` 06, `action_handler` 07, `action_applicability` 08, `automation_trigger` 09) — one domain spanning MARS structural CMDB + Automation DO‑arm (Auth precedent); resolves MARS‑TRANSCODING §1 deferral; passed 5+3 hardening (theorem/doctrine/integration/runtime savants + drift‑guards). Reserves the speculative rest | G | CODED | `ogar-vocab/src/lib.rs`, `ogar-class-view/src/lib.rs` | D‑VOCAB, D‑HIRO‑DO |
-| D‑ACTIONHANDLER‑PARITY | arago HIRO ActionHandler ⟷ OGAR: `assemble_action_handler` walks the OGIT `provides` graph (`ActionHandler→ActionApplicability→ActionCapability`) into `ActionHandlerSpec`/`CapabilitySlot`/`ApplicabilitySlot`/`ActionParam`. Config+ontology+`action-ws` protocol all map to OGAR types: arago `ModelFilter{Var,Mode,Value}`→`StateGuard`; `Capability.Name`→`predicate`; `resultParameters`→output sig; `action-ws` `submitAction→ack→sendActionResult` ⟷ `ActionInvocation` `Pending→Committed` (`commit_via` is the gate). **B2 protocol core SHIPPED** (`action_ws`: typed messages + `submit_to_invocation`/`bind_parameters`/`invocation_to_result`, socket-free, `full_action_ws_roundtrip` proven). Remaining: B1 executor + B2-transport (live WS) + B2-lift (YAML), gated on `PROBE‑OGAR‑ACTIONHANDLER‑RUN` | G (contract+protocol) / H (live runtime) | CODED | `ogar-from-schema/src/{do_arm,action_ws}.rs`, `docs/ARAGO-ACTIONHANDLER-PARITY.md` | D‑HIRO‑DO, D‑MARS‑CLASSID |
+| D‑ACTIONHANDLER‑PARITY | arago HIRO ActionHandler ⟷ OGAR: `assemble_action_handler` walks the OGIT `provides` graph (`ActionHandler→ActionApplicability→ActionCapability`) into `ActionHandlerSpec`/`CapabilitySlot`/`ApplicabilitySlot`/`ActionParam`. Config+ontology+`action-ws` protocol all map to OGAR types: arago `ModelFilter{Var,Mode,Value}`→`StateGuard`; `Capability.Name`→`predicate`; `resultParameters`→output sig; `action-ws` `submitAction→ack→sendActionResult` ⟷ `ActionInvocation` `Pending→Committed` (`commit_via` is the gate). **B2 protocol core SHIPPED + spec-faithful** (`action_ws`: all 6 `action-ws.yaml` message types — submitAction/sendActionResult/acknowledged/negativeAcknowledged/configChanged/error — + `submit_to_invocation`/`bind_parameters`/`invocation_to_result` (result=JSON string ≤1 MiB per spec) + connection consts (`ACTION_WS_PATH`, `auth_subprotocol`, `validate_id`); socket-free, `full_action_ws_roundtrip` proven; harvested from the HIRO 7.0 dev-portal specs §2a). Remaining: B1 executor + B2-transport (live WS) + B2-lift (REST registration→`ActionHandlerSpec`), gated on `PROBE‑OGAR‑ACTIONHANDLER‑RUN` | G (contract+protocol) / H (live runtime) | CODED | `ogar-from-schema/src/{do_arm,action_ws}.rs`, `docs/ARAGO-ACTIONHANDLER-PARITY.md` | D‑HIRO‑DO, D‑MARS‑CLASSID |
 | D‑OSM | `ogar-from-osm-pbf` — Node/Way/Relation; quadkey NiblePath from resolved geometry | H | IDEA | (queued) | D‑VOCAB, `[per rt]` D‑OSM‑3 |
 | D‑PATTERN | `ogar-pattern` — recognition library + confidence (FMA‑D/FIBO/SKR/PROV‑O) | H | IDEA | (queued) | D‑TTL |
 | D‑ACTION | `ogar-actionable` — lifecycle → `ActionDef`/`KausalSpec` | H | IDEA | (queued) | D‑PATTERN |