BeingState:
  health
  stress
  readiness
  balance

KnowingEvent:
  event_type
  timestamp
  severity
  context_flags

PurposeMode:
  PERFORMANCE
  EFFICIENCY
  LONGEVITY
  SAFETY

TimeSignal:
  drift
  recovery_rate
  resilience

*
               ┌────────────────────────────────────────────────────────┐
               │                    Host MCU / SoC                      │
               │ Power policy, sensor fusion, UX, logging, cloud, etc.  │
               │                                                        │
I²C / SPI /    │  ┌─────────────────────────────────────────────────┐   │
MMap bus  ─────┼──┤ RTT-Inside driver / decoder                     ├── ┼──► Fleet analytics / service
               │  │ - Reads RTT_HEALTH/STRESS/READINESS/BALANCE     │   │
               │  │ - Pulls RTT_EVENT_LOG ring buffer               │   │
               │  │ - Sets RTT_PURPOSE mode                         │   │
               │  └─────────────────────────────────────────────────┘   │
               └────────────────────────────────────────────────────────┘
                               ▲                 ▲
                               │                 │ optional interrupts
                               │                 │ (event watermark)
                               │                 │
                               │                 ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                         PMIC / BMS / Sensor IC                            │
│                                                                           │
│  ┌──────────────────────────┐         ┌───────────────────────────────┐   │
│  │    Power Path Control    │         │     Battery Management        │   │
│  │ - Buck/boost/LDO loops   │         │  - Charger control loop       │   │
│  │ - OCP/OVP/UVLO/OTP       │         │  - Protection FETs            │   │
│  │ - Soft-start, sequencing │         │  - Balancing (cell or pack)   │   │
│  └──────────────┬───────────┘         └──────────────┬────────────────┘   │
│                 │                                    │                    │
│                 │                                    │                    │
│  ┌──────────────▼──────────────┐       ┌─────────────▼────────────────┐   │
│  │     ADC / Sensing Frontend  │       │   Safety & Protection FSM    │   │
│  │ - V/I/T sense, coulomb ctr  │       │ - Hard limits + fault flags  │   │
│  │ - optional sensor hub data  │       │ - Latch / retry policy       │   │
│  └──────────────┬──────────────┘       └─────────────┬────────────────┘   │
│                 │                                    │                    │
│                 ├───────────────┐      ┌─────────────┤                    │
│                 │               │      │             │                    │
│                 ▼               ▼      ▼             ▼                    │
│     ┌─────────────────────────────────────────────────────────────────┐   │
│     │          Existing Control Logic (UNCHANGED)                     │   │
│     │  - regulation loops, charge algorithm, protection decisions     │   │
│     └─────────────────────────────────────────────────────────────────┘   │
│                                                                           │
│     ┌─────────────────────────────────────────────────────────────────┐   │
│     │ RTT‑TSB: RTT Telemetry & State Block (OBSERVABILITY ONLY)       │   │
│     │                                                                 │   │
│     │  Inputs (tap only, no control authority):                       │   │
│     │   - V/I/T readings, margins, fault flags, throttle states       │   │
│     │   - loop state (e.g., CC/CV, PFM/PWM), limiter engagement       │   │
│     │   - optional tool: internal timestamps / counters               │   │
│     │                                                                 │   │
│     │  Outputs (register map):                                        │   │
│     │   - BEING: RTT_HEALTH, RTT_STRESS, RTT_READINESS, RTT_BALANCE   │   │
│     │   - TIME: RTT_TIME_HI, RTT_RECOVERY, RTT_DRIFT, RTT_RESILIENCE  │   │
│     │   - KNOWING: RTT_EVENT_LOG ring buffer                          │   │
│     │   - MEANING: RTT_PURPOSE (host writes)                          │   │
│     │                                                                 │   │
│     │  Optional: IRQ on event watermark / critical transition         │   │
│     └─────────────────────────────────────────────────────────────────┘   │
│                                                                           │
│  ┌────────────────────────────────────────────────────────────────────┐   │
│  │ Nonvolatile (optional)                                             │   │
│  │ - retain event log + stress counters across power cycles           │   │
│  └────────────────────────────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────────────────────────┘

IF RTT_STRESS rising AND RTT_READINESS falling:
    prepare mitigation (throttle, warn, log)

IF RTT_HEALTH stable BUT RTT_BALANCE drifting:
    investigate load symmetry or margin erosion

IF repeated low‑severity events cluster:
    flag latent instability

IF high‑severity event follows long stress dwell:
    annotate root‑cause chain

