docs/learnings.md

# Learnings — Failures, Workarounds & Time Savers

## Purpose
Read this file when hitting a repeated error or unexpected behaviour.
Each bullet is a one-liner under 15 words.
No explanations. Only things that save time in future sessions.

---

## Rules for This File
- One line per learning, under 15 words
- Add immediately when a failure or workaround is found
- Never delete a line — they compound over time
- Group by category as list grows

---

## Supabase
- [ ] Add learnings here as they are discovered

## Auth
- [ ] Add learnings here as they are discovered

## Testing
- [ ] Add learnings here as they are discovered

## Next.js
- [ ] Add learnings here as they are discovered

## Deployment
- [ ] Add learnings here as they are discovered

## General
- pyarrow DLL blocked by Windows App Control — all sklearn/sentence_transformers fail locally
- TRL GRPOConfig import chain: trl→transformers→peft→sklearn→pyarrow (DLL fails on Windows)
- Python 3.13 `try:` shows in traceback frame but except block still executes
- Initialize loop variables (terminated, truncated) BEFORE try/except blocks to avoid NameError
- Greedy `\{.*\}` in re.search captures too much — use balanced-brace walker for JSON extraction
- defender.py LLM sometimes returns multiple JSON objects — "Extra data" JSONDecodeError
- pytest must run from project ROOT, not from viral_script_engine/ subdir (module path issue)
- dry-run patches R2/R5 score methods before env import to avoid pyarrow DLL load
- run_escalation_demo.py must also patch R2/R5 stubs at top before ViralScriptEnv import

## Testing
- Mock R2 CoherenceReward.score and R5 DefenderPreservationReward.score in any env test
- GRPOConfig test: use try/except import, not pytest.importorskip (trl is "installed" but fails)

---

## Example Format (remove when real entries exist)
```
## Supabase
- RLS blocks all queries by default — always add select policy first
- supabase db push fails silently if migration has syntax error
- Foreign key inserts require parent row to exist first

## Auth
- JWT expires after 1hr — always call refreshSession before DB ops
- getSession returns null on hard refresh — use onAuthStateChange instead

## Testing
- Jest mock must be reset between tests or state bleeds across cases
- Supabase client must be mocked at module level not inside test

## Next.js
- useEffect runs twice in strict mode — guard with cleanup function
- API routes do not have access to cookies without explicit parsing
```