Operational Workflows & State Machines

The Forms Builder domain operates through controlled state machines that govern how form schemas are authored, validated, published, and deprecated, as well as how respondents navigate multi-step drafts and finalize submissions.

---

1. Schema Authoring & Version Lifecycle

A form schema progresses through a unidirectional lifecycle ensuring that active forms remain stable while permitting continuous design iteration:

stateDiagram-v2
    [*] --> Draft: Administrator Creates / Clones Version
    Draft --> Validating: Publish Request Triggered
    Validating --> Draft: Cycle Detected / Validation Error
    Validating --> ActivePublished: DAG Validated & Zero Cycles Confirmed
    ActivePublished --> Deprecated: Superceded by Newer Version
    ActivePublished --> Archived: Blueprint Decommissioned
    Deprecated --> Archived: All Retention Windows Expired
    Archived --> [*]

Schema Version State Transitions

Current State	Target State	Trigger / Action	Guard Conditions	Primary Actor	Domain Event Emitted
[*]	Draft	Designer creates new blueprint or clones an existing frozen schema	Blueprint code is unique; authoring permissions verified	Form Designer	FormSchemaDraftCreated
Draft	Validating	Designer clicks “Publish Version”	At least one page and one valid input field exist	Form Designer	FormSchemaValidationInitiated
Validating	ActivePublished	System finishes cycle detection and structural verification	Dependency graph is acyclic; all validation descriptors are sound	Schema Validation Engine	FormSchemaPublished
Validating	Draft	System discovers an invalid dependency or structural error	Cycle detected or invalid regex descriptor found	Schema Validation Engine	FormSchemaValidationFailed
ActivePublished	Deprecated	A newer schema version for the same blueprint is published	Newer version achieves ActivePublished state	System Orchestrator	FormSchemaDeprecated
ActivePublished	Archived	Administrator shuts down the form permanently	Blueprint decommission requested; in-flight drafts notified	Form Administrator	FormSchemaArchived
Deprecated	Archived	Formal retention period passes with zero active draft sessions	No open draft sessions remain bound to this version	Lifecycle Daemon	FormSchemaArchived

---

2. Submitter Response & Multi-Step Draft Progression

Respondents interact with multi-step forms through a persistent draft state machine:

flowchart TD
    Start["User Opens Form URL"] --> CheckPolicy{"Access & Quota Valid?"}
    CheckPolicy -->|No: Quota / Expired| Deny["Halt: Show Expiration / Quota Screen"]
    CheckPolicy -->|Yes: Access Granted| InitDraft["Initialize SubmissionDraftSession"]

    InitDraft --> StepView["Render Current Page / Step"]
    StepView --> UserInput["User Inputs Answers"]
    UserInput --> DagEval["Client-Side DAG Evaluation<br/>(Visibility & Formulas Updated)"]

    DagEval --> AutosaveTrigger{"Autosave Triggered?<br/>(Time / Step Navigation)"}
    AutosaveTrigger -->|Yes| SaveDraft["Persist Answers to Draft Session"]
    AutosaveTrigger -->|No| NextStep{"User Navigates Next?"}

    SaveDraft --> NextStep
    NextStep -->|Forward Page| StepGate{"Current Step Valid?"}
    StepGate -->|Fails| ShowErrors["Display Inline Errors"]
    ShowErrors --> UserInput
    StepGate -->|Passes| BranchLogic{"Skip Logic Present?"}
    BranchLogic -->|Jump Ahead| JumpPage["Navigate to Target Page"]
    BranchLogic -->|Sequential| NextPage["Navigate to Step (N+1)"]
    JumpPage --> StepView
    NextPage --> StepView

    NextStep -->|Final Submit Clicked| ServerValidation["Authoritative Server-Side Validation"]
    ServerValidation --> Result{"Exhaustive Validation Pass?"}
    Result -->|Fails| ReturnErrors["Return Field Error Map to User"]
    ReturnErrors --> UserInput

    Result -->|Passes| PurgeHidden["Purge Conditionally Concealed Answers"]
    PurgeHidden --> HashSealing["Generate SHA-256 Response Hash"]
    HashSealing --> CommitSubmission["Commit FormSubmission Aggregate"]
    CommitSubmission --> EmitEvent["Emit FormSubmissionValidated Event"]
    EmitEvent --> TerminateDraft["Purge Draft Session & Display Confirmation"]

---

3. Submission Draft Session State Transitions

Current State	Target State	Trigger / Action	Guard Conditions	Primary Actor	Domain Event Emitted
[*]	SessionInitiated	User loads active form URL or opens invitation token	Form is ActivePublished; quota not reached; not expired	Submitter	FormDraftSessionStarted
SessionInitiated	DraftProgress	Submitter enters values or triggers autosave	Session token valid; payload size within boundaries	Submitter Client	FormDraftStepSaved
DraftProgress	DraftProgress	Submitter navigates between pages or periodically saves	Step answers conform to minimum client requirements	Submitter Client	FormDraftStepSaved
DraftProgress	Submitted	Submitter submits final step and server validation passes	All required active fields valid; response hash sealed	Server Validation Engine	FormSubmissionValidated
DraftProgress	Expired	Inactivity window exceeds session retention (e.g., 30 days)	Current timestamp > session expiration timestamp	Expiration Daemon	FormDraftSessionExpired
DraftProgress	Terminated	Blueprint quota is filled by another concurrent user	Target blueprint transitions to QuotaExhausted	System Concurrency Manager	FormDraftSessionTerminated

---

4. Directed Acyclic Graph (DAG) Runtime Evaluation Workflow

At both runtime client display and authoritative server ingestion, conditional visibility and calculations are resolved through an exact topological evaluation workflow:

flowchart LR
    A["Field Input Change<br/>(e.g., has_dependents = True)"] --> B["Locate DAG Dependents<br/>in Dependency Adjacency Map"]
    B --> C["Topologically Order<br/>Affected Dependent Nodes"]
    C --> D["Evaluate Visibility Expressions<br/>Against Current Answers"]
    D --> E{"Visibility State Changed?"}

    E -->|Becomes Visible| F["Enable Controls & Apply Required Rules"]
    E -->|Becomes Concealed| G["Disable Controls & Mark for Data Purging"]

    F --> H["Evaluate Computed Formulas<br/>(e.g., total_score = sum(...))"]
    G --> H
    H --> I["Update Downstream Dependents<br/>Recursively Along DAG Edges"]
    I --> J["Render Final Visual State<br/>or Finalize Server Validation"]

Dynamic Evaluation Invariants

• Topological Order Execution: If Field $C$ depends on Field $B$, and Field $B$ depends on Field $A$, changes to Field $A$ strictly trigger evaluation of $B$ first, followed by $C$.
• Short-Circuit Protection: If a parent Layout Section evaluates to hidden, all contained child fields are automatically treated as concealed without evaluating their individual conditional logic expressions.