Intiail commit

model.md

@@ -0,0 +1,91 @@
+# Statum Model
+
+## Statum Frames
+
+A statum frame consists of a JSON object with three keys:
+- `content`: a string containing the literal content of the frame.
+- `signer`: a string containing a signer ID.
+- `signature`: a base64 encoded signature verifying the content authored by the signer.
+
+## Statum Slot
+
+- `key`: a server issued ID for the slot.
+- `scope`: a string value that can be one of:
+    - `"device"`: persists between browser sessions.
+    - `"session"`: persists within the browser session (e.g. between tabs).
+    - `"flow"`: persists only within the current tab, while the tab remains on the site (e.g. persits on between navigation)
+    - `"page"`: persists only while the current page is loaded (e.g. clears on navigate).
+    - `"transient"`: does not persist, will never get sent back to the server - random or `null` key each time.
+- `type`: an application defined type name.
+
+## Statum Snapshot
+
+A statum snapshot captures an aspect of the application state at a particular point-in-time. It is usually wrapped in a frame, which must be retained if it is to be sent back to the server after the `transmit_after` time. It contains:
+
+- `as_at`: an ISO 8601 string representing the time the snapshot was authored.
+- `slot`: a slot object (above)
+- `transmit_after`: an ISO 8601 string representing the time the slot will no longer be cached by the server and the application will need to send the snapshot. `undefined` if this is a unidirectional snapshot that never needs to be sent to the server. If it equals `as_at`, then the snapshot must always be sent.
+- `invalid_after`: an IOS 8601 string representing the time this snapshot should be considered invalid and not used.
+- `private`: a base64 encoded string of data only readable by the application server.
+- `public`: a JSON object with application-defines key/values.
+
+## Statum Action
+
+- `uri`: The URI to request.
+- `method`: the HTTP verb to use.
+- `private`: a base64 encoded string of data only readable by the application server (can be `undefined`)
+
+## Statum Directive
+
+- `type`: One of
+    - `"navigate"`: Used to redirect the frontend to a new URI.
+    - `"post"`: Used to cause the frontend to POST some data to a URI.
+    - `"set"`: Used to set a slot to a new snapshot.
+    - `"clear"`: Used to clear a slot.
+
+Depending on the type, it will have other properties.
+
+### Navigate Directive
+
+- `uri`: The URI to navigate to.
+
+### Post Directive
+
+- `uri`: The URI to perform a form post to.
+- `data`: Key/value pairs for form data.
+
+### Set Directive
+
+- `snapshot_frame`: A frame containing a snapshot.
+
+### Clear Directive
+
+- `slot_id`: The ID of the slot to clear.
+
+# Statum HTTP API
+
+
+## Entrypoint Endpoint
+
+`GET /_statum/entrypoint`: Get initial diretives based on the URL. has query param `uri` set to the browsers current `window.location`.
+Returns a JSON array of Statum Directives.
+
+## Slot Post Endpoint
+
+`POST /_statum/slots`: Send a saved state snapshots frame to the server once it has reached its `transmit_after` time window. Sent as a JSON array of Statum Frames. Returns a JSON array of Statum Directives.
+
+## Action Endpoints
+
+The URLs of action endpoints are entirely defined by the action iteself (in the `uri` property). An additional `X-Statum-Private` header should contain the `private` data of the action if present. Returns a JSON array of Statum Directives.
+
+## Request Headers
+
+All HTTP API requests must have a `X-Statum-Slot` header for each relevant slot snapshot in scope.
+
+There are two variations of this header:
+
+- For slots that have a snapshot that are within the `transmit_after` time window, an `as_at` timestamp is sent, e.g. `X-Statum-Slot: key=d3cceb88-c211-41ee-a0b1-6a93f3b6331b; as_at=2026-07-06T07:33:02.332Z`.
+- For slots that have a snapshot which has a `transmit_after` timestamp equal to its `as_at` timestamp, the frame is sent in base64, e.g. `X-Statum-Slot: eyAiY29udGVudCI6ICIuLi4uIiwgInNpZ25lciI6ICJzMSIsICJzaWduYXR1cmUiOiAiZXlBaVkyOXVkR1Z1ZENJNklDSXVMaTR1SWl3Z0luTnBaMjVsY2lJNklDSnpNU0lzSUNKemFXZHVZWFIxY21VaU9pQWlJbjA9In0=`
+
+Before an HTTP request is sent, if one or more slot snapshots's `transmit_after` timestamp is in the past, and it is not equal to its `as_at` timestamp, a pre-flight request should be made to the slot post endpoint, which will in turn provide updated snapshots and a new `as_at` timestamp.
+