ADR-0002 — Taxonomie des schémas de base de données

• Statut : Accepté (2026-08-30 — validation mécanique du mapping : planning/audits/database-schema-taxonomy-validation.md, VERDICT PASS). GO migration conditionné à la Vague 0.
• Date : 2026-08-30
• Portée : toute la base PostgreSQL / Supabase, toutes les couches applicatives qui y accèdent
• Références : planning/audits/b1-database-schema-audit.md, docs/architecture/domain-layer.md, docs/scientific/knowledge-model.md, planning/epics/b0-persistence-mapping-decision.md, ADR-0001, supabase/migrations/20260829150000_add_labs_hadithrank.sql

---

1. Contexte#

La base compte 61 tables métier (58 public + 3 labs), 28 enums, 6 vues, 65 fonctions et 43 triggers — tout dans public, sauf le schéma labs introduit le 2026-08-29 (inventaire vérifié : planning/audits/database-schema-taxonomy-validation.md §3). La séparation en couches décrite par docs/architecture/domain-layer.md s'arrête à l'application : côté base, aucune frontière de bounded context. Les préfixes de noms (narrator_*, commentary_*, transliteration_*) font le travail d'un schéma sans en donner les bénéfices (grants par domaine, SET SCHEMA, isolation d'exposition PostgREST, direction de dépendance visible).

L'audit planning/audits/b1-database-schema-audit.md conclut : restructuration faisable sans refonte applicative massive (client Supabase non typé → pas de régénération de types ; RPC conservables comme façade ; coût réel concentré sur ~54 appels supabase.from() directs et ~52 corps de fonctions référençant public.*). Le moment est optimal : pré-lancement, un seul précédent (labs) déjà conforme.

---

2. Décision#

2.1 Dix schémas par bounded context#

public cesse d'héberger des tables métier. Il ne conserve que la façade API (fonctions RPC exposées, vues-façade stables) et les utilitaires transverses (triggers génériques, normalisation). Le métier est réparti dans dix schémas :

Direction de dépendance (flèche pleine = dépendance structurelle déclarée ; flèche pointillée = lecture transverse par un schéma de plomberie, non exposé) :

2.2 Convention de nommage (figée)#

1. Code de 3 lettres, anglais, [a-z]{3} strict. Pas de _, pas de chiffre, pas de préfixe projet. iam toléré (acronyme établi).
2. Racines arabes écartées (rij, rwt, srh) — préférence explicite pour l'anglais.
3. Un schéma = un bounded context, jamais une couche technique abstraite (data, app).
4. La direction de dépendance est déclarée dans comment on schema et ne doit jamais s'inverser (cor ne référence jamais nar, etc.).
5. Toute évolution de cette liste = amendement de cette ADR + b1-database-schema-audit.md.

2.3 Règles d'appartenance#

• cor porte l'agrégat hadith entier : hadith_chains, hadith_chain_nodes, hadith_embeddings y restent. Pas de schéma rel — la chaîne est l'isnād d'un hadith, l'écriture est atomique, l'agrégat = la frontière. Les futures tables calculées du graphe (poids d'arêtes, caches de chemins, réseaux agrégés) iront dans qua ou un schéma dédié, jamais les tables sources.
• knw n'est pas scindé : knowledge_sources → source_editions → knowledge_entries → narrator_assertions → assertion_evidence forment une seule chaîne d'un seul contexte (docs/scientific/knowledge-model.md). Pas de src / evd.
• public = façade uniquement : RPC exposées + vues-façade stables + helpers transverses. Zéro table métier.
• Les tables projetées vers l'utilisateur mais alimentées par un moteur (ex. narrator_quality_profiles) vivent dans le schéma lu (nar), pas dans le schéma écrivain (qua). Le sens d'écriture est documenté en commentaire de table.

2.4 Accès applicatif#

• La UI n'appelle plus supabase.from() directement. Les lectures passent par des adapters src/infrastructure/supabase/<Domain>RepositorySupabase.ts qui portent le .schema() (DOMAIN_LAYER_V1.md §4).
• Les RPC restent dans public et constituent la couche API officielle ; seuls leurs corps sont re-qualifiés vers les schémas métier.
• Les vues-façade public.* sont réservées à de vraies API stables partagées, pas au masquage d'un couplage applicatif.
• Fonctions SECURITY DEFINER : search_path minimal + qualification explicite totale des références dans le corps (from nar.narrators join cor.hadith_chain_nodes). Aucune résolution implicite.

---

3. Mapping exhaustif (D4)#

3.1 Tables#

3.2 Vues#

3.3 Enums#

3.4 Fonctions#

Un trigger de validation vit dans le schéma de la table qu'il protège. Les helpers réellement génériques restent dans public.

---

4. Séquencement#

Prérequis avant Vague 1 : cette ADR passée en Accepté, §3 validé contre la base réelle, Vague 0 exécutée. Cible : avant S1.5, sans bloquer L1.4-A.

---

5. Playbook de migration (par schéma)#

begin;

create schema <ctx>;
comment on schema <ctx> is '<domaine> — dépend de <…>. Aucune dépendance entrante depuis <…>.';
grant usage on schema <ctx> to anon, authenticated;

alter table public.<t> set schema <ctx>;          -- opération catalogue, pas de réécriture
alter type  public.<e> set schema <ctx>;
alter view  public.<v> set schema <ctx>;

-- fonctions : recréer avec corps qualifié + search_path explicite
create or replace function <ctx>.<f>(...) ... 
  set search_path = <ctx>, cor, nar, public, pg_temp
  as $$ ... from <ctx>.<t> ... $$;

grant select on all tables in schema <ctx> to anon, authenticated;   -- si exposé
alter default privileges in schema <ctx> grant select on tables to anon, authenticated;

commit;

Puis, hors migration : ajouter <ctx> aux Exposed schemas du projet Supabase si lecture directe voulue ; sinon la façade RPC public suffit. Golden test SQL dédié (supabase/tests/).

---

6. Conséquences#

Positives

• Frontières de bounded context matérialisées et non contournables ; direction de dépendance lisible.
• Surface PostgREST réduite de 58 tables public à une façade RPC choisie + quelques vues.
• Grants par domaine (grant … on all tables in schema) au lieu de table par table.
• ing et qua (plomberie) deviennent non exposés → moindre privilège.
• La migration force enfin la séparation Domain / Infrastructure côté app (~54 .from() → ~5 repositories).

Négatives / coûts

• ~52 fonctions à recréer avec corps qualifié (SQL, une fois, couvert par golden tests).
• ~54 sites d'appel .from() à router via repositories (Vagues 2–3).
• Chaque nouvelle migration doit qualifier cor. / nar. / … ; les fixtures de test créent les schémas.
• search_path des fonctions SECURITY DEFINER à auditer un par un.

Neutres

• FK inter-schémas : supportées nativement par PostgreSQL, aucun changement.
• RLS : alter table set schema conserve les policies ; auth.uid() inchangé.
• Types TS : client non typé, rien à régénérer.

---

7. Alternatives écartées#

---

8. Suivi#

• §3 diffé contre la base réelle — planning/audits/database-schema-taxonomy-validation.md (2026-08-30, PASS : 61/61 tables, 6/6 vues, 28/28 enums, 65/65 fonctions, 43/43 triggers, 0 duplicate, 0 contradiction D1–D3)
• ADR passée en Accepté (2026-08-30)
• Vague 0 : snapshot + restore test + manifeste d'ordre du socle supabase/*.sql (blocage B1 du rapport de validation)
• Vague 1 exécutée + golden test
• planning/audits/b1-database-schema-audit.md §7 D4 coché