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}