docs/lifestack_env.md

# lifestack_env.py — Environment Reference

`core/lifestack_env.py` — The main OpenEnv-compatible RL environment for LifeStack.

---

## Overview

`LifeStackEnv` wraps the full simulation: metric cascades, world events, partial
observability, route execution, milestone tracking, and reward calculation.

Key classes in this file:

| Class | Role |
|---|---|
| `LifeStackAction` | Pydantic action schema (metric_changes, resource_cost, action_type, …) |
| `LifeStackObservation` | Pydantic observation schema (metrics, resources, step, done, reward, metadata) |
| `LifeStackState` | Internal state (current_metrics, budget, task, world_state, hidden_state, …) |
| `PartialObsFilter` | Converts full world state into the agent's partial observation |
| `WorldEngine` | Fires deterministic/probabilistic ExoEvents each step |
| `LifeStackEnv` | The environment itself — inherits from OpenEnv `Environment` |

---

## API

### `LifeStackEnv.__init__(seed, task, max_steps=30)`

```python
env = LifeStackEnv()
env = LifeStackEnv(seed=42, max_steps=50)
```

### `LifeStackEnv.reset(...) -> LifeStackObservation`

```python
obs = env.reset(task=my_task, episode_id="ep_001")
```

Parameters:
- `task` — a `Task` object (from `core/task.py`). Defaults to `FlightCrisisTask()`.
- `seed` — optional int for reproducibility.
- `conflict` — legacy `ConflictEvent` for metric disruption on reset.
- `budget` — dict with `time`, `money`, `energy` overrides.
- `person` — optional `SimPerson` for personality-driven drift.

### `LifeStackEnv.step(action) -> LifeStackObservation`

```python
obs = env.step(LifeStackAction(action_type="execute", target="rebook_premium"))
```

Supported `action_type` values:

| Type | Effect |
|---|---|
| `inspect` | Reveals a hidden-state key into the observation |
| `execute` | Attempts to activate a Route by `target` (route id) |
| `wait` | Passes the step; triggers stress penalty after 4 consecutive waits |
| `rollback` | Reverts metrics/budget to the previous step (one-time per episode) |
| `plan` / `communicate` / `spend` / `delegate` | Apply `metric_changes` and `resource_cost` |

### `LifeStackEnv.render()`

Prints a colour-coded terminal summary of the current state and task progress.

---

## PartialObsFilter

```python
PartialObsFilter.filter(task, revealed_keys) -> dict
```

- Base: `task.visible_world` (always visible).
- Keys in `revealed_keys` that exist in `task.mutable_world` → added as-is.
- Keys in `revealed_keys` that exist in `task.hidden_state` → wrapped as  
  `{"value": <val>, "source": "inspect"}` to signal the agent they came from inspect.

---

## Observation `metadata` fields

```python
obs.metadata = {
    "world_state":     dict,   # partial view after filter
    "goal":            str,
    "active_route":    str | None,
    "milestones":      list[str],
    "events":          list[str],
    "success":         bool,
    "failure":         bool,
    "failure_reason":  str,
    "routes_remaining": int,
    "breakdown":       dict,   # reward component breakdown
    "info":            list[str],  # step-level diagnostic messages
}
```

Key `info` message prefixes:

| Prefix | Meaning |
|---|---|
| `INSPECT_REVEALED:` | Key added to inspected list |
| `INSPECT_REVEALED_HIDDEN:` | Key was in `hidden_state` — value included |
| `INSPECT_REDUNDANT:` | Key already revealed, no-op |
| `ROUTE_SUCCESS:` | Route executed and consequences applied |
| `ROUTE_BLOCKED:` | Route was closed by a prior ExoEvent |
| `PRECONDITIONS_FAILED:` | Route preconditions not met |
| `MILESTONE_UNLOCKED:` | A milestone condition was met |
| `EVENT_FIRED:` | An ExoEvent triggered this step |
| `WAIT_CAP_EXCEEDED:` | 4+ consecutive waits — stress penalty applied |

---

## End Conditions

| Condition | `done` | `success` | `failure` |
|---|---|---|---|
| `step_count >= max_steps` | ✅ | depends | — |
| All `success_conditions` met | ✅ | ✅ | — |
| `failure_condition` met | ✅ | — | ✅ |
| Any metric hits 0 | ✅ | — | ✅ |

---

## Change Log

| Date | Change |
|---|---|
| 2026-04-23 | `PartialObsFilter.filter()` now reads `mutable_world` + `hidden_state` directly from `Task`; removed `world` param; hidden keys wrapped with `source: inspect`; `INSPECT_REVEALED_HIDDEN` info message added |