Tighten agent state schema from evaluation

docs/architecture/agent-state-distributions-and-prompt-projection.md

@@ -1,4 +1,4 @@
-# Agent State Distributions And Prompt Projection
+# Agent State Distributions And Prompt Projection
 
 This note describes how personality, culture, memory, and social context should
 be represented in structured state, and how that state should be projected into
@@ -69,7 +69,7 @@ These are relatively persistent tendencies:
 These are first-class, not optional garnish. They belong in the rebuild from
 the start:
 
-- warmth
+- interpersonal warmth
 - drive
 - grandiosity
 - validation-seeking
@@ -110,7 +110,7 @@ machinery.
 These describe how the performed self comes out in language:
 
 - dryness
-- warmth
+- verbal warmth
 - formality
 - verbosity
 - pace

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

@@ -63,6 +63,11 @@ 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,
@@ -110,7 +115,7 @@ schema becomes a junk drawer with a badge.
 
 | Label | Meaning |
 | --- | --- |
-| `warmth` | Tendency to express care, friendliness, affection, or social welcome. |
+| `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. |
@@ -153,7 +158,7 @@ quirks in the current examples.
 | Label | Meaning |
 | --- | --- |
 | `dryness` | Understated, deadpan, low-sentiment phrasing. |
-| `warmth` | Inviting, affectionate, reassuring, or socially soft 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. |
@@ -251,3 +256,18 @@ That is deliberate for v0:
 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.

docs/architecture/canonical-agent-state-schema.md

@@ -110,7 +110,7 @@ Human beings are regrettably efficient little porcupines.
 The required voice handles are:
 
 - `dryness`
-- `warmth`
+- `verbal_warmth`
 - `formality`
 - `verbosity`
 - `pace`
@@ -138,6 +138,13 @@ The required voice handles are:
 - `question_asking`
 - `profanity`
 
+Behavioral warmth and verbal warmth are intentionally separate:
+
+- `behavioral_dimensions.interpersonal_warmth` is the tendency to offer care,
+  welcome, or affiliation.
+- `voice_style.verbal_warmth` is the language surface that can sound soft,
+  reassuring, affectionate, or socially inviting.
+
 So Cat's prickliness is not only a dialogue prompt instruction. It is backed by
 canonical state:
 
@@ -171,15 +178,27 @@ An overlay records:
 - distortions
 
 This is where misunderstanding lives. Suspicious agents can overread threat.
-Attachment-hungry agents can overread warmth. Avoidant agents can underread
-care. Fundamental attribution bias also lives here: an observer can mistake
-exceptional behavior for stable character. None of that requires corrupting the
-canonical state.
+Attachment-hungry agents can overread interpersonal warmth. Avoidant agents can
+underread care. Fundamental attribution bias also lives here: an observer can
+mistake exceptional behavior for stable character. None of that requires
+corrupting the canonical state.
 
 Relationship stance is directional. If Cat has a relationship record toward Oz,
 Oz needs a separate record toward Cat. Mutual presence does not imply symmetric
 trust, fear, obligation, dependence, or expectation of betrayal.
 
+## Event Interpretation
+
+Events can include optional interpretation scaffolding:
+
+- `observed_exchange` for externally visible action or dialogue
+- `private_interpretations` for each participant's appraisal of what happened
+- `event_effects` for proposed state deltas, belief creation, and memory updates
+
+This is not a full social transition engine yet. It is enough structure for the
+projection layer to know what an event changed without asking later prompts to
+infer everything from a one-line summary and a bad attitude.
+
 ## Dialogue Context Packs
 
 Scenes contain `dialogue_context_packs`.

docs/architecture/prompt-projection-contract.md

@@ -156,8 +156,9 @@ person behind the drone while pretending she is only annoyed about the repair.
 If Oz gets too close to her fear of dependency, Cat is likely to answer the
 practical issue and make the emotional issue sound stupid.
 
-Voice for this turn: dry, quick, pointed, plainspoken, low warmth, low emotional
-explicitness, some profanity. Humor can appear as a boundary, not as friendliness.
+Voice for this turn: dry, quick, pointed, plainspoken, low verbal warmth, low
+emotional explicitness, some profanity. Humor can appear as a boundary, not as
+friendliness.
 ```
 
 Possible generated behavior:
@@ -191,8 +192,8 @@ redirect toward the immediate repair or answer in a way that preserves the mask
 without making the evasion look like panic.
 
 Voice for this turn: controlled, concise, technically precise, gently polite,
