fix(property-model): document TypeMismatch convention, reserve adj fields, polish docs

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: sean-parent

property-model/src/cell.rs

@@ -14,7 +14,6 @@ new_key_type! {
 }
 
 /// Internal storage for a single value cell; fields are used by `Sheet` (added in a later task).
-#[allow(dead_code)]
 pub(crate) struct CellData {
     /// The type-erased current value.
     pub(crate) value: Box<dyn Any>,

property-model/src/error.rs

@@ -6,11 +6,14 @@ use std::any::TypeId;
 #[derive(Debug)]
 #[non_exhaustive]
 pub enum Error {
-    /// A value's `TypeId` did not match the cell's registered `TypeId`.
+    /// A value's TypeId did not match the cell's registered TypeId.
+    ///
+    /// - `expected`: the TypeId registered when the cell was created.
+    /// - `found`: the TypeId of the value or declaration supplied by the caller.
     TypeMismatch {
-        /// The expected type ID.
+        /// The TypeId registered when the cell was created.
         expected: TypeId,
-        /// The actual type ID found.
+        /// The TypeId of the value or declaration supplied by the caller.
         found: TypeId,
     },
 
@@ -61,6 +64,24 @@ impl std::error::Error for Error {
 mod tests {
     use super::*;
 
+    #[test]
+    fn type_mismatch_fields_convention() {
+        use std::any::TypeId;
+        let expected = TypeId::of::<i32>();
+        let found = TypeId::of::<f64>();
+        let e = Error::TypeMismatch { expected, found };
+        match e {
+            Error::TypeMismatch {
+                expected: e,
+                found: f,
+            } => {
+                assert_eq!(e, TypeId::of::<i32>());
+                assert_eq!(f, TypeId::of::<f64>());
+            }
+            _ => panic!("wrong variant"),
+        }
+    }
+
     #[test]
     fn type_mismatch_display_contains_type_mismatch() {
         let err = Error::TypeMismatch {

property-model/src/lib.rs

@@ -10,7 +10,7 @@
 //!
 //! # Example
 //!
-//! ```rust,ignore
+//! ```rust
 //! use property_model::{Sheet, Method};
 //!
 //! let mut sheet = Sheet::new();

property-model/src/planner.rs

@@ -4,6 +4,11 @@
 //! strength (write-recency clock value) of the method's output cells — preferring to
 //! derive cells that were written least recently. Phase 2 runs Kahn's algorithm to
 //! produce a dependency-ordered execution sequence.
+//!
+//! The greedy Phase 1 selection is per-relationship with no global optimality guarantee;
+//! it minimises the minimum output-cell strength locally but does not guarantee that the
+//! globally strongest cell is preserved across the whole sheet. A future model checker
+//! will verify solvability.
 
 use std::collections::{HashMap, HashSet, VecDeque};
 

property-model/src/relationship.rs

@@ -111,10 +111,10 @@ impl Method {
 }
 
 /// Internal storage for a relationship; fields are used by `Sheet` (added in a later task).
-#[allow(dead_code)]
 pub(crate) struct RelationshipData {
     pub(crate) methods: Vec<Method>,
     /// Union of all cell IDs referenced by any method in this relationship.
+    #[expect(dead_code, reason = "adj is reserved for the future model checker")]
     pub(crate) adj: Vec<CellId>,
 }
 

property-model/src/sheet.rs

@@ -221,6 +221,7 @@ impl Sheet {
 
     /// Runs the planning pass and executes the selected methods.
     ///
+    /// Clears the changed-cell set from the previous `propagate()` call before planning.
     /// After propagation, call [`Sheet::changed`] to inspect which cells were updated,
     /// and [`Sheet::clear_changed`] when done.
     ///