Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
/* version_cohort.h — Crash-safe exact-build admission across CBM processes. */
#ifndef CBM_DAEMON_VERSION_COHORT_H
#define CBM_DAEMON_VERSION_COHORT_H
#include "daemon/ipc.h"
#include "daemon/service.h"
#include <stdint.h>
typedef struct cbm_version_cohort_manager cbm_version_cohort_manager_t;
typedef struct cbm_version_cohort_lease cbm_version_cohort_lease_t;
typedef struct cbm_version_cohort_daemon_claim cbm_version_cohort_daemon_claim_t;
typedef enum {
CBM_VERSION_COHORT_OK = 0,
CBM_VERSION_COHORT_CONFLICT = 1,
CBM_VERSION_COHORT_BUSY = 2,
CBM_VERSION_COHORT_UNSAFE = 3,
CBM_VERSION_COHORT_IO = 4,
} cbm_version_cohort_status_t;
typedef enum {
CBM_VERSION_COHORT_DAEMON_ABSENT = 0,
CBM_VERSION_COHORT_DAEMON_COORDINATED = 1,
CBM_VERSION_COHORT_DAEMON_UNCOORDINATED = 2,
CBM_VERSION_COHORT_DAEMON_UNSAFE = 3,
CBM_VERSION_COHORT_DAEMON_IO = 4,
} cbm_version_cohort_daemon_presence_t;
typedef enum {
CBM_VERSION_COHORT_MAINTENANCE_ABSENT = 0,
CBM_VERSION_COHORT_MAINTENANCE_REQUESTED = 1,
CBM_VERSION_COHORT_MAINTENANCE_UNSAFE = 2,
CBM_VERSION_COHORT_MAINTENANCE_IO = 3,
} cbm_version_cohort_maintenance_presence_t;
/* A mutation barrier invokes its quiesce callback only after retaining the
* admission lock and observing active lifetime participants. The callback
* must return promptly: the barrier itself bounds only its native lock wait.
* It returns REQUESTED, REFUSED, or ERROR; NOT_NEEDED is reserved for the API
* output when lifetime was already free. REFUSED leaves active work untouched;
* ERROR reports an inability to request orderly quiescence. */
typedef enum {
CBM_VERSION_COHORT_QUIESCE_NOT_NEEDED = 0,
CBM_VERSION_COHORT_QUIESCE_REQUESTED = 1,
CBM_VERSION_COHORT_QUIESCE_REFUSED = 2,
CBM_VERSION_COHORT_QUIESCE_ERROR = 3,
} cbm_version_cohort_quiesce_result_t;
typedef cbm_version_cohort_quiesce_result_t (*cbm_version_cohort_quiesce_fn)(void *context);
/* Managers independently reopen no paths: the endpoint duplicates its
* already-validated owner-only runtime-directory handle. All managers for one
* account therefore meet at the same stable native lock files. */
cbm_version_cohort_manager_t *cbm_version_cohort_manager_new(
const cbm_daemon_ipc_endpoint_t *endpoint);
/* Admission first takes the maintenance gate SH without waiting, holds it
* across the short admission EX transition, then retains SH on the cohort
* lifetime file. Active maintenance therefore fails fast with BUSY. Exact
* identity peers share SH; a different version, build, ABI, or cache root
* is a CONFLICT — retried, with every guard released between attempts, until
* deadline_ms, because the mismatched holder is often a draining daemon or a
* short-lived CLI that is about to leave (#2046). Only when the deadline
* passes is CONFLICT returned with conflict_out populated. deadline_ms is an
* absolute cbm_now_ms() deadline; UINT64_MAX waits indefinitely for locks but
* never for a conflicting holder. Every non-NULL lease_out, including
* cleanup-only IO state, must be released. */
cbm_version_cohort_status_t cbm_version_cohort_acquire(cbm_version_cohort_manager_t *manager,
const cbm_daemon_build_identity_t *identity,
uint64_t deadline_ms,
cbm_version_cohort_lease_t **lease_out,
cbm_daemon_conflict_t *conflict_out);
/* Binary activation takes the lifetime file EX. It therefore refuses while
* any CLI/bootstrap/daemon participant is active and blocks new admissions
* for the complete install/update/uninstall mutation window. */
cbm_version_cohort_status_t cbm_version_cohort_reserve_exclusive(
cbm_version_cohort_manager_t *manager, uint64_t deadline_ms,
cbm_version_cohort_lease_t **lease_out);
/* Coordinated install/update/uninstall barrier for modern CBM participants.
* It first publishes maintenance intent EX, then retains admission EX so no
* new participant can enter, and finally probes lifetime EX. If lifetime is
* busy, quiesce is invoked exactly once and the barrier waits no later than
* the finite absolute deadline_ms. On success the returned mutation lease
* retains maintenance EX, admission EX, and lifetime EX until release. On
* timeout, callback refusal/error, or lock failure it grants no mutation
* authority and releases every safely releasable guard. UINT64_MAX is
* rejected because mutation draining must always be bounded. A non-NULL
* cleanup-only lease_out after IO must still be released by the caller. */
cbm_version_cohort_status_t cbm_version_cohort_reserve_for_mutation(
cbm_version_cohort_manager_t *manager, uint64_t deadline_ms,
cbm_version_cohort_quiesce_fn quiesce, void *quiesce_context,
cbm_version_cohort_quiesce_result_t *quiesce_result_out,
cbm_version_cohort_lease_t **lease_out);
/* Cheap, non-blocking observation of the crash-released maintenance intent.
* Participants use the same native gate before admission, so REQUESTED is an
* authoritative fail-fast signal rather than a filesystem-presence guess. */
cbm_version_cohort_maintenance_presence_t cbm_version_cohort_maintenance_presence(
cbm_version_cohort_manager_t *manager);
/* Terminal-observer variant for threads whose only safe response to an
* observation error is immediate process exit. Unlike the general observer,
* this never logs, flushes stdio, or fail-stops internally when native lock
* cleanup cannot be completed. It returns MAINTENANCE_IO instead; callers must
* then terminate immediately without touching borrowed manager state. A
* REQUESTED result owns no observer lock and may first use a bounded
* cooperative-cancellation grace period. */
cbm_version_cohort_maintenance_presence_t cbm_version_cohort_maintenance_presence_terminal(
cbm_version_cohort_manager_t *manager);
/* The daemon holds this separate EX marker for its generation after taking
* the stable daemon lifetime reservation. A local CLI can therefore
* distinguish a current coordinated daemon from a pre-cohort daemon without
* opening an IPC connection or registering a daemon session. A non-NULL
* claim_out accompanying IO is cleanup-only authority and must be released. */
cbm_version_cohort_status_t cbm_version_cohort_daemon_claim_acquire(
cbm_version_cohort_manager_t *manager, cbm_version_cohort_daemon_claim_t **claim_out);
cbm_private_file_lock_status_t cbm_version_cohort_daemon_claim_release(
cbm_version_cohort_daemon_claim_t **claim_io);
/* Non-owning marker observation for startup turnover. COORDINATED means a
* current daemon still holds its generation claim, including the cleanup
* interval after its listener/lifetime reservation has closed. ABSENT means
* the marker was acquired and released safely; UNSAFE/IO fail closed. */
cbm_version_cohort_daemon_presence_t cbm_version_cohort_daemon_claim_presence(
cbm_version_cohort_manager_t *manager);
/* Native marker ownership, never file existence, establishes a coordinated
* daemon. A retained marker remains authoritative during final cleanup even
* after listener/lifetime teardown. */
cbm_version_cohort_daemon_presence_t cbm_version_cohort_daemon_presence(
cbm_version_cohort_manager_t *manager, const cbm_daemon_ipc_endpoint_t *endpoint);
/* Standalone CLI presence check under its successfully sealed and retained
* startup transition. An absent daemon lifetime is authoritative because no
* current or legacy daemon can start through that guard; an active lifetime
* must still own the current-generation daemon marker to be coordinated. */
cbm_version_cohort_daemon_presence_t cbm_version_cohort_daemon_presence_under_transition(
cbm_version_cohort_manager_t *manager, const cbm_daemon_ipc_endpoint_t *endpoint,
const cbm_daemon_ipc_local_transition_t *transition);
cbm_private_file_lock_status_t cbm_version_cohort_lease_release(
cbm_version_cohort_lease_t **lease_io);
/* Heartbeat for a long-lived holder: refresh every lock file the lease or
* claim holds. An age-based temp cleaner deleting a held file silently ends
* coordination, because the next participant creates and locks a fresh inode
* (#2178). Returns OK when all held files were refreshed, UNSAFE once any is
* lost (its path no longer names the held file), and IO when a still-valid
* file could not be refreshed. The only safe response to UNSAFE is an orderly
* exit; re-claiming would race that participant. IO is transient. */
cbm_version_cohort_status_t cbm_version_cohort_lease_touch(cbm_version_cohort_lease_t *lease);
cbm_version_cohort_status_t cbm_version_cohort_daemon_claim_touch(
cbm_version_cohort_daemon_claim_t *claim);
/* Refuses teardown while a lease or retryable cleanup handle remains. */
cbm_private_file_lock_status_t cbm_version_cohort_manager_free(
cbm_version_cohort_manager_t **manager_io);
/* Best-effort persistent conflict record in the same owner-only daemon log
* used by HELLO conflicts. Admission remains safely rejected if logging fails. */
bool cbm_version_cohort_log_conflict(const cbm_daemon_conflict_t *conflict);
/* Persist the fail-closed migration case where the stable daemon reservation
* is active but no current-generation coordination marker can be verified. */
bool cbm_version_cohort_log_uncoordinated_daemon(const cbm_daemon_build_identity_t *requested);
#ifdef CBM_ENABLE_TEST_SEAMS
/* Monotonic count of admission attempts that met a mismatched live holder and
* retried (#2046). Lets a test prove the waiter observed the conflict before
* the holder left, instead of passing vacuously by arriving late. */
uint64_t cbm_version_cohort_conflict_retries_for_testing(void);
#endif
#endif /* CBM_DAEMON_VERSION_COHORT_H */