Document Aetheria lore grounding architecture

docs/architecture/aetheria-lore-grounding-architecture.md

@@ -0,0 +1,166 @@
+# Aetheria Lore Grounding Architecture
+
+Ghostlight needs two different Aetheria modes:
+
+- grounded historical training
+- procedural Elysium generation
+
+Do not blur them. That is how a useful mystery becomes accidental canon with a
+badge and a clipboard.
+
+## Core Boundary
+
+Planned Aetheria gameplay takes place in Elysium. What happens there is
+intentionally not fully fixed in the lore vault because discovering and shaping
+that history is part of the games themselves.
+
+The Aetheria timeline begins when humanity is transplanted into Elysium. It can
+restart when humanity destroys itself again through negligence, greed,
+institutional capture, civilizational momentum, and the familiar psychological
+trash fire wearing a crown.
+
+That means Elysium-era gameplay scenes are not the best first source for
+grounded Ghostlight training data. They are downstream procedural territory.
+
+For grounded training data, Ghostlight should start from the authored historical
+archive: late Sol, Pre-Elysium institutions, factional flashpoints, personhood
+conflicts, labor regimes, political collapse, and the FTL trigger.
+
+## Revised Architecture
+
+Grounded historical training flow:
+
+```text
+Aetheria authored historical lore
+  -> lore grounding digest
+  -> historical scene fixture
+  -> agent-state fixture
+  -> speaker-local input slice
+  -> projection artifact
+  -> prompt_text
+  -> generated dialogue or drama
+  -> reviewed training example
+```
+
+Procedural Elysium flow:
+
+```text
+grounded pre-Elysium priors
+  -> procedural Elysium branch state
+  -> Ghostlight agents and institutions
+  -> projected dialogue and drama
+  -> simulated branch history
+  -> optional promoted canon after review
+```
+
+The first flow teaches the projector what grounded social pressure looks like.
+The second flow uses that learned machinery to generate Elysium outcomes
+without pretending those outcomes were already settled lore.
+
+## Source Priority
+
+For projection training, prefer sources in this order:
+
+1. Authored historical lore with explicit institutional, social, and political
+   context.
+2. Grounded transition material around the FTL trigger and displacement.
+3. Historical fiction or scene fragments that remain canon-compatible.
+4. Elysium-era procedural fixtures marked as provisional branch material.
+
+Call of the Void and Cat/Oz can remain useful for testing projection mechanics,
+speaker-local boundaries, and prompt shape. They should not be treated as the
+primary grounded training corpus unless the relevant Elysium branch facts are
+intentionally authored or promoted.
+
+## Historical Flashpoint Candidates
+
+Good first fixtures should come from parts of Aetheria that are already
+pressure-dense and source-grounded:
+
+- contract citizenship and debt regimes
+- labor-system enforcement and infrastructure dependency
+- upload abuse and contested personhood
+- uplift or nonhuman personhood conflicts
+- algorithmic governance and predictive policing
+- corporate blocs turning infrastructure into leverage
+- the FTL program as a political escape hatch from Sol's failure
+- the moment around the FTL trigger, where institutions and people discover
+  that escape did not mean absolution
+
+The best scenes are small, local, and socially loaded:
+
+- a worker negotiating dangerous contract terms
+- an upload arguing over continuity, ownership, or service denial
+- a technician asked to sign off on an unsafe FTL dependency
+- a debtor deciding whether help is relief or capture
+- an institutional agent performing compassion while enforcing a machine
+- a family, crew, or workplace discovering that political collapse has become
+  intimate
+
+## Lore Grounding Digests
+
+Before producing training projection examples from a historical flashpoint,
+create a lore grounding digest.
+
+A digest should include:
+
+- source files and relevant line or section notes
+- time period
+- location or institution
+- involved factions, classes, and roles
+- material constraints
+- local norms, taboos, and scripts
+- vocabulary or speech-register cues
+- what each speaker plausibly knows
+- what each speaker misreads
+- author-only context that must not enter prompt text
+- open questions needing lore elaboration
+
+The digest is not a replacement for the lore vault. It is a compiled working
+slice for one fixture, so projection examples can cite grounded pressure
+without dragging the whole archive into every prompt.
+
+## Fixture Types
+
+Use explicit fixture status:
+
+- `historical_grounded`
+- `transition_grounded`
+- `procedural_branch`
+- `promoted_branch`
+
+`historical_grounded` and `transition_grounded` examples can become primary
+training data.
+
+`procedural_branch` examples are useful for testing and generation but should
+not train the projector as if they were fixed lore.
+
+`promoted_branch` examples are procedural outputs that have been reviewed and
+accepted into canon or into a specific authored continuity.
+
+## Projection Rules
+
+Grounded projection examples should prove:
+
+- the prompt text is self-sufficient for the dialogue model
+- setting and institutional context are speaker-local
+- historical pressure appears as lived constraint, not exposition paste
+- the speaker does not know author-only future outcomes
+- the generated behavior follows from state, culture, memory, relationship, and
+  material pressure
+
+If the lore source is too vague for a convincing scene, stop and elaborate the
+lore slice first. Do not train the model to pave over missing social reality
+with confident fog.
+
+## Immediate Plan
+
+1. Keep the Cat/Oz fixture as an Elysium procedural mechanics fixture.
+2. Add a lore grounding digest format.
+3. Choose one authored historical flashpoint from the Aetheria archive.
+4. Build the first `historical_grounded` agent-state fixture from that slice.
+5. Produce reviewed projection examples from that fixture.
+6. Compare those examples against Cat/Oz to separate grounded historical
+   pressure from procedural Elysium branch generation.
+
+Ground the machine in the past. Let it hallucinate the future under supervision.

