@tricoteuses/tisseuse 0.20.0 → 0.21.1

package/README.md

@@ -9,6 +9,22 @@ _Tricoteuses Tisseuse_ is free and open source software.
 
 _Tricoteuses Tisseuse_ started from a full rewrite of [Metslesliens](https://www.npmjs.com/package/metslesliens) by Seb35, published under the "DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE" (WTFPL) version 2.
 
+## Contexte de lecture des références
+
+`addLinksToMarkdown` et `addLinksToHtml` acceptent l’option facultative
+`parsingMode: "document" | "references"`. Le type `ReferenceParsingMode` et
+la liste `referenceParsingModes` sont exportés par le point d’entrée public.
+
+- Sans option, ou avec `"document"`, l’analyse existante est conservée :
+  « Article 2 » peut définir un article d’une loi ou d’un projet de loi.
+- Avec `"references"`, un libellé autonome non législatif tel que
+  « Article 197 du code général des impôts. » peut être lié sans ajouter « l’ ».
+  N’utilisez pas ce mode pour analyser une loi ou un projet/proposition de loi.
+- Les syntaxes doctrinales telles que « CGI, art. 197 » utilisent la grammaire
+  commune dans les deux modes ; il ne s’agit pas d’un sélecteur de corpus.
+
+Voir le [contrat et les limites de validation](../../fonctionnalités/references-autonomes-tisseuse-moulineuse.md).
+
 ## Installation
 
 ### Create database
@@ -31,6 +47,67 @@ 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. Les deux services ont été initialement déployés sur `93daabf0`, correctif et compteurs #314 inclus ; l’[observation ciblée bornée](../../docs/architecture/observation-chargements-titres-canutes.md) est close depuis le 15 octobre 2026 vers 17 h 36 Europe/Paris, avec rollbacks conservés et compteurs désactivés. Minima : 362 reconstructions web, dont neuf sur l’artefact isolé initial et 353 sur des builds ordinaires non qualifiés par leur seul HEAD ; une reconstruction et cinq réutilisations MCP. Le delta complet observé est rejoué sur copies jetables ; Moulineuse suit de nouveau `latest` sans changer d’image exécutée. Ni ces mesures locales ni ce déploiement ne qualifient la rentabilité nette de production. 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.
+
+La [qualification historique du coût net sur stock complet](../../docs/architecture/cout-net-cache-titres-canutes.md) conserve le défaut transactionnel observé avant sa correction par #313. Ses mesures restent attachées à `bb33b942` ; le bon dénominateur est le chargement évitable par objet SQL, pas seulement le redémarrage du processus. Elle n’autorise aucune activation.
+
+`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.
+
+Au checkpoint précédant les installations du 12 octobre, l’[étude locale d’indexation des racines CID](../../docs/architecture/etude-index-cid-racines-canutes.md) confirme la suppression du balayage et l’invariance des résultats sur une copie complète de `texte_version`. Un index d’expression sur le JSONB bloque cependant HOT, même hors du prédicat partiel ; une colonne CID stockée préserve HOT dans la preuve locale. **Ce n’est pas une migration prête ni un gain end-to-end mesuré** : imports, schema/réplication et rollout restent à concevoir, aucun runtime/index/cache de production n’est changé.
+
+La recommandation historique tirée des [statistiques des changements publiés sur 30/60 jours](../../docs/architecture/frequence-changements-canutes.md) révisait la priorité : ~251 fiches texte touchées/jour, dont ~153 modifiées seulement, ne justifient pas seules la colonne dédiée. **Qualifier l’index d’expression partiel plus simple en premier**, avec mesure de la charge d’import réelle et autorisation distincte. Les articles ne sont pas concernés par cet index et les compteurs du standby ne mesurent pas les écritures du primaire. Aucun changement/installation automatique.
+
+### Index d’expression CID des racines
+
+Le [lot de consolidation du 16 octobre](../../docs/architecture/consolidation-canutes-gel-2026-10-16.md) ne modifie pas les résolveurs. Après intégration, nos développements Tisseuse sont gelés quelques jours pour les remaniements de David ; le cache persistant des titres et son hook restent inactifs.
+
+L’index partiel `LEGITEXT%` peut accélérer le lookup des racines sans changer sa requête ni ajouter de colonne. [Installation, garde-fous, tests et état réel](../../docs/architecture/installer-index-cid-racines-canutes.md). Contrôle SELECT-only par défaut :
+
+```sh
+npm run configure:postgres:legi-root-cid-index
+```
+
+L’installation demande `-- --apply` et un rôle administratif sur une cible explicitement autorisée ; réparation d’une construction interrompue uniquement avec `--repair-invalid`. Aucune création depuis `configure`/les lecteurs, aucun cache/triggers/ACL activé. DDL physique répliqué, DDL logique à coordonner localement ; garder dates/ambiguïtés et contrôler imports/WAL. [Coordination Casanabo réalisée sous autorisations distinctes](../../docs/architecture/casanabo-index-cid-replication-canutes.md) : réparation des structures de réplication puis index local, sans activation du cache ni backfill d’embeddings.
+
+### 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 +235,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