Grammar v0.4.0: Agent ergonomics — send-to, @ref, query_trace

Section 20 (Agent Ergonomics) — features designed by an LLM for LLMs:

send-to syntax: `send message to target` alongside `send(target, message)`.
Natural language order for agents; function-call order preserved for compat.
Parser detects form and normalises argument order in AST.

@ref annotations: `@ref("key")` — pointers from code to VeriSimDB entries.
Agents don't need inline comments; they need queryable documentation.
Code stays clean (fewer tokens), rationale lives in database.
Collected in Program.annotations, no operational semantics.

query_trace: `query_trace("branch_label", given_context)` — look up prior
decisions in the trace database. Returns Data record if found, Unit if not.
Harvard-safe (returns Data). Enables explicit trace memoization beyond
the `cached` keyword.

176 tests (169 + 7 new). Zero clippy warnings.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

crates/oo7-core/src/ast.rs

@@ -17,6 +17,18 @@ use serde::{Deserialize, Serialize};
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Program {
     pub declarations: Vec<TopLevelDecl>,
+    /// Collected @ref annotations (Section 20: Agent Ergonomics).
+    /// These have no operational semantics; metadata for agent consumers.
+    #[serde(default)]
+    pub annotations: Vec<RefAnnotation>,
+}
+
+/// Reference annotation: @ref("key") — points to VeriSimDB documentation entry.
+/// Has no operational semantics; metadata for agent consumers.
+/// Part of Section 20: Agent Ergonomics.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RefAnnotation {
+    pub key: String,
 }
 
 /// Top-level declarations.
@@ -377,6 +389,12 @@ pub enum ControlExpr {
     Record(Vec<(String, ControlExpr)>),
     /// List literal in control context
     List(Vec<ControlExpr>),
+    /// query_trace("label", context) — look up prior decision in trace database.
+    /// Section 20: Agent Ergonomics. Harvard-safe: returns Data.
+    QueryTrace {
+        label: String,
+        context: Box<DataExpr>,
+    },
 }
 
 /// Either a single expression or a block of statements.

crates/oo7-core/src/eval.rs

