From d26f0c84a4b1f290aa03b27c1e8c4e822904c9ce Mon Sep 17 00:00:00 2001
From: claude <claude@mycelium.de>
Date: Fri, 24 Jul 2026 10:19:50 +0200
Subject: [PATCH] fix(cli): qualify the desugaring claims to the --real path;
 loud vocabulary-resolve invariant
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Independent post-cycle review (opus, fresh context) on the branch diff
returned one Minor and one Nit; both adjudicated against the source and
fixed:

- Minor: the concepts paragraph and the sweep/walkforward/mc long helps
  claimed the document desugaring unconditionally, but only the --real
  branches route through verb_sugar — the synthetic branches execute
  in-process and register no documents. The claims now carry the --real
  qualifier (and the paragraph names the in-process synthetic path).
  generalize keeps the unconditional wording: its only mode is --real
  (usage requires it), so the claim is true as stated.
- Nit: the vocabulary listing's `None` fallback would have silently printed
  a bare, C29-incomplete row if a rostered type id ever failed to resolve.
  Replaced with a loud expect — an invariant breach should not degrade into
  exactly the surface this cycle exists to remove.

refs #315
---
 crates/aura-cli/src/graph_construct.rs |  8 ++++----
 crates/aura-cli/src/main.rs            | 26 ++++++++++++++------------
 2 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/crates/aura-cli/src/graph_construct.rs b/crates/aura-cli/src/graph_construct.rs
index 75fcb98..fc65fdf 100644
--- a/crates/aura-cli/src/graph_construct.rs
+++ b/crates/aura-cli/src/graph_construct.rs
@@ -277,11 +277,11 @@ pub fn introspect_cmd(cmd: crate::GraphIntrospectCmd, env: &aura_runner::project
     if cmd.vocabulary {
         // C29 (#315): each type id carries its schema's one-line meaning —
         // bare names teach nothing (What do Latch, When, Select, Bias do?).
+        // A rostered id that fails to resolve is an invariant breach; better
+        // loud than a silent C29-incomplete bare row.
         for t in env.type_ids() {
-            match env.resolve(t) {
-                Some(b) => println!("{t:<18} {}", b.schema().doc),
-                None => println!("{t}"),
-            }
+            let b = env.resolve(t).expect("every rostered type id resolves to a builder");
+            println!("{t:<18} {}", b.schema().doc);
         }
     } else if cmd.folds {
         // The fold vocabulary binds at graph-declared taps (C27), so the
diff --git a/crates/aura-cli/src/main.rs b/crates/aura-cli/src/main.rs
index 5b6146a..8f62680 100644
--- a/crates/aura-cli/src/main.rs
+++ b/crates/aura-cli/src/main.rs
@@ -1032,9 +1032,10 @@ const CONCEPTS_HELP: &str = "\
 Author, backtest, and validate trading strategies — research CLI.
 
 Two layers, one vocabulary: the research verbs are the convenience surface —
-sweep, walkforward, mc, and generalize each write registered process/campaign
-documents and execute them (run is their single-backtest sibling). That
-document data plane is directly authorable: `aura process` / `aura campaign`
+over --real data, sweep, walkforward, mc, and generalize desugar to
+registered process/campaign documents and execute them (run is their
+single-backtest sibling; synthetic runs execute in-process). That document
+data plane is directly authorable: `aura process` / `aura campaign`
 (validate | introspect | register | run), growing a document from a bare {}
 via `introspect --unwired`.
 
@@ -1075,17 +1076,17 @@ enum Command {
     Graph(GraphCmd),
     /// Sweep a parameter grid over a strategy or a loaded blueprint.
     ///
-    /// Sugar over the document layer: desugars to a registered process
-    /// (std::sweep) + campaign pair — author the documents directly via
-    /// `aura process` / `aura campaign`.
+    /// Sugar over the document layer: over --real data this desugars to a
+    /// registered process (std::sweep) + campaign pair — author the documents
+    /// directly via `aura process` / `aura campaign`.
     Sweep(SweepCmd),
     /// Walk-forward validation over a strategy or a loaded blueprint. Over --real, the
     /// fixed 90/30-day roller fits to a --from/--to window shorter than it, preserving
     /// the 3:1 IS:OOS ratio, instead of refusing the window outright.
     ///
-    /// Sugar over the document layer: desugars to a registered process
-    /// ([std::grid, std::walk_forward]) + campaign pair — author the documents
-    /// directly via `aura process` / `aura campaign`.
+    /// Sugar over the document layer: over --real data this desugars to a
+    /// registered process ([std::grid, std::walk_forward]) + campaign pair —
+    /// author the documents directly via `aura process` / `aura campaign`.
     Walkforward(WalkforwardCmd),
     /// Grade one candidate across multiple instruments.
     ///
@@ -1097,9 +1098,10 @@ enum Command {
     /// --real, the fixed 90/30-day walk-forward roller fits to a --from/--to window
     /// shorter than it, preserving the 3:1 IS:OOS ratio, instead of refusing outright.
     ///
-    /// Sugar over the document layer: desugars to a registered process
-    /// ([std::grid, std::walk_forward, std::monte_carlo]) + campaign pair —
-    /// author the documents directly via `aura process` / `aura campaign`.
+    /// Sugar over the document layer: over --real data this desugars to a
+    /// registered process ([std::grid, std::walk_forward, std::monte_carlo]) +
+    /// campaign pair — author the documents directly via `aura process` /
+    /// `aura campaign`.
     Mc(McCmd),
     /// List or inspect recorded run families.
     Runs(RunsCmd),