Struct Store 

pub struct Store { /* private fields */ }

Implementations

impl Store

pub fn create_instance( &self, name: &str, substrate: &str, definition: &str, source_overrides: &BTreeMap<String, String>, definition_dir: &str, dirty: bool, ) -> Result<InstanceRecord, StateError>

Create an instance record. Names are unique across substrates: a clash is an error naming the existing substrate, not a sibling. The UNIQUE PRIMARY KEY enforces this on both backends — fleet-wide when the remote plane is configured.

pub fn instance(&self, name: &str) -> Result<Option<InstanceRecord>, StateError>

pub fn instances(&self) -> Result<Vec<InstanceRecord>, StateError>

pub fn tombstone_instance(&self, name: &str) -> Result<(), StateError>

Teardown leaves a tombstone, not amnesia (§2).

pub fn revive_instance( &self, name: &str, definition: &str, source_overrides: &BTreeMap<String, String>, dirty: bool, ) -> Result<(), StateError>

up on a tombstone is a fresh birth under the old name: new definition snapshot, active status, empty journal.

pub fn update_source_overrides( &self, name: &str, source_overrides: &BTreeMap<String, String>, ) -> Result<(), StateError>

Record per-invocation overrides on resume (an explicit, recorded choice — never ambient discovery).

pub fn update_dirty(&self, name: &str, dirty: bool) -> Result<(), StateError>

Record per-invocation dirty mode on resume.

impl Store

pub fn record_checkpoint( &self, instance: &str, step_id: &str, resource_kind: &str, resource_id: &str, payload: &str, ) -> Result<(), StateError>

pub fn checkpoint( &self, instance: &str, step_id: &str, ) -> Result<Option<Checkpoint>, StateError>

pub fn checkpoints(&self, instance: &str) -> Result<Vec<Checkpoint>, StateError>

All checkpoints for an instance in recording order — what an interrupted down must hunt down.

pub fn remove_checkpoint( &self, instance: &str, step_id: &str, ) -> Result<(), StateError>

Remove one checkpoint after its resource is verifiably gone.

impl Store

pub fn renew_lease( &self, instance: &str, duration: Duration, ) -> Result<Lease, StateError>

Set (or reset) the lease to its full duration from now.

pub fn renew_lease_at_recorded_duration( &self, instance: &str, ) -> Result<(), StateError>

Renew at the recorded duration (the start-of-verb renewal: the duration was consented to at creation).

pub fn lease(&self, instance: &str) -> Result<Option<Lease>, StateError>

pub fn delete_lease(&self, instance: &str) -> Result<(), StateError>

A tombstoned instance has no lease left to enforce.

pub fn expired_instances(&self) -> Result<Vec<String>, StateError>

Active instances whose lease has expired — the reaper’s worklist.

impl Store

pub fn claim_lock( &self, instance: &str, operation: &str, ) -> Result<LockClaim, StateError>

Claim the operation lock for instance, taking over a dead (same-host) or stale (foreign-host) holder’s claim. Fails fast with a stable code if a live holder has it — agents retry stuck commands, so overlapping operations are an expected event.

pub fn release_lock(&self, claim: &LockClaim) -> Result<(), StateError>

Release a claim. Only the recorded holder’s release deletes the row, so a stale guard cannot release a successor’s lock.

pub fn lock_holder_alive(&self, instance: &str) -> Result<bool, StateError>

Whether instance is currently mid-operation under a live holder — the reaper must never reap such an instance (§6). A foreign-host holder is treated as live (its PID is unprobeable here) until the lease/staleness machinery resolves it.

impl Store

pub fn record_reap_failure( &self, instance: &str, error: &str, ) -> Result<(), StateError>

Record a failed reap, advancing the backoff. attempts increments; next_retry_at is now + the doubled delay.

pub fn clear_reap_failure(&self, instance: &str) -> Result<(), StateError>

Clear an instance’s reap-failure record — a successful reap or a successful manual down calls this through the engine.

pub fn reap_attempt( &self, instance: &str, ) -> Result<Option<ReapAttempt>, StateError>

pub fn gc_due_tombstones(&self) -> Result<Vec<String>, StateError>

Tombstoned instances whose GC window has elapsed — the reaper deletes the row (FK cascade cleans leases/locks/checkpoints) and removes the logs dir (D14).

pub fn delete_instance(&self, instance: &str) -> Result<(), StateError>

Delete an instance row outright (the GC step). FK cascade removes its leases, locks, checkpoints, and reap-attempt row.

impl Store

pub fn open(path: &Path) -> Result<Self, StateError>

Open (creating and migrating as needed) a local file store.

pub fn open_remote(url: &str, token: &str) -> Result<Self, StateError>

Open against a remote libsql primary (the fleet plane).

pub fn open_configured() -> Result<Self, StateError>

Route by config: STACKLESS_STATE_URL (+ STACKLESS_STATE_TOKEN) selects the remote fleet plane; absent, the local default file.

pub fn open_with_paths(paths: &Paths) -> Result<Self, StateError>

Like Self::open_configured, but uses paths.db_path() for the local backend when no remote URL is set.

pub fn state_dir() -> PathBuf

$XDG_STATE_HOME/stackless, falling back to ~/.local/state/stackless.

pub fn default_path() -> PathBuf

The default per-user location: $XDG_STATE_HOME/stackless/state.db, falling back to ~/.local/state/stackless/state.db.

pub fn now_secs() -> i64

The shared clock, for callers outside the store (the reaper’s tick). Same value Store::now writes into rows.

Trait Implementations

impl Debug for Store

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.