CharacterGardenStack/project.md

# CharacterGarden — System Bible (MVP Architecture)

## Purpose

CharacterGarden is a deterministic roleplay and simulation framework.

The system separates:

* Natural language (LLM / user input)
* Structured intent (parsed actions)
* Truth validation (rules engine)
* World state (persistent simulation)

The system MUST remain deterministic at the core.

---

## Core Principle

The LLM is NOT the source of truth.

The LLM is used ONLY for:

* Parsing natural language → structured actions
* Generating narrative output

ALL validation, state changes, and rules are handled by deterministic code.

---

## System Pipeline

All input MUST pass through the following pipeline:

1. PROSE INPUT

   * Source: user or AI
   * Format: free text

2. PARSER LAYER

   * Converts text → structured actions
   * May use LLM or rule-based parsing
   * Output MUST follow strict schema (see Action Contract)

3. ACTION CONTRACT (STRICT)

   * Only valid structured objects allowed past this point
   * No free text allowed beyond this stage

4. TRUTH ENGINE

   * Deterministic validation of actions
   * No LLM usage allowed
   * Returns validation results

5. WORLD STATE UPDATE

   * Applies valid actions
   * Rejects or partially applies invalid ones

6. RESPONSE GENERATION

   * LLM converts results into narrative output

---

## Hard Rule

The Truth Engine MUST NEVER:

* Parse natural language
* Infer missing intent
* Use probabilistic logic
* Call an LLM

If it does, the architecture is broken.

---

## Action Contract (REQUIRED)

All actions MUST conform to this schema:

```ts
export type Action = {
  actorId: string;
  type: string;
  targetId?: string;
  locationId?: string;
  metadata?: Record<string, any>;
};
```

No additional fields allowed unless explicitly added here.

---

## Turn Structure

Each turn MUST be stored and processed as:

```ts
export type Turn = {
  id: string;
  rawText: string;
  actions: Action[];
  validation: ValidationResult[];
  createdAt: number;
};
```

---

## Validation Result Contract

```ts
export type ValidationResult = {
  actionIndex: number;
  success: boolean;
  reason?: string;
  message?: string;
};
```

Examples:

* "not_your_turn"
* "object_not_found"
* "door_locked"

---

## Required System Layers

### 1. Parser Layer

Function:

```ts
parseTextToActions(text: string): Action[]
```

Responsibilities:

* Convert text → valid Action[]
* Resolve references ("he", "the door")
* May fail or return empty list

Allowed:

* LLM usage
* Heuristics

Not allowed:

* World state mutation
* Validation logic

---

### 2. Truth Engine

Function:

```ts
validateActions(actions: Action[], worldState: WorldState): ValidationResult[]
```

Responsibilities:

* Validate each action deterministically
* No mutation

---

### 3. World State Engine

Function:

```ts
applyActions(actions: Action[], results: ValidationResult[], worldState: WorldState): WorldState
```

Responsibilities:

* Apply ONLY valid actions
* Maintain consistency

---

## World State Requirements

World state MUST:

* Be serializable
* Be versionable
* Support rollback
* Support branching

---

## Database Requirements

Use SQLite.

Minimum tables:

* turns
* actions
* validation_results
* entities
* world_states

Each turn MUST be persisted.

---

## Entity System

Entities MUST have stable IDs.

Example:

```ts
type Entity = {
  id: string;
  name: string;
  type: string;
  attributes: Record<string, any>;
};
```

Parser MUST resolve references to entity IDs.

---

## Failure Handling

Failure is FIRST-CLASS.

Example:

```ts
{
  success: false,
  reason: "door_locked",
  message: "The door cannot be opened."
}
```

The system MUST:

* Return failures clearly
* Allow LLM to narrate failures
* NOT silently fix invalid actions

---

## LLM Adapter Rules

The LLM Adapter MUST:

* Never mutate world state
* Never validate actions
* Only transform data

---

## Development Phases

### Phase 1 — Contract Enforcement (CURRENT)

* Define Action, Turn, ValidationResult
* Refactor all code to use contracts
* Remove any free-text logic from truth engine

---

### Phase 2 — Minimal Truth Engine

Implement test domain:

* Tic-tac-toe OR simple door system

Goal:

* Fully deterministic validation
* No LLM required for correctness

---

### Phase 3 — Parser Improvement

* Add LLM parsing
* Add reference resolution
* Improve action extraction

---

### Phase 4 — Memory System

* Persist entities
* Track history
* Add retrieval support

---

## Non-Goals (For Now)

* No complex AI reasoning inside truth engine
* No autonomous agents
* No multi-agent planning

---

## thoughts.md Requirement

Copilot MUST maintain a file:

```
/thoughts.md
```

After each major change, it MUST append:

* What was implemented
* Why it was implemented
* What assumptions were made
* What remains unclear

This is REQUIRED to maintain continuity across sessions.

---

## Definition of Done (MVP)

The system is complete when:

* A user can input text
* It is parsed into structured actions
* Actions are validated deterministically
* World state updates correctly
* A narrative response is generated

WITHOUT requiring the LLM for correctness.

---

## Final Rule

If any part of the system depends on the LLM to maintain logical correctness,
the architecture has failed.

The LLM is an interface layer, not a reasoning authority.