sleela_registry.h
registry/sleela_registry.h · 166 line(s) · c
/*
* registry/sleela_registry.h -- Sleela Registry: public C ABI.
*
* Idea System(TM) / Idea(TM). From Author; distributive.
*
* A Windows-style hierarchical registry for SLeeLa: a tree of KEYS (like
* HKEY\Path\Sub) each holding named VALUES (settings and feature flags), plus a
* per-entry PROVENANCE record for the registry's own tracked artifacts:
*
* file name, date, author, version, hex id, SHA-256 hash, originality seal.
*
* A new SLeeLa install seeds a baseline registry that is reviewable from a
* terminal (`sleela registry ...`) or a Sleela terminal program. The store is a
* portable, deterministic text format so it is diffable, hashable, and
* idempotent to regenerate.
*
* Design notes:
* - Keys form a path tree; a path is "A/B/C" (forward slashes, root = "").
* - A value is (name -> typed scalar: string/int/bool).
* - A provenance record is attached to a key by name and seals the identity +
* content hash of a tracked file, so tampering or misplacement is visible.
* - Pure C, extern "C", opaque handle, no dependencies beyond the C library.
*/
#ifndef SLEELA_REGISTRY_H
#define SLEELA_REGISTRY_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#define SLEELA_REGISTRY_VERSION "1.0.0"
#define SLEELA_REGISTRY_MAGIC "SLREG" /* file-format magic */
#define SLEELA_REGISTRY_FORMAT 1 /* on-disk format version */
/* Status codes. */
typedef enum sl_reg_status {
SL_REG_OK = 0,
SL_REG_INVALID = -1, /* bad argument / null handle */
SL_REG_NOT_FOUND = -2, /* key or value not found */
SL_REG_EXISTS = -3, /* key/value already exists (where unique) */
SL_REG_LIMIT = -4, /* a bounded table was full */
SL_REG_MALFORMED = -5, /* a store file could not be parsed */
SL_REG_SEAL_BROKEN = -6 /* an originality seal failed verification */
} sl_reg_status;
/* Value kinds a registry value can hold. */
typedef enum sl_reg_kind {
SL_REG_STRING = 0,
SL_REG_INT = 1,
SL_REG_BOOL = 2
} sl_reg_kind;
/*
* Provenance of a tracked registry artifact. Every field is recorded so an
* entry is self-describing and verifiable:
* - name : the file name the entry tracks
* - date : ISO-8601 date/time the entry was recorded
* - author : the authoring party
* - version : the artifact's version string
* - hex_id : a stable hex identity for the entry (16 hex chars)
* - hash : SHA-256 of the tracked file's content (64 hex chars)
* - seal : originality seal = SHA-256 over (hex_id | version | hash |
* author), proving the identity and content were sealed together
*/
typedef struct sl_reg_provenance {
char name[256];
char date[32];
char author[128];
char version[64];
char hex_id[17]; /* 16 hex + NUL */
char hash[65]; /* 64 hex + NUL */
char seal[65]; /* 64 hex + NUL */
} sl_reg_provenance;
/* Opaque registry handle (owns the key tree + values + provenance). */
typedef struct sl_registry sl_registry;
/* ---- lifecycle -------------------------------------------------------- */
sl_registry *sl_reg_create(void);
void sl_reg_destroy(sl_registry *r);
/* Seed the baseline registry a fresh install starts from (root keys for
* System, Settings, Features, Artifacts). Idempotent. */
sl_reg_status sl_reg_seed_defaults(sl_registry *r);
/* ---- keys ------------------------------------------------------------- */
/* Create (or no-op if present) a key at `path` ("A/B/C"); parents are made. */
sl_reg_status sl_reg_key_create(sl_registry *r, const char *path);
int sl_reg_key_exists(const sl_registry *r, const char *path);
/* Number of direct child keys of `path`; fills names[] (each up to cap). */
int sl_reg_key_children(const sl_registry *r, const char *path,
char **names, int max, size_t name_cap);
/* ---- values (settings / features) ------------------------------------- */
sl_reg_status sl_reg_set_string(sl_registry *r, const char *path, const char *name, const char *value);
sl_reg_status sl_reg_set_int(sl_registry *r, const char *path, const char *name, long value);
sl_reg_status sl_reg_set_bool(sl_registry *r, const char *path, const char *name, int value);
/* Read a value; returns the kind via *kind. String read copies into buf. */
sl_reg_status sl_reg_get_string(const sl_registry *r, const char *path, const char *name, char *buf, size_t cap);
sl_reg_status sl_reg_get_int(const sl_registry *r, const char *path, const char *name, long *out);
sl_reg_status sl_reg_get_bool(const sl_registry *r, const char *path, const char *name, int *out);
sl_reg_status sl_reg_value_kind(const sl_registry *r, const char *path, const char *name, sl_reg_kind *kind);
/* A convenience for feature flags: Features/<name> = bool. */
sl_reg_status sl_reg_feature_set(sl_registry *r, const char *name, int enabled);
int sl_reg_feature_enabled(const sl_registry *r, const char *name);
/* ---- provenance + originality seal ------------------------------------ */
/* Compute the originality seal for a provenance record (fills p->seal from
* hex_id|version|hash|author). Deterministic. */
void sl_reg_seal(sl_reg_provenance *p);
/* Verify a record's seal matches its fields (1 = sealed/intact, 0 = broken). */
int sl_reg_seal_verify(const sl_reg_provenance *p);
/* Attach a provenance record to a key (sealing it if the seal is empty). */
sl_reg_status sl_reg_provenance_set(sl_registry *r, const char *path, const sl_reg_provenance *p);
/* Read a key's provenance record. */
sl_reg_status sl_reg_provenance_get(const sl_registry *r, const char *path, sl_reg_provenance *out);
/* SHA-256 of a buffer, as 64 lowercase hex chars into out (>=65 bytes). */
void sl_reg_sha256_hex(const void *data, size_t len, char *out);
/* ---- persistence (portable, deterministic text store) ----------------- */
/* Save the whole registry to `path` in the .sleelareg text format (sorted keys
* -> idempotent). Load replaces the current contents. */
sl_reg_status sl_reg_save(const sl_registry *r, const char *path);
sl_reg_status sl_reg_load(sl_registry *r, const char *path);
/* ---- SQL export ------------------------------------------------------- */
/* Export the whole registry as a portable MySQL/MariaDB script (CREATE TABLE
* registry_entries + deterministic INSERTs), so settings/features/provenance
* are queryable from a database as well as the .sleelareg text store. Rows are
* sorted (idempotent). Writes to `path`; loads with `mysql <db> < file`. */
sl_reg_status sl_reg_export_sql(const sl_registry *r, const char *path);
/* ---- review ----------------------------------------------------------- */
/* Render a human-readable review of the whole tree (or a subtree at `path`,
* NULL = root) into buf; snprintf semantics. Shows keys, values, and for keys
* with provenance the file/author/version/hexid/hash and seal status. */
long sl_reg_review(const sl_registry *r, const char *path, char *buf, size_t cap);
/* Counts for a quick status line. */
int sl_reg_key_count(const sl_registry *r);
int sl_reg_value_count(const sl_registry *r);
int sl_reg_provenance_count(const sl_registry *r);
const char *sl_reg_status_name(sl_reg_status s);
#ifdef __cplusplus
}
#endif
#endif /* SLEELA_REGISTRY_H */