# Setup State Machine

D.7.1 does not implement persistence. This document proposes the model and transitions for D.7.8.

## States

```text
not_started
readiness_checked
foundation_installed
organization_created
administrator_created
scope_configured
sequences_configured
approval_configured
csv_validated
csv_imported
verified
completed
failed
cancelled
```

## Events

```text
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
```

## Transition Rules

| From | Event | To | Guard |
| --- | --- | --- | --- |
| `not_started` | `CHECK_READINESS` | `readiness_checked` | Required readiness checks pass or warnings are acknowledged. |
| `readiness_checked` | `INSTALL_FOUNDATION` | `foundation_installed` | Migrations valid and seed transaction succeeds. |
| `foundation_installed` | `CREATE_ORGANIZATION` | `organization_created` | Organization is created or resolved. |
| `organization_created` | `CREATE_ADMIN` | `administrator_created` | User, membership, and CRM role assignment resolve. |
| `administrator_created` | `CONFIGURE_SCOPE` | `scope_configured` | At least one branch and product type exists. |
| `scope_configured` | `CONFIGURE_SEQUENCES` | `sequences_configured` | Required sequence previews succeed. |
| `sequences_configured` | `CONFIGURE_APPROVAL` | `approval_configured` | Quotation workflow, steps, and matrix resolve. |
| `approval_configured` | `VALIDATE_CSV` | `csv_validated` | Preview has no blocking errors, or no CSV files were selected. |
| `csv_validated` | `IMPORT_CSV` | `csv_imported` | Commit succeeds or CSV import skipped. |
| `csv_imported` | `RUN_VERIFICATION` | `verified` | Required verification checks pass. |
| `verified` | `COMPLETE_SETUP` | `completed` | No blocking failures remain. |
| any non-completed state | `FAIL_STEP` | `failed` | Step returns blocking error. |
| any non-completed state | `CANCEL_SETUP` | `cancelled` | User confirms cancellation. |
| `failed` | `RESUME_SETUP` | prior recoverable state | Failure source still recoverable. |
| completed step state | `RESET_STEP` | earliest affected state | Explicit confirmation and reset scope guard pass. |

## Proposed Persistence

### `setup_runs`

Purpose: one row per setup attempt.

Fields:

- `id`
- `status`
- `mode`: `production | demo_uat | dry_run`
- `target_organization_id`
- `started_by`
- `completed_by`
- `started_at`
- `completed_at`
- `last_error`
- `metadata`
- timestamps

### `setup_run_steps`

Purpose: step-level status, resume, and report storage.

Fields:

- `id`
- `setup_run_id`
- `step_key`
- `status`
- `input_hash`
- `output_json`
- `errors_json`
- `warnings_json`
- `started_at`
- `completed_at`
- timestamps

### `seed_manifests`

Purpose: seed package lifecycle tracking.

Fields:

- `id`
- `setup_run_id`
- `organization_id`
- `name`
- `version`
- `type`
- `checksum`
- `status`
- `applied_by`
- `applied_at`
- `report_json`
- timestamps

### `seed_manifest_items`

Purpose: item-level seed/import report and checksum tracking.

Fields:

- `id`
- `seed_manifest_id`
- `item_key`
- `source_file`
- `checksum`
- `status`
- `imported_count`
- `updated_count`
- `skipped_count`
- `error_count`
- `warning_count`
- `report_json`
- timestamps

## Staleness Rules

- Changing organization setup makes administrator, scope, sequence, approval, CSV, and verification stale.
- Changing administrator makes verification stale.
- Changing scope makes sequences, approval, CSV, and verification stale.
- Changing sequences makes verification stale.
- Changing approval makes CSV quotations and verification stale.
- Changing CSV preview invalidates committed import unless the source file checksum is unchanged.
- Any committed import makes verification stale.

## Cancellation Rules

- `cancelled` keeps report history.
- Cancellation does not rollback already committed successful steps.
- A cancelled setup can resume only through `RESUME_SETUP` with explicit acknowledgement of committed state.