docs/architecture/projection-distillation-plan.md

@@ -33,6 +33,25 @@ Output:
 The student projector should not generate final dialogue. Its job is to build
 the pressure model that a dialogue model can write from.
 
+## Aetheria Training Boundary
+
+For Aetheria, grounded projection training should come primarily from authored
+historical lore rather than from Elysium gameplay-era scenes.
+
+Elysium gameplay content is intentionally malleable: the games discover and
+generate what happens there. Projection examples set inside Elysium should be
+marked as procedural branch material unless their branch facts have been
+explicitly promoted.
+
+Use `docs/architecture/aetheria-lore-grounding-architecture.md` for the
+grounding plan. In short:
+
+- train from historical flashpoints with strong lore grounding
+- use Elysium fixtures like Cat/Oz to test projection mechanics and procedural
+  branch generation
+- do not let a training dataset accidentally canonize Elysium outcomes that are
+  supposed to be generated by the systems
+
 ## Roles
 
 ### Teacher Projector
@@ -122,9 +141,13 @@ world state. The projection dataset is supervised behavior for a projector.
    useful boundary.
 8. Periodically run a small evaluation set before adding more examples.
 
-The first loop should use the Call of the Void fixture because it already has
-Cat, Oz, reciprocal relationship stance, perceived overlays, hidden stakes, and
-speaker-local dialogue packs.
+The Cat/Oz Call of the Void fixture remains useful as the first projection
+mechanics fixture because it already has reciprocal relationship stance,
+perceived overlays, hidden stakes, and speaker-local dialogue packs. It should
+not be treated as the first grounded Aetheria lore-training fixture.
+
+The first grounded training loop should use a historical Aetheria flashpoint
+from the authored lore archive.
 
 ## Evaluation Gates
 
@@ -179,11 +202,14 @@ Minimum useful milestone:
 1. Define `schemas/projection-example.schema.json`. Done.
 2. Add `examples/projections/call-of-the-void.scene-broken-taxi-oz.jsonl` with
    the first reviewed Cat and Oz examples. Done.
-3. Add a deterministic projection input-slice tool that reads the agent-state
+3. Add a lore grounding digest format for historical Aetheria projection
+   fixtures.
+4. Choose the first authored historical flashpoint for grounded training.
+5. Add a deterministic projection input-slice tool that reads the agent-state
    fixture and emits speaker-local input JSON.
-4. Add a teacher prompt template for producing projection artifacts.
-5. Add an evaluator prompt template for projection audits.
-6. Only then consider student fine-tuning.
+6. Add a teacher prompt template for producing projection artifacts.
+7. Add an evaluator prompt template for projection audits.
+8. Only then consider student fine-tuning.
 
 ## Boundaries
 

notes/fresh-workspace-handoff.md

@@ -40,6 +40,8 @@ Ghostlight now has the persistence spine plus the first architecture payload:
   - `docs/architecture/projection-distillation-plan.md`
 - evaluation follow-up docs:
   - `docs/architecture/schema-future-mechanisms.md`
