task-d.7.8

docs/implementation/task-d78-seed-manifest-setup-state-persistence.md

@@ -0,0 +1,86 @@
+# Task D.7.8 Seed Manifest Setup State Persistence
+
+Date: 2026-07-03
+Status: implemented
+
+## Scope Delivered
+
+Added setup persistence schema and migration:
+
+- `setup_runs`
+- `setup_run_steps`
+- `seed_manifests`
+- `seed_manifest_items`
+- `drizzle/0004_setup_state_seed_manifest.sql`
+
+Added setup state services:
+
+- `src/features/setup/server/setup-state.service.ts`
+- `src/features/setup/server/seed-manifest.service.ts`
+
+Added protected setup run APIs:
+
+- `GET /api/setup/run/current`
+- `POST /api/setup/run/start`
+- `POST /api/setup/run/steps`
+- `POST /api/setup/run/complete`
+- `GET /api/setup/run/report`
+
+Updated CSV commit integration:
+
+- Successful non-dry-run CSV commits create seed manifest records.
+- Dry-run commits do not write seed manifest records.
+- Failed commits do not write seed manifest records.
+
+Updated Setup Wizard UI:
+
+- Loads current setup run on mount.
+- Shows resumable/completed setup run banner.
+- Shows persisted step statuses.
+- Saves readiness, CSV preview, CSV commit, and verification step outputs.
+- Marks dependent later steps stale when step input hash changes.
+- Shows persisted seed manifest summaries.
+- Adds complete setup action.
+- Wizard remains usable if persistence APIs fail, with a warning.
+
+## Persistence Behavior
+
+- Step re-runs update the same `setup_run_steps` row.
+- Latest step report replaces prior step report.
+- CSV preview persistence strips raw row values before saving.
+- CSV commit persistence strips row-level raw details before saving.
+- Seed manifest item records store filenames, checksums, counts, status, and safe reports.
+- No raw CSV contents, passwords, password hashes, SQL errors, storage credentials, or secrets are persisted.
+
+## Staleness Rules Implemented
+
+- `readiness` changes mark later setup steps stale.
+- `organization` changes mark administrator, scope, sequence, approval, CSV, and verification steps stale.
+- `scope` changes mark sequence, approval, CSV, and verification steps stale.
+- `sequences` changes mark verification stale.
+- `approval` changes mark CSV and verification stale.
+- `csv_preview` changes mark `csv_commit` stale.
+- `csv_commit` changes mark verification stale.
+
+## Out Of Scope Preserved
+
+- No destructive reset/reseed behavior.
+- No `RESET_STEP` implementation.
+- No installation profile plugin runtime.
+- No CSV parser changes.
+- No setup template changes.
+- No storage or attachment import.
+- No new CRM behavior.
+- No production setup lock enforcement beyond completed status display.
+
+## Validation
+
+- `npm run typecheck -- --pretty false` passed.
+- `npx oxlint src/features/setup src/app/api/setup src/app/dashboard/administration/setup src/db/schema.ts` passed.
+- `npm run db:migrate` passed and applied migrations successfully.
+
+## Residual Notes
+
+- `plans/task-d.7.8.md` was untracked during implementation and was not modified as part of this delivery.
+- The Drizzle migration was added manually to match the current repository migration style and journal.
+- D.7.7 remains responsible for scoped reset/reseed behavior.