Skip to main content

aria_operator/
run.rs

1//! Run Aria, then project a closed operator document.
2
3use aria_engine_backends::ipo::{canonical_json, sha256_hex, NodeRecord};
4use aria_engine_backends::telemetry::{transform, TelemetryRequest};
5use aria_engine_core::config::AriaConfig;
6use aria_engine_core::error::AriaError;
7use serde_json::{json, Map, Value};
8use std::collections::{BTreeMap, BTreeSet, HashSet};
9
10use crate::envelope::{OperatorEnvelope, OperatorNode, OperatorRel, OperatorSpec};
11use crate::index::{norm, GraphIndex};
12use crate::{OPERATOR_ENVELOPE_V1, OPERATOR_SCHEMA_VERSION};
13
14/// Options a binary or test may pin. Defaults match `aria node`.
15#[derive(Debug, Clone)]
16pub struct RunOpts {
17    /// Φ steps.
18    pub steps: u64,
19    /// Seed for byte-determinism.
20    pub seed: Option<u64>,
21    /// Optical modes. `None` uses `AriaConfig::default()`.
22    pub n_modes: Option<usize>,
23    /// Latent dim. `None` uses the config default.
24    pub latent_dim: Option<usize>,
25    /// Test-only 𝒮 escape.
26    pub allow_sub_spec_dims: bool,
27    /// Bind this plan hash. `None` hashes the payload.
28    pub plan_hash: Option<String>,
29    /// Coverage key.
30    pub requirement_id: Option<String>,
31    /// Embed `aria-telemetry-query-v1` under `telemetry` (sheet 09: optional).
32    /// Default off: the Coordinator reads the vertical. Workers that need the
33    /// spine pass `--telemetry`.
34    pub include_telemetry: bool,
35}
36
37impl Default for RunOpts {
38    fn default() -> Self {
39        Self {
40            steps: 32,
41            seed: Some(1),
42            n_modes: None,
43            latent_dim: None,
44            allow_sub_spec_dims: false,
45            plan_hash: None,
46            requirement_id: None,
47            include_telemetry: false,
48        }
49    }
50}
51
52/// Operator-layer failure. Never a Trust write.
53#[derive(Debug, thiserror::Error)]
54pub enum OperatorError {
55    /// Φ / ingest / config.
56    #[error(transparent)]
57    Aria(#[from] AriaError),
58    /// Spec JSON would not parse.
59    #[error("operator spec: {0}")]
60    Spec(String),
61    /// Envelope serialization.
62    #[error("operator json: {0}")]
63    Json(#[from] serde_json::Error),
64    /// Catalog lookup missed.
65    #[error("unknown binary: {0}")]
66    UnknownBinary(String),
67}
68
69impl OperatorError {
70    /// Coordinator exit vocabulary: 1 invariant, 2 config/spec, 3 unused here
71    /// (I/O is the CLI's job).
72    #[must_use]
73    pub fn exit_code(&self) -> i32 {
74        match self {
75            OperatorError::Aria(AriaError::InvariantViolation(_)) => 1,
76            OperatorError::Aria(AriaError::Io(_)) => 3,
77            OperatorError::Aria(_)
78            | OperatorError::Spec(_)
79            | OperatorError::Json(_)
80            | OperatorError::UnknownBinary(_) => 2,
81        }
82    }
83}
84
85/// Run the Aria transform and project this crate's closed operator JSON.
86pub fn run_spec(
87    spec_json: &str,
88    payload: &[u8],
89    opts: &RunOpts,
90) -> Result<OperatorEnvelope, OperatorError> {
91    let spec = parse_spec(spec_json)?;
92    run_operator(&spec, payload, opts)
93}
94
95/// Gateway entry: run any catalog binary by `BIN.*` id.
96pub fn run_binary(
97    binary_id: &str,
98    payload: &[u8],
99    opts: &RunOpts,
100) -> Result<OperatorEnvelope, OperatorError> {
101    let spec = crate::spec_by_id(binary_id)
102        .ok_or_else(|| OperatorError::UnknownBinary(binary_id.to_string()))?;
103    run_operator(spec, payload, opts)
104}
105
106/// One Φ, N projections. Hosted command lists compile through this.
107///
108/// This is the velocity path: Aria names operators from `commands()`, the
109/// gateway transforms the payload once, each binary remains an independent
110/// vertical (B0, B2). HOST identities always return an empty limitation
111/// envelope and never enter Φ (B6: host tools are not research operators).
112pub fn run_many(
113    binary_ids: &[String],
114    payload: &[u8],
115    opts: &RunOpts,
116) -> Result<Vec<OperatorEnvelope>, OperatorError> {
117    if binary_ids.is_empty() {
118        return Ok(Vec::new());
119    }
120    let specs: Vec<&OperatorSpec> = binary_ids
121        .iter()
122        .map(|id| {
123            crate::spec_by_id(id).ok_or_else(|| OperatorError::UnknownBinary(id.clone()))
124        })
125        .collect::<Result<_, _>>()?;
126
127    let research = specs.iter().any(|s| !is_host(s));
128    let (nodes, edges, records, telem_value) = if research {
129        let telem = transform(telemetry_request(payload, opts))?;
130        let telem_value = if opts.include_telemetry {
131            Some(serde_json::to_value(&telem)?)
132        } else {
133            None
134        };
135        (telem.graph.nodes, telem.graph.edges, telem.records, telem_value)
136    } else {
137        (Vec::new(), Vec::new(), BTreeMap::new(), None)
138    };
139    // One indexing pass; every projector below is a lookup (ℙT2).
140    let ix = GraphIndex::build(&nodes, &edges, &records);
141
142    let mut out = Vec::with_capacity(specs.len());
143    for spec in specs {
144        out.push(if is_host(spec) {
145            host_envelope(spec, payload, opts)
146        } else {
147            envelope_from(spec, &ix, telem_value.as_ref(), payload, opts)
148        });
149    }
150    Ok(out)
151}
152
153fn telemetry_request(payload: &[u8], opts: &RunOpts) -> TelemetryRequest {
154    let mut config = AriaConfig::default();
155    if let Some(n) = opts.n_modes {
156        config.n_modes = n;
157    }
158    if let Some(d) = opts.latent_dim {
159        config.latent_dim = d;
160    }
161    config.seed = opts.seed;
162    config.allow_sub_spec_dims = opts.allow_sub_spec_dims;
163    let ingest = flatten_work_telemetry(payload);
164    let mut req = TelemetryRequest::new(ingest);
165    req.config = config;
166    req.steps = opts.steps;
167    req
168}
169
170/// Map mixers (and any binary) may ingest already-processed `aria-work-v1`
171/// callback JSON. Flatten working verticals into a graph. Original payload
172/// bytes stay the plan_hash input — this is a view, not a rewrite.
173fn flatten_work_telemetry(payload: &[u8]) -> Vec<u8> {
174    let Ok(v) = serde_json::from_slice::<Value>(payload) else {
175        return payload.to_vec();
176    };
177    if v.get("schema").and_then(Value::as_str) != Some(crate::WORK_V1) {
178        return payload.to_vec();
179    }
180    let results = v.get("results").and_then(Value::as_array);
181    let Some(results) = results else {
182        return payload.to_vec();
183    };
184    let mut nodes = Vec::new();
185    let mut seen = BTreeSet::new();
186    let mut edges = Vec::new();
187    for r in results {
188        if let Some(arr) = r.get("nodes").and_then(Value::as_array) {
189            for n in arr {
190                let Some(id) = n.get("id").and_then(Value::as_u64) else { continue };
191                if !seen.insert(id) {
192                    continue;
193                }
194                let kind = n
195                    .get("kind")
196                    .or_else(|| n.get("type"))
197                    .and_then(Value::as_str)
198                    .unwrap_or("Observation");
199                let mut obj = serde_json::json!({"id": id, "type": kind, "kind": kind});
200                if let Some(tags) = n.get("tags") {
201                    obj["tags"] = tags.clone();
202                }
203                if let Some(label) = n.get("label").and_then(Value::as_str) {
204                    obj["label"] = json!(label);
205                }
206                nodes.push(obj);
207            }
208        }
209        if let Some(arr) = r.get("relationships").and_then(Value::as_array) {
210            for e in arr {
211                let (Some(from), Some(to)) = (
212                    e.get("from").and_then(Value::as_u64),
213                    e.get("to").and_then(Value::as_u64),
214                ) else {
215                    continue;
216                };
217                let ty = e
218                    .get("type")
219                    .or_else(|| e.get("rel_type"))
220                    .and_then(Value::as_str)
221                    .unwrap_or("RELATED");
222                edges.push(serde_json::json!({"from": from, "to": to, "type": ty}));
223            }
224        }
225    }
226    serde_json::to_vec(&serde_json::json!({"nodes": nodes, "edges": edges}))
227        .unwrap_or_else(|_| payload.to_vec())
228}
229
230fn is_host(spec: &OperatorSpec) -> bool {
231    spec.layer.eq_ignore_ascii_case("HOST") || spec.class.eq_ignore_ascii_case("HOST")
232}
233
234fn is_transform(spec: &OperatorSpec) -> bool {
235    spec.layer.eq_ignore_ascii_case("TRANSFORM") || spec.class.eq_ignore_ascii_case("TRANSFORM")
236}
237
238fn is_tag_op(spec: &OperatorSpec) -> bool {
239    spec.class.eq_ignore_ascii_case("TAG") || spec.layer.eq_ignore_ascii_case("DEEP_TAG")
240}
241
242fn is_refinement(spec: &OperatorSpec) -> bool {
243    spec.layer.eq_ignore_ascii_case("REFINEMENT") || spec.class.eq_ignore_ascii_case("REFINEMENT")
244}
245
246fn parse_spec(spec_json: &str) -> Result<OperatorSpec, OperatorError> {
247    let v: Value = serde_json::from_str(spec_json)
248        .map_err(|e| OperatorError::Spec(e.to_string()))?;
249    OperatorSpec::from_catalog_value(v).map_err(|e| OperatorError::Spec(e.to_string()))
250}
251
252fn run_operator(
253    spec: &OperatorSpec,
254    payload: &[u8],
255    opts: &RunOpts,
256) -> Result<OperatorEnvelope, OperatorError> {
257    if is_host(spec) {
258        return Ok(host_envelope(spec, payload, opts));
259    }
260    let telem = transform(telemetry_request(payload, opts))?;
261    let telem_value = if opts.include_telemetry {
262        Some(serde_json::to_value(&telem)?)
263    } else {
264        None
265    };
266    let ix = GraphIndex::build(&telem.graph.nodes, &telem.graph.edges, &telem.records);
267    Ok(envelope_from(spec, &ix, telem_value.as_ref(), payload, opts))
268}
269
270fn host_envelope(spec: &OperatorSpec, payload: &[u8], opts: &RunOpts) -> OperatorEnvelope {
271    let limitation = if spec.verify {
272        "HOST is not a research operator (B6 Observe-first) — empty vertical, no Φ"
273    } else {
274        "catalog VERIFY=F — operator listed but not product-accepted"
275    };
276    close_envelope(
277        spec,
278        Vec::new(),
279        Vec::new(),
280        Map::new(),
281        None,
282        payload,
283        opts,
284        false,
285        Some(limitation.into()),
286        Vec::new(),
287    )
288}
289
290fn envelope_from(
291    spec: &OperatorSpec,
292    ix: &GraphIndex<'_>,
293    telem_value: Option<&Value>,
294    payload: &[u8],
295    opts: &RunOpts,
296) -> OperatorEnvelope {
297    if is_host(spec) || !spec.verify {
298        return host_envelope(spec, payload, opts);
299    }
300    let (nodes, relationships, properties) = project(spec, ix);
301
302    let truncated = spec.default_limit.is_some_and(|lim| nodes.len() > lim);
303    let nodes = match spec.default_limit {
304        Some(lim) if nodes.len() > lim => nodes.into_iter().take(lim).collect(),
305        _ => nodes,
306    };
307    let keep: BTreeSet<u64> = nodes.iter().map(|n| n.id).collect();
308    let passthrough = is_transform(spec) && spec.pass_through;
309    let relationships: Vec<OperatorRel> = if passthrough {
310        relationships
311    } else {
312        relationships
313            .into_iter()
314            .filter(|r| keep.contains(&r.from) && keep.contains(&r.to))
315            .collect()
316    };
317
318    let extra = uncast_limitations(spec, &nodes, ix.records);
319    close_envelope(
320        spec,
321        nodes,
322        relationships,
323        properties,
324        telem_value,
325        payload,
326        opts,
327        truncated,
328        None,
329        extra,
330    )
331}
332
333fn uncast_limitations(
334    spec: &OperatorSpec,
335    nodes: &[OperatorNode],
336    records: &BTreeMap<u64, NodeRecord>,
337) -> Vec<String> {
338    if !(spec.layer.eq_ignore_ascii_case("ENTITY") || spec.class.eq_ignore_ascii_case("ENTITY")) {
339        return Vec::new();
340    }
341    if nodes.is_empty() {
342        return Vec::new();
343    }
344    let mut out = Vec::new();
345    for n in nodes {
346        let Some(rec) = records.get(&n.id) else { continue };
347        for (field, value) in crate::typecast::uncast_fields(rec) {
348            out.push(format!("uncast_token: {field}={value}"));
349        }
350    }
351    out.sort();
352    out.dedup();
353    out.truncate(8);
354    out
355}
356
357#[allow(clippy::too_many_arguments)] // envelope assembly is a closed struct lowered to args
358fn close_envelope(
359    spec: &OperatorSpec,
360    nodes: Vec<OperatorNode>,
361    relationships: Vec<OperatorRel>,
362    properties: Map<String, Value>,
363    telem_value: Option<&Value>,
364    payload: &[u8],
365    opts: &RunOpts,
366    truncated: bool,
367    force_limitation: Option<String>,
368    extra_limitations: Vec<String>,
369) -> OperatorEnvelope {
370    let passthrough = is_transform(spec) && spec.pass_through;
371    let (coverage_state, no_finding_reason, mut limitations) = if let Some(lim) = force_limitation {
372        ("limitation".to_string(), None, vec![lim])
373    } else if nodes.is_empty() && properties.is_empty() && !passthrough {
374        (
375            "no-finding".to_string(),
376            Some(format!(
377                "{} declared types not present in the Aria graph (empty is valid)",
378                spec.binary_id
379            )),
380            Vec::new(),
381        )
382    } else if truncated {
383        ("truncation".to_string(), None, Vec::new())
384    } else {
385        ("proposal".to_string(), None, Vec::new())
386    };
387    limitations.extend(extra_limitations);
388
389    let payload_obj = serde_json::json!({
390        "nodes": nodes,
391        "relationships": relationships,
392        "properties": properties,
393    });
394    let content_hash = sha256_hex(&canonical_json(&payload_obj));
395    let plan_hash = opts
396        .plan_hash
397        .clone()
398        .unwrap_or_else(|| sha256_hex(payload));
399    let requirement_id = opts
400        .requirement_id
401        .clone()
402        .unwrap_or_else(|| "unbound".into());
403    let subject_ids: Vec<u64> = nodes.iter().map(|n| n.id).collect();
404
405    OperatorEnvelope {
406        schema: OPERATOR_ENVELOPE_V1.into(),
407        binary_id: spec.binary_id.clone(),
408        operator: spec.operator.clone(),
409        schema_version: OPERATOR_SCHEMA_VERSION.into(),
410        crate_name: spec.crate_name.clone(),
411        plan_hash,
412        requirement_id,
413        subject_ids,
414        result_definition_ref: spec.result_definition_ref.clone(),
415        anchor_tags: spec.anchor_tags.clone(),
416        neo4j_hit: false,
417        nodes,
418        relationships,
419        properties,
420        verify: spec.verify,
421        coverage_state,
422        no_finding_reason,
423        limitations,
424        graph: Some(crate::envelope::OperatorGraph::from_spec(spec)),
425        content_hash,
426        telemetry: telem_value.cloned(),
427    }
428}
429
430/// Project one operator through the index. Same semantics as the historical
431/// linear scan (kind/label/`kind|type` for node types; explicit ∪ cast tags
432/// for anchors; edge type for relationships), now O(|matches|) per operator.
433/// ENTITY families then union residual/DEEP_TAG verticals (E10) without a
434/// second Φ.
435#[allow(clippy::too_many_lines)]
436fn project(
437    spec: &OperatorSpec,
438    ix: &GraphIndex<'_>,
439) -> (Vec<OperatorNode>, Vec<OperatorRel>, Map<String, Value>) {
440    let (mut nodes, relationships, properties) = project_core(spec, ix);
441    if spec.layer.eq_ignore_ascii_case("ENTITY") && spec.class.eq_ignore_ascii_case("ENTITY") {
442        let mut seen: BTreeSet<u64> = nodes.iter().map(|n| n.id).collect();
443        for child in crate::family_residuals(&spec.operator) {
444            if child.class.eq_ignore_ascii_case("REL") || child.class.eq_ignore_ascii_case("PROP")
445            {
446                continue;
447            }
448            let (extra, _, _) = project_core(child, ix);
449            for n in extra {
450                if seen.insert(n.id) {
451                    nodes.push(n);
452                }
453            }
454        }
455        nodes.sort_by_key(|n| n.id);
456    }
457    (nodes, relationships, properties)
458}
459
460fn project_core(
461    spec: &OperatorSpec,
462    ix: &GraphIndex<'_>,
463) -> (Vec<OperatorNode>, Vec<OperatorRel>, Map<String, Value>) {
464    let node_of = |i: usize| OperatorNode {
465        id: ix.nodes[i].id,
466        kind: ix.nodes[i].node_type.as_str().to_string(),
467        // Tags ride TAG / DEEP_TAG verticals only — ENTITY envelopes stay
468        // inside the 768 B PEOPLE budget (E3). Mixers re-ingest tags from
469        // the TAG envelopes on the production callback.
470        tags: if is_tag_op(spec) {
471            ix.tags_of(i).to_vec()
472        } else {
473            Vec::new()
474        },
475    };
476    let rel_of = |i: usize| OperatorRel {
477        from: ix.edges[i].from,
478        to: ix.edges[i].to,
479        rel_type: ix.edges[i].edge_type.as_str().to_string(),
480    };
481
482    if is_transform(spec) && spec.pass_through {
483        let nodes = (0..ix.nodes.len()).map(node_of).collect();
484        let rels = (0..ix.edges.len()).map(rel_of).collect();
485        return (nodes, rels, Map::new());
486    }
487
488    let mut properties = Map::new();
489    if let Some(key) = spec.property_key.as_deref() {
490        if let Some(v) = ix.first_prop(key) {
491            properties.insert(key.to_string(), v.clone());
492        }
493    }
494
495    // E5: family TAG + DEEP_TAG with no explicit tags and no 00c hits are
496    // empty. Residual TAG still matches kind.
497    if is_tag_op(spec) && !spec.layer.eq_ignore_ascii_case("RESIDUAL") && !ix.has_tags() {
498        return (Vec::new(), Vec::new(), properties);
499    }
500
501    let allowed_nodes: Vec<String> = spec.node_types.iter().map(|s| norm(s)).collect();
502    let allowed_rels: Vec<String> = spec.relationship_types.iter().map(|s| norm(s)).collect();
503    let allowed_tags: Vec<String> = spec.anchor_tags.iter().map(|s| norm(s)).collect();
504
505    let mut cand: BTreeSet<usize> = BTreeSet::new();
506    if is_refinement(spec) {
507        ix.nodes_by_kindlike(&allowed_nodes, &mut cand);
508        ix.nodes_by_tag(&allowed_tags, &mut cand);
509    } else if is_tag_op(spec) {
510        if spec.layer.eq_ignore_ascii_case("RESIDUAL") {
511            // Residual TAG.* organizes by kind or by tag (S5).
512            ix.nodes_by_kind(&allowed_tags, &mut cand);
513            ix.nodes_by_tag(&allowed_tags, &mut cand);
514        } else {
515            // Family TAG + DEEP_TAG fire on tag evidence only; role tags fire
516            // on anchors that are not their own node types (S1).
517            let fire = firing_tags(spec, &allowed_nodes);
518            let tags = if fire.is_empty() { &allowed_tags } else { &fire };
519            ix.nodes_by_tag(tags, &mut cand);
520            if !allowed_nodes.is_empty() {
521                cand.retain(|&i| ix.kindlike_hits(i, &allowed_nodes));
522            }
523        }
524    } else if spec.class != "PROP" && spec.class != "REL" && !allowed_nodes.is_empty() {
525        ix.nodes_by_kindlike(&allowed_nodes, &mut cand);
526    }
527    let nodes: Vec<OperatorNode> = cand.iter().map(|&i| node_of(i)).collect();
528
529    let is_rel = spec.class == "REL";
530    let keep: HashSet<u64> = if is_rel {
531        ix.nodes.iter().map(|n| n.id).collect()
532    } else {
533        nodes.iter().map(|n| n.id).collect()
534    };
535
536    let mut relationships: Vec<OperatorRel> = ix
537        .edges_by_rel(&allowed_rels)
538        .into_iter()
539        .filter(|&i| {
540            let e = &ix.edges[i];
541            is_rel || (keep.contains(&e.from) && keep.contains(&e.to))
542        })
543        .map(rel_of)
544        .collect();
545
546    // REL operators also list the endpoints they actually used.
547    let nodes = if is_rel {
548        let used: BTreeSet<usize> = relationships
549            .iter()
550            .flat_map(|r| [r.from, r.to])
551            .filter_map(|id| ix.idx_of(id))
552            .collect();
553        let nodes: Vec<OperatorNode> = used.into_iter().map(node_of).collect();
554        let ids: HashSet<u64> = nodes.iter().map(|n| n.id).collect();
555        relationships.retain(|r| ids.contains(&r.from) && ids.contains(&r.to));
556        nodes
557    } else {
558        nodes
559    };
560
561    (nodes, relationships, properties)
562}
563
564/// Role-tag firing set: anchors that are not the operator's own node types.
565/// BUYER anchors BUYER_TAG|PERSON|ACCOUNT with node_types Person|Account → BUYER_TAG.
566fn firing_tags(spec: &OperatorSpec, node_types: &[String]) -> Vec<String> {
567    spec.anchor_tags
568        .iter()
569        .map(|t| norm(t))
570        .filter(|t| !node_types.contains(t))
571        .collect()
572}