+- Aetheria lore grounding docs:
+  - `docs/architecture/aetheria-lore-grounding-architecture.md`
 - first projection example seam:
   - `schemas/projection-example.schema.json`
   - `examples/projections/call-of-the-void.scene-broken-taxi-oz.jsonl`
@@ -66,8 +68,13 @@ state unless explicitly revived.
 
 ## Current Next Action
 
-Build the deterministic projection input-slice tool that reads the Call of the
-Void fixture and emits speaker-local input JSON for one scene/speaker pair.
+Define the lore grounding digest format for historical Aetheria projection
+fixtures, then use it to choose the first authored historical flashpoint for
+grounded training.
+
+Cat/Oz remains useful as an Elysium procedural mechanics fixture, but grounded
+training data should start from authored historical lore rather than gameplay
+era Elysium outcomes.
 
 The evaluation follow-up fixed the immediate v0 schema issues:
 
@@ -85,6 +92,8 @@ Completed projection path items:
 
 Remaining projection path:
 
+- add a lore grounding digest format for historical Aetheria fixtures
+- choose the first authored historical flashpoint for grounded training
 - build a deterministic speaker-local input slicer
 - use a frontier teacher model to generate/audit projection artifacts
 - train a smaller student projector only after the artifact schema, input

notes/ghostlight-current-system-map.md

@@ -49,6 +49,9 @@ state and re-entry discipline.
   - parking lot for appraisal, transition, belief, action, conversation,
     resource, dyad, institution, memory, and embodiment mechanisms not yet
     promoted into the v0 schema
+- `docs/architecture/aetheria-lore-grounding-architecture.md`
+  - boundary and plan for grounding training data in authored Aetheria history
+    while treating Elysium gameplay-era outcomes as procedural branch space
 - `schemas/agent-state.schema.json`
   - v0 canonical agent-state contract for agents, relationships, events,
     scenes, perceived overlays, and dialogue context packs
@@ -78,6 +81,7 @@ state and re-entry discipline.
 - a classifier pipeline
 - a prompt renderer
 - a full projection training corpus
+- a lore grounding digest format
 - a deterministic projection input slicer
 - a student projection model
 - a simulation/event loop
@@ -85,6 +89,7 @@ state and re-entry discipline.
 - a culture prior engine
 
 The canonical agent-state schema and first projection example schema now exist
-as v0 seams. The next implementation target is the deterministic input slicer
-that emits speaker-local state before a renderer turns that state into compact
-pressure prose.
+as v0 seams. The next implementation target is a lore grounding digest format
+for historical Aetheria training fixtures, followed by the deterministic input
+slicer that emits speaker-local state before a renderer turns that state into
+compact pressure prose.

notes/ghostlight-implementation-plan.md

@@ -36,11 +36,16 @@
 4. Build the projection distillation loop. Started.
    - Use `docs/architecture/projection-distillation-plan.md` as the teacher to
      student roadmap.
+   - Use `docs/architecture/aetheria-lore-grounding-architecture.md` to keep
+     Aetheria grounded training separate from procedural Elysium branch
+     generation.
    - Maintain `schemas/projection-example.schema.json`,
      `examples/projections/`, and `tools/validate_projection_examples.py` as
      the first reviewed artifact seam.
+   - Use authored historical Aetheria flashpoints, not malleable Elysium
+     gameplay outcomes, as the first grounded lore-training corpus.
    - Use a frontier teacher model to produce reviewed projection artifacts from
-     structured state.
+     structured state and lore grounding digests.
    - Save accepted and rejected projection examples as supervised data.
    - Train or adapt a smaller student projector only after the artifact schema,
      input slicer, and evaluator are stable.
@@ -56,6 +61,9 @@
 6. Build the first Aetheria authoring consumer.
    - use the Call of the Void slice described in `AetheriaLore` as the first
      concrete content-generation context
+   - treat Call of the Void and other Elysium gameplay-era fixtures as
+     procedural branch material unless specific outcomes are explicitly
+     promoted
    - support dialogue scaffolding and procedural drama for narrated stories
      across the Aetheria timeline
    - do not treat an older corridor-crisis game slice as the implementation

state/evidence.jsonl

