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
/*
* activation_transaction.h -- Transactional binary activation primitives.
*
* This is an internal CLI module. It deliberately knows nothing about daemon
* coordination or editor configuration: callers must acquire the maintenance
* barrier before commit and retain it until finalize/rollback completes.
*/
#ifndef CBM_ACTIVATION_TRANSACTION_H
#define CBM_ACTIVATION_TRANSACTION_H
#include <stdbool.h>
#include <stddef.h>
typedef struct cbm_activation_transaction cbm_activation_transaction_t;
typedef enum {
CBM_ACTIVATION_TRANSACTION_OK = 0,
/* Windows could not unlink an inactive backup (normally because the old
* executable image is still mapped) but safely registered it for deletion
* at reboot. The committed activation remains valid. */
CBM_ACTIVATION_TRANSACTION_DEFERRED = 1,
CBM_ACTIVATION_TRANSACTION_INVALID_ARGUMENT = -1,
CBM_ACTIVATION_TRANSACTION_NO_MEMORY = -2,
CBM_ACTIVATION_TRANSACTION_IO = -3,
CBM_ACTIVATION_TRANSACTION_INVALID_STATE = -4,
/* The post-commit validator rejected the candidate and rollback succeeded. */
CBM_ACTIVATION_TRANSACTION_VALIDATION_FAILED = -5,
/* The target changed, but restoring the retained backup also failed. */
CBM_ACTIVATION_TRANSACTION_ROLLBACK_FAILED = -6,
} cbm_activation_transaction_status_t;
typedef bool (*cbm_activation_transaction_validator_fn)(const char *target_path, void *context);
/* Test-only seam: invoked after an absent target has been revalidated and
* immediately before its staged candidate is published. Production callers
* leave this unset. */
typedef void (*cbm_activation_transaction_before_absent_publish_for_test_fn)(
const char *target_path, void *context);
void cbm_activation_transaction_set_before_absent_publish_for_test(
cbm_activation_transaction_before_absent_publish_for_test_fn hook, void *context);
/* Test-only seam: make the next `count` Windows rename attempts fail as though
* another handle held the file, so the transient-lock retry can be proven
* without racing a real scanner. Inert on POSIX and when count is 0. */
void cbm_activation_transaction_rename_failures_set_for_test(unsigned int count);
/* Stage a candidate beside target_path (therefore on the same filesystem).
* The staged file is private to the current account and executable.
* On POSIX, an IO result leaves errno at the error of the failing system call
* (0 when none applies, e.g. a short read), through the stage cleanup, so a
* caller can name it: a full disk reads "No space left on device". The same
* holds for stage_file below. */
cbm_activation_transaction_status_t cbm_activation_transaction_stage_bytes(
const char *target_path, const void *candidate, size_t candidate_size,
cbm_activation_transaction_t **transaction_out);
/* Copy candidate_path into a private executable stage beside target_path. */
cbm_activation_transaction_status_t cbm_activation_transaction_stage_file(
const char *target_path, const char *candidate_path,
cbm_activation_transaction_t **transaction_out);
/* Prepare an atomic removal. A missing target is a valid no-op transaction. */
cbm_activation_transaction_status_t cbm_activation_transaction_stage_removal(
const char *target_path, cbm_activation_transaction_t **transaction_out);
/* Atomically publish the candidate (or remove the target), retaining any old
* target at backup_path. If validator rejects the post-commit state, this
* function rolls back before returning VALIDATION_FAILED. */
cbm_activation_transaction_status_t cbm_activation_transaction_commit(
cbm_activation_transaction_t *transaction, cbm_activation_transaction_validator_fn validator,
void *validator_context);
/* Restore the retained target after a successful commit. */
cbm_activation_transaction_status_t cbm_activation_transaction_rollback(
cbm_activation_transaction_t *transaction);
/* Accept the committed state and delete the retained backup. On Windows,
* DEFERRED means deletion was safely registered for reboot; deferred_path
* remains available for logging until close(). */
cbm_activation_transaction_status_t cbm_activation_transaction_finalize(
cbm_activation_transaction_t *transaction);
/* Close an object. An uncommitted object is cleanly aborted; a committed but
* unfinalized object is rolled back. On cleanup failure, ownership stays with
* the caller so paths and rollback can be retried. */
cbm_activation_transaction_status_t cbm_activation_transaction_close(
cbm_activation_transaction_t **transaction_io);
const char *cbm_activation_transaction_target_path(const cbm_activation_transaction_t *transaction);
const char *cbm_activation_transaction_staged_path(const cbm_activation_transaction_t *transaction);
const char *cbm_activation_transaction_backup_path(const cbm_activation_transaction_t *transaction);
const char *cbm_activation_transaction_deferred_path(
const cbm_activation_transaction_t *transaction);
const char *cbm_activation_transaction_status_message(cbm_activation_transaction_status_t status);
/* Which security predicate refused the most recent transaction, as
* "predicate (os N)", or "" when nothing refused since the last prepare.
* The predicates refuse without a usable OS last-error, so this is the only
* way a caller can say WHY staging failed. Reset by every prepare/stage
* entry; single-threaded like the rest of the transaction API. */
const char *cbm_activation_transaction_refusal_note(void);
#ifdef CBM_ENABLE_TEST_SEAMS
void cbm_activation_transaction_note_refusal_for_testing(const char *predicate,
unsigned long os_error);
/* Linux only: stand home_root in for /home and owner_uid in for root when
* deciding whether /home or a /home/<name> entry is a trusted alias. NULL
* restores the production values. Inert elsewhere. */
void cbm_activation_transaction_set_home_root_for_testing(const char *home_root,
unsigned long owner_uid);
#if defined(__APPLE__) || defined(__linux__)
/* Exercise the shared alias checks with synthetic link ownership and a real
* target. The caller frees the mapped path; NULL means the alias was refused. */
char *cbm_activation_transaction_map_alias_for_testing(const char *link,
unsigned long link_owner_uid,
unsigned long trusted_owner_uid,
bool accept_own_target, const char *rest);
#endif
void cbm_activation_transaction_write_failures_set_for_testing(unsigned int count, int os_error);
#endif
#endif /* CBM_ACTIVATION_TRANSACTION_H */