feat: schema projections, command transactions, quantum-secure encryption

engram/crates/engram-projection/src/schema.rs

@@ -0,0 +1,133 @@
+/// Schema types for the projection layer.
+///
+/// A `ProjectionSchema` defines a named view over the Engram graph.
+/// It specifies which nodes are in scope and how to extract fields from them.
+use engram_core::types::MemoryTier;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::collections::HashMap;
+
+/// How the projection presents data to the caller.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ProjectionType {
+    /// Nodes as rows; edges become foreign key references.
+    /// Each row is a flat map of field_name → value.
+    Relational,
+    /// Nodes as JSON documents.
+    /// Fields are nested under a "fields" key; metadata at the top level.
+    Document,
+    /// Nodes as column families (node_id → column_name → value).
+    /// Suitable for wide, sparse schemas.
+    WideColumn,
+    /// Simple node_id → content mapping.
+    /// Ignores field mappings; raw content bytes as base64.
+    KeyValue,
+}
+
+/// Which nodes from the activation result set fall within this projection's scope.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", content = "value")]
+pub enum NodeFilter {
+    /// Include nodes whose node_type matches any of the given strings.
+    ByType(Vec<String>),
+    /// Include nodes in any of the given memory tiers.
+    ByTier(Vec<MemoryTier>),
+    /// Include nodes whose tier name contains any of the given tag strings
+    /// (stored in node metadata via content prefix convention).
+    ByTag(Vec<String>),
+    /// Include nodes with activation strength >= threshold.
+    ByActivationThreshold(f32),
+    /// Include nodes whose salience >= threshold.
+    BySalience(f32),
+    /// All of the sub-filters must match (AND).
+    Combined(Vec<NodeFilter>),
+    /// Any sub-filter matches (OR).
+    Any(Vec<NodeFilter>),
+    /// Pass all nodes through without filtering.
+    All,
+}
+
+/// Where to source a projected field's value.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", content = "value")]
+pub enum FieldSource {
+    /// Extract a value from the node's content, interpreted as JSON, using a dot-path.
+    /// E.g., "user.name" extracts `{ "user": { "name": "Alice" } }["user"]["name"]`.
+    ContentJsonPath(String),
+    /// The node's content, raw, as a UTF-8 string (lossy).
+    ContentRaw,
+    /// The node's content as a base64-encoded string.
+    ContentBase64,
+    /// The node's unique identifier.
+    NodeId,
+    /// The node's type as a string.
+    NodeType,
+    /// The node's memory tier as a string.
+    Tier,
+    /// The node's current salience score.
+    Salience,
+    /// The node's importance (caller-set, stable).
+    Importance,
+    /// The activation strength at this node (from spreading activation).
+    ActivationStrength,
+    /// The hop count from the nearest seed node.
+    Hops,
+    /// The node's creation timestamp (Unix ms).
+    CreatedAt,
+    /// The node's last-activated timestamp (Unix ms).
+    LastActivated,
+    /// The node's activation count.
+    ActivationCount,
+    /// A literal constant value.
+    Literal(Value),
+}
+
+/// One field in a projected row.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FieldMapping {
+    /// The name of this field in the projected output.
+    pub field_name: String,
+    /// Where to get the value from.
+    pub source: FieldSource,
+    /// If the source fails to produce a value, use this fallback. Null means omit.
+    pub default: Option<Value>,
+}
+
+/// A complete schema definition.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ProjectionSchema {
+    /// Unique name for this projection.
+    pub name: String,
+    /// Human-readable description.
+    pub description: Option<String>,
+    /// How results are shaped.
+    pub projection_type: ProjectionType,
+    /// Which nodes from the activation result are included.
+    pub node_filter: NodeFilter,
+    /// How to extract fields from each included node.
+    pub field_mappings: Vec<FieldMapping>,
+}
+
+/// One projected node in a Relational or Document projection.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ProjectedRow {
+    /// The source node's UUID (always included).
+    pub node_id: uuid::Uuid,
+    /// Extracted fields as ordered map field_name → value.
+    pub fields: HashMap<String, Value>,
+}
+
+/// The output of running a projection over an activation result set.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ProjectionResult {
+    /// The schema that produced this result.
+    pub schema_name: String,
+    /// How many nodes from the activation set were in scope.
+    pub nodes_in_scope: usize,
+    /// The projected rows.
+    pub rows: Vec<ProjectedRow>,
+    /// For KeyValue projection: node_id (string) → content.
+    pub key_value: Option<HashMap<String, Value>>,
+    /// For WideColumn projection: node_id → column_name → value.
+    pub wide_column: Option<HashMap<String, HashMap<String, Value>>>,
+}