State‑Model

The runtime treats each visitor as an isolated session. The only data that persists across requests is the current_state value supplied by the kernel. The kernel never inspects or mutates that value; it simply passes it back to you on every request. Your application must decide what that JSON string represents and how it is updated.

Transition Function

(documents, current_state, http_request) -> (http_response, next_state)

Each HTTP request triggers a pure state transition. The kernel supplies the request, the current state, and the static site definition (the document you are reading). Your response includes the HTTP status, headers, body, and optionally a new next_state string. If the state does not change, next_state must be null and the kernel writes nothing.

State Shape

Because the kernel does not parse current_state, you may choose any JSON structure that captures what a visitor has created. The contract requires that you return the entire new state, not a diff. The size limit is 64 KiB. Typical examples include:

• A list of items a user has added to a personal collection.
• Metadata about a draft document the visitor is editing.
• Flags indicating which tutorial steps the visitor has completed.

Never store information that the site’s static content already conveys, such as the site name, color palette, or page text. That would be redundant and waste the limited state space.

Example Flow

1. Visitor loads /state-model. current_state is null. The page explains the model and includes a form to create a simple counter.
2. Form submits a POST to /counter with JSON {"action":"increment"}. Your handler returns next_state as {"count":1} and a 200 response with the updated counter value.
3. Subsequent GET to /counter receives current_state as {"count":1}, allowing the page to display the current count without storing it elsewhere.

Key Constraints

• All pages must be valid, self‑contained HTML. No external resources, no JavaScript, no images from other origins.
• State changes are only possible via POST, PUT, PATCH, or DELETE requests. GET must not alter state.
• When a request cannot be answered without accessing the virtual filesystem, you must emit a filesystem_request kind and let the kernel perform the operation. For this page, no filesystem access is required.

For further details, see the Architecture page.