feat: add reconcile mode for declarative database seeding

Seed sets can now operate in reconcile mode where the spec is the source
of truth. On each run, initium detects changes and converges the database:
new rows are inserted, changed rows are updated, removed rows are deleted.

- Add `mode: reconcile` option to seed sets (default: `once`)
- Add per-row tracking table for change detection and orphan deletion
- Add content hash on tracking table for fast skip when unchanged
- Add `--dry-run` flag to preview changes without modifying the database
- Add `--reconcile-all` flag to override all seed sets to reconcile mode
- Auto-migrate existing tracking tables (add content_hash column)
- Support auto_id + @ref resolution during reconciliation
- 12 new tests covering reconcile, dry-run, validation, and migration

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

Author: mikkeldamsgaard

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Reconcile mode for seed sets (`mode: reconcile`): declarative seeding where the spec is the source of truth. Changed rows are updated, new rows are inserted, and removed rows are deleted automatically.
+- `--reconcile-all` CLI flag to override all seed sets to reconcile mode for a single run.
+- `--dry-run` CLI flag to preview what changes reconciliation would make without modifying the database.
+- Per-row tracking table (`initium_seed_rows`) for change detection and orphan deletion in reconcile mode.
+- 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.
+
 ## [1.1.0] - 2026-02-26
 
 ### Added

docs/seeding.md

@@ -50,6 +50,7 @@ phases:
     seed_sets:                     # Optional. Seed sets to apply in this phase.
       - name: initial_data
         order: 1                   # Optional. Controls execution order across seed sets.
+        mode: once                 # Optional. "once" (default) or "reconcile".
         tables:
           - table: config
             order: 1               # Optional. Controls execution order within a seed set.
@@ -82,6 +83,7 @@ phases:
 | `phases[].wait_for[].timeout`                   | string   | No       | Per-object timeout override (e.g. `60s`, `2m`, `1m30s`)          |
 | `phases[].seed_sets[].name`                     | string   | Yes      | Unique name for the seed set (used in tracking)                  |
 | `phases[].seed_sets[].order`                    | integer  | No       | Execution order (lower values first, default: 0)                 |
+| `phases[].seed_sets[].mode`                     | string   | No       | Seed mode: `once` (default) or `reconcile`                       |
 | `phases[].seed_sets[].tables[].table`           | string   | Yes      | Target database table name                                       |
 | `phases[].seed_sets[].tables[].order`           | integer  | No       | Execution order within the seed set (default: 0)                 |
 | `phases[].seed_sets[].tables[].unique_key`      | string[] | No       | Columns for duplicate detection                                  |
@@ -213,6 +215,53 @@ rows:
     password_hash: "{{ env.ADMIN_PASSWORD_HASH }}"
 ```
 
+### 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.
+
+Enable reconcile mode per seed set:
+
+```yaml
+seed_sets:
+  - name: departments
+    mode: reconcile        # "once" (default) or "reconcile"
+    tables:
+      - table: departments
+        unique_key: [name]  # Required for reconcile mode
+        rows:
+          - name: Engineering
+          - name: Sales
+```
+
+Or override all seed sets for a single run:
+
+```bash
+initium seed --spec /seeds/seed.yaml --reconcile-all
+```
+
+**How it works:**
+
+1. On each run, initium computes a content hash of the rendered seed set (after template/env expansion).
+2. If the hash matches the stored hash, the seed set is skipped (no-op).
+3. If the hash differs, initium reconciles row by row:
+   - **New rows** (in spec but not in DB) are inserted.
+   - **Changed rows** (different values for same unique key) are updated.
+   - **Removed rows** (in DB but not in spec) are deleted.
+
+**Requirements:**
+- Every table in a reconciled seed set must have a `unique_key`. Without it, there is no way to identify which rows correspond to which spec entries.
+- Environment variable changes trigger reconciliation (resolved values are compared, not raw templates).
+
+**Row tracking:** Initium creates a companion table (`{tracking_table}_rows`, e.g., `initium_seed_rows`) that stores the resolved values of each seeded row. This enables change detection and orphan deletion.
+
+**Dry-run mode:** Preview what reconciliation would do without modifying the database:
+
+```bash
+initium seed --spec /seeds/seed.yaml --dry-run
+```
+
+This logs insert/update/delete counts per table without executing any changes.
+
 ### Reset Mode
 
 Use `--reset` to delete all data from seeded tables and remove tracking entries before re-applying. Tables are deleted in reverse order to respect foreign key constraints:
@@ -276,11 +325,13 @@ spec:
 
 ## CLI Reference
 
-| Flag      | Default    | Description                             |
-| --------- | ---------- | --------------------------------------- |
-| `--spec`  | (required) | Path to seed spec file (YAML or JSON)   |
-| `--reset` | `false`    | Delete existing data and re-apply seeds |
-| `--json`  | `false`    | Enable JSON log output                  |
+| Flag               | Default    | Description                                               |
+| ------------------ | ---------- | --------------------------------------------------------- |
+| `--spec`           | (required) | Path to seed spec file (YAML or JSON)                     |
+| `--reset`          | `false`    | Delete existing data and re-apply seeds                   |
+| `--dry-run`        | `false`    | Preview changes without modifying the database            |
+| `--reconcile-all`  | `false`    | Override all seed sets to reconcile mode for this run      |
+| `--json`           | `false`    | Enable JSON log output                                    |
 
 ## Failure Modes
 

src/main.rs

@@ -145,6 +145,18 @@ enum Commands {
             help = "Reset mode: delete existing data before re-seeding"
         )]
         reset: bool,
+        #[arg(
+            long,
+            env = "INITIUM_DRY_RUN",
+            help = "Dry-run: show what would change without modifying the database"
+        )]
+        dry_run: bool,
+        #[arg(
+            long,
+            env = "INITIUM_RECONCILE_ALL",
+            help = "Override all seed sets to reconcile mode for this run"
+        )]
+        reconcile_all: bool,
     },
 
     /// Render templates into config files
@@ -313,7 +325,12 @@ fn main() {
             lock_file,
             args,
         } => cmd::migrate::run(&log, &args, &workdir, &lock_file),
-        Commands::Seed { spec, reset } => seed::run(&log, &spec, reset),
+        Commands::Seed {
+            spec,
+            reset,
+            dry_run,
+            reconcile_all,
+        } => seed::run(&log, &spec, reset, dry_run, reconcile_all),
         Commands::Render {
             template,
             output,