World State Engine

Planned / not yet available. A read-only /api/world-state/* API and UI page exist, but no data sources are registered yet (snapshots are empty), and there is no mockforge world-state CLI, no snapshot-creation endpoint, no time-travel queries, and no GraphML/DOT export. This page describes the intended design and is kept for reference; do not rely on it in a released build. Track progress at https://github.com/SaaSy-Solutions/mockforge/issues.

Pillars: [Reality][DevX]

The World State Engine unifies all MockForge state systems into a single “world state” visualization. Think of it as a miniature game engine for your backend—a unified view of personas, lifecycle, reality, time, multi-protocol state, behavior trees, generative schemas, recorded data, and AI modifiers.

Overview

The World State Engine aggregates and visualizes:

  • Personas: Persona profiles, relationships, and graphs
  • Lifecycle: Lifecycle states, transitions, and time-based changes
  • Reality: Reality levels, continuum ratios, and chaos rules
  • Time: Virtual clock state, scheduled events, and time scale
  • Multi-Protocol: Protocol-specific state, sessions, and entity state
  • Behavior: Behavior trees, rules, and AI modifiers
  • Schemas: Generative schema definitions and entity relationships
  • Recorded Data: Recorded requests/responses, fixtures, and replay state
  • AI Modifiers: AI response configurations and modifiers

Key Features

  • Unified State Aggregation: Collects state from all MockForge subsystems
  • Graph Visualization: Represents state as nodes and edges for visualization
  • Real-time Updates: Streams state changes in real-time
  • Time Travel: View state at any point in time
  • Query Interface: Flexible querying of state with filters
  • Export Capabilities: Export state in various formats (JSON, GraphML, DOT)

Usage

There is no mockforge world-state CLI yet. The HTTP server exposes a read-only API under /api/world-state:

# Current snapshot (optional ?workspace=, ?layers=, ?node_types= filters)
curl http://localhost:3000/api/world-state/snapshot

# Current state as a graph (nodes and edges)
curl http://localhost:3000/api/world-state/graph

# Available layers
curl http://localhost:3000/api/world-state/layers

A WebSocket stream of state changes is available at /api/world-state/stream, and the Admin UI has a World State page. Because no data sources are registered yet, these currently return empty state.

State Layers

Personas Layer

Persona profiles and relationships:

{
  "layer": "personas",
  "nodes": [
    {
      "id": "persona:premium-001",
      "type": "persona",
      "data": {
        "traits": {...},
        "relationships": [...]
      }
    }
  ],
  "edges": [
    {
      "from": "persona:premium-001",
      "to": "order:123",
      "type": "has_orders"
    }
  ]
}

Reality Layer

Reality levels and continuum ratios:

{
  "layer": "reality",
  "state": {
    "reality_level": 3,
    "continuum_ratio": 0.5,
    "chaos_rules": [...]
  }
}

Time Layer

Virtual clock and scheduled events:

{
  "layer": "time",
  "state": {
    "virtual_time": "2025-01-27T10:00:00Z",
    "time_scale": 1.0,
    "scheduled_events": [...]
  }
}

Protocols Layer

Protocol-specific state:

{
  "layer": "protocols",
  "state": {
    "http": {
      "sessions": [...],
      "connections": [...]
    },
    "websocket": {
      "connections": [...],
      "subscriptions": [...]
    }
  }
}

Query Interface

The intended design supports filtering by layer, by criteria (persona, reality level, time), and combining several filters. There is no mockforge world-state CLI for this yet. The existing read-only API accepts a structured filter body:

curl -X POST http://localhost:3000/api/world-state/query \
  -H "Content-Type: application/json" \
  -d '{"layers": ["personas", "reality"], "node_types": ["persona"], "include_edges": true}'

Free-form criteria filters (for example reality_level>=3) are not implemented.

Time Travel

Viewing world state at an arbitrary point in time is planned but not implemented. Previously captured snapshots can be fetched by ID with GET /api/world-state/snapshot/{id}.

Export Formats

Exporting world state as JSON, GraphML, or DOT is planned. There is no export command yet; GET /api/world-state/graph returns the current graph as JSON.

Real-World Example

E-Commerce World State

{
  "workspace_id": "ecommerce-123",
  "snapshot_time": "2025-01-27T10:00:00Z",
  "layers": {
    "personas": {
      "nodes": [
        {
          "id": "persona:premium-001",
          "type": "persona",
          "data": {
            "traits": {"tier": "premium"},
            "lifecycle_state": "active"
          }
        },
        {
          "id": "order:456",
          "type": "order",
          "data": {
            "status": "pending",
            "total": 99.99
          }
        }
      ],
      "edges": [
        {
          "from": "persona:premium-001",
          "to": "order:456",
          "type": "has_orders"
        }
      ]
    },
    "reality": {
      "reality_level": 3,
      "continuum_ratio": 0.5,
      "chaos_rules": []
    },
    "time": {
      "virtual_time": "2025-01-27T10:00:00Z",
      "time_scale": 1.0
    }
  }
}

Best Practices

  1. Regular Snapshots: Take snapshots at key points
  2. Query Efficiently: Use filters to query only needed layers
  3. Visualize: Use graph visualization to understand relationships
  4. Time Travel: Use time travel to debug temporal issues
  5. Export for Analysis: Export state for external analysis