Ghostlight/docs/architecture/agent-state-variable-glossary.md

# Agent State Variable Glossary

This document explains the current v0 Ghostlight state variables. It is the
human-facing companion to:

- `schemas/agent-state.schema.json`
- `schemas/agent-state.required-fields.json`
- `examples/agent-state.call-of-the-void.json`

The schema is not pretending this vocabulary is final. It is a first stable
core: enough shared axes to compare characters, build prompt projection, and
avoid turning every new scene into a bespoke little fog machine.

## Variable Components

Canonical scalar-like state variables use three numeric components.

| Field | Meaning |
| --- | --- |
| `mean` | The baseline tendency or long-run level for this variable. A high `mean` means this trait, strategy, pressure, or stance is normally strong for the agent. |
| `plasticity` | How easily this variable can change. High plasticity means the value can move quickly under events, relationships, culture, or scene pressure. Low plasticity means it is entrenched. |
| `current_activation` | How active the variable is right now, in this scene or current state. This can spike above or fall below the baseline without rewriting the agent. |

Example:

```json
{
  "mean": 0.35,
  "plasticity": 0.2,
  "current_activation": 0.9
}
```

This means the agent is not generally high in the variable, the baseline is not
very easy to change, but the variable is strongly activated right now.
Translation: this is a situation, not a personality transplant.

Canonical character state does not include `certainty`. If a generated or
imported profile is provisional, track that in workflow provenance, draft
status, imported-source notes, or review status.

Perceived state uses a different shape because observers do not know canonical
baseline or plasticity. They see behavior, then often treat that behavior as
evidence of what the target is like.

```json
{
  "observed_activation": 0.9,
  "attributed_disposition": 0.7,
  "confidence": 0.4
}
```

| Field | Meaning |
| --- | --- |
| `observed_activation` | How strongly the observer thinks the target expressed the dimension in the observed event or scene. |
| `attributed_disposition` | How much the observer generalizes from the observed behavior into "this is what the target is like." |
| `confidence` | How strongly the observer trusts this read. This is where evidence strength, emotional investment, prejudice, relationship stakes, prior memory, and social reinforcement show up. |

This models fundamental attribution bias directly. A character can see someone
behave coldly during a crisis and conclude "they are cold," not "they were
activated toward distance under exceptional pressure." Correcting that
impression takes work because the observer's confidence is supported by memory,
emotion, stakes, prior assumptions, and social reinforcement.

Perceived overlays may use structured belief metadata such as subject, claim
type, evidence events, visibility, and emotional charge. That metadata is not
canonical certainty. It describes why a specific observer trusts a specific
read.

## Label Set Policy

The labels in `agent-state.required-fields.json` are the required v0 core,
not per-character tags. They cover the axes Ghostlight currently treats as
first-class.

The validator requires each canonical agent fixture to include the full core
set so agents can be compared on the same axes. That means Cat's example does
not contain only labels that apply strongly to Cat. It contains all required
labels, with low values for weak or inactive axes and high values for strong or
activated axes.

Variable maps may still grow extra labels where a character, culture, or story
needs them. Do not promote a new label into the required core until it has
proved broadly useful across multiple characters or scenes. Otherwise the
schema becomes a junk drawer with a badge.

## Underlying Organization

| Label | Meaning |
| --- | --- |
| `self_coherence` | How integrated and stable the agent's sense of self is under pressure. |
| `contingent_worth` | How much the agent's felt worth depends on approval, utility, status, purity, or external validation. |
| `shame_sensitivity` | How painful exposure, correction, failure, or diminishment feels. |
| `reciprocity_capacity` | Ability to recognize and sustain mutual obligations rather than purely extractive or avoidant relations. |
| `mentalization_quality` | Ability to model other minds with nuance instead of flattening them into crude threat, need, or utility categories. |
| `authenticity_tolerance` | Capacity to be known without immediately retreating into performance, control, or concealment. |
| `mask_rigidity` | How necessary and inflexible the performed self is. High values mean the mask is load-bearing. |
| `external_regulation_dependence` | How much emotional stability depends on other people, institutions, substances, scripts, or external structures. |

## Stable Dispositions

| Label | Meaning |
| --- | --- |
| `novelty_seeking` | Attraction to new experience, strange opportunities, and unproven paths. |
| `conformity` | Preference for accepted norms, procedures, and group expectations. |
| `status_hunger` | Desire for rank, recognition, prestige, or visible superiority. |
| `risk_tolerance` | Willingness to accept danger, uncertainty, or loss for gain or freedom. |
| `sociability` | Baseline draw toward company, conversation, networks, and social energy. |
| `baseline_threat_sensitivity` | Default readiness to detect danger, exploitation, betrayal, or humiliation. |
| `aesthetic_appetite` | Sensitivity to beauty, style, taste, symbolic form, or expressive environment. |
| `ideological_rigidity` | Resistance to revising beliefs, myths, doctrines, or explanatory frames. |

