# 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

1. Truth engine must never parse natural language.
2. Only structured actions can mutate world state.
3. Every mutation must pass validation before apply.
4. Rulebook rules are data-driven and editable.
5. Interpreter output is traceable and never auto-trusted when unresolved.
6. 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)

1. Interpret raw turn text using interpreter module.
2. If unresolved:
   - return clarification/rejection state
   - persist trace turn with no applied actions
3. 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

1. LLM adapter hardening
- Tune prompt/schema validation for model drift.
- Add configurable model + timeout policy per environment.

2. Rulebook governance
- Keep versioned rulebook migration path active as rule schema evolves.
- Split rules into policy packs: creation, transfer, social.

3. Testing depth
- Expand Docker-executed integration tests for:
-  createIfMissing authorization matrix
-  transfer ownership/location checks
-  unresolved clarification flows
-  multi-action turn behavior