initial_docs/docs/ARCHITECTURE.md

# Architecture

## Product concept

Thousand-Token Terrarium is a small artificial-life toy.

The creature is not a chatbot and not a scripted pet.

It has:

- a body position in a grid,
- resources,
- senses,
- memories,
- a fast local mind,
- a slow LLM cognition layer,
- a user entity it can hear/see,
- a world the user can modify.

The interesting behavior should come from conflicts:

- hunger vs fear,
- curiosity vs danger,
- comfort vs exploration,
- user call vs distrust,
- slow thought vs fast instinct,
- memory vs present resource pressure.

## Simulation model

Use a top-down grid.

Recommended initial size:

```text
24 x 16
```

Each simulation tick:

```text
1. Increment tick.
2. Update passive world fields.
3. Apply resource drift.
4. Build creature percepts from local radius.
5. Compute appraisals.
6. Fast mind chooses primitive action.
7. Directive resolver and safety arbiter validate action.
8. Apply action.
9. Emit events.
10. Maybe run slow cognition.
11. Update memory/beliefs/notebook.
12. Render state.
```

Decision tick target:

```text
2 Hz
```

Five minutes:

```text
~600 decision ticks
```

Render rate can be higher, but simulation decisions should remain inspectable and deterministic.

## World cells

A cell may contain:

```json
{
  "terrain": "empty | wall | shelter | water | hazard",
  "object_id": "obj_123 or null",
  "entity_id": "creature | user | null",
  "field_values": {
    "food_smell": 0.0,
    "water_smell": 0.0,
    "home_smell": 0.0,
    "danger_smell": 0.0,
    "heat": 0.0,
    "cold": 0.0,
    "sound": 0.0,
    "light": 0.0
  }
}
```

Fields are derived from objects and terrain.

## Creature resources

Use normalized values from `0.0` to `1.0`.

Minimum resources:

```json
{
  "hunger": 0.0,
  "thirst": 0.0,
  "energy": 1.0,
  "fear": 0.0,
  "comfort": 0.5,
  "health": 1.0,
  "temperature": 0.5
}
```

Optional:

```json
{
  "social_trust": 0.4,
  "boredom": 0.0
}
```

Resource drift:

- hunger slowly rises,
- thirst slowly rises if thirst is enabled,
- energy falls from movement and recovers by resting,
- fear decays toward temperament baseline,
- comfort rises in shelter/home-like spaces and falls near danger,
- health changes only from meaningful harm or recovery,
- temperature drifts toward environmental heat/cold.

## World object truth

Objects have objective world-aligned properties.

Example:

```json
{
  "id": "obj_17",
  "label": "hot sweet fruit",
  "position": [12, 7],
  "glyph": "fruit_red",
  "blocks_movement": false,

  "emissions": {
    "food_smell": 0.85,
    "water_smell": 0.0,
    "home_smell": 0.0,
    "danger_smell": 0.15,
    "heat": 0.70,
    "cold": 0.0,
    "sound": 0.0,
    "light": 0.15
  },

  "affordances": {
    "edible": true,
    "drinkable": false,
    "enterable": false,
    "shelter": false,
    "inspectable": true,
    "social_like": false,
    "movable": false
  },

  "effects": {
    "on_consume": {
      "hunger": -0.45,
      "thirst": 0.0,
      "energy": 0.08,
      "fear": 0.08,
      "health": -0.03,
      "temperature": 0.15
    },
    "on_nearby": {
      "fear": 0.01,
      "temperature": 0.04
    },
    "on_inspect": {
      "familiarity": 0.12
    }
  },

  "sensory_words": {
    "visual": ["red", "round"],
    "smell": ["sweet", "food"],
    "touch": ["hot"]
  },

  "hidden": {
    "unknown_effect_strength": 0.25,
    "revealed_after": "inspect_or_consume"
  }
}
```

Object truth does not include:

- novelty,
- desire,
- fear,
- interest,
- creature-specific valence.

Those belong to creature appraisal and memory.

## Creature percepts

Percepts are derived from world truth plus creature position, range, line of sight, and memory.

Example:

```json
{
  "object_id": "obj_17",
  "distance": 2,
  "direction": [1, -1],
  "food_smell_at_body": 0.52,
  "heat_at_body": 0.31,
  "danger_smell_at_body": 0.07,
  "visual_words": ["red", "round"],
  "smell_words": ["sweet", "food"],
  "is_adjacent": false,
  "line_of_sight": true,
  "known_familiarity": 0.10
}
```

The fast mind receives percepts, not raw user text.

## Creature appraisal

Appraisals are internal computed scores.

Example:

```json
{
  "object_id": "obj_17",
  "desire_score": 0.61,
  "threat_score": 0.37,
  "novelty_score": 0.74,
  "uncertainty_score": 0.42,
  "memory_valence": -0.08,
  "dominant_conflict": "hunger_vs_heat"
}
```

`memory_valence` is defined in `docs/MEMORY_AND_EVENTS.md`.

## Fast mind

The fast mind runs every decision tick.

It receives:

- resource state,
- local grid channels,
- percepts,
- appraisals,
- memory values,
- current slow directive,
- priority modifiers,
- user/social channels.

It outputs a primitive action:

```text
move_north
move_south
move_east
move_west
wait
inspect
consume
rest
vocalize
```

It may also output a target or reason for debugging.

## Slow cognition

Slow cognition runs:

- every 20–40 ticks,
- after major events,
- with cooldown,
- never every frame.

Major events include:

- new object placed nearby,
- creature notices unknown object,
- creature consumes something,
- creature is harmed,
- fear spikes,
- user speaks nearby,
- repeated failure,
- object avoided repeatedly,
- rest/shelter event,
- strong resource conflict.

Slow cognition returns:

- private thought,
- interpretation,
- directive,
- priority modifiers,
- memory append,
- object memory updates,
- belief updates,
- ethologist note.

## User entity

The user is represented in the world.

User actions:

- move avatar,
- say text,
- place object,
- trigger demo object,
- maybe gesture.

The creature perceives the user through local social channels.

Example user percept:

```json
{
  "entity_id": "user",
  "distance": 5,
  "direction": [-1, 2],
  "recent_speech": "come here",
  "speech_loudness": 0.6,
  "past_valence": 0.15,
  "trust": 0.42
}
```

The user can influence the creature, but cannot force direct obedience.

## Map generator

The map generator should create seeded, validated worlds.

It must produce:

- connected open space,
- reachable creature spawn,
- reachable user spawn,
- at least one useful resource,
- at least one shelter/safe region,
- at least one ambiguous/risky object,
- at least one curiosity/social-like object if possible,
- enough path variety.

Validation should reject maps where:

- creature is isolated,
- useful resources are unreachable,
- hazards block all paths,
- objects are all too far away,
- object diversity is too low.

Demo scenes may use fixed seeds.

## UI

Minimum UI:

- grid terrarium,
- play/pause/speed/reset,
- object creator,
- user speech input,
- resource bars,
- Mind Lens,
- event log,
- notebook,
- model/compliance diagnostics,
- demo mode.

The UI must remain simple and readable.