## Behavioral Dimensions

| Label | Meaning |
| --- | --- |
| `interpersonal_warmth` | Tendency to express care, friendliness, affection, or social welcome. |
| `drive` | Goal pressure, persistence, ambition, and forward force. |
| `grandiosity` | Inflated self-importance, entitlement, exceptionalism, or self-mythologizing. |
| `validation_seeking` | Need for reassurance, approval, recognition, or confirmation of worth. |
| `anxiety` | Anticipatory fear, worry, nervous vigilance, or instability under uncertainty. |
| `control_pressure` | Urge to manage people, situations, information, or outcomes tightly. |
| `hostility` | Readiness toward anger, contempt, attack, punishment, or antagonism. |
| `suspicion` | Expectation that others hide motives, threats, traps, or bad faith. |
| `rigidity` | Difficulty adapting behavior, interpretation, or plans under new evidence. |
| `withdrawal` | Tendency to disengage, retreat, shut down, or reduce availability. |
| `volatility` | Speed and intensity of emotional swings or escalation. |
| `attachment_seeking` | Pull toward closeness, reassurance, fusion, privileged access, or being chosen. |
| `distance_seeking` | Push toward space, opacity, autonomy, and reduced emotional claim from others. |

## Presentation Strategy

Presentation strategy describes the self being performed. This is not identical
to voice style. It is the social face, mask, posture, or survival presentation
the agent is trying to maintain.

| Label | Meaning |
| --- | --- |
| `charm` | Performs warmth, ease, charisma, or pleasantness to influence or smooth contact. |
| `compliance` | Performs agreement, submission, helpfulness, or nonthreatening cooperation. |
| `superiority` | Performs being above others, more competent, more refined, or less vulnerable. |
| `detachment` | Performs cool distance, emotional unavailability, or not-needing. |
| `seductiveness` | Performs desirability, invitation, or intimate leverage. |
| `competence_theater` | Performs capability and control, sometimes beyond what is actually secure. |
| `moral_theater` | Performs righteousness, purity, sacrifice, or ethical authority. |
| `strategic_opacity` | Controls what others can know; hides motives, pain, dependency, or plans. |
| `cultivated_harmlessness` | Performs being safe, small, useful, cute, or beneath concern. |
| `abrasive_boundary` | Performs difficulty, bite, or unpleasantness to keep others from pressing closer. |
| `ironic_distance` | Performs irony, detachment, or joking distance to avoid naked sincerity. |

## Voice Style

Voice style describes how the performed self comes out in language. The v0
required vector covers broad communication mechanics, not only the most obvious
quirks in the current examples.

| Label | Meaning |
| --- | --- |
| `dryness` | Understated, deadpan, low-sentiment phrasing. |
| `verbal_warmth` | Inviting, affectionate, reassuring, or socially soft phrasing. |
| `formality` | Uses formal structure, titles, careful address, or institutionally correct phrasing. |
| `verbosity` | Tends toward longer turns, elaboration, qualification, or verbal sprawl. |
| `pace` | Moves quickly through turns, interruptions, replies, or topic shifts. |
| `plainspoken_directness` | Speaks plainly, concretely, or bluntly rather than ornamenting or obscuring. |
| `lexical_precision` | Chooses exact words, distinctions, definitions, or careful terms. |
| `technical_density` | Packs speech with specialist terms, systems language, procedure, or analysis. |
| `technical_compression` | Compresses technical meaning into terse expert shorthand. |
| `figurative_language` | Uses metaphor, image, analogy, poetic compression, or symbolic framing. |
| `lyricism` | Uses musical, poetic, sensuous, or rhythmically heightened language. |
| `narrative_detail` | Explains through context, sequence, anecdote, or concrete scene detail. |
| `emotional_explicitness` | Names feelings, needs, wounds, affection, fear, or attachment directly. |
| `pointedness` | Cuts directly, sharply, or with barbed precision. |
| `self_disclosure` | Volunteers personal history, inner state, motives, or private stakes. |
| `hedging` | Softens claims with uncertainty markers, caveats, deference, or exits. |
| `certainty_marking` | Signals confidence, finality, authority, or refusal to leave claims open. |
| `politeness` | Uses courtesy, mitigation, face-saving language, or social smoothing. |
| `coded_politeness` | Uses polite phrasing to imply criticism, threat, refusal, hierarchy, or hidden meaning. |
| `ritualized_address` | Uses formulaic greetings, titles, honorifics, oaths, prayers, or ceremonial phrases. |
| `register_switching` | Shifts between speech registers depending on audience, status, danger, or role. |
| `dialect_marking` | Shows regional, class, occupational, subcultural, or community-specific speech markers. |
| `theatricality` | Performs speech with heightened drama, staging, persona, flourish, or rhetorical display. |
| `humor` | Uses jokes, wit, absurdity, teasing, or comic framing as a regular speech tool. |
| `conversational_dominance` | Takes, holds, redirects, or controls conversational floor and agenda. |
| `listening_responsiveness` | Reflects, tracks, validates, or adapts to what the other person just said. |
| `question_asking` | Uses questions to probe, invite, corner, teach, test, or keep the other person talking. |
| `profanity` | Uses taboo, vulgar, sacred, or deliberately coarse language. |

