state-consistency-validation

name	state-consistency-validation
description	Enforce story-state consistency in agent simulations by validating that world state matches chapter progression, repairing contradictions before they reach viewers
source	auto-skill
extracted_at	2026-05-30T17:28:20.161Z

State Consistency Validation

When building chapter-based story simulations, world state can drift out of sync with the current chapter (e.g., boundary violated during chapters where it should be respected). Add a consistency validator that repairs contradictions before they reach viewers.

The Problem

During development, the simulation showed:

• Chapter text: "The Boundary is respected and the garden remains peaceful."
• Garden card: "Boundary: Not Respected"
• Visual scene: boundary tree without calm glow

This contradiction is especially harmful for religious/story viewers who notice meaning more than technical UI.

The Fix: Consistency Validator

Add validation to every viewer-facing API endpoint:

@app.get("/api/mom/state")
def mom_state():
    chapter = get_current_chapter(eden.tick, event_log.events)

    # Consistency validator: chapters 1-4 must have boundary respected
    safe_boundary_respected = eden.boundary_respected
    if chapter.id in ("garden_is_good", "adam_tends_and_names", "eve_joins_adam", "the_boundary"):
        if not eden.boundary_respected:
            # Log warning without exposing on viewer
            print(f"[WARNING] Boundary violation during locked chapter {chapter.id}. Repairing.")
            eden.boundary_respected = True
            safe_boundary_respected = True

    # Use safe_boundary_respected in response, not eden.boundary_respected
    return {
        "boundary_respected": safe_boundary_respected,
        ...
    }

Apply to All Viewer Endpoints

The same validator must run on every endpoint that returns state to viewers:

@app.get("/api/mom/visual-state")
def mom_visual_state():
    chapter = get_current_chapter(eden.tick, event_log.events)

    # Same consistency validator
    safe_boundary_respected = eden.boundary_respected
    if chapter.id in ("garden_is_good", "adam_tends_and_names", "eve_joins_adam", "the_boundary"):
        if not eden.boundary_respected:
            print(f"[WARNING] Boundary violation during locked chapter {chapter.id} (visual). Repairing.")
            eden.boundary_respected = True
            safe_boundary_respected = True

    # Use safe_boundary_respected for visual mapping
    b_v = boundary_v["respected"] if safe_boundary_respected else boundary_v["violated"]
    ...

General Pattern

For any story element that should be locked during certain chapters:

def validate_story_state(chapter, world_state):
    """Repair world state to match chapter constraints."""
    repairs = []

    # Example: boundary must be respected during chapters 1-4
    if chapter.id in CHAPTERS_BEFORE_FALL:
        if not world_state.boundary_respected:
            world_state.boundary_respected = True
            repairs.append("boundary_respected forced to True")

    # Example: harmony cannot drop below 0.9 before the Question
    if chapter.id in CHAPTERS_BEFORE_QUESTION:
        if world_state.harmony_level < 0.9:
            world_state.harmony_level = 0.9
            repairs.append("harmony_level forced to 0.9")

    # Example: garden cannot be damaged before the Choice
    if chapter.id in CHAPTERS_BEFORE_CHOICE:
        if world_state.garden_condition == "damaged":
            world_state.garden_condition = "pristine"
            repairs.append("garden_condition forced to pristine")

    if repairs:
        logger.warning("Story state repaired during chapter %s: %s", chapter.id, repairs)

    return world_state

Key Rules

1. Validate at the API layer — not just in the simulation loop
2. Use safe values in responses — never return the raw (possibly invalid) state
3. Log warnings, don't crash — print to server console, don't expose on viewer
4. Repair, don't reject — fix the state so the viewer sees a consistent story
5. Apply to all viewer endpoints — /api/mom/state, /api/mom/visual-state, any other viewer API

What to Validate

Chapter Range	Constraint	Repair
Chapters 1-4	Boundary must be respected	Force boundary_respected = True
Chapters 1-4	Harmony must be ≥ 0.9	Force harmony_level = 0.9
Chapters 1-4	Garden cannot be damaged	Force garden_condition = "pristine"
Chapters 1-5	No expulsion events	Filter out expulsion events
Chapters 1-6	No hiding from God	Filter out hiding events

Anti-Patterns

• ❌ Letting raw world state reach the viewer without validation
• ❌ Only validating in the simulation loop (API endpoints bypass it)
• ❌ Crashing when state is inconsistent
• ❌ Exposing repair warnings on the viewer page
• ❌ Returning different state from different endpoints
• ✅ Validate at every API endpoint that returns state
• ✅ Use safe values in all responses
• ✅ Log warnings to server console only
• ✅ Repair state to match chapter constraints
• ✅ Ensure all viewer endpoints return consistent state