Skip to main content

aria_operator/
envelope.rs

1//! Closed operator document (Binary Repository v1 / sheet 09) and the frozen
2//! catalog row that defines one crate.
3
4use serde::{Deserialize, Serialize};
5use serde_json::{Map, Value};
6
7use crate::OPERATOR_ENVELOPE_V1;
8
9/// One catalog operator. Frozen into each crate's `spec.json`.
10#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
11pub struct OperatorSpec {
12    /// `BIN.*` identity.
13    pub binary_id: String,
14    /// Operator enum/name on the envelope.
15    pub operator: String,
16    /// Family / HOST / TRANSFORM / RESIDUAL / DEEP_TAG.
17    pub layer: String,
18    /// NODE / REL / TAG / PROP / ENTITY / …
19    pub class: String,
20    /// Parent family or envelope, when declared.
21    #[serde(default)]
22    pub parent: String,
23    /// Catalog crate field (underscored).
24    #[serde(rename = "crate")]
25    pub crate_name: String,
26    /// Cargo package name (hyphenated).
27    pub package: String,
28    /// `aria/people@v1` (or `pcvc/…@dev` for host tools).
29    #[serde(default)]
30    pub telemetry_fork: String,
31    /// Sheet VERIFY T/F.
32    pub verify: bool,
33    /// Whether a Neo4j template is declared (availability, never Trust).
34    pub neo4j_pass: bool,
35    /// Result-limit when the sheet gave a number.
36    #[serde(default)]
37    pub default_limit: Option<usize>,
38    /// Node kinds this operator may emit.
39    #[serde(default)]
40    pub node_types: Vec<String>,
41    /// Relationship kinds this operator may emit.
42    #[serde(default)]
43    pub relationship_types: Vec<String>,
44    /// Declared anchor tags.
45    #[serde(default)]
46    pub anchor_tags: Vec<String>,
47    /// Plan result type this operator is allowed to satisfy.
48    #[serde(default)]
49    pub result_definition_ref: String,
50    /// Catalog retrieval step (memory / lookup / lift / …).
51    #[serde(default)]
52    pub retrieval_step: String,
53    /// TRANSFORM and HOST pass the Aria graph through without a type filter.
54    #[serde(default)]
55    pub pass_through: bool,
56    /// PROP operators expose this property key only.
57    #[serde(default)]
58    pub property_key: Option<String>,
59    /// Deep-tag taxonomy block.
60    #[serde(default)]
61    pub taxonomy: Option<String>,
62    /// Residual/deep wave letter.
63    #[serde(default)]
64    pub wave: Option<String>,
65}
66
67impl OperatorSpec {
68    /// Parse one catalog / spec.json object.
69    pub fn from_catalog_value(v: Value) -> Result<Self, serde_json::Error> {
70        serde_json::from_value(v)
71    }
72}
73
74/// One typed node on the operator envelope.
75#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
76pub struct OperatorNode {
77    /// Arena id (stable within the envelope).
78    pub id: u64,
79    /// Declared kind for this operator.
80    #[serde(rename = "kind")]
81    pub kind: String,
82    /// Explicit ∪ 00c-cast tags on this node. Omitted when empty so the
83    /// default PEOPLE vertical does not grow. Mixers re-ingest this field.
84    #[serde(default, skip_serializing_if = "Vec::is_empty")]
85    pub tags: Vec<String>,
86}
87
88/// One typed relationship on the operator envelope.
89#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
90pub struct OperatorRel {
91    /// Source id.
92    pub from: u64,
93    /// Target id.
94    pub to: u64,
95    /// Declared rel type.
96    #[serde(rename = "type")]
97    pub rel_type: String,
98}
99
100/// One anchor token with its catalog weight and wave height.
101#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
102pub struct AnchorWeight {
103    /// The declared anchor tag (02 column A).
104    pub tag: String,
105    /// Category weight: # of research binaries declaring this token
106    /// ("Categories define weight for tagged activity on a map", sheet 02).
107    pub weight: u32,
108    /// Wave height ladder: A→1, B→2, C→3, D→4; 0 when no wave is declared.
109    pub height: u8,
110}
111
112/// Grammar position of this operator's return — a deterministic function of
113/// the frozen catalog, never of the payload. Carried on the wire so any
114/// graph consumer (Obsidian, PCVC, a queue) renders the result as-is instead
115/// of re-deriving the grammar. "Node vs rel vs property" is `class`; the
116/// common/uncommon split is `shape`.
117#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
118pub struct OperatorGraph {
119    /// Catalog class (NODE / REL / TAG / PROP / ENTITY / …).
120    pub class: String,
121    /// Catalog layer (ENTITY / RESIDUAL / DEEP_TAG / HOST / TRANSFORM / …).
122    pub layer: String,
123    /// Category weight: max declaring count across this operator's tokens.
124    pub weight: u32,
125    /// Height: this operator's own wave on the ladder (unwaved → 0).
126    pub height: u8,
127    /// `common` when weight ≥ 2, `uncommon` at 1, `isolated` at 0.
128    pub shape: String,
129    /// Declared anchors with their weights/heights, catalog order.
130    #[serde(default, skip_serializing_if = "Vec::is_empty")]
131    pub anchors: Vec<AnchorWeight>,
132}
133
134impl OperatorGraph {
135    /// Grammar block for one catalog row; all numbers come from the static
136    /// token statistics over the frozen catalog.
137    #[must_use]
138    pub fn from_spec(spec: &OperatorSpec) -> Self {
139        let hit = |t: &str| crate::token_stat(t);
140        let weight = spec
141            .anchor_tags
142            .iter()
143            .chain(spec.node_types.iter())
144            .chain(spec.relationship_types.iter())
145            .map(|t| hit(t).0)
146            .chain(spec.property_key.as_deref().map(|k| hit(k).0))
147            .max()
148            .unwrap_or(0);
149        let height = crate::wave_height(spec.wave.as_deref());
150        let shape = match weight {
151            0 => "isolated",
152            1 => "uncommon",
153            _ => "common",
154        }
155        .to_string();
156        let anchors = spec
157            .anchor_tags
158            .iter()
159            .map(|t| {
160                let (w, h) = hit(t);
161                AnchorWeight { tag: t.clone(), weight: w, height: h }
162            })
163            .collect();
164        Self {
165            class: spec.class.clone(),
166            layer: spec.layer.clone(),
167            weight,
168            height,
169            shape,
170            anchors,
171        }
172    }
173}
174
175/// Closed operator JSON. Unknown fields are never written.
176#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
177pub struct OperatorEnvelope {
178    /// Always [`OPERATOR_ENVELOPE_V1`].
179    pub schema: String,
180    /// Catalog `BIN.*`.
181    pub binary_id: String,
182    /// Catalog operator name.
183    pub operator: String,
184    /// Envelope semver.
185    pub schema_version: String,
186    /// Catalog crate name.
187    #[serde(rename = "crate")]
188    pub crate_name: String,
189    /// Observation Plan bind (hex). Payload hash when unbound.
190    pub plan_hash: String,
191    /// Coverage key. `"unbound"` when the host did not supply one.
192    #[serde(default, skip_serializing_if = "is_unbound")]
193    pub requirement_id: String,
194    /// Subject ids looked up.
195    #[serde(default, skip_serializing_if = "Vec::is_empty")]
196    pub subject_ids: Vec<u64>,
197    /// Plan result type.
198    #[serde(rename = "resultDefinitionRef")]
199    pub result_definition_ref: String,
200    /// Tags that justified this return.
201    #[serde(default, skip_serializing_if = "Vec::is_empty")]
202    pub anchor_tags: Vec<String>,
203    /// Neo4j availability only. Never Trust.
204    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
205    pub neo4j_hit: bool,
206    /// Operator-typed nodes.
207    #[serde(default, skip_serializing_if = "Vec::is_empty")]
208    pub nodes: Vec<OperatorNode>,
209    /// Operator-typed relationships.
210    #[serde(default, skip_serializing_if = "Vec::is_empty")]
211    pub relationships: Vec<OperatorRel>,
212    /// Operator-typed properties (PROP binaries; otherwise empty object).
213    #[serde(default, skip_serializing_if = "Map::is_empty")]
214    pub properties: Map<String, Value>,
215    /// Sheet VERIFY bit after projection.
216    pub verify: bool,
217    /// `proposal` | `no-finding` | `limitation` | `truncation` | `failure`.
218    pub coverage_state: String,
219    /// Required when `nodes` is empty and state is no-finding.
220    #[serde(skip_serializing_if = "Option::is_none")]
221    pub no_finding_reason: Option<String>,
222    /// Distinct from failure.
223    #[serde(skip_serializing_if = "Vec::is_empty", default)]
224    pub limitations: Vec<String>,
225    /// Hash of the operator payload (nodes + rels + properties), not notes.
226    pub content_hash: String,
227    /// Grammar position of this return (weight / height / anchors / shape),
228    /// deterministic from the frozen catalog. Graph-first renderers read it;
229    /// additive to sheet 09's required keys.
230    #[serde(default, skip_serializing_if = "Option::is_none")]
231    pub graph: Option<OperatorGraph>,
232    /// Shared Aria spine. Optional (sheet 09). Not an API contract.
233    #[serde(skip_serializing_if = "Option::is_none")]
234    pub telemetry: Option<Value>,
235}
236
237/// Canonical serialized key order of every envelope (all 560 operators emit
238/// this shape; members marked `?` are omitted when empty/none). Workers prune
239/// from this list — the shape is the same for every operator, so pruning is
240/// one operation, never per-binary (𝔸T6 uniform shape).
241pub const ENVELOPE_KEYS: &[(&str, bool)] = &[
242    ("schema", true),
243    ("binary_id", true),
244    ("operator", true),
245    ("schema_version", true),
246    ("crate", true),
247    ("plan_hash", true),
248    ("requirement_id", false),
249    ("subject_ids", false),
250    ("resultDefinitionRef", true),
251    ("anchor_tags", false),
252    ("neo4j_hit", false),
253    ("nodes", false),
254    ("relationships", false),
255    ("properties", false),
256    ("verify", true),
257    ("coverage_state", true),
258    ("no_finding_reason", false),
259    ("limitations", false),
260    ("content_hash", true),
261    ("graph", false),
262    ("telemetry", false),
263];
264
265impl OperatorEnvelope {
266    /// Format tag constructor helper.
267    #[must_use]
268    pub fn schema_tag() -> &'static str {
269        OPERATOR_ENVELOPE_V1
270    }
271
272    /// Working vertical: at least one node, relationship, or property.
273    /// Empty no-finding / HOST limitation / empty pass-through are skeletons
274    /// and must not ship on the production callback (PCVC, Neo4j, CLI).
275    #[must_use]
276    pub fn has_working_data(&self) -> bool {
277        !self.nodes.is_empty() || !self.relationships.is_empty() || !self.properties.is_empty()
278    }
279}
280
281fn is_unbound(s: &str) -> bool {
282    s == "unbound"
283}