task-d.7.7

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

@@ -0,0 +1,130 @@
+# 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.