Domain Invariants & Business Rules (“The Law”)

The Forms Builder domain enforces a strict set of structural, versioning, mathematical, and validation invariants. These rules guarantee data integrity, eliminate circular dependency crashes, ensure forensic compliance, and safeguard historical submissions against retroactive schema corruption.

---

1. Summary Matrix of Forms Builder Invariants

#	Invariant Law	Target Aggregate	Enforcement Point	Consequence of Violation
1	The Schema Freeze Law	FormSchemaVersion	Any structural update attempt	Immediate rejection; system forces cloning into a new Draft version.
2	Acyclic Dependency Graph Law	FormSchemaVersion	Schema publication transition	Publication blocked if cycle detection algorithm discovers closed loops.
3	Authoritative Server Validation Law	FormSubmission	Final submission intake	Submission rejected with an exhaustive validation error payload.
4	Hidden Field Purge Law	FormSubmission	Submission payload normalization	Answers in conditionally concealed fields are purged from final record.
5	Quota & Expiration Guard Law	FormBlueprint	Draft creation & submission intake	Submission blocked if quota is exhausted or cutoff timestamp has passed.
6	Atomic Multi-Step Validation Law	FormSubmission	Final submission commit	Partial or out-of-order submissions blocked; all pages must validate simultaneously.
7	Unique Field Key Law	FormSchemaVersion	Field creation and updating	Rejection of duplicate FieldKey strings within the same schema version.
8	Forensic Response Hash Law	FormSubmission	Submission sealing	Submission cannot be sealed without generating an SHA-256 canonical hash.

---

2. In-Depth Invariant Specifications

1. The Schema Freeze Law

A FormSchemaVersion that has entered the ActivePublished state and has recorded at least one valid FormSubmission becomes permanently and irreversibly frozen.

flowchart TD
    EditAttempt["Structural Edit Request<br/>(Add/Remove Field, Change Regex, Alter Choices)"] --> CheckStatus{"Is Schema Version ActivePublished?"}

    CheckStatus -->|No: Draft State| AllowEdit["ALLOW: Mutate Draft Schema"]
    CheckStatus -->|Yes: Published| CheckSubmissions{"Submissions Count > 0?"}

    CheckSubmissions -->|No: 0 Submissions| AllowUnpublishedEdit["ALLOW: In-Place Adjustment Allowed"]
    CheckSubmissions -->|Yes: >= 1 Submission| EnforceFreeze["REJECT: The Schema Freeze Law Enforced"]

    EnforceFreeze --> ForkAction["MANDATORY: Clone to Schema Version (N+1) as Draft"]

Rules

• Adding, renaming, retyping, or deleting fields on a frozen schema is prohibited.
• Modifying validation descriptors (e.g., changing a field from optional to required) on a frozen schema is prohibited.
• Modifying conditional visibility expressions or skip logic on a frozen schema is prohibited.
• When structural revisions are necessary, the domain automatically clones the frozen version into a new incremented Draft version (e.g., Version 1.0 $\rightarrow$ Version 2.0 Draft). Historical submissions remain bound to Version 1.0.

---

2. The Acyclic Dependency Graph Law

All conditional visibility expressions, dynamic skip logic, and computed formulas across a FormSchemaVersion must form a strict Directed Acyclic Graph (DAG):

$$G = (V, E) \quad \text{where} \quad \forall v \in V, , v \notin \text{Reachable}(v)$$

Rules

• A field cannot conditionally depend on itself ($A \rightarrow A$).
• Circular chains between multiple fields ($A \rightarrow B \rightarrow C \rightarrow A$) are mathematically illegal.
• Forward references in skip logic cannot target preceding pages ($Page_4 \rightarrow Page_2$ is classified as a looping error).
• Before transitioning from Draft to ActivePublished, the schema executes a topological sort and cycle-detection algorithm (Tarjan’s strongly connected components algorithm). Any detected cycle aborts publication immediately.

---

3. The Authoritative Server-Side Validation Law

Client-side validation rules (executed in browsers or mobile clients) exist solely to enhance user experience. The domain treats all incoming submission payloads as completely untrusted.

Rules

• The server-side validation engine iterates through every active, visible field in the targeted schema version.
• Input data types must strictly coerce: strings submitted for integer or float fields trigger immediate rejection.
• String inputs must satisfy defined regular expressions (RegexPattern), minimum/maximum length constraints, and allowed character sets.
• File upload fields must verify that the linked asset token matches approved MIME types and does not exceed maximum byte limits.
• Submission processing halts on the first invariant breach and returns an exhaustive, structured validation report detailing every violating field key.

---

4. The Hidden Field Answer Purge Law

If a field, section, or page becomes conditionally hidden due to prior user selections, any residual values submitted for those hidden controls are purged from the authoritative ValidatedAnswerMap.

Rules

• Prevents “ghost data” contamination: if a respondent selects “Do you own a car? -> Yes”, enters vehicle registration details, and subsequently changes their answer to “No”, the vehicle registration fields become conditionally hidden.
• Upon submission, the engine evaluates the DAG. All fields whose visibility conditions resolve to False are stripped of answers.
• Purged values are never persisted in the final FormSubmission aggregate, ensuring clean analytics and eliminating misleading responses.

---

5. The Quota and Expiration Guard Law

A form blueprint enforces hard operational bounds governing submission availability:

$$\text{CurrentSubmissionsCount} < \text{MaxSubmissionsAllowed} \quad \land \quad \text{CurrentUtcTimestamp} < \text{ExpirationTimestamp}$$

Rules

• When MaxSubmissionsAllowed is defined, incoming submissions are gated through an atomic counter. Once the limit is achieved, the blueprint transitions to QuotaExhausted, rejecting subsequent attempts.
• If the current clock time exceeds ExpirationTimestamp, active draft sessions attempting to submit are rejected with FormExpiredException.
• Draft sessions that are already underway when a quota is reached are rejected gracefully with a formal notice that submission capacity was filled by a concurrent user.

---

6. The Atomic Multi-Step Submission Law

A multi-step form response cannot be finalized in fragments. Transitioning a draft session into a permanent FormSubmission is an atomic, all-or-nothing operation.

Rules

• All pages and steps in the active path (accounting for skip logic) must validate simultaneously.
• Submissions cannot be accepted if an intervening step was skipped illegally or failed validation.
• The transaction commits only when all validated answers, computed fields, and forensic cryptographic hashes are compiled into a unified submission aggregate.

---

7. The Unique Field Key Law

Within any single FormSchemaVersion, every FieldKey identifier must be unique:

$$\forall f_1, f_2 \in \text{Fields}, \quad f_1 \ne f_2 \implies f_1.\text{FieldKey} \ne f_2.\text{FieldKey}$$

Rules

• Field keys are system slugs (lowercase alphanumeric with underscores, e.g., primary_applicant_email).
• Duplicate field keys within the same version cause immediate schema validation failure.
• Sub-fields within a Matrix or Repeater control are scoped hierarchically (e.g., dependents_matrix[0].full_name), preventing key collisions with root fields.

---

8. The Forensic Response Hash Law

Every completed FormSubmission must generate an immutable, tamper-evident cryptographic fingerprint upon creation:

$$\text{ResponseHash} = \text{SHA-256}(\text{CanonicalSort}(\text{ValidatedAnswerMap}) + \text{SchemaVersionId} + \text{SubmissionTimestamp})$$

Rules

• The answer map is serialized into canonical JSON with keys sorted alphabetically in lexicographical order.
• The resulting SHA-256 hash is permanently sealed alongside the submission record.
• Any subsequent attempt to alter an answer value directly in database storage invalidates the hash during forensic audit verification.