The two-layer state model
State is separated into two layers with different lifetimes, different storage, and a strict one-way rule about which may influence the other. The rule is enforced structurally, not by convention.
Durable state what actually happened
- Append-only event log: events are inserted, never modified
- Past events cannot be altered by any code path
- Auditable by construction: the log is the audit trail
- All writes require gateway authorisation
- Survives server restart; loss-free by design
Ephemeral state current session context
- In-memory only, keyed by session ID
- Holds UI context: current view, in-progress flows, flash messages
- Derived from durable state, never the reverse
- Never used as input to durable state transitions
- Discarded on session end; nothing persists to the client
Ephemeral state flows one direction only. Durable state seeds ephemeral state. Ephemeral state never influences durable state transitions. This rule makes client-side state manipulation structurally impossible: there is no client state to manipulate.
The gateway contract
The gateway is the security boundary of the system. All state access — read or write — passes through it. No handler, no middleware, no other package touches state directly. This is not a convention: the Store type is unexported from the state package; only the Gateway is exposed. There is no path around it.
// Reading state — returns a named projection
gateway.Project(ctx, sessionID, "projection-name")
// Writing state — submits a validated intent
gateway.Dispatch(ctx, sessionID, action)Every call through the gateway enforces the same contract:
- Session is authenticated
- Actor is authorised for this action or projection
- Action is valid against current state before any change is applied
- Every transition is appended to the audit log
Authorisation is not middleware. It runs inside the gateway, inside every request. There is no separate runtime layer that can be bypassed with a crafted header.
The action pattern
State changes are expressed as validated intents, not direct mutations. A handler never writes state directly; it submits an action to the gateway.
type Action interface {
Type() string
Validate(ctx, store, sessionID) error
Apply(ctx, store, sessionID) (Event, error)
}The lifecycle of a state change:
- Handler parses the request and constructs an action
- Gateway calls Validate against current state; rejects if invalid
- Gateway calls Apply; produces a new event
- Event is appended to the durable log
- Gateway returns the updated projection to the handler
- Handler renders the projection as HTML: partial for htmx, full page otherwise
No partial application. No silent failure. No client state to reconcile.
Security by construction
Security in most systems is applied as a layer: middleware checks, validation libraries, WAF rules, security headers. Each layer can be misconfigured, bypassed, or forgotten. SAUI takes a different position: the architecture excludes entire vulnerability classes structurally, before any application code runs.
- No client state. State manipulation — the classic "isAdmin: true" attack — requires client-held state to manipulate. The browser holds none. The attack class does not apply.
- No hydration boundary. Server state is never serialised into inline HTML for client reconstruction. The hydration XSS attack class requires this boundary. It does not exist here.
- No middleware security gate. Authorisation runs inside the gateway, inside every request handler. There is no separate runtime layer to bypass. The middleware bypass pattern that produced CVE-2025-29927 (CVSS 9.1) in Next.js cannot occur.
- Append-only event log. Past events cannot be altered by any code path. An attacker with database access cannot rewrite history. The audit trail is a structural property, not a policy.
- No npm dependency graph. htmx is a single vendored file. The rest of the stack is Go standard library. There are no transitive package dependencies and therefore no supply chain attack surface.
These are not mitigations. They are the consequence of an architecture where the dangerous patterns cannot exist.
Progressive enhancement
Every feature is built across four degradation levels. All four must produce correct state; the server owns truth regardless of client capability.
- L0No JS, no CSS
- Native HTML forms, POST submission, PRG pattern. Must always work.
- L1CSS only
- Full layout applied. No visual state that depends on JS class toggling.
- L2JS present, htmx not yet loaded
- Native form submission holds. Full page responses.
- L3htmx loaded
- Partial DOM updates active. Forms intercepted. hx-boost on navigation.
- L4Full baseline JS
- SSE connection for real-time projection updates. View Transitions if supported.