docs/migration/rewrite-status-s46.md

# État du rewrite — Sprints A14-S46 puis S47-S57 (audit + remédiation)

Ce document synthétise l'état du rewrite du Picarones après les 20 sprints
S27-S46 réalisés sur la directive *« rewrite tout, le plus solide, sans
dette technique »*, puis les 11 sprints S47-S57 d'audit/remédiation des
30 dettes identifiées en revue de fin de rewrite (audit 2026-05).

## Statut réel — partial rewrite, pas full rewrite (S57, audit #21 + #24)

Le rewrite est **fonctionnellement complet sur le périmètre des contrats
et de l'architecture cible** (circles propres `domain → formats →
evaluation → pipeline → adapters → app → reports_v2 → interfaces`,
services applicatifs, adapters natifs OCR/LLM/VLM, pipeline planner,
artifact store, web UI native).  La formulation initiale *« rewrite
fonctionnellement complet »* était trop forte sur deux dimensions
relevées par l'audit :

1. **Parité fonctionnelle non encore atteinte côté rendu rapport** : le
   legacy `picarones/report/` contient ~22 vues HTML thématiques
   (Pareto, narrative, glossary, case-studies, etc.) que `reports_v2/`
   ne reproduit pas intégralement.  Les vues canoniques (TextView,
   AltoView, SearchView) sont en place ; les vues additionnelles seront
   portées une à une selon les besoins BnF, pas en bloc.

2. **Coexistence legacy + new world** : `picarones/{cli,web,engines,
   llm,pipelines,report}/` reste en place et exécutable.  Un caller
   externe peut encore importer depuis n'importe lequel.  Cette
   coexistence est volontaire (cf. *Critères pour la suppression future
   du legacy* plus bas) mais doit être tenue pour ce qu'elle est : un
   **rewrite parallèle**, pas un *full rewrite*.  Les usages production
   sont à migrer caller par caller.

3. **Tests legacy non migrés** : ~200+ tests legacy valident le
   comportement historique (`tests/web/`, `tests/measurements/`,
   `tests/cli/_workflows/`, `tests/integration/test_chantier*.py`,
   etc.).  Ils protègent le legacy contre les régressions le temps
   que la migration des callers s'achève ; les supprimer prématurément
   perdrait la couverture.

## Inventaire des modules legacy

| Module | Statut | Nouvelle implémentation | Action S46 |
|--------|--------|--------------------------|------------|
| `picarones/cli/` | LEGACY | `picarones/interfaces/cli/` (3 commandes) | Conserver — features CLI manquantes |
| `picarones/web/` | LEGACY | `picarones/interfaces/web/` (skeleton + 3 routers + UI) | Conserver — UI riche manquante |
| `picarones/engines/` | LEGACY | `picarones/adapters/ocr/` (5 natifs) | Conserver — feature parité (confidences) |
| `picarones/llm/` | RE-EXPORT | `picarones/adapters/llm/` | Déjà migré (re-export pur) |
| `picarones/pipelines/` | LEGACY | (composition via pipeline DAG natif S6+) | Conserver — pas d'équivalent direct |
| `picarones/report/` | LEGACY | `picarones/reports_v2/{html,csv,json}/` | Conserver — vues thématiques manquantes |

## Ce qui est DÉFINITIVEMENT migré (S27-S45)

### Sprints S27-S29 — Fondations architecturales
- `ProjectionEngine` + `EvaluationEngine` séparés (S27)
- `PipelinePlanner` + `ExecutionPlan` (S28)
- `ArtifactStore` avec hash multi-paramètres + persistance filesystem (S29)

### Sprints S30-S34 — 5 OCR engines natifs (NO SHIM)
- `TesseractAdapter` (S30)
- `PeroOCRAdapter` (S31)
- `MistralOCRAdapter` (S32)
- `GoogleVisionAdapter` (S33)
- `AzureDocIntelAdapter` (S34)

Tous héritent directement de `BaseOCRAdapter` (S26), pas du legacy
`BaseOCREngine`. Le legacy peut être supprimé une fois les confidences
migrées vers `ConfidenceArtifact` (sprint dédié).

### Sprints S35-S38 — Web app native (NO SHIM)
- Skeleton FastAPI avec DI (`WebAppState`, `create_app`) — S35
- Routers corpus + benchmark — S36
- JobStore SQLite + jobs router — S37
- UI Jinja2 + static + i18n FR/EN — S38

### Sprints S39-S41 — Format YAML + domain cleanup
- RunSpec étendu (`inputs_from`, `preferred_text_output`) — S39
- `PipelineSpec` migré dans `domain/` — S40
- `artifacts_index.jsonl` séparé — S41

### Sprints S42-S43 — Reports CSV + JSON
- `CsvReportRenderer` — S42
- `JsonReportRenderer` — S43

### Sprints S44-S45 — LLM/VLM nativement intégrés (NO SHIM)
- Les 4 LLM adapters (Anthropic, OpenAI, Mistral, Ollama) ont désormais
  un `execute()` natif compatible `StepExecutor` — S44
- 4 VLM adapters dérivés via MRO multiple — S45

## Critères pour la suppression future du legacy

Pour chaque module legacy à supprimer, il faut :

1. **Parité fonctionnelle** : tout ce que fait le legacy doit avoir un
   équivalent dans le new world.
2. **Migration des tests** : les tests legacy doivent soit migrer vers
   le new world, soit être identifiés comme supprimables.
3. **Migration des callers externes** : si des callers externes
   importent depuis `picarones.web.app` (par ex. dans le HuggingFace
   Space), ils doivent être migrés en amont.
4. **Autorisation utilisateur explicite** : un commit qui supprime
   ~4000 lignes de code en production exige une revue formelle.

## Statistiques globales du rewrite (S1-S57)

- **Tests** : ~4910 tests, 11 skipped, 0 failed au S46 (vs 4504 au
  début du rewrite, S26).  Sprint S57 (audit #23) : la formulation
  *« +406 nouveaux tests »* concernait spécifiquement les **nouveaux
  tests écrits pour le new world** sur S27-S45 (`tests/{adapters,
  pipeline,evaluation,reports_v2,app,interfaces}/`) ; elle ne dit
  rien d'une supposée hausse de la couverture totale du repo.  Les
  tests legacy (`tests/{web,cli,engines,measurements,...}/`) ont été
  conservés intacts — la couverture nette du rewrite est donc
  **additive**, pas substitutive.
- **Lint** : `ruff check picarones/ tests/` clean.
- **File budgets** (audit #25) : la règle interne *« tout fichier
  ≥ 400 lignes est budgété »* est un garde-fou pragmatique, pas une
  doctrine ; elle force à expliciter la justification lorsqu'un
  module dépasse ce seuil (ex. `interfaces/web/app.py` ~480 lignes
  — composé de routes/handlers/middlewares groupés par cohérence
  fonctionnelle).  Aucun fichier ne dépasse 800 lignes après S46.
- **Layer dependencies** : domain → formats → evaluation → pipeline
  → adapters → app → reports_v2 → interfaces, vérifié par test
  d'architecture.

## Sprints d'audit/remédiation S47-S57 (audit institutional readiness)

L'audit *institutional readiness 2026-05* a identifié 30 dettes
techniques résiduelles après le rewrite ciblé.  Elles ont été
adressées en 6 vagues (S47-S57) :

| Vague | Sprint | Issues | Thème |
|-------|--------|--------|-------|
| pré-audit | S47-S48 | #1, #2 | ArtifactStore wired, JobRunner threading |
| A | S49-S51 | #3-#7 | Web security middlewares, confidences sidecar, output paths |
| B | S52-S53 | #8-#11 | AdapterStepError hierarchy, Mistral routing strict, normalize_llm_content path |
| C | S54 | #6 | MRO guard `__init_subclass__` BaseVLMAdapter |
| D | S55 | #14 | Live integration tests `tests/integration/live/` |
| E | S56 | #12, #13, #17, #18, #19, #20, #22, #27, #28, #29 | JobStore schema_version, busy_timeout, model_dump(mode="json"), `_infer_pipeline_name`, etc. |
| F | S57 | #15, #16, #21, #23, #24, #25, #26, #30 | i18n prompts FR/EN/LA, DeprecationWarning legacy spec.py, doc rectifications |

**Tous les 30 issues sont adressés au S57**.  Les détails sont dans
`docs/audits/remediation-plan-2026-05.md`.

### Notes spécifiques (S57)

- **#15 Lazy imports SDK tiers** : les imports `mistralai`, `anthropic`,
  `openai`, `ollama` sont **intentionnellement à l'intérieur des
  méthodes** (`MistralOCRAdapter._call_chat_vision_api`, etc.) plutôt
  qu'au top du module.  Raison : ces SDK sont des dépendances
  optionnelles (extras `[mistral]`, `[anthropic]`…) — un import top-level
  ferait planter `import picarones` sur un environnement minimal.
  Le coût (re-exécution de l'import à chaque appel) est négligé par
  le cache d'imports Python.
- **#16 i18n prompts FR/EN/LA** : `BaseLLMAdapter.DEFAULT_CORRECTION_PROMPTS`
  et `BaseVLMAdapter.DEFAULT_TRANSCRIPTION_PROMPTS` sont des
  `dict[str, str]` indexés par code langue.  Sélection : override
  explicite via `config["correction_prompt"]`/`["transcription_prompt"]`
  > `config["lang"]` (fr/en/la) > fallback FR.
- **#26 Suppression du re-export `picarones.pipeline.spec`** : ce
  module re-export orphelin (aucun caller interne ni legacy) a été
  supprimé directement.  Le chemin canonique unique est
  `picarones.domain.pipeline_spec`, re-exporté au niveau `__init__`
  des packages `picarones.domain` et `picarones.pipeline` (API
  publique standard).
- **#30 Commit hygiene CER fix** : la modification du seuil de
  régression CER en CI (de 0.10 à 0.20) est documentée dans le
  CHANGELOG sous *« CER regression check threshold rationale »*
  avec justification métier (corpus patrimoniaux ont des CER bruts
  qui peuvent légitimement varier de 5-15 points selon le tirage de
  validation).

## Prochaines étapes possibles (post-rewrite)

1. **Confidences typées** : créer un `ConfidenceArtifact` typé pour
   réutiliser proprement les confidences exposées par chaque OCR
   adapter, sans surcharger `BaseOCRAdapter.execute()`.
2. **Vues HTML manquantes** : porter Pareto, Narrative, Glossary du
   legacy `report/` vers `reports_v2/html/` une vue à la fois.
3. **CLI complète** : porter les commandes manquantes (`history`,
   `compare`, `pipeline`, `diagnose`, etc.) dans
   `interfaces/cli/`.
4. **Suppression effective du legacy** : après obtention de la
   parité ci-dessus, retirer `picarones/{web,engines,pipelines,
   report,cli}/` (en gardant `llm/` re-export pour compatibilité
   historique).