fix: address all PR #31 review comments

1. hash.rs: Sort tables by (order, table_name) for deterministic hashing
   when multiple tables share the same order value.

2. db.rs (MySQL): Use SHA-256 generated column (row_key_hash) for the
   row tracking table primary key instead of row_key(255) prefix index,
   preventing key collisions for JSON keys exceeding 255 bytes.

3. docs/seeding.md: Clarify that reconcile mode only reconciles when the
   rendered spec changes (hash mismatch), and that out-of-band DB changes
   are not corrected until a spec change triggers reconciliation.

4. executor.rs: Add runtime guard for --reconcile-all — rejects seed sets
   where any table lacks unique_key, preventing wrong-row updates/deletes
   from identical row keys.

5. executor.rs: Skip hash-based fast path for seed sets containing @ref:
   expressions, since resolved reference targets can change without
   affecting the hash (e.g., upstream auto_id row reinserted).

6. executor.rs: Dry-run mode now treats @ref: as literals via
   resolve_value_dry_run(), preventing failures when refs haven't been
   populated (auto_id + refs within same seed set).

7. schema.rs: Reconcile validation now rejects empty/whitespace unique_key
   entries, reserved column names (_ref) in unique_key, and rows missing
   required unique_key columns.

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

Author: mikkeldamsgaard

CHANGELOG.md

@@ -15,6 +15,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Content hash (`content_hash` column) on the seed tracking table for fast "anything changed?" checks before row-by-row comparison.
 - Automatic migration of existing tracking tables: the `content_hash` column is added transparently on first run. Existing seed sets remain in `once` mode with no behavior change.
 
+### Changed
+- Reconcile hash-skip now only applies to seed sets without `@ref:` expressions. Seed sets containing `@ref:` references always run row-level reconciliation to prevent stale foreign keys when upstream auto-generated IDs shift.
+- Hash computation sorts tables by `(order, table_name)` instead of just `order` for deterministic hashing when multiple tables share the same order value.
+- Dry-run mode treats `@ref:` expressions as literals to avoid failures when references haven't been populated yet (e.g., auto_id + refs within the same seed set).
+
+### Fixed
+- `--reconcile-all` now rejects seed sets where any table is missing `unique_key`, preventing reconciliation from generating identical row keys and updating/deleting wrong rows.
+- Reconcile mode validation now rejects empty/whitespace-only `unique_key` entries and reserved column names like `_ref`.
+- Reconcile mode validation now checks that every row contains all `unique_key` columns, preventing incomplete row keys during reconciliation.
+- MySQL row tracking table now uses SHA-256 generated column (`row_key_hash`) for the primary key instead of `row_key(255)` prefix, preventing key collisions for JSON keys exceeding 255 bytes.
+
 ## [1.1.0] - 2026-02-26
 
 ### Added

docs/seeding.md

@@ -217,7 +217,9 @@ rows:
 
 ### Reconcile Mode
 
-By default, seed sets are applied once and never modified (`mode: once`). Reconcile mode makes seeding declarative: the spec becomes the source of truth, and initium converges the database to match it on every run.
+By default, seed sets are applied once and never modified (`mode: once`). Reconcile mode makes seeding declarative: the rendered spec becomes the source of truth, and initium reconciles the database to match it whenever the rendered spec changes.
+
+If the rendered spec has not changed since the last run (content hash match), initium treats the seed set as already reconciled and skips it. Out-of-band database changes are not corrected until a spec change triggers reconciliation again.
 
 Enable reconcile mode per seed set:
 

src/seed/db.rs

@@ -1318,7 +1318,8 @@ impl Database for MysqlDb {
                 row_key TEXT NOT NULL,
                 row_values TEXT NOT NULL,
                 applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-                PRIMARY KEY (seed_set, table_name, row_key(255))
+                row_key_hash BINARY(32) GENERATED ALWAYS AS (UNHEX(SHA2(row_key, 256))) STORED,
+                PRIMARY KEY (seed_set, table_name, row_key_hash)
             )",
             safe
         );

