8000 mnehmos-engine/docs/GAP.md at main · Mnehmos/mnehmos-engine · GitHub
[go: up one dir, main page]

Skip to content

Latest commit

 

History

History
126 lines (91 loc) · 6.28 KB

GAP.md

File metadata and controls

126 lines (91 loc) · 6.28 KB

Implementation Gap

This project contains two layers that aren't fully aligned:

  1. The runtime (apps/gui-web/scripts/*.mjs) — what actually runs the simulation today
  2. The formal specification (src/ and docs/standalone_engine_*.md) — a TypeScript contract definition of the full architecture

The runtime is a working prototype that demonstrates the core thesis. The spec is the architectural roadmap for what it could become. This document maps the delta.

What's in the runtime

Economy

  • Finite resource deposits with selective renewables
  • Item durability and weapon degradation
  • Lethal hunger escalation
  • Labor-based production chains
  • DM spawn austerity (new NPCs arrive poor)

Agents

  • LLM-driven decisions via OpenRouter
  • Tiered memory (rolling narrative + permanent lessons)
  • Relationship tracking with context
  • Goal progression ([PROGRESS] / [DONE] markers)
  • Stealth with perception-based detection
  • Death and revival (no free respawn)

World

  • Multi-region (Copper Hollow + Thornfield + DM-generated extensions)
  • Distance-based travel (multi-tick journeys)
  • Weather with gameplay effects
  • Auto-save/load every 10 ticks
  • Constraint learning (failure patterns shared across agents)

Interaction

  • Solo action resolution with pre-validation
  • Retry-with-correction loop (failed actions don't waste ticks)
  • Interaction zones (conversation/combat/trade) with sub-ticks
  • Trade atomicity (offer → accept with real item/gold transfer)

DM

  • Tension analysis
  • Proposal types: spawn_npc, create_cell, inject_event, open_connection, send_raid, send_caravan
  • Region-aware prompting
  • Pacing threshold (12 ticks or 5+ tensions)

GUI

  • SSE event streaming with keepalive
  • Reconnect with last-sequence resume
  • Subject projection panel
  • Scene panel with visible actors/entities
  • Event timeline

What's in the spec but NOT in the runtime

Hard constraint engine (M2)

The spec defines 9 validation domains (spatial, referential, status, inventory, ownership, resource, quest, faction, collision). The runtime has pre-validation for a handful of common failures and fuzzy matching. It does not have:

  • A formal validator pipeline
  • Hard rejection of impossible states
  • Rollback on failed commits

Impact: The LLM can propose things that should be impossible and the engine might accept them.

Adjudication (M3)

The spec describes a formal DM adjudication layer that returns structured rulings (allow / allow_modified / deny) for mediated actions. The runtime's DM only generates world events — it doesn't adjudicate individual actions.

Impact: Creative actions that aren't in the action schema get treated as free-form observations rather than genuinely novel mechanics.

Recipe registration / learned rules (M8)

The spec describes a system where validated novel actions become new deterministic rules — the world's physics grow from play. The runtime has no recipe table and no registration pathway.

Impact: The same creative action has to be re-adjudicated every time. Nothing compounds into new mechanics.

Save/load/fork (M7)

The runtime has single-file save/load. The spec describes:

  • Multiple concurrent save slots
  • Fork points (branch the world at tick N)
  • Differential saves (store only what changed)
  • Save migration across schema versions

Impact: You can save and load, but you can't branch the timeline or migrate old saves.

Observer surfaces (M9)

The spec describes formal observer contracts with bounded projections, snapshot lineage, omission markers with provenance, and replay mechanics. The runtime has a functional SSE stream but:

  • No formal event envelope with full provenance
  • No replay from arbitrary tick
  • No multi-observer coordination

Impact: The GUI works, but building alternate viewers (e.g., a map renderer) requires reimplementing projection logic.

Faction system

The spec has full faction mechanics: membership, leadership, territory, diplomacy, taxation, guard enforcement. The runtime has reputation tags and that's it.

Impact: No formal political structures emerge. Dalla's info network and Crow's bandit-ness are informal patterns, not codified institutions.

Quest state machines

The spec defines quests as formal state machines with stages, branching conditions, and completion effects. The runtime tracks goals as simple strings with status prefixes.

Impact: "Quests" are really just agent priorities. No complex multi-agent objectives with defined success criteria.

Type registry

The spec allows runtime extension of entity types, ability definitions, and validation rules. The runtime has hardcoded type handling.

Impact: Adding a genuinely new concept (e.g., magic, diseases, vehicles) requires code changes, not data changes.

Memory compression

The spec has tiered memory: recent (verbatim), compressed (batch-summarized by LLM), important (permanent). The runtime has rolling memory + permanent lessons with no compression layer.

Impact: Old memories just disappear when the rolling window shifts. Important moments from 50 ticks ago are gone unless they became lessons.

Priority roadmap

If this project were to close the gap, the priority order would likely be:

  1. Player action input — Let the human direct the subject agent (easy, high impact on UX)
  2. Hard constraints — Formal validation before committing (medium, very high impact on coherence)
  3. Recipe registration — Compound novel actions into new mechanics (high, defines the long-term vision)
  4. Memory compression — LLM-summarize old memories instead of dropping them (medium)
  5. Faction mechanics — Formal political emergence (high, unlocks civilizational simulation)
  6. Fork/branching saves — Timeline experimentation (medium)
  7. Full observer spec — Enable alternate viewers like map renderers (high)

Why the gap exists

The runtime was built to prove the core thesis quickly: bounded LLM + deterministic validation + persistent consequences = coherent emergence. It succeeds at that proof. The full spec is what a production implementation would look like, refined over many more milestones.

Both layers are honest work. The runtime is shorter, hackier, and demonstrates the idea. The spec is longer, more rigorous, and describes the destination. Neither is "better" — they serve different purposes.

0