@tricoteuses/tisseuse 0.14.12 → 0.14.13

package/README.md

@@ -153,11 +153,12 @@ Les documents sans URL, externes au Sénat, sans Akoma Ntoso ou en échec de par
 
 ## Legal reference resolver
 
-Tisseuse resolves legal references through the Canutes-backed `LegiResolver`.
-`LegiResolver` is exported as an abstract class from both
-`@tricoteuses/tisseuse` and `@tricoteuses/tisseuse/server`, so applications can
-provide another storage-backed implementation. At process startup, the Canutes
-resolver reads the title metadata it needs directly from
+Tisseuse resolves legal references through a `LegiResolver`. `LegiResolver` is
+exported as an abstract class from both `@tricoteuses/tisseuse` and
+`@tricoteuses/tisseuse/server`, so applications can provide another
+storage-backed implementation.
+
+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
 for the lifetime of the process.
@@ -216,6 +217,34 @@ The caller owns the PostgreSQL client and its lifecycle. Importing the adapter
 does not open a connection, read environment variables, or preload title data.
 The generic Tisseuse entry points do not load this adapter.
 
+`FlegiResolver` expects the flat database schema generated by `legi-flat-db`,
+including `text_titles_infos` and `text_titles_infos_parser_cache`. The first
+table is the source relation generated from Canutes. The second is a JSONB cache
+of the parser-aware `TextTitlesInfos` structure used by Tisseuse. It is filled
+lazily by `FlegiResolver`, not by `legi-flat-db` SQL, so the TypeScript parser
+logic remains in this package.
+
+On `preloadTextTitlesInfos`, `FlegiResolver` first tries to load the `current`
+cache row matching the package cache format version. On a miss or format
+mismatch, it takes a PostgreSQL advisory transaction lock, re-checks the cache,
+locks `text_titles_infos` through the `SECURITY DEFINER` helper
+`lock_text_titles_infos_for_parser_cache()`, rebuilds the parser indexes from
+`text_titles_infos`, writes the JSONB cache, then installs it in memory. A trigger
+on `text_titles_infos` invalidates the cache by deleting the `current` row when
+the source title relation changes.
+
+Operational notes for `f_legi` deployments:
+
+- Regenerate or migrate the flat database before using this adapter version; the
+  schema check requires `text_titles_infos_parser_cache`.
+- The runtime role needs `SELECT` on the source tables, `INSERT`/`UPDATE` on the
+  cache table, and `EXECUTE` on `lock_text_titles_infos_for_parser_cache()`.
+- The owner of the `SECURITY DEFINER` helper must be able to lock
+  `text_titles_infos`; `legi-flat-db` sets the helper owner to the importing
+  role.
+- Increment `textTitlesInfosParserCacheFormatVersion` when the serialized
+  `TextTitlesInfos` shape changes.
+
 External adapters can extend the public `LegiResolver` class. The public package
 also exports the resolver option types and `buildAndInstallTextTitlesInfos`, so
 an adapter does not need deep imports into Tisseuse.