HTTP API architecture
OpenAPI defines wire shapes. HTTP API behavior defines ordering, retry, recovery, and resource behavior. This document explains the owners and persistence boundaries behind those operations. Change the HTTP API states the contribution requirements.
On this page: State ownership and Related guides.
State ownership
Session actors, the store transaction connection, the family owner, the settings lock, and the bounded bus own the state below. HTTP handlers call these owners and project their results.
The runtime passes a generic
store.Store handle named
ledger. An extension owns the schema it initializes through that handle. A
generic store handle does not transfer domain ownership to the HTTP adapter.
| State | Implementation owner | Commit or lifetime boundary |
|---|---|---|
| Submitted creation intent | session/, registry, and conversation | Canonical submitted intent is retained separately from resolved defaults and editable configuration. |
| Input admission, delivery, and turn outcomes | operations.gleam and session actor | The store transaction commits consumption with transcript content and turn membership. Live actor state orders execution. |
| Family membership, child creation, and scoped deletion | family.gleam | Membership validation and mutation use the family owner. |
| Session configuration and workspace intent | session_configuration.gleam | Desired state commits before runtime changes. A process that already stopped cannot be restored by rolling back a database write. |
| Session watch | Session actor and http_session_stream.gleam | A captured cursor belongs to one actor generation and its durable high-water mark. |
| Collection watch | bus.gleam and http_events.gleam | The bus bounds admission before subscriber mailboxes. |
| Settings and credentials | sdk/ and settings adapter | The home lock coordinates participating readers and durable publication. Runtime application is separate. |
| Provider login | oauth_flows.gleam | Live listeners belong to the sign-in service, which the daemon passes to its handlers. Admission and terminal records are durable, but a restart does not recreate the listener. |
| Prepared context | context_snapshot.gleam | Only the latest immutable prepared snapshot is retained. Observation does not prepare a request. |
| Extension data | Owning extension | Each extension owns its validation, permissions, migrations, and deletion behavior. |
HTTP API behavior defines caller-visible retry, retention, and failure rules. This table identifies implementation boundaries rather than repeating those contracts.
Composition discovery runs outside the runtime actor in bounded preparation workers. Admission reserves capacity for both observations and preparation, so slow kernel starts cannot occupy every read slot.
Transport choice
Core live updates flow from the daemon to clients, so SSE carries them while reads and mutations use ordinary HTTP. Session watches retain the existing replay and bounded delivery design. The stream contract defines caller-visible reset and overflow behavior.
Settings crash recovery
Provider and MCP changes coordinate public settings and creds.json through a
per-home lock and a durable recovery record. Participating readers finish
committed recovery before reading destination files. Replacement is sequential,
so external filesystem readers do not receive an atomic snapshot across files.
See persisted settings.
sdk/settings_store
owns the recovery sequence:
- Under the home lock, the owner recovers a prior committed replacement before reading or changing settings.
- The settings adapter
checks
If-Matchand constructs the candidate while retaining unrelated sections. It resolves secret-source conflicts and validates the candidate before publication. - The store encodes and validates destination documents. It writes their
replacement bytes into the private
.settings-recoveryrecord, then syncs the home directory. This is the commit decision, before any destination replacement. - Recovery replaces destination files sequentially through
albedo_file.write_private. Each write uses a private temporary file with mode0600, syncs the bytes, and renames the file. Recovery then syncs the home directory. - The owner removes the recovery record and syncs the directory before returning the completed change.
Before the durable commit decision, destination files remain unchanged. After it, recovery completes the replacements rather than undoing them. The record holds replacement bytes, so recovery does not depend on an earlier temporary file surviving. Recovery errors fail the settings operation or startup. A participating reader must not read destination files after failed recovery. The lock and recovery boundary give those readers a consistent group.
Runtime application follows persistence. A post-commit application failure reports the persisted desired state and failed application, without claiming persistence rolled back.
The
settings contribution rules
require bounded private recovery data and explicit crash-point tests. Those
requirements do not imply that every interruption point has been exercised.
settings_test.py includes a blocked-publication
scenario that reports failure until recovery can complete.
Durable facts
Creation provenance, input decisions, workspace intent, and login admission are durable. Their owning migrations run before session admission. An older session without submitted provenance remains usable but cannot prove that it matches a retried creation request. The creation contract describes that distinction.
Login comparison uses protected secret material inside the sign-in service. Its admission records do not contain callback codes or resulting access tokens. The login contract describes restart and retention behavior.
Related guides
- Change the HTTP API: requirements for ownership, secrets, recovery, and validation.
- Persisted settings: settings groups and application.
- Runtime: composition and resource lifetime.
- Durable operations: admission and receipts.
Previous http extensions Next change the api