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.

A SQLite state database feeding a ledger of desired, observed, events, operations, ownership, health, and recovery records, read back by the read-only events, recovery, and diagnostics commands.

Where state lives

State-backed commands resolve their database in a fixed order:

--state-db <absolute-path> on the command line;
the HOSTWRIGHT_STATE_DB environment variable;
the default, ~/Library/Application Support/Hostwright/state/state.sqlite.

# Uses the Application Support default
hostwright status
hostwright events

# Uses an explicit path
hostwright status --state-db /tmp/hostwright.sqlite

State-writing commands create Hostwright-owned directories with mode 0700 and sensitive files with mode 0600, only when a write actually needs them. hostwright paths reports the selected path, its origin (explicit, environment, or application-support-default), the full layout, and readiness without creating anything. A compatible legacy ~/.hostwright/state.sqlite is moved through an identity-bound, resumable migration journal; unknown legacy files are preserved.

Write-path commands (status, logs, apply, cleanup, hostwrightd) run compatible migrations before writing. Read commands (events, recovery, diagnostics) validate the applied schema and fail rather than creating or migrating a database as a side effect.

Path safety

Before opening the database or a lock, Hostwright validates the whole parent chain: paths must be absolute and normalized, directories must be owned by root or the current user and never group- or other-writable, user-controlled symlinks are rejected, and state and lock files must be regular non-symlink 0600 files. State and lock creation use no-follow, exclusive creation, and file synchronization, and SQLite validates every -journal, -wal, and -shm sidecar across the open boundary.

Migration continuity

Migrations are explicit and checksummed. The current schema is version 15.

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 read or write.
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 stays eligible for forward migration.

Recent schema versions added exact observed resource identifiers, network metadata, ownership identity versions, Hostwright UUIDs, runtime-provider binding, fencing fields, immutable image digest locks, signed image-trust, SBOM, vulnerability, and provenance evidence, and storage volume/snapshot/ backup/orphan/quota records. See Runtime adapter: identity and ownership.

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

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. Readers share a state-access fence; writers take an exclusive writer fence; restore, repair, and recover take the exclusive access fence.

No transaction performs runtime mutation. Apply and cleanup write intent first, leave the transaction, call the RuntimeAdapter, then record success or failure.

State maintenance

The hostwright state commands operate on the database only and never touch Apple container resources.

state integrity runs read-only structure, foreign-key, migration-ledger, and projection checks and reports healthy, degraded, or unrecoverable.
state backup takes a verified online backup; state backups lists the catalog. Verified catalogs live under ~/Library/Application Support/Hostwright/backups, or beside an explicit database.
state restore replaces the database from a backup after a dry run and an exact confirmation token, making a pre-restore backup and clearing stale projections.
state repair rebuilds only the reconstructible projection tables when integrity is degraded in exactly those tables, after a dry run and token.
state recover finishes an interrupted restore or repair from its durable journal.

Structural, desired-state, ownership, operation, and audit damage is never auto-repaired; restore from a verified backup instead. See the CLI reference for the exact commands and Events and diagnostics for the read-only inspection surface.