# CrystFlux v1 Triadic構造ガイド

このガイドは、CrystFlux v1のtriadicディレクトリ構造（`core/` / `boundary/` / `adapters/`）を
AIコーダーが誤解なく把握するための **憲法＋標識** です。

目的: 推論コストを低減し、早期収束（思い込み改変）を防ぎ、依存の逆流（`core/` を外側へ引っ張る変更）
を避ける。

起点:
- `ESSENTIAL_FILES_MAP.md`（リポジトリ直下）
- `src/crystflux/v1/core/value_api.py`（public surface）

## Triadic層（入れ子／同心円モデル）

矢印ではなく「中心と外縁」で理解する（解釈の分岐を減らす）:
core が不変の中心、boundary が契約としてそれを包み、adapters が統合/IOとしてさらに外側を包む。

### ASCII（常に読める）

```text
+-----------------------------------+
| adapters  （統合 / IO）           |
|  +-----------------------------+  |
|  | boundary（契約）             |  |
|  |  +-----------------------+  |  |
|  |  | core（不変ロジック）    |  |  |
|  |  +-----------------------+  |  |
|  +-----------------------------+  |
+-----------------------------------+
```

### Mermaid（表示環境でレンダリングされる場合）

```mermaid
flowchart TB
  subgraph A[adapters（統合 / IO）]
    subgraph B[boundary（契約）]
      C[core（不変ロジック）]
    end
  end
```

## 各層
- **Core**: 不変値処理（外部統合を含めない）。
  - 主要: `core/value_api.py`, `core/value_modes.py`, `core/value_core.py`, `core/void_value.py`
- **Boundary**: 契約とスキーマ（何があるか、を定義する。配線方法ではない）。
  - 主要: `boundary/crystallizer_port.py`, `boundary/event_schema.py`, `boundary/*_logger.py`
- **Adapters**: 配線/統合（契約をどう実装し、どう接続するか）。
  - 主要: `adapters/crystallizer_impl.py`, `adapters/*_logger_impl.py`, `adapters/pydantic.py`

## Importルール

依存は矢印で書かず、「importしてよい／してはいけない」で固定する。

- `core/` は `boundary/` と `adapters/` を import してはいけない。
- `boundary/` は `core/` を import してよい。
- `adapters/` は `boundary/` と `core/` を import してよい。

### 許可 / 不許可（要約表）

| import元 | import可 | import不可 |
|---|---|---|
| `crystflux.v1.core.*` | 標準ライブラリ, `crystflux.v1.core.*` | `crystflux.v1.boundary.*`, `crystflux.v1.adapters.*` |
| `crystflux.v1.boundary.*` | 標準ライブラリ, `crystflux.v1.core.*`, `crystflux.v1.boundary.*` | `crystflux.v1.adapters.*` |
| `crystflux.v1.adapters.*` | 標準ライブラリ, `crystflux.v1.core.*`, `crystflux.v1.boundary.*`, `crystflux.v1.adapters.*` |（v1では特になし）|

注: 実行時は “adapters が core を呼ぶ” ことが多いが、import方向は上のルールが正。

## AIコーダー向けTips

- 変更の起点は `src/crystflux/v1/core/value_api.py` と `ESSENTIAL_FILES_MAP.md`。
- `core/` は純粋に保つ: 観測/ログは `boundary/` + `adapters/` で外付けする。
- モード: Strict（fail-fast）, Latent（欠損/不一致をVOIDへ）, Dream（未定義許容＋観測）。
- `with_value`/`map` の意味論（VOID → None、JSON正規化）は
  `src/crystflux/v1/core/TECH_NOTES.md` に記載。`with_value` は新しい Value を返し、
  元の Value を変更しない。

## 例
`Crystallizer.latent(data).get('key').as_str()` – VOIDフォールバック。

## リソース
- 読み順マップ: `ESSENTIAL_FILES_MAP.md`
- 設計哲学: `docs/01-concepts/README.md`