@@ -22,3 +22,4 @@
 {"ts": "2026-05-01T19:57:04+00:00", "type": "design", "status": "accepted", "note": "Evaluation follow-up accepted immediate schema fixes: split interpersonal_warmth from verbal_warmth, add Cat perception of Oz, populate Cat/Oz relationship summaries, enrich event-drone-lie with observed exchange, private interpretations, and event effects, and park broader social-simulation mechanisms in docs/architecture/schema-future-mechanisms.md."}
 {"ts": "2026-05-01T20:02:29+00:00", "type": "implementation", "status": "accepted", "note": "Added ghostlight.projection_example.v0 schema, first reviewed Cat/Oz projection JSONL examples for scene-broken-taxi-oz, projection example validator, and package scripts that validate both agent-state and projection seams. Next projection implementation step is deterministic speaker-local input slicing."}
 {"ts": "2026-05-01T20:19:04+00:00", "type": "design", "status": "accepted", "note": "Projection prompt_text must be self-sufficient for the dialogue model: include speaker-local setting, historical, cultural, socioeconomic, and embodiment context needed for the turn rather than relying on source refs or the full projection artifact."}
+{"ts": "2026-05-01T20:31:43+00:00", "type": "design", "status": "accepted", "note": "Revised Aetheria projection-training architecture: grounded training data should start from authored historical lore flashpoints, while Elysium gameplay-era scenes such as Cat/Oz are procedural branch material unless explicitly promoted. Next step is a lore grounding digest format and first historical flashpoint selection."}

state/map.yaml

@@ -26,6 +26,7 @@ constraints:
   - Reuse proven machinery where it fits before inventing ornate nonsense.
   - Do not treat an older corridor-crisis game slice as the active Ghostlight implementation target.
   - Do not use the obsolete Call of the Void colony-fleet return-home twist; current Aetheria canon sequesters the whole Solar system into Elysium.
+  - Do not treat malleable Elysium gameplay-era outcomes as fixed lore for grounded training data unless a branch outcome is explicitly promoted.
 
 invariants:
   - The map is canonical and slow-changing.
@@ -36,6 +37,7 @@ invariants:
   - Personality must be modeled as layered organization, presentation, and situational activation, not just one bag of labels.
   - Authoring outputs must remain explainable in terms of state, relationship, pressure, memory, and goals.
   - Dialogue generation should be character-local: each prompt should restrict context to what the speaking character knows, feels, wants, remembers, hides, and perceives.
+  - Aetheria grounded training data should come from authored historical lore; procedural Elysium scenes are branch material until reviewed or promoted.
 
 data_flow:
   observe:
@@ -61,6 +63,7 @@ active_subgoals:
   - Define how culture shapes priors, incentives, masks, and economic behavior without turning populations into clones.
   - Define the boundary between canonical signal, perceived signal, and prompt projection.
   - Support content generation for the Call of the Void slice in AetheriaLore and dialogue scaffolding or procedural drama for narrated Aetheria timeline stories.
+  - Ground projection training in authored Aetheria historical flashpoints before using Ghostlight to generate Elysium branch history.
 
 accepted_design:
   - Ghostlight owns the deeper agent-state, personality, culture, relationship, and prompt-projection architecture; other projects can remain consumers instead of shrines.
@@ -87,7 +90,8 @@ accepted_design:
   - Events can carry lightweight observed exchange, private interpretation, and event-effect scaffolding so prompt projection can reason from appraisal and consequence without pretending the v0 schema is already a full transition engine.
   - Future social-simulation mechanisms should be documented and tested through projection artifacts before promotion into the canonical schema.
   - Projection examples use `ghostlight.projection_example.v0` JSONL records with traceable known facts, active pressures, tensions, response affordances, voice surface, rendered prompt text, and audit checks.
+  - Aetheria projection training has two modes: historical grounded fixtures from authored lore, and procedural Elysium branch fixtures that test generation without canonizing gameplay-era outcomes.
 
 current_status:
-  summary: Ghostlight now has the Epiphany-style persistence spine, the first architecture payload, the v0 canonical agent-state schema seam, prompt projection docs, immediate schema fixes from evaluation, first reviewed Cat/Oz projection examples, and a documented teacher/student distillation path for projection.
-  next_action: Build the deterministic projection input-slice tool that reads the Call of the Void fixture and emits speaker-local input JSON for one scene/speaker pair.
+  summary: Ghostlight now has the Epiphany-style persistence spine, the first architecture payload, the v0 canonical agent-state schema seam, prompt projection docs, immediate schema fixes from evaluation, first reviewed Cat/Oz projection examples, a revised Aetheria lore-grounding architecture, and a documented teacher/student distillation path for projection.
+  next_action: Define the lore grounding digest format for historical Aetheria projection fixtures, then choose the first authored historical flashpoint for grounded training.