partition_api.h
philosophy/partition_api.h · 189 line(s) · c
#ifndef SLEELA_PHILOSOPHY_PARTITION_API_H
#define SLEELA_PHILOSOPHY_PARTITION_API_H
/*
* Uniform three-level API for the philosophy event tree.
*
* One interface is applied identically at three levels (consistent OOD):
* - BRANCH : an individual node/event, as it occurs.
* - PARTITION : a named group of branches.
* - SYSTEM : the whole tree's branching nature (height and maturations).
*
* A partition's behavior is the composition of its branches'; the system's is
* the composition of its partitions'. The same eight operations and the same
* eleven fired activities exist at every level.
*
* Eight operations:
* add, delete, prune, renegotiate, system, analysis, control, feature.
*
* Eleven activities fired via a dispatch table on each operation:
* workers, listeners, controllers, event-handlers, exchanger,
* memory-analysis, saving, retirement, scandal, nursing, pro-bono.
*
* - scandal : raise an audit/alarm when a target violates an invariant
* (too many traits, weight out of [1,9], over-height,
* or more than the 3-maturation cap).
* - nursing : remediation pass that repairs/rebalances a degraded or
* inconsistent target back to consistency.
* - pro-bono : low-priority, no-cost opportunistic maintenance pass
* (prune/renegotiate when the target is idle).
*
* The whole tree matures ("grows indistinguished") at most SL_TREE_MATURATION_MAX
* (3) times across its whole nature; the usual case is 1. The system basis is a
* small fan of SL_TREE_BASIS_NODES (2-3) nodes, not more.
*
* This layer is additive. It wraps event_tree / consistency_monitor /
* signal_toss and leaves their APIs unchanged. It performs no I/O: "saving" is
* an in-memory snapshot, consistent with the module's no-files rule.
*/
#include "consistency_monitor.h"
#include "event_tree.h"
#include "signal_toss.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* ---- Whole-tree basis / maturation caps -------------------------------- */
#define SL_TREE_BASIS_NODES_MIN 2u
#define SL_TREE_BASIS_NODES_MAX 3u
#define SL_TREE_MATURATION_USUAL 1u
#define SL_TREE_MATURATION_MAX 3u
#define SL_PARTITION_NAME_CAPACITY 48u
#define SL_PARTITION_CAPACITY 32u
/* ---- Levels ------------------------------------------------------------ */
typedef enum sl_level {
SL_LEVEL_BRANCH = 0,
SL_LEVEL_PARTITION,
SL_LEVEL_SYSTEM
} sl_level;
/* ---- Operations -------------------------------------------------------- */
typedef enum sl_op {
SL_OP_ADD = 0,
SL_OP_DELETE,
SL_OP_PRUNE,
SL_OP_RENEGOTIATE,
SL_OP_SYSTEM,
SL_OP_ANALYSIS,
SL_OP_CONTROL,
SL_OP_FEATURE,
SL_OP_COUNT
} sl_op;
/* ---- Activities (dispatch table) --------------------------------------- */
typedef enum sl_activity {
SL_ACT_WORKERS = 0,
SL_ACT_LISTENERS,
SL_ACT_CONTROLLERS,
SL_ACT_EVENT_HANDLERS,
SL_ACT_EXCHANGER,
SL_ACT_MEMORY_ANALYSIS,
SL_ACT_SAVING,
SL_ACT_RETIREMENT,
SL_ACT_SCANDAL,
SL_ACT_NURSING,
SL_ACT_PRO_BONO,
SL_ACT_COUNT
} sl_activity;
/* Bitmask of activities. SL_ACT_ALL fires every activity an op supports. */
typedef uint32_t sl_activity_mask;
#define SL_ACT_BIT(activity) ((sl_activity_mask)1u << (activity))
#define SL_ACT_ALL ((sl_activity_mask)((1u << SL_ACT_COUNT) - 1u))
/* ---- Scientist-addressed research requests ----------------------------- *
* The module does not encode IQ or any intelligence scale (see README 3.2).
* Figures supplied as "IQ" are recorded here only as open requests addressed
* to the scientific community to establish the base merit of this series. */
#define SL_RESEARCH_TEXT_CAPACITY 192u
typedef struct sl_research_request {
char subject[SL_RESEARCH_TEXT_CAPACITY]; /* what scientists are asked to assess */
double claimed_figure; /* the supplied figure, e.g. 200.0 */
bool validated; /* always false here: pending science */
} sl_research_request;
/* ---- Activity outcome -------------------------------------------------- */
typedef struct sl_activity_outcome {
sl_activity activity;
bool fired;
bool ok;
uint64_t magnitude; /* op-specific count (nodes touched, pruned, etc.) */
} sl_activity_outcome;
typedef struct sl_op_result {
sl_op op;
sl_level level;
sl_status status;
sl_activity_mask requested;
sl_activity_mask fired;
sl_activity_outcome outcomes[SL_ACT_COUNT];
sl_consistency_report consistency;
uint64_t scandals; /* invariant violations flagged this op */
uint64_t nursed; /* remediations performed this op */
} sl_op_result;
/* An observer invoked for every fired activity (the "event handlers"/"listeners"
* seam). ctx is the user pointer registered on the engine. */
typedef void (*sl_activity_observer)(
const sl_op_result *result, const sl_activity_outcome *outcome, void *ctx);
typedef struct sl_partition_engine sl_partition_engine;
/* ---- Lifecycle --------------------------------------------------------- */
sl_partition_engine *sl_partition_engine_create(uint64_t now);
void sl_partition_engine_destroy(sl_partition_engine *engine);
void sl_partition_engine_set_observer(
sl_partition_engine *engine, sl_activity_observer observer, void *ctx);
void sl_partition_engine_set_now(sl_partition_engine *engine, uint64_t now);
/* Create/find named partitions (returns index, or -1 on failure/full). */
int sl_partition_create(sl_partition_engine *engine, const char *name);
int sl_partition_index(const sl_partition_engine *engine, const char *name);
size_t sl_partition_count(const sl_partition_engine *engine);
/* ---- The uniform operation entry point --------------------------------- *
* Dispatches op at the given level, firing the activities in `activities`
* that the op supports, and writes a full result. For SL_LEVEL_BRANCH and
* SL_LEVEL_PARTITION, partition_index selects the partition; for
* SL_LEVEL_SYSTEM it is ignored. `event` is used by SL_OP_ADD (branch level);
* `id` is used by SL_OP_DELETE. */
sl_status sl_partition_dispatch(
sl_partition_engine *engine, sl_level level, int partition_index,
sl_op op, sl_activity_mask activities,
const sl_event *event, uint64_t id, sl_op_result *out);
/* ---- Convenience wrappers for the eight ops (fire SL_ACT_ALL) ---------- */
sl_status sl_partition_add(sl_partition_engine *, int partition_index, const sl_event *, sl_op_result *);
sl_status sl_partition_delete(sl_partition_engine *, int partition_index, uint64_t id, sl_op_result *);
sl_status sl_partition_prune(sl_partition_engine *, int partition_index, double floor_w, sl_op_result *);
sl_status sl_partition_renegotiate(sl_partition_engine *, int partition_index, sl_op_result *);
sl_status sl_partition_system(sl_partition_engine *, int partition_index, sl_op_result *);
sl_status sl_partition_analysis(sl_partition_engine *, int partition_index, sl_op_result *);
sl_status sl_partition_control(sl_partition_engine *, int partition_index, bool run_workers, sl_op_result *);
sl_status sl_partition_feature(sl_partition_engine *, int partition_index, sl_activity activity, bool enable, sl_op_result *);
/* ---- System (whole-tree) helpers --------------------------------------- */
sl_status sl_system_op(sl_partition_engine *, sl_op, sl_activity_mask, sl_op_result *);
unsigned sl_system_maturations(const sl_partition_engine *engine);
unsigned sl_system_basis_nodes(const sl_partition_engine *engine);
/* Record an "IQ"/figure as an open request to scientists (never a score). */
sl_status sl_system_add_research_request(
sl_partition_engine *engine, const char *subject, double figure);
size_t sl_system_research_request_count(const sl_partition_engine *engine);
bool sl_system_research_request_at(
const sl_partition_engine *engine, size_t i, sl_research_request *out);
/* ---- Stringization ----------------------------------------------------- */
const char *sl_level_string(sl_level);
const char *sl_op_string(sl_op);
const char *sl_activity_string(sl_activity);
#ifdef __cplusplus
}
#endif
#endif