1use 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#[derive(Debug, Clone)]
16pub struct RunOpts {
17 pub steps: u64,
19 pub seed: Option<u64>,
21 pub n_modes: Option<usize>,
23 pub latent_dim: Option<usize>,
25 pub allow_sub_spec_dims: bool,
27 pub plan_hash: Option<String>,
29 pub requirement_id: Option<String>,
31 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#[derive(Debug, thiserror::Error)]
54pub enum OperatorError {
55 #[error(transparent)]
57 Aria(#[from] AriaError),
58 #[error("operator spec: {0}")]
60 Spec(String),
61 #[error("operator json: {0}")]
63 Json(#[from] serde_json::Error),
64 #[error("unknown binary: {0}")]
66 UnknownBinary(String),
67}
68
69impl OperatorError {
70 #[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
85pub 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
95pub 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
106pub 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 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
170fn 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)] fn 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#[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: 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 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 ix.nodes_by_kind(&allowed_tags, &mut cand);
513 ix.nodes_by_tag(&allowed_tags, &mut cand);
514 } else {
515 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 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
564fn 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}