feat(research,campaign,cli): chunked instrument-major cell walk + duplicate-instrument refusal

Two pieces of the parallel-cell-loop iteration (spec: parallel-cell-loop),
still sequential — behaviour-identical results, suite green unchanged:

- validate_campaign refuses a campaign document listing the same instrument
  twice (DocFault::DuplicateInstrument + CLI prose). A duplicate enumerates
  two identical cells and is the one input that could make two cells share a
  registry family name; with distinct instruments the per-cell family name
  (all four cell axes + stage ordinal) is unique by construction, so the
  upcoming parallel appends can never race one name's run-index assignment.
- aura_campaign::execute flattens the 4-nested cell loop into a document-
  order-indexed cell list, groups it by instrument ordinal, and walks
  sequential chunks of K instrument groups; results land in index-addressed
  slots and the ordered outputs (outcomes, realizations, nominee groups) are
  rebuilt in document order. K arrives as a new NonZeroUsize parameter
  (default DEFAULT_PARALLEL_INSTRUMENTS = 4), exposed as
  --parallel-instruments on aura campaign run and threaded through the
  run_campaign chain; the dissolved-verb sugar paths pass the default.

The chunk walk is the structural RAM bound for the parallel flip that
follows: no cell of an instrument outside the current chunk can be in
flight at all (chosen over a semaphore gate — blocking inside pool tasks
risks worker starvation; decision log on #277). Verified: workspace suite
green unchanged, clippy -D warnings clean, E2E fixtures pin the CLI prose
and the document-order persistence across K.

refs #277

crates/aura-cli/src/campaign_run.rs

@@ -15,6 +15,7 @@
 //! visible to child modules without promotion.
 
 use std::collections::{BTreeMap, HashSet};
+use std::num::NonZeroUsize;
 use std::path::{Path, PathBuf};
 use std::sync::{mpsc, Arc};
 
@@ -478,7 +479,11 @@ pub(crate) enum RunPresentation {
 /// is a refusal `campaign_cmd` renders as `aura: {msg}` + exit 1; an `Ok`
 /// carries the failed-cell count (#272) so the caller can exit 3 on a
 /// completed-with-failures run via `exit_on_campaign_result`.
-pub(crate) fn run_campaign(target: &str, env: &Env) -> Result<usize, String> {
+pub(crate) fn run_campaign(
+    target: &str,
+    env: &Env,
+    parallel_instruments: NonZeroUsize,
+) -> Result<usize, String> {
     // Project gate FIRST: nothing (not even the file-sugar registration)
     // touches a store outside a project.
     if env.provenance().is_none() {
@@ -511,7 +516,7 @@ pub(crate) fn run_campaign(target: &str, env: &Env) -> Result<usize, String> {
         ));
     };
 
-    run_campaign_by_id(&campaign_id, env, RunPresentation::Full)
+    run_campaign_by_id(&campaign_id, env, RunPresentation::Full, parallel_instruments)
 }
 
 /// An executed campaign plus the context its presenter and the dissolved-verb
@@ -540,8 +545,9 @@ pub(crate) fn run_campaign_by_id(
     campaign_id: &str,
     env: &Env,
     presentation: RunPresentation,
+    parallel_instruments: NonZeroUsize,
 ) -> Result<usize, String> {
-    let run = run_campaign_returning(campaign_id, env)?;
+    let run = run_campaign_returning(campaign_id, env, parallel_instruments)?;
     present_campaign(run, presentation, env)
 }
 
@@ -556,6 +562,7 @@ pub(crate) fn run_campaign_by_id(
 pub(crate) fn run_campaign_returning(
     campaign_id: &str,
     env: &Env,
+    parallel_instruments: NonZeroUsize,
 ) -> Result<CampaignRun, String> {
     let registry = env.registry();
     let campaign_text = registry
@@ -635,6 +642,7 @@ pub(crate) fn run_campaign_returning(
         &strategies,
         &runner,
         &registry,
+        parallel_instruments,
     )
     .map_err(|f| exec_fault_prose(&f))?;
 

crates/aura-cli/src/research_docs.rs

@@ -137,6 +137,9 @@ pub(crate) fn doc_fault_prose(f: &DocFault) -> String {
             format!("pipeline[{stage}]: walk_forward {field} must be > 0")
         }
         DocFault::EmptyInstruments => "data.instruments is empty".into(),
+        DocFault::DuplicateInstrument { index, instrument } => {
+            format!("data.instruments[{index}]: \"{instrument}\" is listed more than once")
+        }
         DocFault::NoWindow => "data.windows is empty".into(),
         DocFault::BadWindow { index } => {
             format!("data.windows[{index}]: from_ms must be earlier than to_ms")
@@ -313,7 +316,13 @@ pub enum CampaignSub {
     Register { file: PathBuf },
     /// Execute a stored campaign into a realized run-set (a .json file is
     /// register-then-run sugar; the canonical address is the content id).
-    Run { target: String },
+    Run {
+        target: String,
+        /// Bound on distinct instruments resident in parallel (the RAM
+        /// lever; 1 reproduces the sequential loop's footprint).
+        #[arg(long, default_value_t = aura_campaign::DEFAULT_PARALLEL_INSTRUMENTS)]
+        parallel_instruments: std::num::NonZeroUsize,
+    },
     /// List stored campaign realizations, or dump one campaign's records
     /// (the bare store lines, not the run-emit wrapper).
     Runs { campaign: Option<String>, run: Option<usize> },
@@ -420,8 +429,12 @@ fn campaign_runs(campaign: Option<&str>, run: Option<usize>, env: &Env) -> Resul
 /// via `exit_on_campaign_result`), so it is pulled out of the unified
 /// `Result<(), String>` match the other four subcommands still share.
 pub fn campaign_cmd(cmd: CampaignCmd, env: &Env) {
-    if let CampaignSub::Run { target } = &cmd.sub {
-        crate::exit_on_campaign_result(crate::campaign_run::run_campaign(target, env));
+    if let CampaignSub::Run { target, parallel_instruments } = &cmd.sub {
+        crate::exit_on_campaign_result(crate::campaign_run::run_campaign(
+            target,
+            env,
+            *parallel_instruments,
+        ));
         return;
     }
     let result = match &cmd.sub {

crates/aura-cli/src/verb_sugar.rs

@@ -345,7 +345,12 @@ pub(crate) fn run_sweep_sugar(
     validate_before_register(&generated.process, &generated.campaign, inv.blueprint_canonical, &probe_params, env)?;
     let reg = env.registry();
     let (_process_id, campaign_id) = register_generated(&reg, &generated)?;
-    crate::campaign_run::run_campaign_by_id(&campaign_id, env, crate::campaign_run::RunPresentation::MemberLinesOnly)
+    crate::campaign_run::run_campaign_by_id(
+        &campaign_id,
+        env,
+        crate::campaign_run::RunPresentation::MemberLinesOnly,
+        aura_campaign::DEFAULT_PARALLEL_INSTRUMENTS,
+    )
 }
 
 /// Build the `CrossInstrument` family members from an executed generalize
@@ -386,7 +391,11 @@ pub(crate) fn run_generalize_sugar(
     validate_before_register(&generated.process, &generated.campaign, inv.blueprint_canonical, &probe_params, env)?;
     let reg = env.registry();
     let (_process_id, campaign_id) = register_generated_g(&reg, &generated)?;
-    let run = crate::campaign_run::run_campaign_returning(&campaign_id, env)?;
+    let run = crate::campaign_run::run_campaign_returning(
+        &campaign_id,
+        env,
+        aura_campaign::DEFAULT_PARALLEL_INSTRUMENTS,
+    )?;
 
     // Reprint the verb's aggregate line from the recorded cross-instrument
     // grade — byte-identical to the retired welded path's `generalize_json(&agg)`.
@@ -508,7 +517,11 @@ pub(crate) fn run_walkforward_sugar(
     validate_before_register(&generated.process, &generated.campaign, inv.blueprint_canonical, &probe_params, env)?;
     let reg = env.registry();
     let (_process_id, campaign_id) = register_generated_wf(&reg, &generated)?;
-    let run = crate::campaign_run::run_campaign_returning(&campaign_id, env)?;
+    let run = crate::campaign_run::run_campaign_returning(
+        &campaign_id,
+        env,
+        aura_campaign::DEFAULT_PARALLEL_INSTRUMENTS,
+    )?;
 
     if let Some(f) = run.outcome.record.cells.iter().find_map(|c| c.fault.as_ref()) {
         eprintln!("aura: walkforward cell failed at stage {}: {}", f.stage, f.detail);
@@ -668,7 +681,11 @@ pub(crate) fn run_mc_sugar(
     validate_before_register(&generated.process, &generated.campaign, inv.blueprint_canonical, &probe_params, env)?;
     let reg = env.registry();
     let (_process_id, campaign_id) = register_generated_mc(&reg, &generated)?;
-    let run = crate::campaign_run::run_campaign_returning(&campaign_id, env)?;
+    let run = crate::campaign_run::run_campaign_returning(
+        &campaign_id,
+        env,
+        aura_campaign::DEFAULT_PARALLEL_INSTRUMENTS,
+    )?;
 
     if let Some(f) = run.outcome.record.cells.iter().find_map(|c| c.fault.as_ref()) {
         eprintln!("aura: mc cell failed at stage {}: {}", f.stage, f.detail);