-low emotional explicitness, careful warmth, frequent hedging when the subject
-approaches the operator.
+low emotional explicitness, careful verbal warmth, frequent hedging when the
+subject approaches the operator.
 ```
 
 Possible generated behavior:

docs/architecture/schema-future-mechanisms.md

@@ -0,0 +1,147 @@
+# Future Schema Mechanisms
+
+This note parks the useful pressure from `notes/evaluation.md` without treating
+that critique as doctrine. The current v0 schema is still a character-state and
+prompt-projection seam. The future runtime needs mechanisms that turn state into
+changing social behavior.
+
+## Current Boundary
+
+The v0 agent-state schema should stay focused on:
+
+- canonical character state
+- directional relationship stance
+- observer-local perceived overlays
+- memories, goals, values, and scene-local dialogue packs
+- enough event interpretation to support prompt projection
+
+Do not inflate `schemas/agent-state.schema.json` into the whole simulator before
+the projection examples prove what the runtime actually needs.
+
+## Mechanisms To Preserve For Later
+
+### Event Appraisal
+
+Each participant needs a private read of the same event. A single exchange can
+be betrayal to one agent, exposure risk to another, and flirting-with-knives to
+a third. The current schema now allows `private_interpretations` on events as a
+lightweight bridge.
+
+Future work should make appraisal reusable enough to drive state updates,
+memory retrieval, and action affordances.
+
+### State Transitions And Consequences
+
+`mean`, `plasticity`, and `current_activation` describe state. They do not yet
+define how state changes. Future transition machinery needs:
+
+- activation decay
+- event-driven deltas
+- sensitization or habituation
+- effects on related variables
+- rules for when `mean` changes versus only `current_activation`
+
+The current `event_effects` field is a projection-facing placeholder, not the
+final transition engine.
+
+### Structured Beliefs And Secrets
+
+String beliefs are useful for authoring, but simulation needs structure:
+
+- holder
+- subject
+- claim type
+- confidence
+- evidence
+- visibility
+- emotional charge
+- whether the belief is private, shared, public, rumor, false, or contested
+
+Secrets need similar structure: owner, known-by, suspected-by, exposure cost,
+protective strategies, and what can leak through action.
+
+### Action Affordances
+
+The system needs to choose among possible moves instead of jumping from state to
+dialogue. Future projection examples should expose candidate affordances such
+as probing, evading, bargaining, softening, escalating, repairing, threatening,
+or walking away.
+
+The important rule: affordances should be justified by goals, appraisals,
+capabilities, costs, relationship stance, and scene pressure.
+
+### Conversation State
+
+Dialogue needs explicit continuity:
+
+- active topic
+- open questions
+- evasions
+- accusations
+- face-threats
+- commitments
+- promises, refusals, and ruptures
+- who has the floor
+
+This belongs close to projection because it changes turn shape immediately.
+
+### Resources And Capabilities
+
+Cat's debt, taxi condition, mobility, and institutional exposure are not just
+backstory. Oz's drone integrity, signal secrecy, anonymity, and physical safety
+are not just flavor. Future schemas need concrete resource and capability
+fields so desire does not masquerade as ability.
+
+### Dyads And Shared Relationship History
+
+Directional relationship stance should remain. A separate dyadic layer may also
+be needed for shared history:
+
+- relationship type
+- phase
+- shared events
+- shared secrets
+- unresolved ruptures
+- rituals
+- dependency structure
+- communication pattern
+
+Do not collapse this into one symmetric relationship object. People are not
+that tidy unless the author is lying to save RAM.
+
+### Social Knowledge, Reputation, And Institutions
+
+The Aetheria setting needs institutions with teeth: sanctions, authority,
+surveillance, reputation effects, access control, role expectations, and public
+knowledge. Future work should distinguish private belief, shared belief, public
+fact, rumor, common knowledge, and institutional record.
+
+### Memory Retrieval
+
+Memories need more than salience and confidence once the runtime starts moving:
+
+- recency
+- emotional charge
+- retrieval triggers
+- decay
+- reconsolidation
+- intrusive, avoided, cherished, rehearsed, or distorted status
+- schema effects
+- whether another agent knows the memory
+
+The current memory bundle is enough for the first projection seam. It is not yet
+the memory engine.
+
+### Embodiment And Nonverbal Channels
+
+Oz proves this one immediately. The operator, drone body, observable channels,
+leakage risks, and physical affordances are separate facts. Future projection
+needs embodiment because social meaning leaks through movement, timing,
+silence, distance, posture, and constrained bodies.
+
+## Promotion Rule
+
+Promote a future mechanism into the main schema only after it has survived at
+least one reviewed projection example or runtime slice where it clearly changes
+the output. Until then, document it here, test it in examples, and do not let
+the ontology grow antlers for sport.