# Brain Module — Codex (per FVW v8 §22)

**Module ID:** `oscar.brain`
**Per FVW v8 v0.10.0 §22:** C1-C9 contract items.
**Status:** Constitutional behaviour contract.

---

## C1 — Behaviour Inventory

| File | LOC | Exports | Purpose |
|---|---|---|---|
| `app/src/brain/orchestrator.ts` | varies | `orchestrate` | rules → cached → AI fallback |
| `app/src/brain/rules/classify-tree.ts` | 167 | `classifyTree`, `ClassifyResult` | 10+ deterministic rules |
| `app/src/brain/rules/check-compliance.ts` | 152 | `checkCompliance` | BS5837 minimum checks |
| `app/src/brain/cached-standards.ts` | varies | `cachedStandards`, `getCached` | Pre-baked summaries |
| `app/src/brain/post-processor.ts` | varies | `postProcess` | Output cleanup |
| `app/src/brain/manifest.ts` | varies | `brainManifest`, `BrainChunk`, `BrainManifest` | Local LLM declaration (Qwen 0.5B Q4KM STUB) |
| `app/src/brain/chunk-loader.ts` | varies | `loadChunk`, `verifyGgufMagic` | Chunked download |
| `app/src/brain/download-manager.ts` | varies | `downloadBrain` | UI-triggered brain download |

**Behaviour inventory (C1):**
- `orchestrate` is the entrypoint; tries rules first, then cached, then AI
- `classifyTree` runs all 10+ rules with confidence scoring; highest-confidence wins
- `checkCompliance` runs BS5837 minimum checks
- `getCached` looks up pre-baked summaries
- `verifyGgufMagic` validates chunk integrity
- `downloadBrain` is UI-triggered

---

## C2 — State Machine with Transitions

Brain has install state:
- `not-downloaded` → `downloading` → `loaded` → `loading-into-memory` → `ready`
- Failure transitions: `not-downloaded` → `failed` (on chunk verify error)

Per `brain/download-manager.ts`.

---

## C3 — Side Effect List

| Side effect | When | Persistence |
|---|---|---|
| IDB chunk persistence | Brain download | IDB (separate chunks table or localStorage) |
| localStorage `oscar:brain-downloaded` | On download completion | `oscar:brain-downloaded` |
| Network: chunk downloads | Brain download | per-chunk GET requests |
| §15.3 CEILING VIOLATION: Qwen 0.5B exceeds 2M cap by 250× | STUB until §15.3-bis ratified |

---

## C4 — Input Validation Contract

| Input | Validates | Rejection behaviour |
|---|---|---|
| Tree description | non-empty | returns `{ category: 'unknown', confidence: 0 }` |
| Compliance check inputs | valid BS5837 fields | returns failure list |
| Chunk SHA-256 | matches expected hash | rejects chunk; marks brain as failed |

---

## C5 — Failure Modes

| Failure | Handling |
|---|---|
| Rule match confidence < 0.80 | return lowest confidence + "no match" annotation |
| Chunk verify fails | reject chunk; download manager reports error |
| AI fallback fails | return cached standard summary (Layer 5 in smart adapter) |
| §15.3 ceiling violation | brain marked as STUB; never fully available |

---

## C6 — User Simulation List

| # | Flow | Expected |
|---|---|---|
| USIM-1 | User describes "15m mature oak in good condition" | category B fires with ≥0.80 confidence |
| USIM-2 | User describes "dying tree" | category C fires (if rule exists) or unknown |
| USIM-3 | User asks for compliance check on a tree | checklist returned with pass/fail per BS5837 §X |
| USIM-4 | User clicks "Download brain" | chunks fetched sequentially; SHA verified |

---

## C7 — Reproducibility Test

Deterministic: same tree description → same classification.

Test: `tests/brain/rules.test.ts` has 44 tests verifying rule output stability.

---

## C8 — Shape Matrix

Per FVW v8 §30.

| Surface | Modes | Chips | States |
|---|---|---|---|
| Brain manifest download UI | view-only, download-triggered | navigate, cancel | not-downloaded, downloading, loaded, failed |

---

## C9 — State Shape Inventory

### C9.1 localStorage
- `oscar:brain-downloaded`

### C9.2 In-memory
- Manifest cache
- Chunk loader state
- Orchestrator state (current rule, cached standard, AI fallback result)

### C9.3 IDB
- (Brain chunks: not currently persisted; per Phase 7 design they go to localStorage)

---

## END OF BRAIN CODEX