src/seed/executor.rs

@@ -195,6 +195,17 @@ impl<'a> SeedExecutor<'a> {
         );
 
         if is_reconcile {
+            // Guard: reconcile requires unique_key on every table.
+            // Schema validation catches this for mode: reconcile, but --reconcile-all
+            // can force reconcile on mode: once seed sets that lack unique_key.
+            for ts in &ss.tables {
+                if ts.unique_key.is_empty() {
+                    return Err(format!(
+                        "cannot reconcile seed set '{}': table '{}' has no unique_key (required for reconcile mode)",
+                        name, ts.table
+                    ));
+                }
+            }
             return self.reconcile_seed_set(ss);
         }
 
@@ -361,9 +372,20 @@ impl<'a> SeedExecutor<'a> {
         // Compute hash of current spec (resolve env vars, keep @ref: as literals)
         let current_hash = compute_seed_set_hash(ss, &|val| self.resolve_value(val))?;
 
-        // Check stored hash for quick skip
+        // Check stored hash for quick skip.
+        // Only skip if the seed set has no @ref: expressions, because
+        // compute_seed_set_hash treats @ref: values as literals. Resolved
+        // reference targets can change without affecting the hash (e.g.,
+        // upstream auto_id row deleted/reinserted), and skipping could leave
+        // stale foreign keys.
         let stored_hash = self.db.get_seed_hash(&self.tracking_table, name)?;
-        if stored_hash.as_deref() == Some(current_hash.as_str()) {
+        let has_refs = ss.tables.iter().any(|ts| {
+            ts.rows.iter().any(|row| {
+                row.values()
+                    .any(|v| v.as_str().map(|s| s.starts_with("@ref:")).unwrap_or(false))
+            })
+        });
+        if !has_refs && stored_hash.as_deref() == Some(current_hash.as_str()) {
             self.log.info(
                 "seed set unchanged (hash match), skipping",
                 &[("seed_set", name)],
@@ -633,6 +655,15 @@ impl<'a> SeedExecutor<'a> {
         Ok(())
     }
 
+    /// Resolve a value for dry-run: treats `@ref:` as literals to avoid failures
+    /// when refs haven't been populated (common with auto_id + refs in same seed set).
+    fn resolve_value_dry_run(&self, val: &serde_yaml::Value) -> Result<String, String> {
+        match val {
+            serde_yaml::Value::String(s) if s.starts_with("@ref:") => Ok(s.clone()),
+            _ => self.resolve_value(val),
+        }
+    }
+
     /// Dry-run: compute what reconciliation would do without modifying the DB.
     fn dry_run_reconcile_tables(&mut self, ss: &SeedSet) -> Result<(), String> {
         let mut tables: Vec<&TableSeed> = ss.tables.iter().collect();
@@ -659,7 +690,7 @@ impl<'a> SeedExecutor<'a> {
                     if key == "_ref" {
                         continue;
                     }
-                    let resolved = self.resolve_value(val)?;
+                    let resolved = self.resolve_value_dry_run(val)?;
                     columns.push(key.clone());
                     values.push(resolved.clone());
                     if ts.unique_key.contains(key) {
@@ -2362,4 +2393,36 @@ phases:
         assert!(result.is_err());
         assert!(result.unwrap_err().contains("invalid mode"));
     }
+
+    #[test]
+    fn test_reconcile_all_rejects_missing_unique_key() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let db_path = dir.path().join("test.db");
+        let db_path_str = db_path.to_str().unwrap();
+
+        let sqlite = SqliteDb::connect(db_path_str).unwrap();
+        setup_db_with_tables(&sqlite);
+
+        // mode: once with no unique_key + reconcile_all should error
+        let yaml = r#"
+database:
+  driver: sqlite
+  url: ":memory:"
+phases:
+  - name: phase1
+    seed_sets:
+      - name: no_uk
+        tables:
+          - table: departments
+            rows:
+              - name: Engineering
+"#;
+        let plan = SeedPlan::from_yaml(yaml).unwrap();
+        let log = test_logger();
+        let mut exec = SeedExecutor::new(&log, Box::new(sqlite), "initium_seed".into(), false)
+            .with_reconcile_all(true);
+        let result = exec.execute(&plan);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("no unique_key"));
+    }
 }

src/seed/hash.rs

@@ -16,7 +16,7 @@ pub fn compute_seed_set_hash(
     let mut hasher = Sha256::new();
 
     let mut tables: Vec<_> = ss.tables.iter().collect();
-    tables.sort_by_key(|t| t.order);
+    tables.sort_by(|a, b| a.order.cmp(&b.order).then_with(|| a.table.cmp(&b.table)));
 
     for ts in &tables {
         hasher.update(ts.table.as_bytes());

src/seed/schema.rs

@@ -238,6 +238,35 @@ impl SeedPlan {
                     ts.table, ss.name
                 ));
             }
+            if ss.is_reconcile() {
+                if ts.unique_key.iter().any(|k| k.trim().is_empty()) {
+                    return Err(format!(
+                        "table '{}' in seed_set '{}' has empty or whitespace-only entries in unique_key when mode is 'reconcile'",
+                        ts.table, ss.name
+                    ));
+                }
+                let reserved_keys = ["_ref"];
+                if let Some(reserved) = ts
+                    .unique_key
+                    .iter()
+                    .find(|k| reserved_keys.contains(&k.as_str()))
+                {
+                    return Err(format!(
+                        "table '{}' in seed_set '{}' uses reserved column '{}' in unique_key when mode is 'reconcile'",
+                        ts.table, ss.name, reserved
+                    ));
+                }
+                for (row_idx, row) in ts.rows.iter().enumerate() {
+                    for uk in &ts.unique_key {
+                        if !row.contains_key(uk) {
+                            return Err(format!(
+                                "table '{}' in seed_set '{}': row {} is missing unique_key column '{}'",
+                                ts.table, ss.name, row_idx + 1, uk
+                            ));
+                        }
+                    }
+                }
+            }
         }
         Ok(())
     }
@@ -646,4 +675,67 @@ phases:
         let plan = SeedPlan::from_yaml(yaml).unwrap();
         assert!(plan.phases[0].seed_sets.is_empty());
     }
