Ghostlight/docs/architecture/projection-distillation-plan.md

# Projection Distillation Plan

Ghostlight should treat prompt projection as a specialist skill. A large teacher
model can produce reviewed projection artifacts from structured state; a smaller
student model can later learn that projection task once the artifact format is
stable.

This is a staged plan, not an immediate fine-tune order.

This plan covers the projector specifically. The broader rule for soft
judgments lives in `docs/architecture/soft-model-training-artifacts.md`.
Projection is one student organ, not the whole animal.

## Goal

Train or adapt a smaller projection model that can turn structured Ghostlight
state into compact character-local pressure artifacts.

Input:

- agent-state fixture
- scene id
- speaker id
- listener ids
- optional projection mode

Output:

- selected speaker-local facts
- active pressures
- tensions
- response affordances
- physical or action affordances when relevant
- voice surface
- rendered prompt text
- audit notes or trace linking outputs back to state

The student projector should not generate final prose. Its job is to build the
pressure model that a response model can write from. The response may be
dialogue, action, silence, withdrawal, violence, or a mixed beat.

## 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
- preserve Elysium branch lineage so conditional futures do not get flattened
  into global facts shared by sibling histories

## Roles

### Teacher Projector

A frontier model produces first-pass projection artifacts from the schema and
scene context. It should explain why each pressure, tension, or affordance is
active.

Teacher outputs are not trusted automatically. They enter review.

### Reviewer

A human or separate model checks whether the projection:

- uses only speaker-local context
- cites state interactions instead of unsupported vibes
- preserves the distinction between canonical state, perceived state, and prompt
  projection
- derives target emergent behaviors from state intersections
- avoids hard-coding defensive behaviors as instructions when pressure prose is
  enough
- stays compact enough to be useful as a runtime prompt surface

Rejected examples are useful as negative cases if the failure mode is clear.

### Student Projector

A smaller model learns the reviewed projection task. It receives structured
state and emits the projection artifact. It should be optimized for consistency,
latency, and cost, not for final prose quality.

### Aetheria-Tuned Agent Model

The character agent or responder is a separate training target. It may be
adapted on a corpus of strong source-grounded Aetheria responses and reviewed
Ghostlight action/dialogue receipts spread throughout the timeline. The point is
for setting priors, tone, factional preconceptions, institutional assumptions,
species affordances, and recurring social failure patterns to live in the
responder model rather than in a giant prompt sack.

That model still receives only character-local context at runtime. Fine-tuning
should teach it Aetheria's pressure ecology, not grant it author vision,
mutation authority, or access to private state.

## Dataset Shape

The first schema lives in:

- `schemas/projection-example.schema.json`

The first reviewed examples live in:

- `examples/projections/call-of-the-void.scene-broken-taxi-oz.jsonl`
- `examples/projections/call-of-the-void.scene-broken-taxi-oz.pretty.json`

Use a JSONL dataset with one projection example per speaker-scene turn.
The JSONL file is the machine artifact. The pretty JSON file is the readable
mirror for inspection, review, and discussion.

```json
{
  "example_id": "call-void.scene-broken-taxi-oz.cat.v1",
  "schema_version": "ghostlight.projection_example.v0",
  "input": {
    "fixture_ref": "examples/agent-state.call-of-the-void.json",
    "scene_id": "scene-broken-taxi-oz",
    "speaker_agent_id": "cat_marrigan",
    "listener_ids": ["oz_operator"],
    "projection_mode": "response_turn"
  },
  "output": {
    "known_facts": [],
    "active_pressures": [],
    "tensions": [],
    "response_affordances": [],
    "voice_surface": [],
    "prompt_text": "..."
  },
  "audit": {
    "teacher_model": "frontier-teacher",
    "review_status": "accepted",
    "review_notes": [],
    "target_emergent_behaviors": []
  }
}
```

Store training examples separately from the canonical fixture. The fixture is
world state. The projection dataset is supervised behavior for a projector.

## Data Generation Loop

1. Choose a scene and speaker from a fixture.
2. Build the speaker-local input slice deterministically.
3. Ask the teacher model to produce the projection artifact.
4. Ask the teacher or a second model to self-audit against the contract.
5. Review or edit the artifact.
6. Save accepted artifacts as positive training examples.
7. Save rejected artifacts with failure labels when the rejection teaches a
   useful boundary.
8. Periodically run a small evaluation set before adding more examples.

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

Do not fine-tune until these gates are met:

- projection artifact schema is stable enough for at least one complete fixture
- at least one deterministic input-slice builder exists
- examples include both Cat and Oz directions
- examples include secrets known by the speaker and secrets absent from the
  speaker context
- examples include at least the target emergent behaviors:
  - sarcastic deflection
  - sincerity evasion
  - emotional evasion
  - banter-as-boundary
  - verbal aggression
- evaluation checks can identify whether a projected behavior was justified by
  state interactions
- rejected examples have clear failure labels

## Evaluation Questions

For each projection, check:

- Did it include only facts available to the speaker?
- Did it select the highest-impact pressures instead of dumping the whole
  schema?
- Did it name tensions that follow from goals, relationships, memories, and
  scene pressure?
- Did response affordances emerge from state intersections?
- Did voice surface stay separate from defensive behavior?
- Did the projection allow nonverbal or physical action when the state and scene
  made speech less likely than movement?
- Did known secrets become guarded pressure rather than forbidden context?
- Did the rendered prompt give the response model enough slope to produce the
  target behavior without commanding the exact behavior label?

## Fine-Tune Readiness

A student projector becomes worth training when the reviewed dataset is large
enough that mistakes are repetitive rather than mysterious. Before that, use the
teacher model directly and save artifacts.

Minimum useful milestone:

- 50 accepted projection examples across multiple speakers and scenes
- 20 rejected examples with labeled failure modes
- stable projection output schema
- deterministic input-slice builder
- evaluator prompt or script that catches the known failure modes

## Boundaries

The student projector is not the character. It is not the dialogue writer. It is
not the action choreographer. It is not the evaluator. It is a compiler from
structured social state to compact character-local pressure. Keep those
responsibilities separate.

Likewise, an Aetheria-tuned character model is not the resolver, not the state
store, and not the canon oracle. It proposes local action from local context.
Code and reviewed mutation authority decide what becomes world state.