PERFORMANCE → tolerate higher stress, shorter recovery
EFFICIENCY  → favor balance and thermal stability
LONGEVITY   → prioritize low drift and recovery margin
SAFETY      → interpret stress conservatively

IF RTT_DRIFT increasing over weeks:
    schedule inspection or derate policy

IF RTT_RECOVERY slowing:
    reduce peak load or adjust duty cycle

// RTT-TSB Reference Module (pseudocode)
// Goal: observe, interpret, and log RTT-Inside signals without affecting safety/control loops.
 
// ----------------------------
// Platform hooks you provide
// ----------------------------
// rtt_bus_read(addr, *buf, len)  -> returns bool success
// rtt_bus_write(addr, *buf, len) -> returns bool success
// now_ms()                       -> monotonic ms
// persist_store(key, data, len)  -> optional (NVM)
// persist_load(key, *data, len)  -> optional (NVM)
// system_log(level, msg, ...)    -> host logging
// request_soft_mitigation(hint)  -> optional: ask higher-level policy to consider actions
//                                  (never directly changes PMIC/BMS safety logic)
 
 
// ----------------------------
// RTT-TSB register addresses (from your map)
// ----------------------------
#define RTT_ID          0x00
#define RTT_STATUS      0x01
#define RTT_PURPOSE     0x02
#define RTT_HEALTH      0x03
#define RTT_STRESS      0x04
#define RTT_READINESS   0x05
#define RTT_BALANCE     0x06
#define RTT_TEMP_GRAD   0x07
#define RTT_V_MARGIN    0x08
#define RTT_I_STRESS    0x09
#define RTT_TIME_HI_L   0x0A  // 16-bit (0x0A..0x0B)
#define RTT_RECOVERY    0x0C
#define RTT_DRIFT       0x0D
#define RTT_RESILIENCE  0x0E
#define RTT_EVENT_PTR   0x0F
#define RTT_EVENT_LOG   0x10  // 0x10..0x1F (16 entries x 8 bytes)
 
// Event entry size and count
#define RTT_EVENT_BYTES   8
#define RTT_EVENT_COUNT  16
 
// Purpose values
typedef enum {
  PURPOSE_UNDECLARED = 0x00,
  PURPOSE_PERFORMANCE = 0x01,
  PURPOSE_EFFICIENCY  = 0x02,
  PURPOSE_LONGEVITY   = 0x03,
  PURPOSE_SAFETY      = 0x04
} rtt_purpose_t;
 
 
// ----------------------------
// Data model used by OEM firmware
// ----------------------------
typedef struct {
  uint8_t health;
  uint8_t stress;
  uint8_t readiness;
  uint8_t balance;
 
  uint8_t temp_grad;
  uint8_t v_margin;
  uint8_t i_stress;
 
  uint16_t time_hi;
  uint8_t recovery;
  uint8_t drift;
  uint8_t resilience;
 
  uint32_t sample_ms;
} rtt_sample_t;
 
typedef struct {
  // Ring-read state
  uint8_t last_event_ptr;
 
  // Trend baselines (simple, robust)
  uint8_t health_ema;
  uint8_t stress_ema;
  uint8_t readiness_ema;
 
  // Escalation debounce / rate limit
  uint32_t last_notice_ms;
  uint32_t last_warn_ms;
 
  // Purpose state
  rtt_purpose_t purpose;
 
  // Optional persistence flags
  bool have_persist;
} rtt_ctx_t;
 
 
// ----------------------------
// Utility: clamp and EMA
// ----------------------------
static uint8_t ema_u8(uint8_t prev, uint8_t x, uint8_t alpha_num, uint8_t alpha_den) {
  // prev = prev*(1-a) + x*a ; a = alpha_num/alpha_den
  // integer-safe
  uint16_t p = (uint16_t)prev * (alpha_den - alpha_num);
  uint16_t n = (uint16_t)x * alpha_num;
  return (uint8_t)((p + n) / alpha_den);
}
 
static bool rtt_read_u8(uint8_t reg, uint8_t *out) {
  return rtt_bus_read(reg, out, 1);
}
 
static bool rtt_read_u16_le(uint8_t reg_lsb, uint16_t *out) {
  uint8_t b[2];
  if (!rtt_bus_read(reg_lsb, b, 2)) return false;
  *out = (uint16_t)b[0] | ((uint16_t)b[1] << 8);
  return true;
}
 
