# Essential Files Map

> Essential understanding for CrystFlux v1. Follow these phases in order.

## Also Useful (Optional Reference)
- `src/crystflux/v1/STRUCTURE.md` — Triadic "constitution" (layers + import rules).
- `src/crystflux/v1/core/TECH_NOTES.md` — Implementation notes and design decisions.

---

## Phase 1: Foundation (Required)
- `src/crystflux/v1/core/json_types.py` — Type system (JsonValue, JsonMapping, JsonArray, SortedJsonValue).
- `src/crystflux/v1/core/freeze_value.py` — Deep immutability enforcement (MappingProxyType, tuple).
- `src/crystflux/v1/core/void_reason.py` — VOID reason enumeration (MISSING_KEY, TYPE_MISMATCH, etc.).

**Understanding**: These files establish the foundational type system and immutability guarantees that all CrystFlux values depend on.

---

## Phase 2: Value API (Required)
- `src/crystflux/v1/core/value_api.py` — Public surface protocol (navigation, array ops, safe/strict accessors).
- `src/crystflux/v1/core/void_value.py` — VOID singleton (absorbs all failures, falsy, no revival).

**Understanding**: These files define the public interface that all values expose and the null object pattern that handles failure states.

---

## Phase 3: Core Mechanics (Required)
- `src/crystflux/v1/core/value_core.py` — BaseValue (shared freezing, classification, safe accessors).

**Understanding**: This is the base class that all mode values inherit from, providing common mechanics for value manipulation.

---

## Phase 4: Mode Semantics (Required)
- `src/crystflux/v1/core/value_modes.py` — Strict / Latent / Dream behaviors, VOID handling, hooks.

**Understanding**: These files define the three core modes and their distinct error handling strategies. This is where "truth depends on mode" is implemented.

---

## Phase 5: Array Operations (Optional - For array usage)
- `src/crystflux/v1/core/value_array.py` — ArrayOpsMixin (map, filter, first_rest, rest_last).
- `src/crystflux/v1/core/value_projections.py` — Projection helpers (it placeholder, predicates for lambda omission).

**Understanding**: These files provide array-specific operations with mode-aware fallbacks, and projection helpers for concise filter/map expressions (e.g., `filter(it.age > 21)`). Read only if you need array manipulation.

---

## Phase 6: Factory & Adapters (Optional - For implementation understanding)
- `src/crystflux/v1/boundary/mode_contracts.py` — Mode resolution utilities (CrystMode, resolve_mode).
- `src/crystflux/v1/boundary/crystallizer_port.py` — CrystallizerPort protocol.
- `src/crystflux/v1/adapters/crystallizer_impl.py` — Crystallizer implementation (hooks, frame inspection).
- `src/crystflux/v1/adapters/dream_context.py` — Dream mode context manager (research use only, explicit opt-in required via `enable_dream_mode()`).

**Understanding**: These files define how external data is converted into CrystFlux values. The `crystallizer_impl.py` provides the factory implementation with hooks and frame inspection. The `dream_context.py` enables Dream mode via `enable_dream_mode()` context manager or `with_dream_mode()` decorator (research use only; explicit opt-in required). Read only if you need to understand the factory layer or add Dream mode experiments.

---

## Phase 7: Extended (Optional - For logging/observation)
- `src/crystflux/v1/boundary/event_schema.py` — DesireEvent / MissingEvent.
- `src/crystflux/v1/boundary/desire_logger.py` / `src/crystflux/v1/boundary/missing_logger.py` — Logger contracts.
- `src/crystflux/v1/adapters/desire_logger_impl.py` / `src/crystflux/v1/adapters/missing_logger_impl.py` — Logger implementations.

**Understanding**: These files provide observation and logging capabilities for navigation failures and desire path tracking. Read only if you need monitoring or debugging features.

---

## Phase 8: Design Background (Optional - For philosophy)
- `docs/01-concepts/README.md` — Entropy and fluctuation theory.

**Understanding**: These documents explain the theoretical foundation and design philosophy behind CrystFlux. Read only if you're interested in the "why" behind the architecture.

---

## Summary

| Phase | Files | Essential For |
|-------|-------|---------------|
| 1-4 | Foundation + API + Mechanics + Modes | **Essential** — Core understanding required |
| 5 | Array Ops & Projections | Array heavy workflows |
| 6 | Factory + Adapters | Implementation work |
| 7 | Extended | Monitoring / Debugging |
| 8 | Design Background | Architecture / Philosophy |

**Recommended Path**: Complete Phases 1-4 first. These provide the essential understanding needed for most CrystFlux tasks.
