albedo docs

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.

StateImplementation ownerCommit or lifetime boundary
Submitted creation intentsession/creation.gleam, registry, and conversationCanonical submitted intent is retained separately from resolved defaults and editable configuration.
Input admission, delivery, and turn outcomesoperations.gleam and session actorThe store transaction commits consumption with transcript content and turn membership. Live actor state orders execution.
Family membership, child creation, and scoped deletionfamily.gleamMembership validation and mutation use the family owner.
Session configuration and workspace intentsession_configuration.gleamDesired state commits before runtime changes. A process that already stopped cannot be restored by rolling back a database write.
Session watchSession actor and http_session_stream.gleamA captured cursor belongs to one actor generation and its durable high-water mark.
Collection watchbus.gleam and http_events.gleamThe bus bounds admission before subscriber mailboxes.
Settings and credentialssdk/settings_store and settings adapterThe home lock coordinates participating readers and durable publication. Runtime application is separate.
Provider loginoauth_flows.gleamLive 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 contextcontext_snapshot.gleamOnly the latest immutable prepared snapshot is retained. Observation does not prepare a request.
Extension dataOwning extensionEach 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:

  1. Under the home lock, the owner recovers a prior committed replacement before reading or changing settings.
  2. The settings adapter checks If-Match and constructs the candidate while retaining unrelated sections. It resolves secret-source conflicts and validates the candidate before publication.
  3. The store encodes and validates destination documents. It writes their replacement bytes into the private .settings-recovery record, then syncs the home directory. This is the commit decision, before any destination replacement.
  4. Recovery replaces destination files sequentially through albedo_file.write_private. Each write uses a private temporary file with mode 0600, syncs the bytes, and renames the file. Recovery then syncs the home directory.
  5. 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.

Previous http extensions Next change the api