alla-allaos-fullstack/docs/implementation/task-d77-scoped-reset-reseed-engine.md

Task D.7.7 Scoped Reset Reseed Engine

Date: 2026-07-03 Status: implemented

Scope Delivered

Added setup reset/reseed server foundations:

• 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
• src/features/setup/server/reset-scopes.ts

Added protected setup maintenance APIs:

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

Reset Behavior

Reset preview is implemented for all D.7.7 scopes:

• foundation_reset
• organization_reset
• business_reset
• demo_uat_reset
• full_reset
• csv_import_rollback
• setup_run_reset

Reset execute is implemented only where ownership and safety are clear:

• setup_run_reset
  • Deletes setup metadata only.
  • Deletes setup_runs, setup_run_steps, seed_manifests, and seed_manifest_items.
  • Does not delete business, organization, foundation, or user data.
• business_reset
  • Deletes organization-scoped CRM business rows only.
  • Retains organization, users, memberships, and foundation rows.
  • Marks matching seed manifests rolled_back.
  • Marks CSV commit and verification setup steps stale.

The following scopes intentionally block execution with safe reports:

• foundation_reset
• organization_reset
• demo_uat_reset
• full_reset
• csv_import_rollback

These are blocked until service-specific seed/reseed wrappers, deterministic UAT ownership markers, or reversible manifest ownership metadata are available.

Reseed Behavior

Reseed preview exists for:

• foundation
• demo_uat
• csv_manifest

Reseed execute is blocked in D.7.7 and returns a safe report. This avoids duplicating seed scripts or pretending CSV manifests can be replayed when original CSV payloads are not persisted.

Safety Guards

All reset/reseed APIs require:

• super_admin
• non-production environment
• non-production-like database host/name
• explicit scope or target
• preview before execute
• valid previewHash
• valid short-lived confirmationToken
• exact typed confirmation phrase

Organization-aware scopes require organizationId.

Report Behavior

Preview reports include:

• scope or reseed target
• affected tables
• estimated row counts
• retained data
• deleted data
• storage cleanup plan
• seed manifest impact
• warnings and blocking errors
• confirmation phrase
• preview hash
• confirmation token and expiry

Execute reports include:

• execution status
• deleted row estimate
• updated manifest count
• best-effort storage cleanup result

Storage cleanup is report-only/best-effort and never silently deletes approved production artifacts.

Out Of Scope Preserved

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

Validation

• npm run typecheck -- --pretty false passed.
• npx oxlint 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 src/features/setup/server/reset-scopes.ts src/app/api/setup/reset src/app/api/setup/reseed passed.

Residual Notes

• Full reset remains delegated to existing guarded scripts operationally; the dashboard API returns a blocking report instead of running process-level database reset commands.
• csv_import_rollback remains report-only because D.7.8 seed manifest records do not persist enough row-level reversible ownership metadata for arbitrary rollback.
• demo_uat_reset remains blocked until UAT rows have deterministic persisted ownership markers beyond seed conventions.