# Task D.7.8 – Seed Manifest and Setup State Persistence ## Objective Add persistent setup run tracking and seed manifest lifecycle tracking for ALLA OS Initial Setup. This task must make the Setup Wizard resumable, auditable, and able to persist setup reports across browser refreshes and future setup sessions. D.7.8 should build on: - D.7.2 Readiness and Verification APIs - D.7.3 CSV Template Pack - D.7.4 CSV Preview Validation Engine - D.7.5 CSV Commit Import Engine - D.7.6 Dashboard Setup Wizard UI This task must not implement destructive reset/reseed behavior. Reset remains D.7.7. --- ## Review Before Implementation Review: - AGENTS.md - plans/task-d.7.md - plans/task-d.7.1.md - plans/task-d.7.2.md - plans/task-d.7.3.md - plans/task-d.7.4.md - plans/task-d.7.5.md - plans/task-d.7.6.md - docs/setup/setup-state-machine.md - docs/setup/seed-version-manifest.md - docs/setup/setup-wizard-blueprint.md - docs/setup/verification-matrix.md - docs/setup/reset-reseed-matrix.md - docs/setup/setup-plugin-architecture.md - src/db/schema.ts - src/features/setup/** - src/app/dashboard/administration/setup/page.tsx - src/app/api/setup/** - existing migration conventions under drizzle/ --- ## Implementation Scope Add setup persistence tables: - setup_runs - setup_run_steps - seed_manifests - seed_manifest_items Add migration through existing Drizzle workflow. Add schema definitions to: src/db/schema.ts or appropriate split schema location if the repo already uses modular schema files. Add setup persistence services: src/features/setup/server/setup-state.service.ts src/features/setup/server/seed-manifest.service.ts Add API routes: GET /api/setup/run/current POST /api/setup/run/start POST /api/setup/run/step POST /api/setup/run/complete GET /api/setup/run/report Update setup wizard UI to: - load current setup run - resume prior step status - persist step outputs - show completed/pending/stale step status - persist finish report - show setup completed state Update CSV commit flow to optionally record seed manifest and manifest items. --- ## Database Tables ### setup_runs Purpose: One row per setup attempt/session. Suggested fields: id status mode target_organization_id started_by completed_by started_at completed_at last_error metadata created_at updated_at Status values: not_started readiness_checked foundation_installed organization_created administrator_created scope_configured sequences_configured approval_configured csv_validated csv_imported verified completed failed cancelled Mode values: production demo_uat dry_run --- ### setup_run_steps Purpose: Step-level state, input hash, output report, warning/error history. Suggested fields: id setup_run_id step_key status input_hash output_json errors_json warnings_json started_at completed_at created_at updated_at Step status values: not_started running passed warning failed skipped stale --- ### seed_manifests Purpose: Track seed/import package lifecycle. Suggested fields: id setup_run_id organization_id name version type checksum status source applied_by applied_at report_json created_at updated_at Type values: foundation organization business demo_uat setup_state Status values: pending applied skipped warning failed rolled_back --- ### seed_manifest_items Purpose: Track per-file/per-seed item checksum and result. Suggested fields: id seed_manifest_id item_key source_file checksum status imported_count updated_count skipped_count error_count warning_count report_json created_at updated_at --- ## State Machine Rules Use: docs/setup/setup-state-machine.md Required events: CHECK_READINESS INSTALL_FOUNDATION CREATE_ORGANIZATION CREATE_ADMIN CONFIGURE_SCOPE CONFIGURE_SEQUENCES CONFIGURE_APPROVAL VALIDATE_CSV IMPORT_CSV RUN_VERIFICATION COMPLETE_SETUP FAIL_STEP CANCEL_SETUP RESUME_SETUP RESET_STEP For D.7.8, implement only non-destructive events. Do not implement RESET_STEP destructive behavior. RESET_STEP can return: not implemented until D.7.7 --- ## Persistence Rules Every setup step should persist: - step key - status - input hash - output summary/report - warnings - errors - completed timestamp If the same step is re-run: - update same step row - keep latest report - mark dependent later steps as stale when needed Staleness rules: - readiness changed → all later steps stale - organization changed → admin, scope, sequence, approval, CSV, verification stale - scope changed → sequence, approval, CSV, verification stale - sequence changed → verification stale - approval changed → CSV and verification stale - CSV preview changed → commit stale - CSV commit changed → verification stale --- ## Setup Run Behavior ### Current Run GET /api/setup/run/current Returns: - active setup run if exists - latest completed setup run if no active run - setup step summaries - manifest summaries - completion status ### Start Run POST /api/setup/run/start Creates new setup run. Rules: - super_admin only - if active run exists, return existing run unless `forceNew=true` - mode defaults to production - target organization optional until resolved ### Save Step POST /api/setup/run/step Persists step report. Input: - setupRunId - stepKey - status - inputHash - output - warnings - errors Rules: - validate step key - update run status based on state machine - mark downstream stale steps as needed ### Complete Run POST /api/setup/run/complete Rules: - all required steps must be passed/warning acknowledged - blocking failure prevents completion - verification must be latest and not stale - writes completed_at and status completed - returns final report ### Report GET /api/setup/run/report Returns: - setup run summary - steps - manifests - final readiness/verification/import summaries --- ## Seed Manifest Behavior When CSV commit succeeds, create or update a manifest. Recommended package: crm-business-import Manifest item per committed CSV file. For each file: - source_file - checksum - status - imported_count - updated_count - skipped_count - error_count - warning_count - report_json Version: 1.0.0 Source: csv Type: business Checksum behavior: - same version + same checksum = skipped/already applied - same version + changed checksum = warning unless force mode - new checksum after successful import creates new manifest revision or new manifest row depending on chosen implementation If D.7.5 import is dryRun: - do not write seed manifest - optionally persist setup step output only --- ## API Security - all routes protected - require super_admin for D.7.8 - never expose raw SQL errors - never expose passwords, password hashes, secrets, storage credentials - report only safe summaries - setup reports can include filenames and counts, not raw CSV contents --- ## UI Updates Update: src/features/setup/components/setup-wizard.tsx Add: - load current setup run on mount - resume banner - persisted step status - stale step badge - completed setup summary - save step result after readiness, preview, commit, verification - complete setup button on finish step - report panel from persisted data Important: The wizard should still work if persistence API fails, but must show a warning. --- ## Out Of Scope - Destructive reset/reseed - RESET_STEP implementation - installation profile engine - plugin runtime - CSV parser changes unless needed for checksum - setup template changes - storage import - attachment import - new CRM behavior - production setup lock enforcement beyond completed status display --- ## Deliverables Required schema/migration: src/db/schema.ts drizzle migration file Required services: src/features/setup/server/setup-state.service.ts src/features/setup/server/seed-manifest.service.ts Required API routes: src/app/api/setup/run/current/route.ts src/app/api/setup/run/start/route.ts src/app/api/setup/run/step/route.ts src/app/api/setup/run/complete/route.ts src/app/api/setup/run/report/route.ts Required UI update: src/features/setup/components/setup-wizard.tsx Optional helpers: src/features/setup/server/setup-state-machine.ts src/features/setup/server/setup-report.service.ts --- ## Acceptance Criteria ✓ setup_runs table exists. ✓ setup_run_steps table exists. ✓ seed_manifests table exists. ✓ seed_manifest_items table exists. ✓ Drizzle migration generated. ✓ Current setup run API works. ✓ Start setup run API works. ✓ Save setup step API works. ✓ Complete setup run API works. ✓ Setup report API works. ✓ Wizard can resume current run after refresh. ✓ Wizard shows persisted step statuses. ✓ Wizard marks stale dependent steps after rerun. ✓ CSV commit creates seed manifest records when commit succeeds. ✓ dryRun commit does not create seed manifest records. ✓ Completed setup run stores final report. ✓ All APIs require super_admin. ✓ No destructive reset logic is implemented. ✓ No secrets or raw CSV contents are persisted. ✓ Typecheck passes or unrelated failures are documented. --- ## Suggested Verification Run: npm run db:generate npm run db:migrate npm run typecheck Run scoped lint: npx oxlint src/features/setup src/app/api/setup src/app/dashboard/administration/setup src/db/schema.ts Manual test: 1. Open Setup Wizard. 2. Start setup run. 3. Run readiness. 4. Refresh browser. 5. Confirm readiness result persists. 6. Upload CSV and preview. 7. Refresh browser. 8. Confirm preview step status persists without raw CSV content. 9. Commit CSV. 10. Confirm seed manifest and manifest item rows exist. 11. Run verification. 12. Complete setup. 13. Refresh browser. 14. Confirm completed setup summary appears. 15. Try as non-super_admin. 16. Confirm access denied. --- ## Follow-up After D.7.8: D.7.7 – Scoped Reset and Reseed Engine D.7.9 – Installation Profile and Plugin Runtime Enhancement