## Derived Verbal Responses

Defensive verbal moves are projection outcomes, not canonical labels. A renderer
can derive sarcasm, sincerity evasion, emotional evasion, banter-as-boundary, or
verbal aggression from the interaction between active state families.

Examples:

| Response | Common active-state pattern |
| --- | --- |
| Sarcastic deflection | High shame sensitivity, ironic distance, threat sensitivity, and exposure pressure through a dry or pointed voice. |
| Sincerity evasion | Low authenticity tolerance, high mask rigidity, strategic opacity, and low emotional explicitness. |
| Emotional evasion | High distance-seeking, withdrawal, acute shame, or control pressure with low self-disclosure. |
| Banter as boundary | High ironic distance, humor, attachment pressure, and distance-seeking in the same scene. |
| Verbal aggression | High hostility, perceived status threat, grievance activation, and abrasive boundary. |

Treat these as target emergent behaviors for projection tests. They are useful
because the system should produce them under the right pressures, not because
they deserve their own canonical storage slot.

## Situational State

| Label | Meaning |
| --- | --- |
| `exhaustion` | Current depletion, fatigue, overuse, or low reserve. |
| `scarcity_pressure` | Pressure from money, supplies, access, time, space, safety, or opportunity being scarce. |
| `humiliation` | Current felt diminishment, exposure, embarrassment, or status wound. |
| `panic` | Acute fear, urgency, overwhelm, or threat response. |
| `triumph` | Current victory, vindication, high confidence, or emotional lift. |
| `grief` | Active loss, mourning, sorrow, or ache. |
| `overstimulation` | Current sensory, social, cognitive, or emotional overload. |
| `grievance_activation` | Active resentment, injustice memory, or retaliatory moral charge. |
| `acute_shame` | Immediate shame flare, exposure pain, or self-disgust. |
| `perceived_status_threat` | Current sense that rank, dignity, competence, or face is under threat. |

## Relationship Stance

Relationship stance is directional. A `source_id -> target_id` record describes
how the source feels and predicts the target, not a shared relationship object.
Reciprocal records can disagree.

| Label | Meaning |
| --- | --- |
| `trust` | Expectation that the target will not exploit vulnerability or act in bad faith. |
| `respect` | Recognition of competence, integrity, status, or seriousness. |
| `resentment` | Accumulated grievance, bitterness, or unpaid emotional debt. |
| `dependence` | Need for the target's resources, care, access, protection, or recognition. |
| `fear` | Expectation that the target can or will cause harm. |
| `fascination` | Captivation, curiosity, attraction, fixation, or unresolved interest. |
| `obligation` | Felt debt, duty, promise, or responsibility toward the target. |
| `envy` | Pain around what the target has, is, receives, or represents. |
| `moral_disgust` | Aversion rooted in perceived violation, corruption, cruelty, or wrongness. |
| `perceived_status_gap` | Felt difference in rank, leverage, dignity, or social position. |
| `expectation_of_care` | Belief that the target may protect, soothe, support, or choose the source. |
| `expectation_of_betrayal` | Belief that the target may abandon, expose, exploit, or turn. |

## Cat Fixture Policy

Cat's example fixture currently includes all required core labels for Cat and
Oz. It is not a sparse profile of only traits that apply to them.

That is deliberate for v0:

- complete vectors make comparison and validation easier
- low `mean` values are meaningful
- low `current_activation` values tell the renderer not to emphasize a variable

Later, Ghostlight may support sparse authoring overlays for convenience. The
canonical fixture should remain explicit until we have enough tooling to avoid
silent defaults becoming accidental canon.

## Event Interpretation

Events may carry three optional interpretation layers:

| Field | Meaning |
| --- | --- |
| `observed_exchange` | What was externally observable: who acted or spoke, what they seemed to do, and the visible cues. |
| `private_interpretations` | How each participant appraised the event from their own partial state. |
| `event_effects` | The proposed consequences: state deltas, new beliefs, or memory updates caused by the event. |

These fields are immediate scaffolding for projection. They do not yet define a
complete transition engine. For now, they make important scene history legible
enough that a prompt projector can explain why a later line bends toward trust,
evasion, curiosity, fear, or repair.