feat(aura-engine, aura-cli): the blueprint name op — name_gate on every authored intake

An eleventh op-script op {"op":"name","name":"<n>"} sets the composite
render name (engine Op::Name + CLI OpDoc mirror); omitting it keeps the
default "graph" byte-identically. The default leaked everywhere one
research project has more than one strategy: every store entry named
graph, every default tap recording sharing traces/graph/, and two
use-splices of unnamed blueprints colliding on the default instance
identifier — the authored name dissolves all three through existing
mechanics (no downstream site edited).

Mechanics: at-most-once per script (doc-op precedent), position-free
(read only at finish). A shared deterministic name_gate (aura-engine:
non-empty, no path separators, not . or ..) guards every seam where a
name is born from authored data, because the name keys a trace
directory unsanitized: the op intake (GraphSession::set_name) and all
four CLI fresh-file envelope intakes (register, introspect
--content-id FILE, the bare graph FILE viewer, aura run FILE — the run
route reached begin_run(signal.name()) ungated, and introspect
--params FILE rode the same parse). Store read-back (reproduce, use
resolution, introspect/params by content id) stays deliberately
ungated — C29: registered artifacts are never retroactively
invalidated — pinned by a test that plants a bad-root-name blueprint
via the registry API and asserts introspect --params still answers.
Refusal prose is single-sourced (name_gate_fault_prose) so every seam
reads identically, op-indexed on the op route.

Identity semantics: the authored name hashes into the content id (a
named document is a different document) and never into the identity id
(names are stripped as debug symbols, C23) — pinned by a twin test.
The previously untested use-splice instance-name default
(construction.rs) got its ratifying pin before the collision claim
leans on it. The registry label (register --name) stays orthogonal.

Review rounds caught and fixed: the envelope gate initially fired on
store read-back (C29 violation at the introspect surface), and the
run/params fresh-file routes were unenumerated intake seams — closed
with the call-site classification now recorded in the wrapper docs.

Verification: cargo build/test/clippy -D warnings all green (99 test
targets, 0 failures, independently re-run); the new run-route test was
RED-verified by hand-removing the gate.

closes #331
refs #328, #311

Spec: blueprint-name-op (fork minutes on #331)

crates/aura-cli/src/graph_construct.rs

@@ -8,9 +8,9 @@ use std::collections::BTreeMap;
 use std::path::Path;
 
 use aura_engine::{
-    blueprint_from_json, blueprint_identity_json, blueprint_to_json, replay, ArgOpError,
-    BindOpError, BlueprintDoc, CompileError, Composite, GraphSession, LoadError, Op, OpError,
-    Scalar, ScalarKind,
+    blueprint_from_json, blueprint_identity_json, blueprint_to_json, name_gate, replay, ArgOpError,
+    BindOpError, BlueprintDoc, CompileError, Composite, GraphSession, LoadError, NameGateFault, Op,
+    OpError, Scalar, ScalarKind,
 };
 use aura_runner::runner::render_value;
 use serde::Deserialize;
@@ -22,9 +22,10 @@ use crate::research_docs::resolve_id_prefix;
 #[cfg(test)]
 use aura_vocabulary::std_vocabulary;
 
-/// The op-list reference `aura graph build --help` appends (#323): the ten
-/// op kinds with their fields and one worked element each. Lives beside
-/// [`OpDoc`] so a new op variant is one screen away from its help line.
+/// The op-list reference `aura graph build --help` appends (#323): the eleven
+/// op kinds with their fields and one worked element each (#331: `name` joins
+/// the roster, ten -> eleven). Lives beside [`OpDoc`] so a new op variant is
+/// one screen away from its help line.
 pub const OP_REFERENCE: &str = r#"Op-list reference (stdin: a JSON array of op objects, applied in order):
   {"op":"source","role":"price","kind":"F64"}
       declare a bound root input role of a scalar kind
@@ -50,6 +51,9 @@ pub const OP_REFERENCE: &str = r#"Op-list reference (stdin: a JSON array of op o
   {"op":"use","ref":{"name":"agree"},"name":"gate","bind":{"sma.length":{"I64":9}}}
       splice a registered blueprint (by "content_id" or "name") under an
       instance name ("bind" path-qualifies the spliced instance's params)
+  {"op":"name","name":"ny_momentum"}
+      set the composite's render name, at most once per script (default
+      "graph" if omitted)
 
 Node types and their ports: aura graph introspect --vocabulary | --node <T>"#;
 
@@ -111,6 +115,9 @@ enum OpDoc {
         #[serde(default)]
         bind: BTreeMap<String, Scalar>,
     },
+    /// Set the composite's render name (#331) — script-level, at most once;
+    /// the op-script twin of `replay`'s seeded default name (`"graph"`).
+    Name { name: String },
 }
 
 /// A `use` op's reference (#317) — exactly one of a store content id (full