static bool rtt_write_u8(uint8_t reg, uint8_t val) {
  return rtt_bus_write(reg, &val, 1);
}
 
 
// ----------------------------
// Init: detect block, restore state, set purpose
// ----------------------------
bool rtt_init(rtt_ctx_t *ctx, rtt_purpose_t purpose) {
  memset(ctx, 0, sizeof(*ctx));
  ctx->purpose = purpose;
 
  uint8_t id = 0;
  if (!rtt_read_u8(RTT_ID, &id)) {
    system_log("INFO", "RTT-TSB not detected");
    return false;
  }
 
  // Optional: restore last_event_ptr, EMAs from NVM
  // (Keep it simple: persistence is nice, not required.)
  ctx->have_persist = false;
  // if (persist_load("rtt_ctx", ctx_blob, ...) success) ctx->have_persist = true;
 
  // Declare operating intent (annotation only)
  (void)rtt_write_u8(RTT_PURPOSE, (uint8_t)purpose);
 
  // Initialize event pointer baseline
  uint8_t ptr = 0;
  if (rtt_read_u8(RTT_EVENT_PTR, &ptr)) ctx->last_event_ptr = ptr;
 
  ctx->last_notice_ms = 0;
  ctx->last_warn_ms = 0;
 
  system_log("INFO", "RTT-TSB detected (id=0x%02X), purpose=%u", id, purpose);
  return true;
}
 
 
// ----------------------------
// Read one sample (single-bus pass if you batch reads on real platform)
// ----------------------------
bool rtt_read_sample(rtt_sample_t *s) {
  memset(s, 0, sizeof(*s));
  s->sample_ms = now_ms();
 
  if (!rtt_read_u8(RTT_HEALTH, &s->health)) return false;
  if (!rtt_read_u8(RTT_STRESS, &s->stress)) return false;
  if (!rtt_read_u8(RTT_READINESS, &s->readiness)) return false;
  if (!rtt_read_u8(RTT_BALANCE, &s->balance)) return false;
 
  (void)rtt_read_u8(RTT_TEMP_GRAD, &s->temp_grad);
  (void)rtt_read_u8(RTT_V_MARGIN, &s->v_margin);
  (void)rtt_read_u8(RTT_I_STRESS, &s->i_stress);
 
  (void)rtt_read_u16_le(RTT_TIME_HI_L, &s->time_hi);
  (void)rtt_read_u8(RTT_RECOVERY, &s->recovery);
  (void)rtt_read_u8(RTT_DRIFT, &s->drift);
  (void)rtt_read_u8(RTT_RESILIENCE, &s->resilience);
 
  return true;
}
 
 
// ----------------------------
// Event log pull: read only new entries since last pointer
// Pointer semantics assumed: increments mod (RTT_EVENT_COUNT)
// If silicon uses different semantics, adapt here.
// ----------------------------
typedef struct {
  uint8_t type;
  uint8_t severity;
  uint16_t t_rel;       // relative timestamp
  uint8_t ctx_flags;
  uint32_t reserved;    // compact placeholder
} rtt_event_t;
 
static bool rtt_read_event_entry(uint8_t index, rtt_event_t *e) {
  uint8_t addr = (uint8_t)(RTT_EVENT_LOG + (index * RTT_EVENT_BYTES));
  uint8_t b[RTT_EVENT_BYTES];
  if (!rtt_bus_read(addr, b, RTT_EVENT_BYTES)) return false;
 
  e->type = b[0];
  e->severity = b[1];
  e->t_rel = (uint16_t)b[2] | ((uint16_t)b[3] << 8);
  e->ctx_flags = b[4];
  e->reserved = (uint32_t)b[5] | ((uint32_t)b[6] << 8) | ((uint32_t)b[7] << 16);
  return true;
}
 
void rtt_pull_new_events(rtt_ctx_t *ctx) {
  uint8_t ptr = 0;
  if (!rtt_read_u8(RTT_EVENT_PTR, &ptr)) return;
 
  // No new events
  if (ptr == ctx->last_event_ptr) return;
 
  uint8_t i = ctx->last_event_ptr;
  while (i != ptr) {
    rtt_event_t e;
    if (rtt_read_event_entry(i, &e)) {
      system_log("INFO", "RTT_EVENT type=%u sev=%u trel=%u flags=0x%02X",
                 e.type, e.severity, e.t_rel, e.ctx_flags);
 
      // Optional: persist event in host log store
      // persist_store("rtt_evt", ...)
 
      // Soft escalation hook (policy layer decides what to do)
      // Keep this non-invasive: just request attention.
      if (e.severity >= 0xC0) {
        request_soft_mitigation("RTT_EVENT_HIGH_SEVERITY");
      }
    }
    i = (uint8_t)((i + 1) % RTT_EVENT_COUNT);
  }
 
  ctx->last_event_ptr = ptr;
  // Optional persistence of pointer
  // persist_store("rtt_ptr", &ctx->last_event_ptr, 1);
}
 
 
// ----------------------------
// Interpretation: convert samples into stable insights
// - trend detection (EMA)
// - thresholding (purpose-aware)
// - rate limiting messages to avoid spam
// ----------------------------
static void rtt_update_trends(rtt_ctx_t *ctx, const rtt_sample_t *s) {
  // A gentle EMA: a = 1/8
  ctx->health_ema = ema_u8(ctx->health_ema, s->health, 1, 8);
  ctx->stress_ema = ema_u8(ctx->stress_ema, s->stress, 1, 8);
  ctx->readiness_ema = ema_u8(ctx->readiness_ema, s->readiness, 1, 8);
}
 
