API Reference

GESA TypeScript API

Complete interface definitions for implementing GESA in TypeScript or JavaScript.

---

Core Interfaces

GESARecommendation

The output of every GESA cycle. Every field is observable and traceable.

interface GESARecommendation {
  // What to do
  strategy:               string

  // How confident GESA is (0–100)
  confidence:             number

  // How many similar historical episodes support this recommendation
  episodicSupport:        number

  // Current annealing temperature at time of recommendation
  temperature:            number

  // true = generated under high temperature (novel/less-proven)
  // false = generated under low temperature (validated/conservative)
  explorationBias:        boolean

  // Human-readable explanation of why this strategy was recommended
  reasoning:              string

  // IDs of the specific episodes that support this recommendation
  episodeRefs:            string[]

  // How many candidate strategies were evaluated before selecting this one
  alternativesConsidered: number

  // Rate of change of DRIFT across recent episodes
  // Negative = gap closing, Zero = stuck, Positive = widening
  gapVelocity:            number
}

GESAConfig

interface GESAConfig {
  // Temperature profile for this GESA instance
  temperatureProfile:    'fast' | 'standard' | 'slow' | 'adaptive'

  // Initial temperature (default: 100)
  T0:                    number

  // How many episodes to retrieve per cycle (default: 10)
  retrievalLimit:        number

  // Minimum episodes before GESA recommendations are returned
  // (below this, falls back to Fetch recommendation)
  coldStartThreshold:    number

  // Domain configuration
  domain:                string
  decayConstant:         number  // milliseconds

  // Similarity weight overrides (default weights sum to 1.0)
  similarityWeights?: {
    domainMatch:         number  // default: 0.30
    driftProximity:      number  // default: 0.25
    dimensionMatch:      number  // default: 0.20
    temperatureProximity: number // default: 0.15
    outcomePolarity:     number  // default: 0.10
  }
}

---

Core Functions

gesa.cycle()

Run one complete GESA optimization cycle (steps 1–5).

async function cycle(
  context: EpisodeContext
): Promise<GESARecommendation | null>

Returns null if episode store is below cold start threshold.

Example:

const recommendation = await gesa.cycle({
  domain: 'workplace',
  dimension: 'D6_Operational',
  driftScore: 42,
  driftSign: 'positive',
  gapVelocity: +2.1,
  fetchScore: 1340,
  chirp: 85,
  perch: 72,
  wake: 68,
  tags: ['pain_streak', 'high_load'],
  metadata: {
    teamId: 'team-alpha',
    sprintPhase: 'mid',
    cognitiveLoad: 88
  }
})

gesa.storeOutcome()

Store the outcome of a previous action (steps 7–8).

async function storeOutcome(
  episodeId: string,
  outcome: EpisodeOutcome
): Promise<void>

This call also advances the temperature (COOL step).

Example:

await gesa.storeOutcome('ep_0234', {
  driftAfter: 28,
  gapChange: 14,        // 42 - 28 = 14 point improvement
  timeToResolve: 6,     // 6 days
  success: true,
  notes: 'WIP reduction effective — pain streak resolved by day 6',
  observedAt: new Date(),
  confidence: 90
})

gesa.captureAction()

Record that an action was taken (before outcome is known).

async function captureAction(
  context: EpisodeContext,
  action: EpisodeAction
): Promise<string>  // Returns episode ID for later outcome update

gesa.analysePatterns()

Retrieve pattern analysis across the episode store for a domain.

async function analysePatterns(params: {
  domain:             string
  dimension?:         string
  minEpisodicSupport: number
}): Promise<PatternAnalysis[]>

interface PatternAnalysis {
  pattern:           string    // The action type or cascade path pattern
  frequency:         number    // How often this pattern appears
  successRate:       number    // 0–1
  avgGapClosure:     number    // Average DRIFT points closed
  avgTimeToResolve:  number    // Average time to resolution
  temperatureRange:  [number, number]  // Temperature range when effective
}

---

Temperature API

class GESATemperature {
  readonly current: number
  readonly profile: 'fast' | 'standard' | 'slow' | 'adaptive'
  readonly episodeCount: number

  cool(): void                    // Advance by one cooling step
  reset(T0?: number): void        // Reset to initial temperature
  setProfile(p: string): void     // Change cooling profile
  estimateEpisodesTo(T: number): number  // How many episodes until T?
}

---

Episode Store Interface

GESA requires any storage backend to implement:

interface EpisodeStore {
  // Write a new episode (without outcome)
  write(episode: Omit<Episode, 'outcome' | 'driftAfter'>): Promise<string>

  // Update episode with outcome (immutable pattern: creates updated record)
  updateOutcome(id: string, outcome: EpisodeOutcome): Promise<void>

  // Retrieve episodes by similarity (implementation-specific)
  query(context: EpisodeContext, limit: number): Promise<Episode[]>

  // Get all completed episodes for a domain
  getCompleted(domain: string): Promise<Episode[]>

  // Count episodes for a domain
  count(domain: string): Promise<number>
}

---

Constants

// Default similarity weights
const DEFAULT_SIMILARITY_WEIGHTS = {
  domainMatch:          0.30,
  driftProximity:       0.25,
  dimensionMatch:       0.20,
  temperatureProximity: 0.15,
  outcomePolarity:      0.10
}

// Default cooling rates
const COOLING_RATES = {
  fast:     0.85,
  standard: 0.95,
  slow:     0.99
}

// Default decay constants (milliseconds)
const DECAY_CONSTANTS = {
  content:     30  * 86400 * 1000,
  trading:     30  * 86400 * 1000,
  browser:     14  * 86400 * 1000,
  product:     90  * 86400 * 1000,
  workplace:   180 * 86400 * 1000,
  business_6d: 180 * 86400 * 1000
}

// Default cold start threshold
const COLD_START_THRESHOLD = 20  // episodes per domain

// Initial temperature
const DEFAULT_T0 = 100

---

→ Research & References