Home /Modules/artificial-intelligence/rrs_signal_monitor.h

rrs_signal_monitor.h

artificial-intelligence/rrs/rrs-signal-monitor/rrs_signal_monitor.h · 113 line(s) · c

#ifndef SLEELA_AI_LLM_RRS_SIGNAL_MONITOR_H
#define SLEELA_AI_LLM_RRS_SIGNAL_MONITOR_H
/*
 * RRS signal monitor — observability over the RRS ternary 1/0/2 signal stream.
 *
 * It watches an RRS feed-forward and produces a "signal analysis": for every
 * premise in every stage it records the EFFECTIVE ternary signal actually used
 * (after RRS subtracts faith and after the responsibility prelude forces
 * elimination), the reason an elimination occurred, and the running power. It
 * then reports the per-signal / per-stage tallies and the potestas culmination.
 *
 * The monitor is read-only: it never changes an RRS outcome. It re-derives the
 * effective signal exactly as sllmrrs_fold_stage does, so the analysis matches
 * what the model actually computed. No weights, no allocation beyond a caller-
 * sized record buffer.
 *
 *   1 = AFFIRM     (+1 power)
 *   0 = ELIMINATE  (breaks the stage's strict AND)
 *   2 = POWER_ADD  (+2 power, binary-simple power addition)
 */
#include "../rrs.h"
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#if defined(_WIN32) && defined(SLEELA_AI_SHARED)
# if defined(SLEELA_AI_BUILD)
#  define SLLMRM_API __declspec(dllexport)
# else
#  define SLLMRM_API __declspec(dllimport)
# endif
#elif defined(__GNUC__) && defined(SLEELA_AI_SHARED)
# define SLLMRM_API __attribute__((visibility("default")))
#else
# define SLLMRM_API
#endif

#define SLLMRM_ABI_VERSION 1u

/* Why a premise was eliminated (0). NONE means it was not eliminated. */
typedef enum sllmrm_reason {
 SLLMRM_REASON_NONE=0,            /* affirmed / power-added, not eliminated */
 SLLMRM_REASON_SIGNALLED_NO=1,    /* the premise itself signalled ELIMINATE */
 SLLMRM_REASON_FAITH=2,           /* faith/trial premise subtracted by RRS */
 SLLMRM_REASON_RESPONSIBILITY=3   /* responsibility prelude unmet at stage 2 */
} sllmrm_reason;

typedef enum sllmrm_status {
 SLLMRM_OK=0, SLLMRM_INVALID_ARGUMENT=1, SLLMRM_CAPACITY=2
} sllmrm_status;

/* One observed signal event: a premise, its stage, the effective signal RRS
   used, the elimination reason (if any), and the running power after it. */
typedef struct sllmrm_event {
 sllmrrs_stage  stage;
 uint32_t       index_in_stage;   /* 0-based within the stage */
 const char    *text;             /* borrowed from the premise */
 sllmrrs_signal effective_signal; /* 1/0/2 actually applied */
 sllmrm_reason  reason;           /* why eliminated, or NONE */
 uint32_t       running_power;    /* cumulative power up to and including this event */
} sllmrm_event;

/* Tallies of the full run. */
typedef struct sllmrm_tally {
 uint32_t affirm;        /* count of effective AFFIRM (1) */
 uint32_t eliminate;     /* count of effective ELIMINATE (0) */
 uint32_t power_add;     /* count of effective POWER_ADD (2) */
 uint32_t by_reason[4];  /* indexed by sllmrm_reason */
 uint32_t stage_power[SLLMRRS_STAGE_COUNT];
 uint32_t total_power;
 sllmrrs_potestas potestas;
 int solid;
} sllmrm_tally;

/* A caller-owned monitor: a fixed event buffer plus running tallies. */
typedef struct sllmrm_monitor {
 uint32_t abi_version;
 sllmrm_event *events;   /* caller-owned buffer */
 size_t        event_cap;
 size_t        event_count;
 sllmrm_tally  tally;
} sllmrm_monitor;

SLLMRM_API const char *sllmrm_reason_name(sllmrm_reason reason);

/* Initialize a monitor over a caller-owned event buffer (may be NULL/0 to tally
   only, without recording individual events). */
SLLMRM_API sllmrm_status sllmrm_monitor_init(sllmrm_monitor *monitor,
                                             sllmrm_event *event_buffer,
                                             size_t event_capacity);

/* Observe a full RRS feed-forward: runs sllmrrs_feed_forward, re-derives the
   effective per-premise signal (matching the model), records events (up to the
   buffer capacity; overflow is reported via SLLMRM_CAPACITY but tallies remain
   complete), and fills the tally. 'result_out' (optional) receives the RRS
   result. The stageN/countN inputs are the same premises passed to RRS. */
SLLMRM_API sllmrm_status sllmrm_observe(sllmrm_monitor *monitor,
                                        const sllmrrs_premise *stage1, size_t n1,
                                        const sllmrrs_premise *stage2, size_t n2,
                                        const sllmrrs_premise *stage3, size_t n3,
                                        sllmrrs_result *result_out);

/* Write a compact, human-readable signal-analysis report to 'out' (a caller
   buffer of 'cap' bytes). Returns the number of bytes that would be written
   (like snprintf); never writes past cap. Safe with out=NULL/cap=0 to size. */
SLLMRM_API int sllmrm_format_report(const sllmrm_monitor *monitor, char *out, size_t cap);

#ifdef __cplusplus
}
#endif
#endif