spencer
fc10e46ccc
- Added new contracts for intent interpretation, including InterpreterOutput and ResolverMode. - Implemented deterministic intent resolver with clarity checks for ambiguous references and empty input. - Developed LLM intent resolver that communicates with an external model, handling JSON responses and fallback clarifications. - Created an interpretTurn function to manage intent resolution based on the selected resolver mode. - Introduced validation for interpreter output to ensure integrity before processing actions. - Established a turn manager to orchestrate turn processing, including action validation and world state mutation. - Added integration tests to verify the functionality of the new intent resolution system. Co-authored-by: Copilot <copilot@github.com>
3.6 KiB
3.6 KiB
CharacterGarden MVP - Current Architecture (April 2026)
Core Principle
The simulation engine is deterministic and authoritative. The LLM layer is an intent interpreter and resolver, not a source of truth.
Live System Layers
User / LLM Input (Prose) | [Intent Interpreter Layer] | [Turn Manager] | [Truth Engine + Scene Rulebook Validation] | [World Mutation Engine] | [Persistence Layer] | [Frontend/API Response]
Non-Negotiable Rules
- Truth engine must never parse natural language.
- Only structured actions can mutate world state.
- Every mutation must pass validation before apply.
- Rulebook rules are data-driven and editable.
- Interpreter output is traceable and never auto-trusted when unresolved.
- Every turn remains replayable end-to-end.
Current Canonical Actions
- inspect
- move
- open
- take
- introduce
- describe
- transfer
Action Contracts (Current)
- Action shape is contract-based in app/src/contracts/action.ts
- Validation contracts in app/src/contracts/validation.ts
- Turn contracts in app/src/contracts/turn.ts
- Interpreter contracts in app/src/contracts/intent.ts
Scene Rulebook (Data-Driven Validation)
Validation is now externalized into SceneRulebook definitions.
Key capabilities already implemented:
- Actor authorization checks (actorIdIn, actorNameIn)
- Conditional creation checks (actionMetadataEq)
- Inventory ownership checks (itemInInventory)
- Existing deterministic checks (entity type/exists, same location, attribute checks)
This supports:
- Restricting who can introduce characters
- Restricting who can create missing items via take
- Validating transfer only when actor owns item and recipient is valid
Turn Execution (Current)
- Interpret raw turn text using interpreter module.
- If unresolved:
- return clarification/rejection state
- persist trace turn with no applied actions
- If resolved:
- validate actions with truth engine + active rulebook
- apply successful actions
- persist turn, actions, validation results, and world state
Interpreter + Turn Manager (New)
- Interpreter module: app/src/interpreter/interpretTurn.ts
- Turn manager orchestrator: app/src/turns/turnManager.ts
- processTurn delegates to turn manager: app/src/turns/processTurn.ts
Current interpreter statuses:
- resolved
- needs_clarification
- rejected
Current Domain Behaviors
- take can create missing items when createIfMissing is present and actor is authorized by rulebook
- introduce can create missing characters when rulebook allows
- transfer moves items between inventories when rulebook checks pass
Persistence (Current)
SQLite tables already backing turns and world snapshots:
- turns
- actions
- validation_results
- entities
- world_states
- rulebooks
API Surface (Current)
- GET /api/state
- POST /api/turn
- POST /api/reset
- GET /api/rulebook
- PUT /api/rulebook
- GET /api/rulebooks
Operational Rule: Validation in Docker
Build and runtime checks should run in containers, not host Node.
- Backend build: docker compose run --rm app npm run build
- Frontend build: docker compose run --rm frontend npm run build
Immediate Path Forward
- LLM adapter hardening
- Tune prompt/schema validation for model drift.
- Add configurable model + timeout policy per environment.
- Rulebook governance
- Keep versioned rulebook migration path active as rule schema evolves.
- Split rules into policy packs: creation, transfer, social.
- Testing depth
- Expand Docker-executed integration tests for:
- createIfMissing authorization matrix
- transfer ownership/location checks
- unresolved clarification flows
- multi-action turn behavior