@@ -143,6 +150,7 @@ impl OpDoc {
             OpDoc::Doc { .. } => "doc".to_string(),
             OpDoc::Use { name: Some(n), .. } => format!("use {n:?}"),
             OpDoc::Use { name: None, .. } => "use".to_string(),
+            OpDoc::Name { .. } => "name".to_string(),
         }
     }
 }
@@ -182,6 +190,7 @@ impl From<OpDoc> for Op {
                 name,
                 bind: bind.into_iter().collect(),
             },
+            OpDoc::Name { name } => Op::Name { name },
         }
     }
 }
@@ -257,9 +266,25 @@ fn format_op_error(e: &OpError) -> String {
         OpError::UnknownSubgraph { ref_id } => {
             format!("use: no subgraph for content id {ref_id:?}")
         }
+        OpError::DuplicateName => "a script names its blueprint at most once".to_string(),
+        OpError::BadName { name, fault } => name_gate_fault_prose(name, fault),
     }
 }
 
+/// Phrase a `name_gate` shape violation as prose (#331): shared by this
+/// module's op-intake `format_op_error` `BadName` arm and the
+/// blueprint-envelope intake's root-name gate (`composite_from_authored_text`
+/// below) — the shape rule has exactly one seam-independent cause per fault,
+/// so both data-borne birth routes for a name read identically.
+fn name_gate_fault_prose(name: &str, fault: &NameGateFault) -> String {
+    let cause = match fault {
+        NameGateFault::Empty => "must be non-empty",
+        NameGateFault::ContainsSeparator => "must not contain '/' or '\\'",
+        NameGateFault::DotSegment => "must not be \".\" or \"..\"",
+    };
+    format!("blueprint name {name:?} is invalid: {cause} (a single path segment)")
+}
+
 /// Resolve one `use` op's [`UseRef`] to the full store content id (#317):
 /// verbatim if it already IS a 64-hex content id, else a unique content-id
 /// prefix (#302 semantics, reusing [`resolve_id_prefix`]) or a registry name
@@ -649,7 +674,7 @@ pub fn introspect_cmd(cmd: crate::GraphIntrospectCmd, env: &aura_runner::project
                         std::process::exit(1);
                     }
                 };