static uint8_t stress_warn_threshold(rtt_purpose_t p) {
  // Purpose adjusts interpretation, not silicon behavior.
  switch (p) {
    case PURPOSE_PERFORMANCE: return 0xD0; // tolerate higher stress
    case PURPOSE_EFFICIENCY:  return 0xB0;
    case PURPOSE_LONGEVITY:   return 0xA0;
    case PURPOSE_SAFETY:      return 0x90; // conservative
    default:                  return 0xB0;
  }
}
 
static uint8_t readiness_min_threshold(rtt_purpose_t p) {
  switch (p) {
    case PURPOSE_PERFORMANCE: return 0x50;
    case PURPOSE_EFFICIENCY:  return 0x60;
    case PURPOSE_LONGEVITY:   return 0x70;
    case PURPOSE_SAFETY:      return 0x80;
    default:                  return 0x60;
  }
}
 
void rtt_interpret_and_report(rtt_ctx_t *ctx, const rtt_sample_t *s) {
  rtt_update_trends(ctx, s);
 
  uint32_t t = s->sample_ms;
 
  // Notice: early drift / aging signals (low frequency)
  if (s->drift >= 0xB0 && (t - ctx->last_notice_ms) > 6UL * 60 * 60 * 1000) {
    system_log("NOTICE", "RTT drift elevated (0x%02X), consider service/derate planning", s->drift);
    ctx->last_notice_ms = t;
  }
 
  // Warning: stress rising + readiness falling (core RTT-Inside pattern)
  uint8_t s_warn = stress_warn_threshold(ctx->purpose);
  uint8_t r_min  = readiness_min_threshold(ctx->purpose);
 
  bool high_stress = (s->stress >= s_warn) || (ctx->stress_ema >= s_warn);
  bool low_ready   = (s->readiness <= r_min) || (ctx->readiness_ema <= r_min);
 
  if (high_stress && low_ready && (t - ctx->last_warn_ms) > 60 * 1000) {
    system_log("WARN", "RTT condition risk: stress high (0x%02X), readiness low (0x%02X)",
               s->stress, s->readiness);
 
    // Soft mitigation request: policy layer may throttle, reduce duty cycle,
    // reduce sensor rate, adjust charging profile, or notify user.
    request_soft_mitigation("RTT_STRESS_HIGH_READINESS_LOW");
    ctx->last_warn_ms = t;
  }
 
  // Optional: if balance is drifting, recommend investigation
  if (s->balance <= 0x40 && (t - ctx->last_warn_ms) > 2 * 60 * 1000) {
    system_log("INFO", "RTT balance low (0x%02X); check margin symmetry / load transients", s->balance);
  }
}
 
 
// ----------------------------
// Main periodic task (call from scheduler)
// ----------------------------
void rtt_task_1s(rtt_ctx_t *ctx) {
  rtt_sample_t s;
  if (!rtt_read_sample(&s)) return;
 
  // 1) Pull events first (causal context)
  rtt_pull_new_events(ctx);
 
  // 2) Interpret state safely
  rtt_interpret_and_report(ctx, &s);
 
  // 3) Optional: store downsampled trend points (e.g., every 60s)
  // persist_store("rtt_trend", ...)
}
 
 
// ----------------------------
// Mode transitions: declare purpose when product intent changes
// ----------------------------
void rtt_set_purpose(rtt_ctx_t *ctx, rtt_purpose_t purpose) {
  if (ctx->purpose == purpose) return;
  ctx->purpose = purpose;
  (void)rtt_write_u8(RTT_PURPOSE, (uint8_t)purpose);
  system_log("INFO", "RTT purpose set to %u", purpose);
}