+
+    #[test]
+    fn test_reconcile_rejects_empty_unique_key_entry() {
+        let yaml = r#"
+database:
+  driver: sqlite
+  url: ":memory:"
+phases:
+  - name: p
+    seed_sets:
+      - name: s
+        mode: reconcile
+        tables:
+          - table: t
+            unique_key: ["", "k"]
+            rows:
+              - k: a
+"#;
+        let err = SeedPlan::from_yaml(yaml).unwrap_err();
+        assert!(err.contains("empty or whitespace-only"));
+    }
+
+    #[test]
+    fn test_reconcile_rejects_reserved_unique_key() {
+        let yaml = r#"
+database:
+  driver: sqlite
+  url: ":memory:"
+phases:
+  - name: p
+    seed_sets:
+      - name: s
+        mode: reconcile
+        tables:
+          - table: t
+            unique_key: [_ref]
+            rows:
+              - _ref: r1
+"#;
+        let err = SeedPlan::from_yaml(yaml).unwrap_err();
+        assert!(err.contains("reserved column '_ref'"));
+    }
+
+    #[test]
+    fn test_reconcile_rejects_row_missing_unique_key_column() {
+        let yaml = r#"
+database:
+  driver: sqlite
+  url: ":memory:"
+phases:
+  - name: p
+    seed_sets:
+      - name: s
+        mode: reconcile
+        tables:
+          - table: t
+            unique_key: [email]
+            rows:
+              - name: Alice
+"#;
+        let err = SeedPlan::from_yaml(yaml).unwrap_err();
+        assert!(err.contains("missing unique_key column 'email'"));
+    }
 }