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

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

---

## C1 — Behaviour Inventory

| File | LOC | Exports | Purpose |
|---|---|---|---|
| `app/src/intelligence/ArboricultureProvider.ts` | ~70 | `ArboricultureProvider`, `createArboricultureProvider` | Provider wrapper (id: `oscar-arboriculture-provider`) |
| `app/src/intelligence/adapters/types.ts` | varies | `LlmAdapter`, request/response types | Adapter interface |
| `app/src/intelligence/adapters/stub.ts` | varies | `stub` adapter | Canned responses (used as fallback) |
| `app/src/intelligence/adapters/smart.ts` | varies | `smart` adapter | 9-layer dispatcher (default) |
| `app/src/intelligence/adapters/local.ts` | varies | `local` adapter | Local Qwen 0.5B (STUB — §15.3 violation) |
| `app/src/intelligence/adapters/anthropic.ts` | varies | `anthropic` adapter | Claude API (requires key) |
| `app/src/intelligence/adapters/openai.ts` | varies | `openai` adapter | OpenAI API (requires key) |
| `app/src/intelligence/standards/BS5837.ts` | varies | plain-language summary | UK trees |
| `app/src/intelligence/standards/BS3998.ts` | varies | summary | tree work |
| `app/src/intelligence/standards/BS8545.ts` | varies | summary | trees + construction |
| `app/src/intelligence/standards/AIA.ts` | varies | summary | Arboricultural Impact |
| `app/src/intelligence/standards/AMS.ts` | varies | summary | Arboricultural Method |
| `app/src/intelligence/standards/ARB.ts` | varies | summary | ARB code of ethics |
| `app/src/intelligence/standards/library.ts` | varies | `StandardsLibrary`, `listStandards` | Standards container |
| `app/src/intelligence/standards/system-prompt.ts` | varies | `arboricultureSystemPrompt` | System prompt |

---

## C2 — State Machine

Per-adapter: `idle → calling → done | error`.
Per-provider: `idle → active (with adapter set) → swap → idle`.

---

## C3 — Side Effect List

- IDB: none directly (data flows through action chips)
- localStorage: `oscar:provider` (which adapter active)
- Network (anthropic/openai): API calls with API key from env
- Network (local): GGUF model chunks (STUB — does not actually work)

---

## C4 — Input Validation Contract

| Input | Validates | Rejection |
|---|---|---|
| API key (anthropic/openai) | non-empty | throws on `complete()` |
| Prompt | non-empty (per ask.ts writing trigger) | see ask.ts |
| Active adapter | registered | throws |

---

## C5 — Failure Modes

| Failure | Handling |
|---|---|
| anthropic 401 | throws; askOscar returns error |
| openai 401 | throws; askOscar returns error |
| local brain not downloaded | throws §15.3 ceiling violation error |
| Smart Layer 9 (no match) | returns clarifying question |

---

## C6 — User Simulations

10+ user simulations in coverage-matrix.md.

---

## C7 — Reproducibility

Smart adapter is deterministic per §22 C7. Generative adapters are not.

Tests: `tests/unit/intelligence.test.ts` (8 tests) + `vp/intelligence.test.ts` (11 invariants).

---

## C8 — Shape Matrix

Per-surface = `provider` selector in Settings.
Per-mode = `thinking-config | direct-call`.
Per-chip = `select | test | clear`.
Per-state = `idle | active | calling | error`.

---

## C9 — State Shape Inventory

### C9.1 localStorage
- `oscar:provider` (which adapter is active)

### C9.2 In-memory
- ArboricultureProvider.config.adapter
- Standards library state

### C9.3 IDB
- None (adapters are stateless for the most part)

---

## END OF INTELLIGENCE CODEX