@@ -982,6 +982,39 @@ impl Evaluator {
 
             ControlExpr::Migrate { .. } => RtValue::Unit, // Migration semantics not yet implemented
 
+            ControlExpr::QueryTrace { label, context } => {
+                // Section 20: Agent Ergonomics — look up prior decision in trace.
+                // Evaluate the context (pure Data) for potential future matching.
+                let _ctx_val = self.eval_data(context, env);
+
+                // Search the trace for a record matching the label.
+                let matching = self.trace.records.iter().find(|r| r.branch_id == *label);
+                match matching {
+                    Some(record) => {
+                        // Return the trace record as a Data record.
+                        let mut fields = HashMap::new();
+                        fields.insert(
+                            "branch_id".to_string(),
+                            RtValue::String(record.branch_id.clone()),
+                        );
+                        fields.insert(
+                            "chosen".to_string(),
+                            RtValue::String(record.chosen.clone()),
+                        );
+                        fields.insert(
+                            "reason".to_string(),
+                            RtValue::String(record.reason.clone()),
+                        );
+                        fields.insert(
+                            "timestamp".to_string(),
+                            RtValue::String(record.timestamp.clone()),
+                        );
+                        RtValue::Record(fields)
+                    }
+                    None => RtValue::Unit, // No prior decision found.
+                }
+            }
+
             ControlExpr::MethodCall(receiver_expr, method, args) => {
                 let receiver = self.eval_control_expr(receiver_expr, env);
                 let evaluated_args: Vec<RtValue> = args

crates/oo7-core/src/eval_tests.rs

@@ -1092,4 +1092,77 @@ mod tests {
 
         assert_eq!(reply, RtValue::String("got:world".to_string()));
     }
+
+    // ================================================================
+    // SECTION 20: AGENT ERGONOMICS — query_trace
+    // ================================================================
+
+    #[test]
+    fn eval_query_trace_miss() {
+        // query_trace with no prior matching trace record returns Unit.
+        let mut evaluator = Evaluator::new();
+        let env = Env::new();
+
+        let expr = ControlExpr::QueryTrace {
+            label: "nonexistent".to_string(),
+            context: Box::new(DataExpr::String("ctx".to_string())),
+        };
+
+        let result = evaluator.eval_control_expr(&expr, &env);
+        assert_eq!(result, RtValue::Unit);
+    }
+
+    #[test]
+    fn eval_query_trace_hit() {
+        // Make a traced branch decision, then query_trace finds it.
+        use crate::trace::TraceRecord;
+        use serde_json::Value as JsonValue;
+
+        let mut evaluator = Evaluator::new();
+        let env = Env::new();
+
+        // Manually inject a trace record (simulating a prior branch decision).
+        let record = TraceRecord {
+            branch_id: "test_branch".to_string(),
+            branch_options: vec!["left".to_string(), "right".to_string()],
+            given_contexts: JsonValue::Null,
+            chosen: "left".to_string(),
+            reason: "predicate match".to_string(),
+            trace_report: JsonValue::Null,
+            timestamp: "2026-03-24T00:00:00Z".to_string(),
+            agent_id: "evaluator".to_string(),
+            hermeneutic_context: JsonValue::Null,
+        };
+        evaluator.trace.append(record);
+
+        let expr = ControlExpr::QueryTrace {
+            label: "test_branch".to_string(),
+            context: Box::new(DataExpr::Int(42)),
+        };
+
+        let result = evaluator.eval_control_expr(&expr, &env);
+
+        // Should return a Record with branch_id, chosen, reason, timestamp.
+        match result {
+            RtValue::Record(fields) => {
+                assert_eq!(
+                    fields.get("branch_id"),
+                    Some(&RtValue::String("test_branch".to_string()))
+                );
+                assert_eq!(
+                    fields.get("chosen"),
+                    Some(&RtValue::String("left".to_string()))
+                );
+                assert_eq!(
+                    fields.get("reason"),
+                    Some(&RtValue::String("predicate match".to_string()))
+                );
+                assert_eq!(
+                    fields.get("timestamp"),
+                    Some(&RtValue::String("2026-03-24T00:00:00Z".to_string()))
+                );
+            }
+            other => panic!("Expected Record, got {:?}", other),
+        }
+    }
 }

crates/oo7-core/src/grammar.pest

@@ -15,7 +15,15 @@
 // Top-level
 // ============================================================
 
-program = { SOI ~ top_level_decl* ~ EOI }
+program = { SOI ~ (annotation | top_level_decl)* ~ EOI }
+
+// ============================================================
+// Annotations (Section 20: Agent Ergonomics)
+// ============================================================
+
+annotation = { ref_annotation }
+
+ref_annotation = { "@ref" ~ "(" ~ string_literal ~ ")" }
 
 top_level_decl = {
     data_binding
@@ -103,7 +111,9 @@ control_stmt = {
 let_binding = { "linear"? ~ "let" ~ pattern ~ "=" ~ control_expr }
 
 send_stmt = {
-    "send_final" ~ "(" ~ control_expr ~ "," ~ control_expr ~ ")"
+    "send_final" ~ control_expr ~ "to" ~ control_expr
+    | "send" ~ control_expr ~ "to" ~ control_expr
+    | "send_final" ~ "(" ~ control_expr ~ "," ~ control_expr ~ ")"
     | "send" ~ "(" ~ control_expr ~ "," ~ control_expr ~ ")"
 }
 
@@ -140,7 +150,8 @@ control_call_or_access = {
 }
 
 control_primary = {
-    "migrate" ~ "(" ~ control_expr ~ "," ~ "from" ~ ":" ~ locale_expr ~ "," ~ "to" ~ ":" ~ locale_expr ~ ")"
+    "query_trace" ~ "(" ~ string_literal ~ "," ~ data_expr ~ ")"
+    | "migrate" ~ "(" ~ control_expr ~ "," ~ "from" ~ ":" ~ locale_expr ~ "," ~ "to" ~ ":" ~ locale_expr ~ ")"
     | "exchange" ~ "(" ~ control_expr ~ "," ~ control_expr ~ ")"
     | "receive" ~ "(" ~ ")"
     | float_literal
@@ -543,6 +554,7 @@ keyword = {
     | "one_for_one" | "one_for_all" | "rest_for_one"
     | "budget" | "speculative" | "cached" | "dispatch" | "hypatia" | "onnx" | "custom"
     | "omega" | "zero" | "batch"
+    | "to" | "query_trace"
 }
 
 integer_literal = @{ "-"? ~ ASCII_DIGIT+ }

crates/oo7-core/src/parser.rs

@@ -54,18 +54,41 @@ pub fn parse_program(input: &str) -> Result<Program, ParseError> {
 /// Build a `Program` from the top-level `program` rule.
 fn build_program(pair: pest::iterators::Pair<Rule>) -> Program {
     let mut declarations = Vec::new();
+    let mut annotations = Vec::new();
     for inner in pair.into_inner() {
         match inner.as_rule() {
             Rule::top_level_decl => {
                 if let Some(decl) = build_top_level_decl(inner) {
                     declarations.push(decl);
                 }
             }
+            Rule::annotation => {
+                if let Some(ann) = build_annotation(inner) {
+                    annotations.push(ann);
+                }
+            }
             Rule::EOI => {}
             _ => {}
         }
     }
-    Program { declarations }
+    Program {
+        declarations,
+        annotations,
+    }
+}
+
+/// Build an annotation from the `annotation` rule.
+/// Currently only supports @ref annotations.
+fn build_annotation(pair: pest::iterators::Pair<Rule>) -> Option<RefAnnotation> {
+    let inner = pair.into_inner().next()?;
+    match inner.as_rule() {
+        Rule::ref_annotation => {
+            let str_pair = inner.into_inner().next()?;
+            let key = parse_string_literal(str_pair.as_str());
+            Some(RefAnnotation { key })
+        }
+        _ => None,
+    }
 }
 
 /// Build a single top-level declaration.
@@ -238,12 +261,36 @@ fn build_let_binding(pair: pest::iterators::Pair<Rule>) -> ControlStmt {
 }
 
 /// Build a `send` or `send_final` statement.
+///
+/// Two forms are supported (Section 20: Agent Ergonomics):
+/// - Natural-language: `send message to target` / `send_final message to target`
+///   (first expr is message, second is target)
+/// - Parenthesised: `send(target, message)` / `send_final(target, message)`
+///   (first expr is target, second is message)
+///
+/// The AST always stores target first, message second.
 fn build_send_stmt(pair: pest::iterators::Pair<Rule>) -> ControlStmt {
     let src = pair.as_str();
     let is_final = src.starts_with("send_final");
+
+    // Detect whether this is the `to` form or the parenthesised form.
+    // The `to` form does NOT contain a '(' after the keyword.
+    let keyword_len = if is_final { "send_final".len() } else { "send".len() };
+    let after_keyword = src[keyword_len..].trim_start();
+    let is_to_form = !after_keyword.starts_with('(');
+
     let mut inner = pair.into_inner();
-    let target = build_control_expr(inner.next().unwrap());
-    let message = build_control_expr(inner.next().unwrap());
+    let first = build_control_expr(inner.next().unwrap());
+    let second = build_control_expr(inner.next().unwrap());
+
+    // In the `to` form: first=message, second=target → swap to AST order.
+    // In the `()` form: first=target, second=message → already correct.
+    let (target, message) = if is_to_form {
+        (second, first)
+    } else {
+        (first, second)
+    };
+
     if is_final {
         ControlStmt::SendFinal { target, message }
     } else {
@@ -443,6 +490,17 @@ fn build_control_primary(pair: pest::iterators::Pair<Rule>) -> ControlExpr {
     let mut inner = pair.into_inner().peekable();
 
     // Check for special forms by source text prefix
+    if src.starts_with("query_trace") {
+        // query_trace("label", data_expr)
+        let str_pair = inner.next().unwrap();
+        let label = parse_string_literal(str_pair.as_str());
+        let data_pair = inner.next().unwrap();
+        let context = build_data_expr(data_pair);
+        return ControlExpr::QueryTrace {
+            label,
+            context: Box::new(context),
+        };
+    }
     if src.starts_with("migrate") {
         // migrate(expr, from: locale, to: locale)
         let expr = build_control_expr(inner.next().unwrap());