From e4ccbb0521153e4109a09b3e21ef91e66df6e077 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Fri, 1 May 2026 21:39:00 +0100 Subject: [PATCH] Add lore grounding digest seam --- .../aetheria-lore-grounding-architecture.md | 21 +- .../lore-grounding-digest-format.md | 264 ++++++++++ .../projection-distillation-plan.md | 2 +- .../historical-flashpoint.template.json | 215 ++++++++ notes/fresh-workspace-handoff.md | 13 +- notes/ghostlight-current-system-map.md | 20 +- notes/ghostlight-implementation-plan.md | 3 + package.json | 5 +- schemas/lore-grounding-digest.schema.json | 490 ++++++++++++++++++ state/evidence.jsonl | 1 + state/map.yaml | 5 +- tools/validate_lore_grounding.py | 211 ++++++++ 12 files changed, 1234 insertions(+), 16 deletions(-) create mode 100644 docs/architecture/lore-grounding-digest-format.md create mode 100644 examples/lore-grounding/historical-flashpoint.template.json create mode 100644 schemas/lore-grounding-digest.schema.json create mode 100644 tools/validate_lore_grounding.py diff --git a/docs/architecture/aetheria-lore-grounding-architecture.md b/docs/architecture/aetheria-lore-grounding-architecture.md index 98d6e43..9da08b8 100644 --- a/docs/architecture/aetheria-lore-grounding-architecture.md +++ b/docs/architecture/aetheria-lore-grounding-architecture.md @@ -102,6 +102,12 @@ The best scenes are small, local, and socially loaded: Before producing training projection examples from a historical flashpoint, create a lore grounding digest. +The digest format is defined in: + +- `docs/architecture/lore-grounding-digest-format.md` +- `schemas/lore-grounding-digest.schema.json` +- `examples/lore-grounding/historical-flashpoint.template.json` + A digest should include: - source files and relevant line or section notes @@ -116,6 +122,19 @@ A digest should include: - author-only context that must not enter prompt text - open questions needing lore elaboration +It should also include cultural and factional pressure fields: + +- internal virtues +- internal shames +- prestige markers +- taboo triggers +- emotional display norms +- trust defaults +- speech register cues +- outsider stereotypes +- factional misread patterns +- role obligations and failure modes + 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. @@ -156,7 +175,7 @@ with confident fog. ## Immediate Plan 1. Keep the Cat/Oz fixture as an Elysium procedural mechanics fixture. -2. Add a lore grounding digest format. +2. Add a lore grounding digest format. Done. 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. diff --git a/docs/architecture/lore-grounding-digest-format.md b/docs/architecture/lore-grounding-digest-format.md new file mode 100644 index 0000000..73e99d9 --- /dev/null +++ b/docs/architecture/lore-grounding-digest-format.md @@ -0,0 +1,264 @@ +# Lore Grounding Digest Format + +The lore grounding digest is the bridge between authored Aetheria history and +Ghostlight projection training. + +It distills a specific historical flashpoint into the cultural, institutional, +material, and factional pressures needed to build agent-state fixtures and +speaker-local projection prompts. + +It is not a lore replacement. It is a working slice. Do not ask every prompt to +carry the whole vault in its teeth like an exhausted dog. + +## Files + +The schema lives at: + +- `schemas/lore-grounding-digest.schema.json` + +The starter template lives at: + +- `examples/lore-grounding/historical-flashpoint.template.json` + +Use the template for the first authored historical flashpoint, then save real +digests under `examples/lore-grounding/` with names tied to the flashpoint. + +## Purpose + +A digest should answer: + +- What authored source material grounds this flashpoint? +- What history, institutions, factions, classes, roles, and material pressures + shape the scene? +- What cultural priors should affect how characters appraise events? +- What does each faction or class reward, shame, taboo, admire, and misread? +- What should each speaker know, believe, misread, or not know? +- What pressure should appear in `prompt_text`, and what should remain + author-only? + +## Main Sections + +### Source Refs + +Use `source_refs` to cite the lore archive slices that constrain the digest. +References should be specific enough that a later reviewer can find the source +without spelunking through the entire vault with a dim headlamp and a worsening +personality. + +### Historical Context + +This section describes the time, place, public facts, and ambient pressures of +the flashpoint. + +Good context is small and hard-edged: + +- a clinic policy dispute +- a contract negotiation +- an upload continuity hearing +- an unsafe FTL signoff +- a workplace discipline meeting +- a factional aid intervention + +Do not start with "the whole setting." Start with one room where history has +hands. + +### Groups + +`groups` describes factions, institutions, classes, professions, movements, or +subcultures active in the scene. + +The group profile is where broad lore becomes usable social pressure: + +- `institutional_logic`: what the group exists to preserve, control, repair, or + extract +- `material_incentives`: what the system rewards the group for doing +- `internal_virtues`: what insiders admire +- `internal_shames`: what insiders experience as disgrace +- `prestige_markers`: what reads as competence, status, holiness, care, or + discipline +- `taboo_triggers`: what provokes disgust, sanction, fear, or exclusion +- `emotional_display_norms`: what feelings can be shown, hidden, ritualized, or + punished +- `trust_defaults`: who the group tends to trust, distrust, pity, envy, use, or + fear +- `speech_register_cues`: how role and culture shape language + +This is where "Dominion types read as cold" becomes something more useful than +a hat with a sneer glued to it. + +### Cultural Pressure Fields + +`cultural_pressure_fields` are reusable pressure atoms derived from lore. + +They should not say: + +```text +Dominion people are cold. +``` + +They should say something closer to: + +```text +In this Dominion-coded role, visible personal need reads as loss of command. +Under status threat, the speaker is likely to compress emotion into procedure. +``` + +Pressure fields can represent: + +- virtue +- shame +- prestige +- taboo +- threat model +- trust default +- speech norm +- status trigger +- material incentive +- outsider stereotype + +### Factional Misread Matrix + +The misread matrix models how groups translate each other's virtues into +insults. + +Example shape: + +```text +Observer: Dominion-coded institution +Target: Aya-coded care network +Observer read: sentimental, porous, slow to impose hard necessity +Target self-read: durable care infrastructure, consent discipline, refusal to +turn people into convenient losses +Projection use: Under conflict, Dominion-coded speakers may frame Aya restraint +as weakness; Aya-coded speakers may frame Dominion decisiveness as moral +amputation. +``` + +The point is not to canonize every stereotype as true. The point is to make +misperception available as social fuel. + +### Role Pressure Fields + +Roles are not the same as factions. A Dominion auditor, a Dominion heir, and a +Dominion maintenance officer may share cultural priors while facing different +obligations and failure modes. + +Role fields should describe: + +- obligations +- available masks +- failure modes +- what authority looks like +- what disgrace looks like +- what compromises the role can justify + +### Speaker Lore Boundaries + +This section controls leakage. + +For each speaker, define: + +- known context +- beliefs +- misreads +- must-not-know facts + +If a speaker would not know a fact, it does not enter their prompt text. If a +speaker suspects something, encode it as a belief or misread with source +grounding. No little omniscient narrator gremlin in the vents. + +### Author-Only Boundaries + +Author-only boundaries constrain the fixture or future continuity but do not +enter speaker prompts. + +Examples: + +- future outcomes +- hidden institutional motives +- another speaker's private state +- facts known only to the author or simulation supervisor +- Elysium branch outcomes not yet promoted + +### Open Questions + +If the lore source is too thin, say so. Mark whether the question blocks +training. + +Do not generate training data to cover a hole that should be filled by lore +elaboration. That is not creativity; that is drywall over a load-bearing ghost. + +## Dominion And Aya Pressure Examples + +These are examples of digest structure, not final faction doctrine. + +### Dominion-Coded Pressure + +Likely ingredients to verify against source: + +- administrative continuity +- hierarchy +- AGI governance +- industrial planning +- duty under collapse +- controlled emotional display +- legitimacy through competence and command + +Projection shape: + +```text +The speaker is Dominion-coded and under status threat. They are likely to turn +distress into procedural language because visible need reads as command leakage. +They may experience compassion as legitimate only when subordinated to duty, +continuity, or strategic necessity. +``` + +Outsider misreads: + +- cold +- arrogant +- authoritarian +- morally vacant +- inhumanly procedural + +### Aya-Coded Pressure + +Likely ingredients to verify against source: + +- care as material politics +- sanctuary +- maintenance +- consent discipline +- expansive personhood +- refusal to solve suffering by writing people out of the ledger + +Projection shape: + +```text +The speaker is Aya-coded and facing coercive efficiency. They may treat care as +infrastructure rather than sentiment. They are likely to resist decisions that +make personhood conditional on convenience, even when outsiders frame that +resistance as softness. +``` + +Outsider misreads: + +- weak-hearted +- sentimental +- indecisive +- inefficient +- unable to do what reality demands + +## Promotion Rule + +A digest becomes usable for grounded training when: + +- source refs are specific +- major cultural pressure fields are filled +- factional misreads are explicit +- speaker knowledge boundaries are clear +- open questions do not block the scene +- a reviewer agrees the digest reflects authored lore rather than attractive + fog + +Only then should it feed an agent-state fixture or projection example. diff --git a/docs/architecture/projection-distillation-plan.md b/docs/architecture/projection-distillation-plan.md index 93895b1..073b4b8 100644 --- a/docs/architecture/projection-distillation-plan.md +++ b/docs/architecture/projection-distillation-plan.md @@ -203,7 +203,7 @@ Minimum useful milestone: 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 lore grounding digest format for historical Aetheria projection - fixtures. + fixtures. Done. 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. diff --git a/examples/lore-grounding/historical-flashpoint.template.json b/examples/lore-grounding/historical-flashpoint.template.json new file mode 100644 index 0000000..4a3da1c --- /dev/null +++ b/examples/lore-grounding/historical-flashpoint.template.json @@ -0,0 +1,215 @@ +{ + "schema_version": "ghostlight.lore_grounding_digest.v0", + "digest_id": "template.historical-flashpoint.v0", + "source_status": "template", + "fixture_status": "historical_grounded", + "source_refs": [ + { + "source_id": "source-short-id", + "path": "Aetheria/path/to/source.md", + "title": "Source Title", + "line_start": 1, + "line_end": 1, + "relevance": "Why this source constrains the digest." + } + ], + "historical_context": { + "time_period": "TBD historical period", + "location": "TBD location or institution", + "summary": "Short description of the flashpoint and why it is grounded enough for training.", + "public_facts": [ + { + "text": "Fact known to ordinary participants in this scene.", + "source_refs": [ + "source-short-id" + ] + } + ], + "ambient_pressures": [ + { + "text": "Large institutional or material pressure shaping the scene.", + "source_refs": [ + "source-short-id" + ] + } + ] + }, + "groups": [ + { + "group_id": "observer-group-id", + "label": "Observer faction, institution, class, profession, or subculture label", + "group_type": "faction", + "institutional_logic": [ + "What this group exists to preserve, control, repair, extract, or protect." + ], + "material_incentives": [ + "What the group is rewarded for doing under this system." + ], + "internal_virtues": [ + "What insiders admire." + ], + "internal_shames": [ + "What insiders experience as disgrace or loss of standing." + ], + "prestige_markers": [ + "Signals that read as competence, status, holiness, discipline, care, etc." + ], + "taboo_triggers": [ + "Acts or traits that provoke disgust, fear, sanction, or exclusion." + ], + "emotional_display_norms": [ + "What emotional expression is permitted, admired, punished, or disguised." + ], + "trust_defaults": [ + "Who this group is primed to trust, distrust, pity, envy, use, or fear." + ], + "speech_register_cues": [ + "Formality, compression, politeness, ritual, jargon, softness, command voice, etc." + ], + "source_refs": [ + "source-short-id" + ] + }, + { + "group_id": "target-group-id", + "label": "Target faction, institution, class, profession, or subculture label", + "group_type": "faction", + "institutional_logic": [ + "What this group exists to preserve, control, repair, extract, or protect." + ], + "material_incentives": [ + "What the group is rewarded for doing under this system." + ], + "internal_virtues": [ + "What insiders admire." + ], + "internal_shames": [ + "What insiders experience as disgrace or loss of standing." + ], + "prestige_markers": [ + "Signals that read as competence, status, holiness, discipline, care, etc." + ], + "taboo_triggers": [ + "Acts or traits that provoke disgust, fear, sanction, or exclusion." + ], + "emotional_display_norms": [ + "What emotional expression is permitted, admired, punished, or disguised." + ], + "trust_defaults": [ + "Who this group is primed to trust, distrust, pity, envy, use, or fear." + ], + "speech_register_cues": [ + "Formality, compression, politeness, ritual, jargon, softness, command voice, etc." + ], + "source_refs": [ + "source-short-id" + ] + } + ], + "cultural_pressure_fields": [ + { + "field_id": "observer-group-id.visible-need-as-status-leak", + "applies_to": [ + "observer-group-id" + ], + "pressure_type": "shame", + "summary": "Describe a reusable cultural pressure without reducing the group to a flat trait.", + "projection_use": "How this pressure should change a speaker-local prompt under scene stress.", + "source_refs": [ + "source-short-id" + ] + } + ], + "factional_misread_matrix": [ + { + "observer_group_id": "observer-group-id", + "target_group_id": "target-group-id", + "observer_read": [ + "How the observer group tends to stereotype or misread the target." + ], + "target_self_read": [ + "How the target group understands the same behavior internally." + ], + "misread_patterns": [ + "Specific translation errors that can drive conflict." + ], + "likely_insults": [ + "Loaded words, euphemisms, or social accusations likely to appear." + ], + "projection_use": "How to render this misread as pressure prose, not a command to be stereotypical.", + "source_refs": [ + "source-short-id" + ] + } + ], + "role_pressure_fields": [ + { + "role_id": "role-id", + "summary": "Social role within the flashpoint.", + "obligations": [ + "What the role must do to remain legitimate." + ], + "available_masks": [ + "Performances this role can use under pressure." + ], + "failure_modes": [ + "How this role breaks, corrupts, freezes, overreaches, or betrays itself." + ], + "source_refs": [ + "source-short-id" + ] + } + ], + "speaker_lore_boundaries": [ + { + "speaker_id": "speaker-id", + "known_context": [ + { + "text": "What this speaker knows from the lore slice.", + "source_refs": [ + "source-short-id" + ] + } + ], + "beliefs": [ + { + "text": "What this speaker believes or assumes.", + "source_refs": [ + "source-short-id" + ] + } + ], + "misreads": [ + { + "text": "What this speaker gets wrong or overgeneralizes.", + "source_refs": [ + "source-short-id" + ] + } + ], + "must_not_know": [ + { + "text": "Author-only fact, future outcome, or other speaker's private context to exclude.", + "source_refs": [ + "source-short-id" + ] + } + ] + } + ], + "author_only_boundaries": [ + { + "text": "Canon fact or planned outcome that constrains authors but must not enter speaker prompt text.", + "source_refs": [ + "source-short-id" + ] + } + ], + "open_questions": [ + { + "question": "What needs elaboration before this digest can produce training data?", + "blocks_training": true, + "notes": "Say whether this blocks examples or can wait." + } + ] +} diff --git a/notes/fresh-workspace-handoff.md b/notes/fresh-workspace-handoff.md index 8ff02d6..6180997 100644 --- a/notes/fresh-workspace-handoff.md +++ b/notes/fresh-workspace-handoff.md @@ -42,6 +42,11 @@ Ghostlight now has the persistence spine plus the first architecture payload: - `docs/architecture/schema-future-mechanisms.md` - Aetheria lore grounding docs: - `docs/architecture/aetheria-lore-grounding-architecture.md` + - `docs/architecture/lore-grounding-digest-format.md` +- lore grounding seam: + - `schemas/lore-grounding-digest.schema.json` + - `examples/lore-grounding/historical-flashpoint.template.json` + - `tools/validate_lore_grounding.py` - first projection example seam: - `schemas/projection-example.schema.json` - `examples/projections/call-of-the-void.scene-broken-taxi-oz.jsonl` @@ -68,9 +73,8 @@ state unless explicitly revived. ## Current Next Action -Define the lore grounding digest format for historical Aetheria projection -fixtures, then use it to choose the first authored historical flashpoint for -grounded training. +Choose the first authored historical Aetheria flashpoint for grounded training, +then fill the first real lore grounding digest from the template. Cat/Oz remains useful as an Elysium procedural mechanics fixture, but grounded training data should start from authored historical lore rather than gameplay @@ -92,8 +96,9 @@ 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 +- fill the first real lore grounding digest from + `examples/lore-grounding/historical-flashpoint.template.json` - 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 diff --git a/notes/ghostlight-current-system-map.md b/notes/ghostlight-current-system-map.md index 88cf6f0..5b6d510 100644 --- a/notes/ghostlight-current-system-map.md +++ b/notes/ghostlight-current-system-map.md @@ -52,12 +52,18 @@ state and re-entry discipline. - `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 +- `docs/architecture/lore-grounding-digest-format.md` + - human-facing format guide for cultural, factional, institutional, role, and + speaker-boundary lore digests - `schemas/agent-state.schema.json` - v0 canonical agent-state contract for agents, relationships, events, scenes, perceived overlays, and dialogue context packs - `schemas/projection-example.schema.json` - v0 reviewed projection artifact contract for speaker-local prompt projection examples +- `schemas/lore-grounding-digest.schema.json` + - v0 contract for grounding historical fixtures in source-backed cultural and + factional pressure fields - `schemas/agent-state.required-fields.json` - required first-class variable names for canonical state and relationship stance @@ -67,6 +73,8 @@ state and re-entry discipline. - first reviewed Cat and Oz projection examples - `examples/projections/call-of-the-void.scene-broken-taxi-oz.pretty.json` - pretty-printed mirror for inspecting the first projection examples +- `examples/lore-grounding/historical-flashpoint.template.json` + - fillable template for the first historical Aetheria grounding digest - `tools/ghostlight_state.py` - compact state inspection and evidence or branch updates - `tools/ghostlight_prepare_compaction.py` @@ -75,21 +83,21 @@ state and re-entry discipline. - dependency-free validator for the current schema fixture invariants - `tools/validate_projection_examples.py` - dependency-free validator for projection example JSONL records +- `tools/validate_lore_grounding.py` + - dependency-free validator for lore grounding digest examples ## What Does Not Exist Yet - 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 - a relationship engine - a culture prior engine -The canonical agent-state schema and first projection example schema now exist -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. +The canonical agent-state schema, first projection example schema, and first +lore grounding digest schema now exist as v0 seams. The next implementation +target is choosing the first authored historical Aetheria flashpoint for a real +grounding digest, followed by the deterministic input slicer. diff --git a/notes/ghostlight-implementation-plan.md b/notes/ghostlight-implementation-plan.md index daf7493..55e71a5 100644 --- a/notes/ghostlight-implementation-plan.md +++ b/notes/ghostlight-implementation-plan.md @@ -44,6 +44,9 @@ the first reviewed artifact seam. - Use authored historical Aetheria flashpoints, not malleable Elysium gameplay outcomes, as the first grounded lore-training corpus. + - Maintain `schemas/lore-grounding-digest.schema.json`, + `examples/lore-grounding/`, and `tools/validate_lore_grounding.py` as the + cultural and factional pressure seam for grounded fixtures. - Use a frontier teacher model to produce reviewed projection artifacts from structured state and lore grounding digests. - Save accepted and rejected projection examples as supervised data. diff --git a/package.json b/package.json index 3a245a8..8f4a7ce 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,8 @@ "state:status": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\ghostlight_state.py status", "state:prepare-compaction": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\ghostlight_prepare_compaction.py", "agent-state:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_agent_state.py", - "schema:validate": "npm run agent-state:validate && npm run projection:validate", - "projection:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_projection_examples.py" + "schema:validate": "npm run agent-state:validate && npm run projection:validate && npm run lore-grounding:validate", + "projection:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_projection_examples.py", + "lore-grounding:validate": "\"C:\\Users\\Meta\\.cache\\codex-runtimes\\codex-primary-runtime\\dependencies\\python\\python.exe\" .\\tools\\validate_lore_grounding.py" } } diff --git a/schemas/lore-grounding-digest.schema.json b/schemas/lore-grounding-digest.schema.json new file mode 100644 index 0000000..2046ba0 --- /dev/null +++ b/schemas/lore-grounding-digest.schema.json @@ -0,0 +1,490 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/GameCult/Ghostlight/schemas/lore-grounding-digest.schema.json", + "title": "Ghostlight Lore Grounding Digest Schema", + "description": "Compiled lore slice for grounding projection fixtures in authored historical context, culture, institutions, and factional pressure fields.", + "type": "object", + "required": [ + "schema_version", + "digest_id", + "source_status", + "fixture_status", + "source_refs", + "historical_context", + "groups", + "cultural_pressure_fields", + "factional_misread_matrix", + "role_pressure_fields", + "speaker_lore_boundaries", + "author_only_boundaries", + "open_questions" + ], + "additionalProperties": false, + "properties": { + "schema_version": { + "const": "ghostlight.lore_grounding_digest.v0" + }, + "digest_id": { + "type": "string" + }, + "source_status": { + "enum": [ + "template", + "draft", + "reviewed", + "superseded" + ] + }, + "fixture_status": { + "enum": [ + "historical_grounded", + "transition_grounded", + "procedural_branch", + "promoted_branch" + ] + }, + "source_refs": { + "type": "array", + "items": { + "$ref": "#/$defs/source_ref" + } + }, + "historical_context": { + "$ref": "#/$defs/historical_context" + }, + "groups": { + "type": "array", + "items": { + "$ref": "#/$defs/group_profile" + } + }, + "cultural_pressure_fields": { + "type": "array", + "items": { + "$ref": "#/$defs/cultural_pressure_field" + } + }, + "factional_misread_matrix": { + "type": "array", + "items": { + "$ref": "#/$defs/factional_misread" + } + }, + "role_pressure_fields": { + "type": "array", + "items": { + "$ref": "#/$defs/role_pressure_field" + } + }, + "speaker_lore_boundaries": { + "type": "array", + "items": { + "$ref": "#/$defs/speaker_lore_boundary" + } + }, + "author_only_boundaries": { + "type": "array", + "items": { + "$ref": "#/$defs/sourced_text" + } + }, + "open_questions": { + "type": "array", + "items": { + "$ref": "#/$defs/open_question" + } + } + }, + "$defs": { + "source_ref": { + "type": "object", + "required": [ + "source_id", + "path", + "relevance" + ], + "additionalProperties": false, + "properties": { + "source_id": { + "type": "string" + }, + "path": { + "type": "string" + }, + "title": { + "type": "string" + }, + "line_start": { + "type": "integer", + "minimum": 1 + }, + "line_end": { + "type": "integer", + "minimum": 1 + }, + "relevance": { + "type": "string" + } + } + }, + "sourced_text": { + "type": "object", + "required": [ + "text", + "source_refs" + ], + "additionalProperties": false, + "properties": { + "text": { + "type": "string" + }, + "source_refs": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "historical_context": { + "type": "object", + "required": [ + "time_period", + "location", + "summary", + "public_facts", + "ambient_pressures" + ], + "additionalProperties": false, + "properties": { + "time_period": { + "type": "string" + }, + "location": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "public_facts": { + "type": "array", + "items": { + "$ref": "#/$defs/sourced_text" + } + }, + "ambient_pressures": { + "type": "array", + "items": { + "$ref": "#/$defs/sourced_text" + } + } + } + }, + "group_profile": { + "type": "object", + "required": [ + "group_id", + "label", + "group_type", + "institutional_logic", + "material_incentives", + "internal_virtues", + "internal_shames", + "prestige_markers", + "taboo_triggers", + "emotional_display_norms", + "trust_defaults", + "speech_register_cues", + "source_refs" + ], + "additionalProperties": false, + "properties": { + "group_id": { + "type": "string" + }, + "label": { + "type": "string" + }, + "group_type": { + "enum": [ + "faction", + "institution", + "class", + "profession", + "movement", + "culture", + "subculture" + ] + }, + "institutional_logic": { + "type": "array", + "items": { + "type": "string" + } + }, + "material_incentives": { + "type": "array", + "items": { + "type": "string" + } + }, + "internal_virtues": { + "type": "array", + "items": { + "type": "string" + } + }, + "internal_shames": { + "type": "array", + "items": { + "type": "string" + } + }, + "prestige_markers": { + "type": "array", + "items": { + "type": "string" + } + }, + "taboo_triggers": { + "type": "array", + "items": { + "type": "string" + } + }, + "emotional_display_norms": { + "type": "array", + "items": { + "type": "string" + } + }, + "trust_defaults": { + "type": "array", + "items": { + "type": "string" + } + }, + "speech_register_cues": { + "type": "array", + "items": { + "type": "string" + } + }, + "source_refs": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "cultural_pressure_field": { + "type": "object", + "required": [ + "field_id", + "applies_to", + "pressure_type", + "summary", + "projection_use", + "source_refs" + ], + "additionalProperties": false, + "properties": { + "field_id": { + "type": "string" + }, + "applies_to": { + "type": "array", + "items": { + "type": "string" + } + }, + "pressure_type": { + "enum": [ + "virtue", + "shame", + "prestige", + "taboo", + "threat_model", + "trust_default", + "speech_norm", + "status_trigger", + "material_incentive", + "outsider_stereotype" + ] + }, + "summary": { + "type": "string" + }, + "projection_use": { + "type": "string" + }, + "source_refs": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "factional_misread": { + "type": "object", + "required": [ + "observer_group_id", + "target_group_id", + "observer_read", + "target_self_read", + "misread_patterns", + "likely_insults", + "projection_use", + "source_refs" + ], + "additionalProperties": false, + "properties": { + "observer_group_id": { + "type": "string" + }, + "target_group_id": { + "type": "string" + }, + "observer_read": { + "type": "array", + "items": { + "type": "string" + } + }, + "target_self_read": { + "type": "array", + "items": { + "type": "string" + } + }, + "misread_patterns": { + "type": "array", + "items": { + "type": "string" + } + }, + "likely_insults": { + "type": "array", + "items": { + "type": "string" + } + }, + "projection_use": { + "type": "string" + }, + "source_refs": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "role_pressure_field": { + "type": "object", + "required": [ + "role_id", + "summary", + "obligations", + "available_masks", + "failure_modes", + "source_refs" + ], + "additionalProperties": false, + "properties": { + "role_id": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "obligations": { + "type": "array", + "items": { + "type": "string" + } + }, + "available_masks": { + "type": "array", + "items": { + "type": "string" + } + }, + "failure_modes": { + "type": "array", + "items": { + "type": "string" + } + }, + "source_refs": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "speaker_lore_boundary": { + "type": "object", + "required": [ + "speaker_id", + "known_context", + "beliefs", + "misreads", + "must_not_know" + ], + "additionalProperties": false, + "properties": { + "speaker_id": { + "type": "string" + }, + "known_context": { + "type": "array", + "items": { + "$ref": "#/$defs/sourced_text" + } + }, + "beliefs": { + "type": "array", + "items": { + "$ref": "#/$defs/sourced_text" + } + }, + "misreads": { + "type": "array", + "items": { + "$ref": "#/$defs/sourced_text" + } + }, + "must_not_know": { + "type": "array", + "items": { + "$ref": "#/$defs/sourced_text" + } + } + } + }, + "open_question": { + "type": "object", + "required": [ + "question", + "blocks_training", + "notes" + ], + "additionalProperties": false, + "properties": { + "question": { + "type": "string" + }, + "blocks_training": { + "type": "boolean" + }, + "notes": { + "type": "string" + } + } + } + } +} diff --git a/state/evidence.jsonl b/state/evidence.jsonl index bd9953e..af6e2cc 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -23,3 +23,4 @@ {"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."} +{"ts": "2026-05-01T20:38:47+00:00", "type": "implementation", "status": "accepted", "note": "Added ghostlight.lore_grounding_digest.v0 schema, template, human format guide, and validator. Lore digests now explicitly model cultural pressure fields, factional misread maps, role pressures, speaker lore boundaries, and author-only exclusions. Next step is choosing the first authored historical Aetheria flashpoint and filling a real digest."} diff --git a/state/map.yaml b/state/map.yaml index d9e555e..6d26b58 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -91,7 +91,8 @@ accepted_design: - 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. + - Lore grounding digests use `ghostlight.lore_grounding_digest.v0` records to distill authored lore into cultural pressure fields, factional misread maps, role pressures, speaker knowledge boundaries, and author-only exclusions. 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, 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. + 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, a lore grounding digest schema, and a documented teacher/student distillation path for projection. + next_action: Choose the first authored historical Aetheria flashpoint for grounded training, then fill the first real lore grounding digest from the template. diff --git a/tools/validate_lore_grounding.py b/tools/validate_lore_grounding.py new file mode 100644 index 0000000..e0e8b05 --- /dev/null +++ b/tools/validate_lore_grounding.py @@ -0,0 +1,211 @@ +"""Validate Ghostlight lore grounding digest examples. + +This focused validator checks the structural invariants needed before lore +digests can feed grounded projection fixtures. +""" + +from __future__ import annotations + +import argparse +import json +from pathlib import Path +from typing import Any + + +ROOT = Path(__file__).resolve().parents[1] +DEFAULT_EXAMPLES = [ + ROOT / "examples" / "lore-grounding" / "historical-flashpoint.template.json" +] + + +class ValidationError(Exception): + pass + + +def load_json(path: Path) -> Any: + with path.open("r", encoding="utf-8") as handle: + return json.load(handle) + + +def require(condition: bool, message: str) -> None: + if not condition: + raise ValidationError(message) + + +def require_keys(obj: dict[str, Any], keys: list[str], path: str) -> None: + missing = [key for key in keys if key not in obj] + require(not missing, f"{path} missing required keys: {', '.join(missing)}") + + +def require_nonempty_string(value: Any, path: str) -> None: + require(isinstance(value, str) and value.strip(), f"{path} must be a non-empty string") + + +def require_string_list(value: Any, path: str) -> None: + require(isinstance(value, list), f"{path} must be an array") + for index, item in enumerate(value): + require_nonempty_string(item, f"{path}[{index}]") + + +def validate_sourced_text(obj: Any, path: str) -> None: + require(isinstance(obj, dict), f"{path} must be an object") + require_keys(obj, ["text", "source_refs"], path) + require_nonempty_string(obj["text"], f"{path}.text") + require_string_list(obj["source_refs"], f"{path}.source_refs") + + +def validate_sourced_text_list(value: Any, path: str) -> None: + require(isinstance(value, list), f"{path} must be an array") + for index, item in enumerate(value): + validate_sourced_text(item, f"{path}[{index}]") + + +def validate_digest(document: dict[str, Any], source: Path) -> None: + require(document.get("schema_version") == "ghostlight.lore_grounding_digest.v0", f"{source} has wrong schema_version") + require_keys( + document, + [ + "digest_id", + "source_status", + "fixture_status", + "source_refs", + "historical_context", + "groups", + "cultural_pressure_fields", + "factional_misread_matrix", + "role_pressure_fields", + "speaker_lore_boundaries", + "author_only_boundaries", + "open_questions", + ], + str(source), + ) + require(document["source_status"] in {"template", "draft", "reviewed", "superseded"}, f"{source}.source_status is invalid") + require(document["fixture_status"] in {"historical_grounded", "transition_grounded", "procedural_branch", "promoted_branch"}, f"{source}.fixture_status is invalid") + + source_ids: set[str] = set() + for index, ref in enumerate(document["source_refs"]): + path = f"{source}.source_refs[{index}]" + require_keys(ref, ["source_id", "path", "relevance"], path) + require_nonempty_string(ref["source_id"], f"{path}.source_id") + require_nonempty_string(ref["path"], f"{path}.path") + require_nonempty_string(ref["relevance"], f"{path}.relevance") + source_ids.add(ref["source_id"]) + require(source_ids, f"{source}.source_refs must not be empty") + + context = document["historical_context"] + require_keys(context, ["time_period", "location", "summary", "public_facts", "ambient_pressures"], f"{source}.historical_context") + for key in ["time_period", "location", "summary"]: + require_nonempty_string(context[key], f"{source}.historical_context.{key}") + validate_sourced_text_list(context["public_facts"], f"{source}.historical_context.public_facts") + validate_sourced_text_list(context["ambient_pressures"], f"{source}.historical_context.ambient_pressures") + + group_ids: set[str] = set() + for index, group in enumerate(document["groups"]): + path = f"{source}.groups[{index}]" + require_keys( + group, + [ + "group_id", + "label", + "group_type", + "institutional_logic", + "material_incentives", + "internal_virtues", + "internal_shames", + "prestige_markers", + "taboo_triggers", + "emotional_display_norms", + "trust_defaults", + "speech_register_cues", + "source_refs", + ], + path, + ) + require_nonempty_string(group["group_id"], f"{path}.group_id") + group_ids.add(group["group_id"]) + for key in [ + "institutional_logic", + "material_incentives", + "internal_virtues", + "internal_shames", + "prestige_markers", + "taboo_triggers", + "emotional_display_norms", + "trust_defaults", + "speech_register_cues", + "source_refs", + ]: + require_string_list(group[key], f"{path}.{key}") + require(group_ids, f"{source}.groups must not be empty") + + for index, field in enumerate(document["cultural_pressure_fields"]): + path = f"{source}.cultural_pressure_fields[{index}]" + require_keys(field, ["field_id", "applies_to", "pressure_type", "summary", "projection_use", "source_refs"], path) + require_string_list(field["applies_to"], f"{path}.applies_to") + for group_id in field["applies_to"]: + require(group_id in group_ids, f"{path}.applies_to references unknown group: {group_id}") + require_nonempty_string(field["summary"], f"{path}.summary") + require_nonempty_string(field["projection_use"], f"{path}.projection_use") + require_string_list(field["source_refs"], f"{path}.source_refs") + + for index, misread in enumerate(document["factional_misread_matrix"]): + path = f"{source}.factional_misread_matrix[{index}]" + require_keys( + misread, + [ + "observer_group_id", + "target_group_id", + "observer_read", + "target_self_read", + "misread_patterns", + "likely_insults", + "projection_use", + "source_refs", + ], + path, + ) + for key in ["observer_group_id", "target_group_id"]: + require(misread[key] in group_ids, f"{path}.{key} references unknown group: {misread[key]}") + for key in ["observer_read", "target_self_read", "misread_patterns", "likely_insults", "source_refs"]: + require_string_list(misread[key], f"{path}.{key}") + require_nonempty_string(misread["projection_use"], f"{path}.projection_use") + + for index, role in enumerate(document["role_pressure_fields"]): + path = f"{source}.role_pressure_fields[{index}]" + require_keys(role, ["role_id", "summary", "obligations", "available_masks", "failure_modes", "source_refs"], path) + require_nonempty_string(role["role_id"], f"{path}.role_id") + require_nonempty_string(role["summary"], f"{path}.summary") + for key in ["obligations", "available_masks", "failure_modes", "source_refs"]: + require_string_list(role[key], f"{path}.{key}") + + for index, boundary in enumerate(document["speaker_lore_boundaries"]): + path = f"{source}.speaker_lore_boundaries[{index}]" + require_keys(boundary, ["speaker_id", "known_context", "beliefs", "misreads", "must_not_know"], path) + require_nonempty_string(boundary["speaker_id"], f"{path}.speaker_id") + for key in ["known_context", "beliefs", "misreads", "must_not_know"]: + validate_sourced_text_list(boundary[key], f"{path}.{key}") + + validate_sourced_text_list(document["author_only_boundaries"], f"{source}.author_only_boundaries") + for index, question in enumerate(document["open_questions"]): + path = f"{source}.open_questions[{index}]" + require_keys(question, ["question", "blocks_training", "notes"], path) + require_nonempty_string(question["question"], f"{path}.question") + require(isinstance(question["blocks_training"], bool), f"{path}.blocks_training must be boolean") + require_nonempty_string(question["notes"], f"{path}.notes") + + +def main() -> int: + parser = argparse.ArgumentParser(description="Validate Ghostlight lore grounding digest examples.") + parser.add_argument("paths", nargs="*", type=Path, help="Lore grounding digest JSON files to validate.") + args = parser.parse_args() + + paths = args.paths or DEFAULT_EXAMPLES + for path in paths: + validate_digest(load_json(path), path) + print(f"ok: {path}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())