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

Task D.7.7 – Scoped Reset and Reseed Engine

Objective

Implement a safe, non-production Scoped Reset and Reseed Engine for ALLA OS Initial Setup.

This task must allow controlled reset/reseed operations for setup, foundation, organization, business, demo/UAT, and CSV-imported data while preserving production safety guards.

D.7.7 must use the Setup State and Seed Manifest foundations from D.7.8 where possible.

This task must not introduce any destructive reset path for production.

---

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
• plans/task-d.7.8.md
• docs/setup/reset-reseed-matrix.md
• docs/setup/seed-version-manifest.md
• docs/setup/setup-state-machine.md
• docs/setup/seed-matrix.md
• docs/setup/import-mapping.md
• src/db/schema.ts
• src/features/setup/**
• src/app/api/setup/**
• scripts/seed-reset.ts
• scripts/db/reset-database.ts
• scripts/seed-system.ts
• scripts/seed-uat.ts
• src/db/seeds/**/*
• existing storage provider implementation

---

Implementation Scope

Create reset/reseed services:

src/features/setup/server/reset.service.ts src/features/setup/server/reseed.service.ts

Optional helpers:

src/features/setup/server/reset-guards.ts src/features/setup/server/reset-report.ts src/features/setup/server/reset-scopes.ts

Create API routes:

POST /api/setup/reset/preview POST /api/setup/reset/execute POST /api/setup/reseed/preview POST /api/setup/reseed/execute

Optional UI integration:

Add a Maintenance panel in Setup Wizard or Administration Setup page.

---

Reset Scopes

Implement scopes from docs/setup/reset-reseed-matrix.md:

foundation_reset

organization_reset

business_reset

demo_uat_reset

csv_import_rollback

setup_run_reset

full_reset

---

Scope Rules

foundation_reset

Deletes and optionally reseeds organization-scoped foundation rows.

May affect:

• ms_options
• document_sequences
• approval workflows
• approval steps
• approval matrices
• document template foundation rows
• document library foundation rows
• notification templates
• report definitions

Must retain:

• users
• organizations
• memberships
• business CRM data unless explicitly selected

---

organization_reset

Deletes target organization and tenant-scoped rows.

Must require exact organization code/name confirmation.

Must retain:

• global users unless explicitly selected

Must delete:

• memberships for target organization
• CRM role assignments/profiles for target organization
• organization-scoped foundation rows
• business rows for target organization

---

business_reset

Deletes CRM business records for target organization.

May affect:

• customers
• contacts
• contact shares
• leads
• opportunities
• quotations
• quotation items
• quotation parties
• quotation topics
• quotation topic items
• followups
• business attachment metadata

Must retain:

• organization
• users
• memberships
• foundation rows
• setup run history unless explicitly selected

---

demo_uat_reset

Deletes deterministic Demo/UAT rows only.

Must rely on:

• UAT seed markers
• deterministic emails/codes
• seed manifest records
• known UAT seed package names

Must retain:

• production foundation
• non-UAT business data

---

csv_import_rollback

Rolls back rows associated with a seed manifest/import package when safely reversible.

Rules:

• only rollback manifest-owned rows
• block rollback if rows were changed after import and no safe conflict policy exists
• if rollback is not fully safe, return warning and require manual review
• do not pretend arbitrary rollback is safe

---

setup_run_reset

Deletes setup run metadata only.

May affect:

• setup_runs
• setup_run_steps
• seed_manifests
• seed_manifest_items

Must not delete:

• business data
• foundation data
• organizations
• users

---

full_reset

Must use existing guarded reset script behavior.

Rules:

• block in production
• require explicit allow flag
• require typed confirmation
• local/test only by default
• do not expose casually in UI

---

Safety Guards

All destructive actions require:

• super_admin
• non-production environment
• explicit scope
• target organization when scope is organization-aware
• typed confirmation
• preview before execute
• confirmation token generated from preview
• token expires after short duration
• execute must match preview hash/token

Block when:

• NODE_ENV=production
• production-like database host/name is detected
• missing target organization
• missing typed confirmation
• preview was not run
• preview token expired
• preview hash mismatch
• affected row count exceeds safe threshold unless force flag is provided

---

Preview Behavior

Reset preview must not delete anything.

Preview returns:

• scope
• target organization
• affected tables
• estimated row counts
• retained data
• deleted data
• storage cleanup plan
• manifest impact
• warnings
• blocking errors
• confirmation phrase
• previewHash
• confirmationToken

Example:

{ "scope": "business_reset", "targetOrganization": "ALLA", "summary": { "tables": 12, "rows": 520, "warnings": 2, "errors": 0 }, "affectedTables": [], "confirmationPhrase": "RESET BUSINESS ALLA", "previewHash": "...", "confirmationToken": "..." }

---

Execute Behavior

Execute requires:

• scope
• previewHash
• confirmationToken
• typed confirmation phrase

Execution must:

1. Rebuild preview.
2. Compare previewHash.
3. Validate token.
4. Validate typed confirmation.
5. Run reset inside transaction where DB-only.
6. Handle storage cleanup best-effort.
7. Persist reset report to setup run if available.
8. Return final report.

---

Reseed Behavior

Reseed is optional but recommended for:

