State store
Hostwright’s local state store is SQLite, using the system SQLite3 library
with zero external dependencies. It persists desired-state snapshots, observed runtime
snapshots, the event ledger, operation records, ownership records, health
results, restart policy state, restart recovery records, and operation recovery
groups with step-level checkpoints.
Secure selected paths
Section titled “Secure selected paths”The default database is ~/Library/Application Support/Hostwright/state/state.sqlite.
--state-db takes precedence over HOSTWRIGHT_STATE_DB, then the documented default.
Use hostwright paths --json to inspect the selected layout. Private managed directories
require mode 0700; sensitive files require 0600. Unsafe ownership, ACLs, links,
or writable parents fail closed.
State-writing commands can apply compatible migrations. Read-only state queries validate an existing schema without creating or migrating it.
Migration continuity
Section titled “Migration continuity”Migrations are explicit and checksummed:
- Schema version 24 is the latest supported version. A database migrated by a newer Hostwright release fails closed with an incompatible-schema error; Hostwright does not downgrade or convert.
- Each migration records a checksum in
schema_migrations. A known version with an unexpected checksum fails before any application reads or writes. - Applied migration history must be a contiguous prefix starting at version 1. A database recording a later migration while omitting an earlier one fails closed. A valid older contiguous prefix remains eligible for explicit forward migration.
Schema v24 retains lifecycle, storage, network, restart, and ownership authority and adds authenticated local control, audit/RBAC, admission, durable scheduler reservations, and installed-identity rotation fencing. This is single-Mac state; cluster authority is deferred.
What is (and is not) stored
Section titled “What is (and is not) stored”Normalized columns hold identifiers, project and service names, timestamps, lifecycle states, operation status, event severity, restart status, recovery checkpoints, lock leases, and hashes. JSON blobs hold ports, networks, mounts, environment snapshots, event and operation payloads, and recovery metadata, all redacted before persistence.
Concurrency
Section titled “Concurrency”The contract is single-writer: one CLI command or daemon may write a state
database at a time. Hostwright uses SQLite full-mutex mode, a bounded busy
timeout, and BEGIN IMMEDIATE transactions. If another process holds a write
lock beyond the timeout, Hostwright reports a locked database instead of
waiting indefinitely. Operation-group acquisition is atomic across concurrent
stores, with exactly one winner.
No transaction performs runtime mutation. Apply and cleanup write intent first, leave the transaction, call the RuntimeAdapter, then record success or failure.
Verified backup, restore, and repair
Section titled “Verified backup, restore, and repair”Use hostwright state integrity --json, hostwright state backups --json, and
hostwright state recover --json to inspect health and retained recovery evidence.
Online backup publishes a verified private catalog. Restore requires confirmation
and preserves a pre-restore backup or quarantined corrupt source. Repair rebuilds
only supported projections; it never invents ownership authority.
Read the state command reference for the exact backup/restore/repair arguments and confirmation tokens. Current-release installation and recovery qualification remains pending; this prerelease has no GA durability claim.