alla-allaos-fullstack/plans/task-d.7.8.md

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