-                match composite_from_any(&text, env) {
+                match composite_from_authored_text(&text, env) {
                     Ok(c) => c,
                     Err(m) => {
                         eprintln!("aura: {m}");
@@ -819,6 +844,18 @@ pub(crate) fn blueprint_slot_prose(doc: &str, env: &aura_runner::project::Env) -
 /// envelope (a JSON object: `format_version` + `blueprint`) OR a construction
 /// op-list (a JSON array) — shape-discriminated on the top-level JSON type,
 /// each canonicalized by its own rules.
+///
+/// **Ungated by design (#331 review finding).** This is the STORE READ-BACK
+/// shape: `params_lines`'s content-id fetch (`resolve_blueprint_text`'s
+/// non-file branch) — `introspect --params <ID>` and, by the same
+/// convention, `validate_campaign_refs`'s already-ungated `blueprint_from_json`
+/// call — reads whatever is already sitting in the store, and C29 says a
+/// registered artifact is never retroactively invalidated. Freshly authored
+/// FILE text (a hand-edited document that has not yet passed through a gated
+/// intake) goes through [`composite_from_authored_text`] instead, never here
+/// — `params_lines`'s OWN file branch is such a case (#331 delta re-review:
+/// it used to call straight through to this fn, missing the gate; fixed by
+/// branching on `resolve_blueprint_text`'s file-vs-store flag).
 pub(crate) fn composite_from_any(text: &str, env: &aura_runner::project::Env) -> Result<Composite, String> {
     let value: serde_json::Value =
         serde_json::from_str(text).map_err(|e| format!("invalid document: {e}"))?;
@@ -836,12 +873,68 @@ pub(crate) fn composite_from_any(text: &str, env: &aura_runner::project::Env) ->
     }
 }
 
+/// The FILE-intake counterpart of [`composite_from_any`] (#331 review
+/// finding): identical parse, plus the blueprint-envelope root-name shape
+/// gate. Every call site that builds a `Composite` from text freshly read
+/// off disk (`graph register`, `graph introspect --content-id <FILE>`, the
+/// bare `aura graph <FILE>` viewer, and `graph introspect --params <FILE>`'s
+/// file branch) goes through this wrapper — never the ungated
+/// `composite_from_any` — because a hand-edited envelope with
+/// `"name":"../x"` would otherwise register/build cleanly and write
+/// `traces/../x/` at run time (`trace_store.rs` joins the name unsanitized).
+/// Gating the composite's name unconditionally (not just on the Object
+/// branch) is harmless: an op-script-built composite's name already passed
+/// the op-intake gate (`GraphSession::set_name`), so re-checking it here is
+/// redundant, not restrictive — it keeps this wrapper a single shared choke
+/// point rather than one that has to re-discriminate the JSON shape. Only
+/// the ROOT name is checked: the filesystem seam consumes exclusively the
+/// root name. Store read-back (reproduce, `use`-splice resolution from the
+/// registry, and `params_lines`'s content-id branch) never reaches this
+/// function — C29's "registered artifacts are never retroactively
+/// invalidated" stays intact.
+///
+/// **One deliberate exception:** `aura run <blueprint.json>`'s loaded-blueprint
+/// branch (`dispatch_run`, main.rs) also reads a fresh FILE and reaches the
+/// same unsanitized `traces/<name>/` seam (via `run_signal_r`/`run_measurement`
+/// -> `bind_tap_plan` -> `TraceStore::begin_run`), so it too must gate the root
+/// name — but it does NOT route through this wrapper, because its grammar is
+/// deliberately narrower than `composite_from_any`'s (envelope-only, no
+/// op-script array fallback; a bare `blueprint_from_json` call with its own
+/// load-error prose/hint convention). Routing it through this wrapper would
+/// silently loosen that grammar to also accept op-scripts. It instead calls
+/// [`gate_authored_root_name`] directly, sharing the identical `name_gate` +
+/// `name_gate_fault_prose` primitives this wrapper uses — so the refusal wording
+/// is byte-identical across all five authored-file-intake routes even though
+/// the shape-discrimination step is not shared by `dispatch_run`.
+pub(crate) fn composite_from_authored_text(
+    text: &str,
+    env: &aura_runner::project::Env,
+) -> Result<Composite, String> {
+    let composite = composite_from_any(text, env)?;
+    gate_authored_root_name(composite.name())?;
+    Ok(composite)
+}
+
+/// The root-name shape gate itself (#331 delta re-review), factored out of
+/// [`composite_from_authored_text`] so `dispatch_run`'s narrower-grammar file
+/// intake (see that fn's doc comment) can share the exact `name_gate` call and
+/// `name_gate_fault_prose` wording without going through the shape-discriminating
+/// wrapper.
+pub(crate) fn gate_authored_root_name(name: &str) -> Result<(), String> {
+    name_gate(name).map_err(|fault| name_gate_fault_prose(name, &fault))
+}
+
 /// Resolve a blueprint document's bytes from a file path or a 64-hex content
 /// id in the project store (the campaign-run target-addressing convention).
 /// The id shape is `aura_runner::axes::is_content_id` — the same predicate
 /// `campaign run`'s target resolution uses, so the two FILE-or-id surfaces
-/// cannot drift apart on what counts as a store address.
-fn resolve_blueprint_text(target: &str, env: &aura_runner::project::Env) -> Result<String, String> {
+/// cannot drift apart on what counts as a store address. The `bool` names
+/// which branch fired: `true` for a FRESH FILE read, `false` for a STORE
+/// (content-id) fetch — `params_lines` (#331 delta re-review) uses it to
+/// decide whether the root-name gate applies (a fresh file must gate; a
+/// store read-back must not, C29) without re-deriving the FILE-vs-id
+/// distinction a second time.
+fn resolve_blueprint_text(target: &str, env: &aura_runner::project::Env) -> Result<(String, bool), String> {
     // A CLI arg tolerates the `content:` display prefix (#194); doc ref
     // fields stay bare-only.
     let target = target
@@ -851,11 +944,12 @@ fn resolve_blueprint_text(target: &str, env: &aura_runner::project::Env) -> Resu
     let path = Path::new(target);
     if path.is_file() {
         return std::fs::read_to_string(path)
+            .map(|text| (text, true))
             .map_err(|e| format!("cannot read {}: {e}", path.display()));
     }
     if aura_runner::axes::is_content_id(target) {
         return match env.registry().get_blueprint(target) {
-            Ok(Some(json)) => Ok(json),
+            Ok(Some(json)) => Ok((json, false)),
             Ok(None) => Err(format!("no blueprint {target} in the project store")),
             Err(e) => Err(e.to_string()),
         };
@@ -872,12 +966,16 @@ fn resolve_blueprint_text(target: &str, env: &aura_runner::project::Env) -> Resu
 /// `bound_param_space()`'s names are already RAW (#203), so no blueprint-name
 /// concatenation is needed — line-identical to the reconciled `--list-axes`
 /// bound pass (`list_blueprint_axes`, main.rs), same `render_value` lexicon.
+/// #331 delta re-review: the FILE target is a FOURTH freshly-authored-file
+/// intake this fn's own `composite_from_any` call had missed gating — a FILE
+/// routes through [`composite_from_authored_text`] instead; a content id
+/// (STORE read-back) keeps the ungated `composite_from_any` (C29).
 fn params_lines(target: &str, env: &aura_runner::project::Env) -> Result<String, String> {
     use std::fmt::Write as _;
-    let text = resolve_blueprint_text(target, env)?;
+    let (text, is_file) = resolve_blueprint_text(target, env)?;
     // Shape-discriminated like file-mode --content-id: an op-script (array)
     // builds through the one-build tail, an envelope (object) loads (#202).
-    let composite = composite_from_any(&text, env)?;
+    let composite = if is_file { composite_from_authored_text(&text, env)? } else { composite_from_any(&text, env)? };
     let mut out = String::new();
     for p in composite.param_space() {
         let _ = writeln!(out, "{}:{:?}", p.name, p.kind);
@@ -918,7 +1016,9 @@ fn register_blueprint(
         .map_err(|e| format!("cannot read {}: {e}", file.display()))?;
     // Shape-discriminated like file-mode --content-id (#202): either shape
     // canonicalizes to the envelope form, so the stored id is shape-invariant.
-    let composite = composite_from_any(&text, env)?;
+    // Gated (#331 review finding): this text is freshly authored FILE bytes,
+    // not a store read-back, so `composite_from_authored_text` applies.
+    let composite = composite_from_authored_text(&text, env)?;
     let canonical = blueprint_to_json(&composite).map_err(|e| format!("serialize error: {e:?}"))?;
     let id = crate::content_id(&canonical);
     let registry = env.registry();

crates/aura-cli/src/main.rs

@@ -1884,6 +1884,19 @@ fn dispatch_run(a: RunCmd, env: &aura_runner::project::Env) {
                 eprintln!("aura: {path}: {msg}");
                 std::process::exit(2);
             });
+            // #331 delta re-review: this is the third freshly-authored-FILE
+            // intake (`register`, `introspect --content-id <FILE>`, and this
+            // one) that must gate the root name before it ever reaches the
+            // filesystem — both run arms below feed `signal.name()` straight
+            // into `bind_tap_plan`'s `TraceStore::begin_run`, which joins it
+            // unsanitized (`trace_store.rs`). Not routed through
+            // `composite_from_authored_text` itself (see that fn's doc
+            // comment on why); same `name_gate`/`name_gate_fault_prose`
+            // primitives, this arm's own load-error exit/prose convention.
+            if let Err(msg) = graph_construct::gate_authored_root_name(signal.name()) {
+                eprintln!("aura: {path}: {msg}");
+                std::process::exit(2);
+            }
             // Shape dispatch (C28 phase 3): a `bias` output → the strategy path
             // (wrap_r + R evaluation), byte-identical; else ≥1 declared tap → a
             // bare measurement run (no wrap_r); else an inert blueprint → refuse.
@@ -1981,7 +1994,7 @@ fn dispatch_graph(a: GraphCmd, env: &aura_runner::project::Env) {
                     eprintln!("aura: {path}: {e}");
                     std::process::exit(2);
                 });
-                let bp = graph_construct::composite_from_any(&doc, env).unwrap_or_else(|msg| {
+                let bp = graph_construct::composite_from_authored_text(&doc, env).unwrap_or_else(|msg| {
                     eprintln!("aura: {path}: {msg}");
                     std::process::exit(2);
                 });