Advanced Models
Developer Guide
StateMachine Execution Model
March 29, 2026
Why StateMachines
Every business entity in HTQL — orders, discounts, inventory, procurement — is governed by a StateMachine. This is not a design pattern suggestion. It is an architectural constraint.
A StateMachine defines the only valid states an entity can occupy and the only valid transitions between them. If a transition is not defined, it cannot happen. If a transition’s preconditions are not met, it is rejected.
This eliminates an entire class of bugs: invalid states. There is no “corrupted order.” No “half-applied discount.” No “inventory that doesn’t add up.” Because the system makes these states mathematically impossible.
1
State Definition
Each aggregate defines its valid states as an enum. A discount might be DRAFT | VALIDATED | APPROVED | ACTIVE | EXPIRED. An inventory movement: EXPECTED | RESERVED | COMMITTED | VERIFIED | RECONCILED. The StateMachine enforces these boundaries.
2
Transition Guards
Every transition has preconditions (guards) that must be satisfied. A discount cannot move from DRAFT to ACTIVE without passing margin threshold validation, stacking rule checks, and exposure limit evaluation. Guards are financial rules, not optional checks.
3
Event Sourcing
Each transition produces an immutable event. Events are persisted to a journal with version numbers. The aggregate’s current state is the result of replaying all events in order. This provides a complete, tamper-proof audit trail.
4
Optimistic Concurrency
Transitions include an expected version number. If the aggregate has been modified since it was loaded (persist_transition(expected_version=N)), the transition is rejected. No lost updates. No race conditions.
INVARIANTS
Financial invariants are enforced at every transition. Journal entries are generated atomically. Balance updates are part of the same transaction.
No gap between execution and recording. Reporting is a byproduct of valid transitions.
ATOMICITY
If a transition fails validation, the entire transaction rolls back. No partial state. No cleanup required. The aggregate remains in its last valid state.
This is what deterministic execution means: every outcome is predictable, repeatable, and auditable.
The Result: No Invalid States
The StateMachine model means your system cannot contain inconsistent data. Not “should not” — cannot.
Every entity follows a defined lifecycle. Every transition is validated. Every event is recorded. Every state is provably correct.
This eliminates reconciliation, manual corrections, and after-the-fact adjustments. The system is its own audit trail.
You Don’t Need Better Reporting. You Need Guaranteed Correctness.
Most systems show you what went wrong after the fact. HTQL guarantees correctness before execution. Every transaction validated. Every rule enforced. Every outcome deterministic. This is not analytics — this is control infrastructure.
Profit Guard Insights
Topic
The Leak You Don't See Is the One That Hurts Most
You don’t notice it at first. Sales are coming in. Customers are buying. Your dashboards look fine. Revenue is moving. Everything appears to be working. And yet, something feels off. Margins are tighter than expected. Cash doesn’t stretch as far as it should. Promotions feel like they’re “working”… but not delivering the financial outcome you assumed. This is where most merchants get it wrong. They think profit is lost in big decisions. **It isn’t.** It’s lost in small, repeated, invisible ones.
April 19, 2026
Topic
Discounts Don't Destroy Profit. Lack of Control Does
Discounts are powerful. They move inventory. They increase conversion. They create urgency. They reward customers. Used correctly, they accelerate growth. Used incorrectly, they destroy margin. **The difference is not the discount itself. It’s control.**
April 19, 2026
Topic
Inventory Is Not Stock. It's Capital at Risk
Most merchants think in units. How many items are in stock. How fast they are moving. How many are sold. But this is the wrong lens. Inventory is not stock. It is capital. **Locked capital. Allocated capital. At-risk capital.** Every unit sitting on a shelf represents money that is not working. Every unit in the wrong store represents missed opportunity. Every unit reserved unnecessarily represents blocked revenue.
April 19, 2026
Topic
Loyalty and Gift Cards: The Costs You Don't See Coming
They feel like assets. Loyalty programs build retention. Gift cards generate upfront cash. Customers engage more. Sales increase. On the surface, everything looks positive. But beneath that surface lies a financial reality most merchants ignore. **Loyalty is a liability. Gift cards are deferred obligations.** Every point issued is a future cost. Every gift card sold is revenue not yet earned.
April 19, 2026
Topic
The Moment Everything Changes
There is a moment every serious merchant experiences. It’s not loud. It’s not dramatic. But it is decisive. It’s the moment you realise: **the problem was never sales. It was control.** You were generating revenue. You were running promotions. You were moving inventory. But profit wasn’t following. Not consistently. Not predictably. And you couldn’t explain why.
April 19, 2026