Merge pull request #240 from stlab/worktree-adam-rs/planner-generalization-phase-b

Generalize planner seedfill and stage selected guard prerequisites

Author: sean-parent

adam-lang/src/error_labels.rs

@@ -33,6 +33,17 @@ pub(crate) fn site_label(
             _ => generic_site_label(site, cell_name),
         },
 
+        Error::SeedCycle { .. } => match site {
+            ErrorSite::Relationship(_) => {
+                "this relationship is part of the seed dependency cycle".to_string()
+            }
+            ErrorSite::Cell(c) => match cell_name(*c) {
+                Some(name) => format!("cell `{name}` is part of the seed dependency cycle"),
+                None => "this cell is part of the seed dependency cycle".to_string(),
+            },
+            _ => generic_site_label(site, cell_name),
+        },
+
         Error::Conflict { .. } => match site {
             ErrorSite::Relationship(_) => {
                 "this relationship is part of an overconstrained group".to_string()
@@ -50,14 +61,16 @@ pub(crate) fn site_label(
             _ => generic_site_label(site, cell_name),
         },
 
-        // Two site shapes share this variant: self-duplicate (a method's own outputs list
-        // repeats a cell) is `[Method/MethodIndex, Cell(repeated output)]`; cross-method
-        // (two methods claim the same output set) is `[Method(later), Method(earlier),
-        // Cell(shared)…]`. A `Cell` site always means "this cell is claimed more than
-        // once", in *both* shapes — checking it before the numeric-index arms below is
-        // what keeps the self-duplicate case (whose `sites[1]` is a `Cell`, not the
-        // earlier method) from being mislabelled as "collides with this earlier method".
-        Error::DuplicateMethodOutputs { .. } => match site {
+        // Three site shapes share this variant: self-duplicate (a method's own outputs
+        // list repeats a cell) is `[Method/MethodIndex, Cell(repeated output)]`;
+        // identical output sets are `[Method(later), Method(earlier), Cell(shared)…]`;
+        // nested output sets are `[Method(later), Method(earlier), Cell(shared subset)…]`.
+        // Overlapping non-nested output sets are valid and never reach this branch.
+        // A `Cell` site always means "this cell is claimed more than once", in *all*
+        // shapes — checking it before the numeric-index arms below keeps the self-duplicate
+        // case (whose `sites[1]` is a `Cell`, not the earlier method) from being
+        // mislabelled as "collides with this earlier method".
+        Error::InvalidMethodOutputs { .. } => match site {
             ErrorSite::Cell(c) => match cell_name(*c) {
                 Some(name) => format!("output cell `{name}` is claimed more than once"),
                 None => "this output cell is claimed more than once".to_string(),
@@ -139,6 +152,22 @@ mod tests {
         assert_eq!(label, "cell `mode` is part of the cycle");
     }
 
+    #[test]
+    fn seed_cycle_sites_are_labelled_as_part_of_the_seed_cycle() {
+        let relationship = adam_rs::RelationshipId::default();
+        let cell = CellId::default();
+        let e = adam_rs::Error::SeedCycle {
+            sites: vec![ErrorSite::Relationship(relationship), ErrorSite::Cell(cell)],
+        };
+        let relationship_label = site_label(&e, 0, &|_| Some("x".to_string()));
+        let cell_label = site_label(&e, 1, &|_| Some("x".to_string()));
+        assert_eq!(
+            relationship_label,
+            "this relationship is part of the seed dependency cycle"
+        );
+        assert_eq!(cell_label, "cell `x` is part of the seed dependency cycle");
+    }
+
     #[test]
     fn site_label_describes_mismatched_method_cells() {
         let e = adam_rs::Error::MismatchedMethodCells {
@@ -155,8 +184,8 @@ mod tests {
     }
 
     #[test]
-    fn site_label_describes_duplicate_method_outputs() {
-        let e = adam_rs::Error::DuplicateMethodOutputs {
+    fn site_label_describes_invalid_method_outputs() {
+        let e = adam_rs::Error::InvalidMethodOutputs {
             sites: vec![
                 adam_rs::ErrorSite::MethodIndex(1),
                 adam_rs::ErrorSite::MethodIndex(0),
@@ -169,15 +198,15 @@ mod tests {
         assert!(site_label(&e, 2, &name).contains("out"));
     }
 
-    // Regression test for the self-duplicate shape of `DuplicateMethodOutputs`: a method's own
+    // Regression test for the self-duplicate shape of `InvalidMethodOutputs`: a method's own
     // `outputs` list repeats a cell (e.g. `relationship { (b, b) := (a, a2); }`), which
     // `Sheet::add_relationship` reports as `sites: vec![MethodIndex(idx), Cell(o)]` -- only two
     // sites, with `sites[1]` a `Cell`, not a second method. Labelling `index == 1` by raw
     // position (as the cross-method case does) would wrongly print "collides with this earlier
     // method" onto the cell caret, even though there is no earlier method here.
     #[test]
-    fn site_label_describes_duplicate_method_outputs_self_duplicate() {
-        let e = adam_rs::Error::DuplicateMethodOutputs {
+    fn site_label_describes_invalid_method_outputs_self_duplicate() {
+        let e = adam_rs::Error::InvalidMethodOutputs {
             sites: vec![
                 adam_rs::ErrorSite::MethodIndex(0),
                 adam_rs::ErrorSite::Cell(adam_rs::CellId::default()),

adam-rs/src/error.rs

@@ -42,11 +42,11 @@ pub enum Error {
     /// A `CellId` or `RelationshipId` was not found in the sheet.
     InvalidId,
 
-    /// No valid method assignment exists (overconstrained).
+    /// No valid method assignment exists, or staged prerequisite provenance conflicts
+    /// with the final selected plan.
     Conflict {
-        /// A subset-minimal group of relationships that together admit no valid
-        /// method assignment: removing any member of the group makes the remainder
-        /// feasible. Every entry is `ErrorSite::Relationship`.
+        /// Relationships, methods, and cells involved in an impossible assignment or
+        /// an incompatible staged prerequisite reuse.
         sites: Vec<ErrorSite>,
     },
 
@@ -59,6 +59,15 @@ pub enum Error {
         sites: Vec<ErrorSite>,
     },
 
+    /// The seed dependency graph contains a non-self cycle.
+    SeedCycle {
+        /// The cycle's members in deterministic traversal order, starting at the first
+        /// revisited `Cell` and alternating through the sibling `Relationship`s that
+        /// force the cycle. The closing relationship appears last; the starting cell is
+        /// not repeated at the end.
+        sites: Vec<ErrorSite>,
+    },
+
     /// A method's function returned an error during execution.
     MethodFailed {
         /// The underlying error the method's function (or a requirement's/conditional's
@@ -91,13 +100,14 @@ pub enum Error {
     },
 
     /// A method's own `outputs` list names a cell more than once, or two methods in
-    /// the same relationship have identical `outputs` sets.
-    DuplicateMethodOutputs {
+    /// the same relationship have identical or nested `outputs` sets. Overlapping
+    /// output sets are allowed when neither set nests the other.
+    InvalidMethodOutputs {
         /// `sites[0]` is the method (by index within the `Vec` passed to
         /// `add_relationship`) whose output set collided. For a method's own outputs
         /// repeating a cell, further entries are the repeated cell(s). For two methods
-        /// sharing an output set, `sites[1]` is the earlier method's index and further
-        /// entries are the shared output cell(s).
+        /// with identical or nested output sets, `sites[1]` is the earlier method's
+        /// index and further entries are the duplicate or nested subset cell(s).
         sites: Vec<ErrorSite>,
     },
 
@@ -169,16 +179,17 @@ impl std::fmt::Display for Error {
             Error::InvalidId => write!(f, "invalid cell or relationship id"),
             Error::Conflict { .. } => write!(f, "no valid method assignment (overconstrained)"),
             Error::Cycle { .. } => write!(f, "selected methods form a cycle"),
+            Error::SeedCycle { .. } => write!(f, "seed dependency cycle"),
             Error::MethodFailed { error, .. } => write!(f, "method execution failed: {error}"),
             Error::InvalidMethod { .. } => write!(f, "method is structurally invalid"),
             Error::MismatchedMethodCells { .. } => write!(
                 f,
                 "methods in a relationship must reference the same set of cells"
             ),
-            Error::DuplicateMethodOutputs { .. } => write!(
+            Error::InvalidMethodOutputs { .. } => write!(
                 f,
                 "a method's outputs must be duplicate-free, and no two methods in a \
-                 relationship may share an outputs set"
+                 relationship may have identical or nested output sets"
             ),
             Error::InvalidConditional { .. } => write!(f, "conditional is structurally invalid"),
             Error::InvalidOutput => write!(f, "output is structurally invalid"),
@@ -218,10 +229,11 @@ impl Error {
             | Error::MethodFailed { sites, .. }
             | Error::InvalidMethod { sites }
             | Error::MismatchedMethodCells { sites }
-            | Error::DuplicateMethodOutputs { sites }
+            | Error::InvalidMethodOutputs { sites }
             | Error::InvalidCellKind { sites }
             | Error::Conflict { sites }
             | Error::Cycle { sites }
+            | Error::SeedCycle { sites }
             | Error::DependencyCycle { sites }
             | Error::InvalidConditional { sites } => sites,
             _ => &[],
@@ -324,6 +336,7 @@ mod tests {
         assert!(std::error::Error::source(&Error::InvalidId).is_none());
         assert!(std::error::Error::source(&Error::Conflict { sites: vec![] }).is_none());
         assert!(std::error::Error::source(&Error::Cycle { sites: vec![] }).is_none());
+        assert!(std::error::Error::source(&Error::SeedCycle { sites: vec![] }).is_none());
         assert!(std::error::Error::source(&Error::InvalidMethod { sites: vec![] }).is_none());
         assert!(
             std::error::Error::source(&Error::TypeMismatch {
@@ -337,7 +350,7 @@ mod tests {
             std::error::Error::source(&Error::MismatchedMethodCells { sites: vec![] }).is_none()
         );
         assert!(
-            std::error::Error::source(&Error::DuplicateMethodOutputs { sites: vec![] }).is_none()
+            std::error::Error::source(&Error::InvalidMethodOutputs { sites: vec![] }).is_none()
         );
     }
 
@@ -365,9 +378,9 @@ mod tests {
     }
 
     #[test]
-    fn duplicate_method_outputs_display_contains_outputs() {
+    fn invalid_method_outputs_display_contains_outputs() {
         assert!(
-            Error::DuplicateMethodOutputs { sites: vec![] }
+            Error::InvalidMethodOutputs { sites: vec![] }
                 .to_string()
                 .contains("outputs")
         );
@@ -442,6 +455,15 @@ mod tests {
         );
     }
 
+    #[test]
+    fn seed_cycle_display_mentions_seed_dependency_cycle() {
+        assert!(
+            Error::SeedCycle { sites: vec![] }
+                .to_string()
+                .contains("seed dependency cycle")
+        );
+    }
+
     #[test]
     fn dependency_cycle_has_no_source() {
         assert!(std::error::Error::source(&Error::DependencyCycle { sites: vec![] }).is_none());
@@ -454,6 +476,13 @@ mod tests {
         assert_eq!(e.sites(), &[site]);
     }
 
+    #[test]
+    fn seed_cycle_exposes_its_sites() {
+        let site = ErrorSite::Cell(CellId::default());
+        let e = Error::SeedCycle { sites: vec![site] };
+        assert_eq!(e.sites(), &[site]);
+    }
+
     #[test]
     fn error_site_variants_are_distinct() {
         let a = ErrorSite::MethodIndex(0);

adam-rs/src/planner.rs

@@ -15,7 +15,10 @@
 //!
 //! Method selection is value-blind, including for self-referencing components: a
 //! self-referencing chain reaches the correct values through [`build_seeds`], which
-//! reconstructs each self-referencing input's value at execution time (see
+//! replays the release pass's elimination state to choose sibling seed methods,
+//! reconstructs each self-referencing input's value at execution time, and reports
+//! non-self seed dependency cycles as [`Error::SeedCycle`] rather than substituting a
+//! revisited source value (see
 //! `docs/superpowers/specs/2026-09-07-adam-rs-value-aware-self-ref-planning-design.md`),
 //! not through a value-aware assignment choice.
 //!
@@ -31,6 +34,7 @@
 
 use std::any::Any;
 use std::collections::{HashMap, HashSet};
+use std::rc::Rc;
 
 use slotmap::SlotMap;
 
@@ -50,18 +54,18 @@ use digraph::{Node, add_filter_edges, build_digraph, topological_order};
 use matching::pure_outputs;
 use release::ReleaseFailure;
 
-pub(crate) use seed::build_seeds;
+pub(crate) use seed::{SeedEvaluationCache, SeedSource, build_seeds, build_seeds_for_steps};
 
 /// The seed value each self-referencing input should read this round, keyed by cell. A
 /// cell absent from the map reads its own `source`. See [`seed`] and
 /// `docs/superpowers/specs/2026-09-07-adam-rs-value-aware-self-ref-planning-design.md`.
-pub(crate) type Seeds = HashMap<CellId, Box<dyn Any>>;
+pub(crate) type Seeds = HashMap<CellId, Rc<dyn Any>>;
 
 /// One step of a [`Plan`]'s `execution_order`: either a selected method, or reapplying a
 /// source cell's filter against its (now-settled) current argument values.
 ///
 /// See `docs/superpowers/specs/2026-08-25-adam-rs-filter-revalidation-design.md` §2.2.
-#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub(crate) enum PlanStep {
     /// Execute method `usize` of relationship `RelationshipId`.
     Method(RelationshipId, usize),
@@ -77,6 +81,11 @@ pub(crate) enum PlanStep {
 pub(crate) struct Plan {
     /// Selected steps (methods and filter reclamps) in execution order.
     pub(crate) execution_order: Vec<PlanStep>,
+    /// The exact deterministic cell sequence the release pass evaluated when
+    /// tentatively eliminating sources; [`seed::build_seeds`] replays sibling-local
+    /// elimination against this order when choosing seed methods, so sibling selection
+    /// follows actual elimination state rather than declaration order.
+    pub(crate) elimination_order: Vec<CellId>,
     /// Cells that can never be a source under the relationships this plan considered.
     /// See [`forced_output_cells`].
     pub(crate) forced_outputs: HashSet<CellId>,
@@ -110,8 +119,8 @@ pub(crate) fn plan(
 ) -> Result<Plan, Error> {
     let (forced_outputs, alive) = forced_output_cells(relationships, active);
 
-    let assignment = match release::resolve(cells, relationships, active) {
-        Ok(a) => a,
+    let release = match release::resolve(cells, relationships, active) {
+        Ok(result) => result,
         Err(ReleaseFailure::NoAssignment) => {
             return Err(Error::Conflict {
                 sites: conflict_sites(relationships, active),
@@ -123,6 +132,7 @@ pub(crate) fn plan(
             });
         }
     };
+    let assignment = release.assignment;
 
     let mut adj = build_digraph(&assignment, relationships);
     add_filter_edges(&mut adj, cells, &assignment);
@@ -171,11 +181,14 @@ pub(crate) fn plan(
         .map(|(&rel_id, _)| rel_id)
         .collect();
 
-    Ok(Plan {
+    let plan = Plan {
         execution_order,
+        elimination_order: release.elimination_order,
         forced_outputs,
         forced_relationships,
-    })
+    };
+    debug_assert_eq!(plan.elimination_order.len(), cells.len());
+    Ok(plan)
 }
 
 /// Maps a cyclic assignment to `Relationship`/`Cell` sites in loop order.
@@ -595,6 +608,27 @@ mod tests {
         assert_eq!(plan.execution_order, vec![PlanStep::Method(rel, 0)]);
     }
 
+    #[test]
+    fn plan_retains_release_elimination_order() {
+        let mut sheet = Sheet::new();
+        let a = sheet.add_cell(0_i32);
+        let b = sheet.add_cell(0_i32);
+        let c = sheet.add_cell(0_i32);
+        sheet
+            .add_relationship(vec![
+                Method::from_fn_2_1([a, b], c, |x: &i32, y: &i32| Ok(*x + *y)),
+                Method::from_fn_2_1([a, c], b, |x: &i32, y: &i32| Ok(*y - *x)),
+                Method::from_fn_2_1([b, c], a, |x: &i32, y: &i32| Ok(*y - *x)),
+            ])
+            .unwrap();
+        sheet.write(a, 5_i32).unwrap();
+
+        let active: HashSet<_> = sheet.relationships().collect();
+        let plan = crate::planner::plan(&sheet.cells, &sheet.relationships, &active).unwrap();
+
+        assert_eq!(plan.elimination_order, vec![a, c, b]);
+    }
+
     #[test]
     fn no_filter_reclamp_step_for_a_filtered_cell_that_is_derived_this_round() {
         let mut sheet = Sheet::new();

adam-rs/src/planner/matching.rs

@@ -536,14 +536,15 @@ mod tests {
         let p_b = sheet.add_cell(0_i32);
         let u = sheet.add_cell(0_i32);
         let v = sheet.add_cell(0_i32);
+        let w = sheet.add_cell(0_i32);
         let i32_ty = std::any::TypeId::of::<i32>();
 
         let r_b = sheet
             .add_relationship(vec![
                 Method::new(
-                    vec![p_b],
+                    vec![p_b, w],
                     vec![u, v],
-                    vec![i32_ty],
+                    vec![i32_ty, i32_ty],
                     vec![i32_ty, i32_ty],
                     |args| {
                         let p = *args[0].downcast_ref::<i32>().unwrap();
@@ -552,12 +553,12 @@ mod tests {
                 ),
                 Method::new(
                     vec![p_b, v],
-                    vec![u],
+                    vec![u, w],
+                    vec![i32_ty, i32_ty],
                     vec![i32_ty, i32_ty],
-                    vec![i32_ty],
                     |args| {
                         let p = *args[0].downcast_ref::<i32>().unwrap();
-                        Ok(vec![Box::new(p)])
+                        Ok(vec![Box::new(p), Box::new(p)])
                     },
                 ),
             ])