• foundation_reset
• demo_uat_reset
• csv_import_rollback after cleanup

Reseed must call existing seed services/scripts through safe wrappers.

Do not duplicate seed data.

Supported reseed targets:

foundation

demo_uat

csv_manifest

Rules:

• foundation reseed is idempotent
• demo/UAT reseed is deterministic
• csv_manifest reseed requires original manifest/files available or block with clear reason

---

Storage Cleanup

Storage cleanup must be:

• best-effort
• scoped
• reported
• never silent

Rules:

• delete setup-owned temp objects only when safe
• delete demo-generated objects only under demo prefix
• do not delete approved immutable artifacts unless explicit full reset/demo reset and policy allows
• if cleanup fails, DB transaction should not necessarily rollback unless storage cleanup is required by scope
• report leftover keys

---

Seed Manifest Integration

Use D.7.8 seed manifest tables.

Reset preview should show:

• affected seed manifests
• affected seed manifest items
• whether import rollback is safe
• checksum/package info

Reset execute should update manifest status when applicable:

• rolled_back
• warning
• failed

Do not delete manifest rows unless scope is setup_run_reset.

---

Setup State Integration

Reset should update setup run state when applicable.

Examples:

• business_reset marks csv_commit and verification stale
• foundation_reset marks readiness, scope, sequence, approval, CSV, and verification stale
• setup_run_reset clears setup state only
• organization_reset cancels or invalidates active setup runs for that organization

Do not implement destructive RESET_STEP from UI unless explicitly scoped.

---

API Contracts

POST /api/setup/reset/preview

Input:

scope organizationId? organizationCode? manifestId? options?

Output:

ResetPreviewReport

---

POST /api/setup/reset/execute

Input:

scope previewHash confirmationToken confirmationPhrase organizationId? organizationCode? manifestId? options?

Output:

ResetExecuteReport

---

POST /api/setup/reseed/preview

Input:

target organizationId? organizationCode? manifestId? options?

Output:

ReseedPreviewReport

---

POST /api/setup/reseed/execute

Input:

target previewHash confirmationToken confirmationPhrase organizationId? organizationCode? manifestId? options?

Output:

ReseedExecuteReport

---

UI Requirements If Implemented

Add Maintenance panel:

• Reset scope selector
• Target organization selector
• Preview button
• Affected tables/counts
• Warnings/errors
• Typed confirmation input
• Execute button
• Final report

UI must hide or disable destructive actions when environment is production.

---

Out Of Scope

• Production reset workflow
• Silent automatic reset
• Arbitrary rollback without manifest ownership
• Deleting approved production artifacts
• New seed data creation
• Installation profile engine
• Plugin runtime
• Backup/restore
• Data anonymization
• Cross-environment migration
• Email/storage secret reset
• Changing CRM business behavior

---

Deliverables

Required:

src/features/setup/server/reset.service.ts src/features/setup/server/reseed.service.ts src/features/setup/server/reset-guards.ts src/features/setup/server/reset-report.ts

API routes:

src/app/api/setup/reset/preview/route.ts src/app/api/setup/reset/execute/route.ts src/app/api/setup/reseed/preview/route.ts src/app/api/setup/reseed/execute/route.ts

Optional:

src/features/setup/components/setup-maintenance-panel.tsx

---

Acceptance Criteria

✓ Reset preview API exists.

✓ Reset execute API exists.

✓ Reseed preview API exists.

✓ Reseed execute API exists.

✓ All APIs require super_admin.

✓ Production destructive reset is blocked.

✓ Preview is required before execute.

✓ Execute requires valid previewHash.

✓ Execute requires valid confirmationToken.

✓ Execute requires typed confirmation phrase.

✓ Organization-aware scopes require target organization.

✓ Preview returns affected tables and estimated rows.

✓ Execute uses transaction for DB-only deletes.

✓ Storage cleanup is best-effort and reported.

✓ Seed manifest status updates for rollback/reset where applicable.

✓ Setup run steps are marked stale after reset.

✓ full_reset delegates to existing guarded reset behavior or blocks with clear instructions.

✓ No reset deletes approved immutable artifacts unless explicitly allowed by scope policy.

✓ No seed logic is duplicated.

✓ Typecheck passes or unrelated failures are documented.

---

Suggested Verification

Run:

npm run typecheck

Run scoped lint:

npx oxlint src/features/setup src/app/api/setup

Manual test:

1. Run business_reset preview for ALLA.
2. Confirm affected table counts are shown.
3. Execute without preview token.
4. Confirm blocked.
5. Execute with wrong confirmation phrase.
6. Confirm blocked.
7. Execute with valid token and phrase in local environment.
8. Confirm rows deleted and foundation retained.
9. Run setup verification.
10. Confirm CSV/verification steps stale.
11. Try in NODE_ENV=production.
12. Confirm destructive reset is blocked.
13. Run setup_run_reset.
14. Confirm setup metadata deleted but business rows remain.
15. Run csv_import_rollback for manifest.
16. Confirm only manifest-owned rows are affected or rollback is blocked with manual review warning.

---

Follow-up

After D.7.7:

D.7.9 – Installation Profile and Plugin Runtime Enhancement

D.7.10 – Setup Integration Test and Golden Dataset