alla-allaos-fullstack/docs/setup/setup-state-machine.md

Setup State Machine

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

States

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

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.