@tricoteuses/tisseuse 0.19.3 → 0.21.0

package/README.md

@@ -31,6 +31,49 @@ exit
 npm install
 ```
 
+### Cache de l’index des titres juridiques dans Canutes
+
+**Cache persistant non activé.** La [qualification de coût #312](https://git.tricoteuses.fr/logiciels/tricoteuses-juridique/pulls/312) ne démontre pas sa rentabilité en production. Le [correctif transactionnel #310](../../docs/architecture/correction-repli-transaction-titres-canutes.md), intégré via [#313](https://git.tricoteuses.fr/logiciels/tricoteuses-juridique/pulls/313), traite aussi les préchargements d’articles des vrais consommateurs. Son intégration ne prouve pas sa présence dans les services ; une [observation ciblée bornée](../../docs/architecture/observation-chargements-titres-canutes.md) est préparée séparément. Les tests historiques de l’[audit initial](../../docs/architecture/audit-optimisation-canutes-tisseuse.md) ne suffisaient pas à qualifier cette chaîne avec `TransactionSql`. ACL/réplication et exploitation restent à valider ; la [procédure](../../docs/architecture/deployer-optimisation-canutes-tisseuse.md) et les commandes ci-dessous ne sont pas une autorisation d’activation.
+
+L’index préconstruit des titres juridiques est stocké dans `tisseuse.text_titles_infos_parser_cache`, avec la révision de `tisseuse.text_titles_infos_parser_state`. Un lecteur n’écrit jamais ce cache : il le charge si ses gardes et sa révision sont valides, sinon construit les titres en mémoire. L’absence des tables ou de grants de lecture entraîne aussi un repli mémoire.
+
+Les linkers et `CanutesResolver` acceptent un pool `Sql` ou une transaction `TransactionSql` **`REPEATABLE READ READ ONLY` / `SERIALIZABLE READ ONLY`**. Les transactions fournies sont réutilisées sans `BEGIN` imbriqué ; `READ COMMITTED` et les transactions écrivables sont refusés, pas implicitement modifiés. BOFiP/BOSS/Ameli utilisent le premier mode. Les lectures de cache optionnelles sont protégées par savepoints ; aucune écriture du lecteur. L’index mémoire reste propre à l’objet SQL exact : une nouvelle transaction peut refaire le chargement, même dans un processus chaud. Le snapshot fourni reste ouvert pendant le parsing, avec un coût potentiel de rétention MVCC ; ce n’est pas le petit snapshot interne d’un pool.
+
+`npm run configure` crée les tables et fonctions, sans changer la version globale du schéma (12). Les déclencheurs et ACL sont une étape administrative distincte sur le **primaire**, après préparation du DDL des abonnés logiques :
+
+```sh
+npm run configure:postgres:legi-resolver -- \
+  --reader-roles '<role-lecteur>,<role-replication>' \
+  --builder-roles '<role-constructeur>'
+npm run warm:postgres:legi-titles # après les imports, sur le primaire seulement
+```
+
+Quatre déclencheurs suivent les modifications pertinentes de titres, dans la transaction source. Le warmup construit hors transaction à partir d’un snapshot et vérifie la révision avant publication ; un import concurrent provoque un retry. Un cache déjà valide est réutilisé ; `--force` impose une reconstruction. Ne pas simplement réactiver un déclencheur qui a été désactivé : réinstaller avec la commande administrative pour invalider les titres devenus douteux.
+
+L’index composite texte/numéro existant de Canutes n’est pas dupliqué. L’option administrative `--index-num` crée ou répare un index numéro seul, uniquement si les plans mesurés justifient son ajout. Ces opérations ne font plus partie de la configuration courante.
+
+Tests PostgreSQL dédiés : `TISSEUSE_CACHE_TEST_DATABASE_URL=… npm run test:postgres:legi-cache` (base neuve `tisseuse_cache_test_*`, jamais Canutes). Profilage complet en lecture seule : `npm run profile:canutes-bill -- <fichier> --format assemblee-html --date YYYY-MM-DD --titles source|cache --runs 3`. Les hashes des HTML liés/directives permettent de vérifier l’équivalence. Le [profilage après index CID](../../docs/architecture/performance-canutes-apres-index.md) mesure désormais le vrai cache persistant sur une copie jetable de 62 327 projections de titres, sans activation de production : premier chargement local médian 2 674 → 349 ms, réutilisation mémoire 0,7 ms dans les deux modes. Ce n’est pas une prédiction du gain réseau/imports en production. La même qualification reprend le court-circuit CPU de #289 et propose des lectures structurelles plus petites, avec sorties complètes inchangées sur huit PJL et les deux backends ; ces propositions restent indépendantes de l’adoption native #273/#275. Le [profilage du parcours actuel sur Canutes réelle](../../docs/architecture/profilage-canutes-liens-actions.md) identifie surtout un préchargement global d’articles trop volumineux et des parcours CPU coûteux.
+
+Pour diagnostiquer la solution actuelle, `--titles source` est désormais le mode par défaut. Le CLI impose une session PostgreSQL read-only, une seule connexion et un timeout de 30 s par requête (ajustable avec `--statement-timeout-ms`, maximum 120 s). Il fournit les temps/lignes par signature SQL sans enregistrer les paramètres ; `--details` capture les phases du parseur et du résolveur, `--plans` ajoute des EXPLAIN sans ANALYZE hors chronométrage. `--article-candidates legacy|bounded` compare le transfert global initial à l’optimisation des numéros fréquents, sur le même parseur et la même base. `bounded` est le défaut ; `legacy` est réservé au profilage. La [comparaison mesurée](../../docs/architecture/optimisation-prechargement-articles-canutes.md) donne environ 25 % de gain sur le document Sénat, sans nouvelle structure ni index. `--article-lookups individual|batch` compare les recherches texte/numéro individuelles au préchargement ciblé, en conservant le mode global choisi. `batch` est le défaut ; `individual` désactive seulement le hint pour le profilage. La [comparaison sur quatre documents](../../docs/architecture/optimisation-recherches-texte-numero-canutes.md) montre un gain chaud supplémentaire de ~1,7 s côté Assemblée et ~3 s côté Sénat sur les deux références. Les lots sont limités en couples potentiels, pas en versions, et conservent toutes les périodes. Un timeout ou une erreur produit un rapport partiel et un code de sortie non nul. Les durées SQL sont celles vues du client, transfert et décodage inclus ; ne pas additionner les phases imbriquées.
+
+L’[optimisation CPU du rendu AKN et des directives](../../docs/architecture/optimisation-cpu-rendu-directives-tisseuse.md), avec les deux optimisations SQL maintenues, réduit ensuite le traitement chaud du Sénat de **24,67 à 14,51 s** (−41,2 %), sans changer les sorties des quatre documents comparés. Les faibles variations Assemblée ne démontrent pas un gain robuste. Le marquage des tableaux cités reste conservé et les normalisations sont réutilisées dans un cache borné propre à chaque extraction, sans nouvel état global. Aucun changement de Canutes, aucune fusion ni aucun déploiement ; les coûts restants et la revue/CI du dernier commit restent à traiter.
+
+### Intégration autorisée des adoptions natives et de la performance
+
+#273 et #275 sont intégrées à `main` par `f27c62d4` puis `bde427c8`, après réussite des deux jobs de tests de chaque head. Le [rapport d’intégration](../../docs/architecture/integration-native-performance-tisseuse.md) vérifie les deux flags supprimés, les sorties combinées et l’invariance complète du candidat #297 après ces fusions. La voie CPU choisie est #297, pas une seconde intégration de #289. Les qualifications historiques ci-dessous gardent leurs bases et limites : pas de cache activé, nouveau benchmark ou déploiement manuel.
+
+### Requalification historique des propositions sur `main` 40041bee
+
+Le [rapport commun](../../docs/architecture/requalification-tisseuse-main-40041bee.md) consigne le retour favorable de David côté legi-ui avec ses limites de runtime/SHA et les rebases indépendants #273/#275/#297. Les fichiers source et sorties restent inchangés par rebase ; la combinaison native retrouve ses sorties qualifiées et #297 conserve exactement les documents du nouveau main. Les mesures de cache/performance précédentes restent historiques ; aucun cache activé, fusion ou déploiement.
+
+### Comparer Canutes et `f_legi` en lecture seule
+
+`npm run profile:legi-bill -- <fichier> --resolver canutes|flegi --format … --date … --titles source --runs 3 --details --document-output /tmp/document.json` utilise les variables `CANUTES_DB_*` pour la base choisie. Le mode `flegi` emploie un résolveur de profilage qui ne construit ni n’écrit le cache natif ; `--titles cache` exige un cache existant compatible et échoue sinon. Les modes Canutes `legacy`/`individual` ne s’appliquent pas à `flegi`.
+
+`npm run compare:legi-bills -- /tmp/canutes.json /tmp/flegi.json --max-examples 10 --output /tmp/comparaison.json` compare hors ligne l’égalité exacte, les AST/positions, les ensembles de cibles et les multiensembles des liens légaux. Les fichiers sont écrits hors chronométrage, sans écrasement et avec permissions restrictives. Les paramètres SQL ne sont pas exportés ; ne pas additionner les phases imbriquées ni confondre mémoire de fin et pic.
+
+La [comparaison réelle sur huit documents](../../docs/architecture/comparaison-canutes-flegi-tisseuse.md) montre des temps chauds du même ordre et aucun écart grammatical, mais **101 écarts de cibles** liés aux historiques et aux divisions, ainsi que des liens européens absents côté `f_legi`. Les sorties ne sont pas déclarées équivalentes ; les [huit cas de divisions sont qualifiés](../../docs/architecture/qualification-divisions-canutes-flegi.md), avec des erreurs de cibles héritées/texte parent à corriger séparément. La lecture du cache existant `f_legi` ne mesure pas le gain du cache Canutes, toujours différé.
+
 ## Server Configuration
 
 Create a `.env` file to set configuration variables (you can use `example.env` as a template). Then:
@@ -158,6 +201,42 @@ exported as an abstract class from both `@tricoteuses/tisseuse` and
 `@tricoteuses/tisseuse/server`, so applications can provide another
 storage-backed implementation.
 
+In the **native quotation-scope candidate, not yet agreed or merged**, references
+inside standalone quotations cannot change the outside amended-text context for
+any resolver. The temporary `isolateStandaloneCitationContext` property, Canutes
+override and diagnostic forwarding are removed together. Adapters declaring the
+property should remove their override. Grammar and source positions remain
+unchanged; the initial candidate deliberately changed native links/targets and
+preserved Canutes outputs. David subsequently requested anaphoric carryover
+between related quotations. The [corrective qualification](../../docs/architecture/correction-anaphores-citations-tisseuse.md)
+restores explicit same/said-code references without changing outside action
+scope, and intentionally corrects some Canutes links too. Adoption remains
+blocked pending consumer validation; archived B0235 article mapping and the
+reported future 1519 A version remain explicitly limited/unresolved.
+
+This proposal requires David's native/other-adapter validation and coordinated
+adoption with [the action-target proposal #273](https://git.tricoteuses.fr/logiciels/tricoteuses-juridique/pulls/273)
+to remove remaining bad inherited action targets. Mixed target roles still need
+review. No native SQL rewrite or adoption acceptance is presumed. See
+[the scope, evidence and explicit remaining limits](../../docs/architecture/adoption-native-citations.md).
+
+In the **native adoption candidate, not yet agreed or merged**, both bill parsers
+stop explicitly numbered unlinked references from inheriting unrelated targets
+and support only explicitly referred, unambiguous adjacent renumberings for all
+resolvers and prelinked HTML. The temporary `scopeExplicitBillActionTargets`
+property, Canutes override and all conditional plumbing are removed together;
+external adapters declaring that property should remove their override.
+
+Correct native targets change deliberately; HTML, links, grammar and positions
+remain unchanged on the tested corpus. Canutes results remain unchanged. No new
+snapshots or fixed expectations validate known native errors. Native and
+other-adapter adoption remains proposed to David (`dsmadja`), not accepted; no SQL
+reimplementation is required. See [the qualification and removal candidate](../../docs/architecture/adoption-native-cibles-actions.md).
+The separate quotation-context capability remains unchanged.
+The independent action increment did not include the optimization, cache,
+quotation-context or root-fallback work. Those separate increments are now
+combined without changing the native opt-out.
+
 The default Canutes resolver reads the title metadata it needs directly from
 `legifrance.texte_version` and builds the parser indexes in memory. Concurrent
 callers share the same preload operation, and the resulting indexes remain fixed