Lifecycle and head

States

State	Meaning
stopped	Created, never started (or the daemon restarted). No process; no data directory yet if never woken.
running	A hyphae serve process is up on this project’s loopback port and /v2/* is forwarded.
sleeping	The process was terminated on request. The data directory is retained; wake it any time.

Wake up (POST /v0/projects/{id}/wakeup) starts the engine, initialising the directory on first start, and waits up to 15 s for it to answer. Sleep (POST …/sleep) sends the process a graceful stop and keeps the directory.

Snapshots and restores need the project asleep: Native’s tools require the directory lock that a running engine holds. Trying while running answers 409 tenant_running.

head is a probe, not a hash

GET /v0/projects/{id}/head reports what the engine itself says, under the engine’s field names. The Cloud computes no digest of its own.

• While running, source: live_probe: the Cloud calls GET /v2/capabilities on the engine and returns engine (hyphae version --json fields), the endpoint, protocol_minor, the request id and the raw capabilities envelope.
• While asleep, source: offline_status: the Cloud runs hyphae status --data-dir on the directory and returns engine, lineage (catalog_version, directory_lineage, logical_time_micros, root_digest, visible_csn) and latest_snapshot.
• Never started: 409 tenant_not_running with a hint to wake up first.

A lineage position (visible_csn, root_digest) is only reported while asleep — reading it needs the directory lock. A running project’s head is a live probe.