idea_system.h
idea/idea_system.h · 302 line(s) · c
/*
* idea_system.h -- Idea System(TM) native core, public C ABI.
*
* Idea System(TM) / Idea(TM). From Author; distributive.
*
* This header is the VM-facing contract for the special native code the
* Standard SLeeLa VM may need to implement that is not originally Sleela
* (the Sleela "Sleela runnable" lives under /lib/idea). It is pure C with
* a stable, extern "C" surface so the C++ facade (idea_system.cpp) and the
* Sleela native bridge can both link against it.
*
* The narrative it supports:
* - A signal-distributed System loads and receives its signal input from a
* known internet resource: a hex code the Content Author controls, served
* from github.com. The default locator is the Author's wiki page.
* - That input drives a forward, LINEAR solution Series that may be
* arbitrarily deep but is sized to <= 30 hours of content with <= 9
* decisions that are seemly and important (design goals; law is careful,
* so bounded exceptions are tolerated and merely recorded).
* - The System is in Maintenance of System and then State. The State IS the
* System; the System is prevaricated upon its State. A user cannot really
* know the difference: the System presents what it presents -- its State.
* Not all is present/capable in a given State.
* - Time progresses forward and is ultimate and company to the Series. The
* stream (0..30h) may SEEM to loop or retry, but it is consistent in Time.
*/
#ifndef IDEA_SYSTEM_H
#define IDEA_SYSTEM_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* ---- Versioning ------------------------------------------------------- */
#define IDEA_SYSTEM_NAME "Idea System(TM)"
#define IDEA_SYSTEM_VERSION "1.0.0"
/* ---- Design-goal bounds (law is careful; these are seemly, not rigid) -- */
/* The Series is bounded to <= 30 hours of content. */
#define IDEA_MAX_HOURS 30
#define IDEA_MAX_SECONDS (IDEA_MAX_HOURS * 3600)
/* <= 9 decisions that are seemly, important. */
#define IDEA_MAX_DECISIONS 9
/* The Series may be arbitrarily deep; this is a generous reachability cap */
/* aligned with the SLeeLa Constitution (system depth 3024). */
#define IDEA_MAX_SERIES_DEPTH 3024
/* Complexity degree max from the Constitution (1 direct .. 4 federated). */
#define IDEA_MAX_DEGREE 4
/* ---- Status codes ----------------------------------------------------- */
typedef enum idea_status {
IDEA_OK = 0,
IDEA_INVALID = -1, /* bad argument / null handle */
IDEA_LIMIT = -2, /* a design-goal bound was exceeded */
IDEA_NOT_FOUND = -3,
IDEA_INPUT_UNAVAILABLE = -4, /* internet resource not reachable */
IDEA_INPUT_MALFORMED = -5, /* fetched payload was not valid hex */
IDEA_EXHAUSTED = -6, /* Series reached its end of Time */
IDEA_CORRUPT = -7
} idea_status;
/* The System presents exactly one State at a time. The State IS the */
/* System; a user cannot know which is which -- only what is presented. */
typedef enum idea_state_kind {
IDEA_STATE_LOADING = 0, /* loading the signal-distributed system */
IDEA_STATE_RECEIVING = 1, /* receiving signal input from the internet */
IDEA_STATE_SOLVING = 2, /* advancing through the solution Series */
IDEA_STATE_DECIDING = 3, /* at a seemly, important decision point */
IDEA_STATE_LOOPING = 4, /* seems to loop/retry, but consistent */
IDEA_STATE_PRESENT = 5, /* presenting what is present/capable */
IDEA_STATE_FINAL = 6 /* Finality: end of Time for this Series */
} idea_state_kind;
/* Organization axes -- the Scheme on which the System is organized. */
typedef enum idea_scheme {
IDEA_SCHEME_CONCEPT = 0, /* organization based on Concepts */
IDEA_SCHEME_FINALITY = 1, /* organization based on Finality */
IDEA_SCHEME_SIGNAL = 2, /* organization based on the Signal/Stream */
IDEA_SCHEME_SOCIETY = 3 /* what happens in the Society */
} idea_scheme;
/* Opaque handle to a running Idea System(TM). Callers never see internals */
/* (the same bounded-handle discipline the SLeeLa core uses). */
typedef struct idea_system idea_system;
/* ---- The known internet resource (Author-controlled signal source) ----- */
/*
* The signal input is a hex code the Content Author controls, served from
* github.com. This is the default locator; the Author (or the Sleela
* runnable) may override it with idea_set_source_url before loading. The
* core itself performs no network I/O at construction or test time -- the
* fetch is routed through a pluggable fetcher (see idea_fetch_fn) so the
* System is deterministic and testable offline.
*/
#define IDEA_DEFAULT_SOURCE_URL \
"https://github.com/mearvk/Senior.Senate.Attorney.E44Hrs/wiki/US-Title-Brands"
/*
* A fetcher pulls the raw body of the known internet resource into caller
* memory. Returns the number of bytes written to buf (<= cap), or a negative
* idea_status on failure. The returned bytes are expected to contain a hex
* code (whitespace and 0x prefixes are tolerated by the decoder).
*
* user is the opaque pointer registered with idea_set_fetcher.
*
* NOTE: by default the System uses its OWN built-in HTTP(S) fetcher
* (idea_http_fetch, see below) which really contacts the internet resource.
* Registering a custom fetcher overrides it (useful for tests / offline runs).
*/
typedef long (*idea_fetch_fn)(const char *url, char *buf, size_t cap, void *user);
/*
* The built-in network fetcher (Option 2: HTTP in the core). It performs a
* real HTTP/1.1 GET of `url` over a TCP socket (HTTPS URLs are fetched through
* the system `curl` if available, since the core carries no TLS stack). It is
* the default fetcher installed by idea_create(). Returns bytes written, or a
* negative idea_status. Not available on platforms without BSD sockets, in
* which case it returns IDEA_INPUT_UNAVAILABLE.
*/
long idea_http_fetch(const char *url, char *buf, size_t cap, void *user);
/* ---- Lifecycle -------------------------------------------------------- */
/* Create a fresh System in state IDEA_STATE_LOADING. Returns NULL on OOM. */
idea_system *idea_create(void);
/* Destroy a System and release all its memory. NULL is a no-op. */
void idea_destroy(idea_system *sys);
/* Override the known internet resource URL (defaults to IDEA_DEFAULT_...). */
idea_status idea_set_source_url(idea_system *sys, const char *url);
const char *idea_source_url(const idea_system *sys);
/*
* Register the fetcher used to receive signal input from the internet
* resource, plus an opaque user pointer handed back to it. If no fetcher is
* registered, idea_receive_signal returns IDEA_INPUT_UNAVAILABLE.
*/
idea_status idea_set_fetcher(idea_system *sys, idea_fetch_fn fetch, void *user);
/* ---- Signal input (the hex code from github.com) ---------------------- */
/*
* Receive the signal: fetch the Author's hex code from the known resource and
* fold it into the System as the seed of the Series. Advances the presented
* State to IDEA_STATE_RECEIVING. On success the decoded signal bytes are
* retained inside the System and used to size/seed the Series.
*/
idea_status idea_receive_signal(idea_system *sys);
/*
* Feed a hex code directly (bypassing the fetcher) -- used by the Author to
* provide the URL data, and by tests. hex may contain spaces, newlines, and
* optional 0x prefixes; it must decode to at least one byte.
*/
idea_status idea_feed_hex(idea_system *sys, const char *hex);
/* Number of decoded signal bytes currently held, or 0. */
size_t idea_signal_len(const idea_system *sys);
/* ---- The signal payload format (what the Author's hex encodes) -------- */
/*
* The Author's hex code is not merely a size seed: it is a structured payload
* the Content Author / controller designs. The decoded bytes are read as:
*
* byte 0 : magic 'I' (0x49) -- identifies an Idea(TM) payload
* byte 1 : magic 'D' (0x44)
* byte 2 : format version (currently 1)
* byte 3 : hours (1..30; clamped) -- length of the Series
* byte 4 : decisions (1..9; clamped) -- seemly, important choices
* byte 5 : scheme (0..3 -> idea_scheme)
* byte 6..7 : depth (big-endian u16, 1..3024; clamped)
* byte 8 : flags (bit0 = author-designed, else "what the Society does")
* byte 9..N : opaque Author content bytes (fold into the Series seed)
*
* A payload that does not begin with the 'I''D' magic is treated as a legacy
* raw signal: the whole thing is folded into the seed and the Series is sized
* from it (the pre-format behaviour), so old hex codes still work.
*/
#define IDEA_PAYLOAD_MAGIC0 0x49 /* 'I' */
#define IDEA_PAYLOAD_MAGIC1 0x44 /* 'D' */
#define IDEA_PAYLOAD_VERSION 1
#define IDEA_PAYLOAD_HEADER 9 /* fixed header length in bytes */
#define IDEA_FLAG_AUTHORED 0x01 /* bit0: Author designed; else Society */
/* Did the received signal carry a well-formed Idea(TM) payload header? */
int idea_payload_valid(const idea_system *sys);
/* The format version from the payload (0 if none / legacy raw signal). */
int idea_payload_version(const idea_system *sys);
/* True if the Series shows what the Author designs; false => what the Society
* does. (Reads IDEA_FLAG_AUTHORED; legacy raw signals default to authored.) */
int idea_is_authored(const idea_system *sys);
/* ---- The solution Series (forward, linear; Time is ultimate) ---------- */
/*
* Build the solution Series from the received signal. The Series is linear
* and forward: a sequence of stages across 0..30h, with <= 9 decision points.
* Depth may be arbitrary up to IDEA_MAX_SERIES_DEPTH. Must be called after a
* signal has been received/fed; otherwise IDEA_INVALID.
*/
idea_status idea_build_series(idea_system *sys);
/*
* Advance Time by delta_seconds and let the System maintain itself (System in
* Maintenance of System and then State). This is the single forward step:
* Time progresses, the Series moves, and the presented State is recomputed.
* It may SEEM to loop/retry (IDEA_STATE_LOOPING) but is consistent in Time.
* Returns IDEA_EXHAUSTED once Time reaches the end of the Series (Finality).
*/
idea_status idea_tick(idea_system *sys, long delta_seconds);
/* ---- Presentation (the System presents its State) --------------------- */
/* The State the System currently presents. */
idea_state_kind idea_present_state(const idea_system *sys);
/* Elapsed Time in seconds (0..IDEA_MAX_SECONDS). */
long idea_elapsed_seconds(const idea_system *sys);
/* Fraction of the Series completed, 0.0..1.0 (Time is ultimate). */
double idea_progress(const idea_system *sys);
/* How many of the <= 9 seemly decisions have been reached so far. */
int idea_decisions_taken(const idea_system *sys);
/* The current depth within the (possibly deep) Series. */
int idea_series_depth(const idea_system *sys);
/*
* Not all is present/capable in a given State. Reports whether a named
* capability is present in the System's current State. Unknown names and
* NULL yield 0 (not present).
*/
int idea_is_capable(const idea_system *sys, const char *capability);
/*
* Render what the System presents -- a human-readable line describing its
* current State, Time, progress, decisions, and scheme. Writes a
* NUL-terminated string into buf (truncated to cap) and returns the number of
* bytes that would be written (excluding NUL), or negative on error.
*/
long idea_present(const idea_system *sys, char *buf, size_t cap);
/* ---- Organization (Scheme / Concepts / Finality) ---------------------- */
/* Set the organizing Scheme. Defaults to IDEA_SCHEME_CONCEPT. */
idea_status idea_set_scheme(idea_system *sys, idea_scheme scheme);
idea_scheme idea_scheme_of(const idea_system *sys);
/*
* Register an AI objective the System pursues as it advances (bounded; at
* most IDEA_MAX_DECISIONS objectives, mirroring the seemly-decision budget).
* Returns IDEA_LIMIT once the budget is full.
*/
idea_status idea_add_objective(idea_system *sys, const char *objective);
int idea_objective_count(const idea_system *sys);
/* ---- Canvas / frame clock (the Sleela Canvas Hz rate) ----------------- */
/*
* The Idea(TM) System is presented on a Sleela Canvas. Two rates apply, and
* they are deliberately decoupled -- exactly as user-interface/DRAW-API.md's
* frame clock separates presentation from simulation:
*
* - PRESENT_HZ : the Canvas View refresh rate the window loop honours
* (what the user sees). Matches the SleelaUI house default.
* - SIM_HZ : the live Idea(TM) System simulation rate -- a deterministic
* fixed timestep for advancing the Series, independent of the
* display. This is what keeps Time "consistent" even when a
* frame seems to loop or retry.
*/
#define IDEA_CANVAS_PRESENT_HZ 60.0 /* Canvas View FPS (presentation) */
#define IDEA_CANVAS_SIM_HZ 120.0 /* live Idea(TM) System sim fixed step */
/* The fixed simulation timestep in seconds (1 / IDEA_CANVAS_SIM_HZ). */
double idea_sim_timestep(void);
/*
* A tiny deterministic fixed-step accumulator, mirroring the DRAW-API frame
* clock's fixed_step: feed it the real per-frame delta (seconds) and it tells
* you how many 120 Hz simulation steps to run this frame. Stateless across
* calls except for the accumulator you own.
*
* double acc = 0;
* int steps = idea_fixed_steps(dt, &acc); // run this many sim ticks
*/
int idea_fixed_steps(double frame_dt_seconds, double *accumulator);
/* Human-readable name for a state kind / status / scheme (never NULL). */
const char *idea_state_name(idea_state_kind k);
const char *idea_status_name(idea_status s);
const char *idea_scheme_name(idea_scheme s);
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* IDEA_SYSTEM_H */