# 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