TenantAtlas/specs/140-onboarding-lifecycle-operation-checkpoints-concurrency-mvp/data-model.md

Data Model: Onboarding Lifecycle, Operation Checkpoints & Concurrency MVP

Entity: TenantOnboardingSession

Existing persisted workflow record for managed tenant onboarding drafts.

Fields

Field	Type	Required	Notes
id	bigint	yes	Primary key
workspace_id	foreign key	yes	Workspace ownership and authorization boundary
tenant_id	foreign key nullable	conditional	May remain null before tenant identification, per constitution exception
entra_tenant_id	string	yes	Current draft identity key for resumable uniqueness
current_step	string nullable	no	Existing UI-oriented step breadcrumb; no longer canonical workflow truth
state	json nullable	no	Detailed persisted step data and run references
started_by_user_id	foreign key nullable	no	Draft creator
updated_by_user_id	foreign key nullable	no	Last mutating actor
completed_at	timestamp nullable	no	Terminal historical marker
cancelled_at	timestamp nullable	no	Terminal historical marker
version	bigint or integer	yes	Starts at 1, increments on every relevant successful mutation
lifecycle_state	controlled string or enum	yes	Canonical workflow state
current_checkpoint	controlled string or enum nullable	no	Governing checkpoint for forward progress
last_completed_checkpoint	controlled string or enum nullable	no	Last satisfied checkpoint
reason_code	string nullable	no	Machine-readable lifecycle precision
blocking_reason_code	string nullable	no	Machine-readable explicit blocker
created_at	timestamp	yes	Existing audit chronology
updated_at	timestamp	yes	Existing audit chronology

Relationships

• Belongs to Workspace
• Belongs to Tenant when identified
• Belongs to startedByUser
• Belongs to updatedByUser
• References relevant verification and bootstrap OperationRun records through IDs stored in state

Validation Rules

• version >= 1
• lifecycle_state must be one of the controlled lifecycle values
• current_checkpoint and last_completed_checkpoint must be null or one of the controlled checkpoint values
• blocking_reason_code must be null unless the workflow is actually blocked from forward progress
• completed_at and cancelled_at remain mutually exclusive terminal markers
• Terminal records (completed_at or cancelled_at set) are non-editable

Entity: OnboardingLifecycleState

Controlled value set used for canonical workflow truth.

Values

Value	Meaning
draft	No active governing checkpoint run and not yet ready for activation
verifying	Relevant verification run is queued or running
action_required	Operator intervention is required before safe progression
bootstrapping	One or more selected bootstrap runs are queued or running
ready_for_activation	All gating conditions are satisfied and the workflow awaits final activation
completed	Activation succeeded and the draft is historical
cancelled	Draft was intentionally cancelled and is historical

Entity: OnboardingCheckpoint

Controlled checkpoint precision used for progression and UI state.

Values

Value	Meaning
identify	Tenant identity or workspace-scoped start state
connect_provider	Provider selection or connection management checkpoint
verify_access	Verify Access checkpoint
bootstrap	Optional bootstrap checkpoint
complete_activate	Final activation checkpoint

Entity: OnboardingReasonCode

Machine-readable precision for non-terminal workflow state.

Expected starter values

• verification_blocked_permissions
• verification_failed
• provider_connection_changed
• verification_result_stale
• bootstrap_failed
• bootstrap_partial_failure
• owner_activation_required

This list is intentionally controlled and should be extended centrally rather than spread through page code.

Entity: RelevantCheckpointRun

Derived relationship between a draft and the OperationRun records that currently govern progression.

Verification invariants

• The verification run must match the currently selected provider connection.
• A queued or running verification run implies lifecycle_state = verifying.
• A terminal verification run only allows progression when it is current for the selected connection and satisfies readiness conditions.

Bootstrap invariants

• Bootstrap run references remain stored in state as selected run metadata.
• One or more queued or running relevant bootstrap runs imply lifecycle_state = bootstrapping.
• Any blocking bootstrap failure moves the workflow to action_required.

State Transition Model

From	Trigger	To	Notes
draft	verification started	verifying	Relevant verification run created or reused
verifying	verification succeeds and no bootstrap selected	ready_for_activation	Verification must be current for selected connection
verifying	verification succeeds and bootstrap started	bootstrapping	Selected bootstrap runs become active
verifying	verification blocked, failed, stale, or mismatched	action_required	reason_code and optional blocking_reason_code set
action_required	blocker resolved by rerun or reset	verifying, bootstrapping, ready_for_activation, or draft	Chosen by centralized lifecycle recalculation
bootstrapping	all selected bootstrap runs complete successfully	ready_for_activation	No remaining blocker allowed
bootstrapping	selected bootstrap run fails in blocking way	action_required	Failure reason preserved
any editable state	cancel action	cancelled	Terminal and immutable
ready_for_activation	activation succeeds	completed	Terminal and immutable

Concurrency Contract

• Every relevant mutation must carry an expected version.
• The write path must compare expected version to persisted version inside the same transaction or atomic update.
• On mismatch, no lifecycle field, checkpoint field, JSON state, or related run reference may be partially written.
• Conflict rejection keeps the user on the wizard and returns a visible refresh-required error.