Crate olai_stack_state 

The shared trestle state store.

One SQLite database under the trestle home ($TRESTLE_HOME, else the platform data directory), shared by the trestle CLI and the desktop app. It holds:

• Workspaces: sets of environments sharing a host, with their VarSets.
• Environments: an editable Draft (the placement-free env.toml, the module.yaml texts it lists, vars) and a head.
• Revisions: numbered, immutable snapshots of a draft with a digest. Nothing in the API changes one, and the database refuses an update.
• Instances: a revision to run, whether it should run, overrides and the overlay sources it takes.
• SlotLeases: host-wide, so two instances never share a slot whatever their workspace (slots per workspace clashed across workspaces).

Secrets are stored as SecretRefs only; their values stay with their provider.

Several processes use the store at once: writes are serialized (a writer waits for another’s), and a Watcher notices commits made elsewhere. A store with a newer schema than this crate knows is refused (Error::UnsupportedVersion).

trestle-workspace.toml and environment directories stay as an exchange format: Store::import_workspace drops placement (the store leases slots itself), and Store::export_instances and Store::export_workspace write slots, so the exported directory runs with docker compose up like any workspace.

use olai_stack_state::{Draft, Store};
use olai_stack_topology::{EnvManifest, PlanCtx, Selection};

let store = Store::open_default()?;
let ws = store.create_workspace("demo", false)?;
let manifest = EnvManifest::new(Selection::modules(["unity-catalog"]), PlanCtx::default());
let env = store.create_environment(&ws.id, "dev", Draft::new(manifest))?;
let rev = store.commit_draft(&env.id)?;
let instance = store.create_instance(&env.id, rev.number())?;
let lease = store.lease_slot(&instance.id)?;
println!("dev r{} on slot {}", rev.number(), lease.slot);

Structs

Draft

What an environment’s next revision will be: its manifest, the module manifests it lists and the vars a commit freezes. Editable; committing it makes a Revision.

Environment

An environment of a workspace: its editable draft, the vars all its revisions see, and its latest revision.

EnvironmentId

An Environment’s id.

Instance

A revision as something to run: which one, whether it should be running, the overrides on top of its vars and the sources whose overlays it takes. Where it runs is its SlotLease (none until it is leased one).

InstanceId

An Instance’s id.

Revision

A numbered, immutable snapshot of an environment: the placement-free manifest, the module manifests it lists and its vars, with a digest of all three. Nothing in the API changes a revision once committed; the type has no setters, and the store refuses an update.

SecretRef

Where a secret’s value lives. The store keeps only this reference; the value stays with the provider (the OS keychain, the process environment).

SlotLease

A slot held by an instance, host-wide: no two instances on the host share one, whatever their workspace.

SourceBinding

An overlay source an instance takes: its name, and what the source needs to know about the instance (which branch, say). The config is merged over the workspace’s config for the same source. Neither holds secrets.

Store

The trestle state: workspaces, their environments (each a draft and numbered, immutable revisions), instances and the host-wide slot leases, in one SQLite database (WAL mode, so readers never block the writer).

VarSet

Named variables, as a workspace, an environment, a revision or an instance sets them.

Watcher

Notices commits to the store made through any other connection, in this process or another (the CLI writing while the app is open, say). It holds its own connection and compares SQLite’s PRAGMA data_version, which changes exactly when someone else commits. It says that something changed, not what: a consumer re-reads what it shows.

Workspace

A set of environments sharing a Docker host, their vars, and whether their gateways share a mesh network.

WorkspaceId

A Workspace’s id.

Enums

Desired

Whether an instance should be running.

Error

What can go wrong reading or writing the Store.

VarScope

Which mutable VarSet a change applies to.

VarValue

One variable’s value: a literal, or a reference to a secret.

Constants

DB_FILE

The database file inside the state directory.

ENV_FILE

The environment manifest’s file name inside an environment directory.

SCHEMA_VERSION

The schema version this crate writes and reads.

TRESTLE_HOME_VAR

The environment variable naming the trestle state directory.

Functions

read_env_dir

An environment directory’s env.toml and the module manifests it lists, as a draft.

trestle_home

The trestle state directory: $TRESTLE_HOME when set, else trestle in the platform’s data directory (e.g. ~/Library/Application Support/trestle, ~/.local/share/trestle).

Type Aliases

Result

The crate’s result type.