Types

All types below are exported from @kumbatio/energy-system.

EnergyLevel

type EnergyLevel = 0 | 25 | 50 | 75 | 100

Discrete cognitive capacity values. The model is fixed at five levels - see Levels for their definitions and compatibility helpers for bridging other models.

EnergySource

type EnergySource = 'manual' | 'scheduled' | 'inferred'

How the energy level was set. Source affects engine reconciliation priority: manual outranks scheduled, which outranks inferred.

EnergyPresence

type EnergyPresence = 'visible' | 'muted' | 'hidden'

How a UI element participates at a given energy level:

• visible: rendered normally
• muted: rendered but de-emphasized (reduced opacity, secondary styling)
• hidden: not rendered at all

EnergyPresenceMap

type EnergyPresenceMap = Readonly<Record<EnergyLevel, EnergyPresence>>

A complete presence declaration: one presence value per energy level. This is the annotation apps attach to components/views to state which energy levels they belong to (e.g. "hide the AI chat at 50 and below"). Build one with defineEnergyPresence.

Validation constants

const ENERGY_LEVEL_VALUES: ReadonlySet<number>          // 0, 25, 50, 75, 100
const ENERGY_SOURCE_VALUES: ReadonlySet<EnergySource>   // 'manual', 'scheduled', 'inferred'
const ENERGY_PRESENCE_VALUES: ReadonlySet<EnergyPresence> // 'visible', 'muted', 'hidden'

Frozen, mutation-proof sets for runtime validation (add/delete/clear are disabled). Prefer the guards isEnergyLevel, isEnergySource, and isEnergyPresence, which narrow types.

EnergyState

A point-in-time snapshot of cognitive capacity. Created via createEnergyState or by the engine; always frozen.

/>

EnergyClock

interface EnergyClock {
  now(): number
}

Time source contract for deterministic environments (tests, simulations). Everywhere a clock option is accepted, a plain () => number also works.

EnergyChangeListener

type EnergyChangeListener = (state: EnergyState, prev: EnergyState) => void

Callback for energy state changes.

CognitiveProfile

What the brain can handle at a given energy level.

/>

The four field types are also exported standalone:

type DecisionCapacity = 'high' | 'moderate' | 'low' | 'minimal' | 'none'
type FocusDuration = 'extended' | 'moderate' | 'short' | 'minimal' | 'none'
type TaskComplexity = 'complex' | 'moderate' | 'routine' | 'simple' | 'consumption'
type InterruptionTolerance = 'high' | 'moderate' | 'low' | 'minimal' | 'none'

EnergyLevelDefinition

Complete metadata for a single energy level. Retrieved via getEnergyLevel / getEnergyLevels.

/>

AdaptationStrategy

interface AdaptationStrategy<TConfig> {
  name: string
  describe(level: EnergyLevel): string
  resolve(level: EnergyLevel): TConfig
}

Maps energy levels to application behavior. Pure function contract - given a level, produce a configuration.

/>

See Strategies for the built-in implementations.

EnergyPersistence

Storage contract - implement per platform, or use the built-in adapters.

/>

EnergyMetrics

Computed, app-agnostic metrics from an energy state snapshot. Produced by getEnergyMetrics.

/>

Presence-related types

EnergyPresenceSpec is documented on the Presence page. Session, gate, deferral, and compatibility types are documented alongside their factories on Sessions and gates, Deferral, and Metrics and compatibility.