v0.2.12

chapters/038-resolver-et-lockfile.md

@@ -0,0 +1,166 @@
+# 38. Resolver et lockfile
+
+## 38.1 Modèle de résolution — V1 REQUIS — FIGÉ
+
+Trois notions sont distinguées :
+
+```text
+identity          vendor/package
+selector          vendor/package@requirement
+resolved instance vendor/package@MAJOR.MINOR.PATCH
+```
+
+Le manifest et les imports `from` utilisent le selector. Le compilateur/linker consomme finalement des instances exactes.
+
+## 38.2 Déduplication transitive — V1 REQUIS — FIGÉE
+
+Deux dépendances transitives peuvent demander des ranges qui se chevauchent.
+
+Si une même version exacte satisfait toutes les contraintes regroupables, le resolver doit préférer une instance commune.
+
+Exemple :
+
+```text
+A -> foo/bar@^2.0
+B -> foo/bar@^2.5
+```
+
+peut être résolu par une seule instance `foo/bar@2.x` compatible.
+
+Si les contraintes ne peuvent pas être satisfaites par une instance commune, plusieurs versions exactes peuvent coexister :
+
+```text
+A -> foo/bar@^2.0
+B -> foo/bar@^3.0
+```
+
+La politique normative privilégie :
+
+```text
+1. conservation des versions déjà verrouillées lorsqu'elles restent valides ;
+2. minimisation du nombre d'instances distinctes ;
+3. versions SemVer compatibles les plus élevées lorsqu'une nouvelle résolution est nécessaire.
+```
+
+L'algorithme interne exact du resolver n'est pas imposé par la Bible ; seul le résultat déterministe est normatif.
+
+## 38.3 Prereleases — V1 REQUIS — FIGÉ
+
+Un requirement stable ne sélectionne pas implicitement une prerelease.
+
+Une prerelease doit être explicitement autorisée par le requirement conformément aux règles SemVer.
+
+## 38.4 Sources et unicité du contenu — V1 REQUIS — FIGÉ
+
+Une coordonnée exacte :
+
+```text
+vendor/package@1.2.3
+```
+
+ne doit pas désigner simultanément deux contenus/sources différents dans une même résolution.
+
+Un remplacement explicite de source est possible via le manifest, mais après application du remplacement il ne reste qu'une source effective pour l'instance exacte.
+
+## 38.5 Lockfile — V1 REQUIS — FIGÉ
+
+Le lockfile est :
+
+```text
+saselang.lock
+```
+
+Il est consulté à chaque build.
+
+Il n'est réécrit que si la résolution effective change ou doit être complétée ; un build ordinaire n'effectue pas d'upgrade opportuniste lorsqu'une version verrouillée reste compatible.
+
+Le premier build sans lockfile peut le générer.
+
+## 38.6 Racine de résolution — V1 REQUIS — FIGÉE
+
+Package autonome :
+
+```text
+project.manifest.toml
+saselang.lock
+```
+
+Workspace :
+
+```text
+workspace.manifest.toml
+saselang.lock
+projects/.../project.manifest.toml
+```
+
+Lorsqu'un projet est construit comme membre d'un workspace, le lockfile du workspace fait autorité.
+
+## 38.7 Contenu minimal du lock — V1 REQUIS — FIGÉ EN PRINCIPE
+
+Le lock enregistre au minimum :
+
+```text
+identité vendor/package
+selector/requirement d'origine
+version exacte résolue
+kind
+source exacte
+locator stable lorsque pertinent
+checksum/intégrité lorsque pertinent
+commit exact pour Git
+features résolues
+instances multi-version
+graphe de dépendances
+conditions target/features pertinentes
+```
+
+Le lock ne doit pas enregistrer comme identité portable un chemin absolu découvert vers une bibliothèque système telle que `/usr/lib/...`.
+
+## 38.8 Modes de résolution — V1 REQUIS — FIGÉS EN PRINCIPE
+
+La toolchain doit fournir conceptuellement trois comportements :
+
+```text
+normal
+    utilise le lock ;
+    le complète/corrige si nécessaire ;
+    n'upgrade pas gratuitement
+
+locked
+    interdit toute modification du lock ;
+    échoue si le graphe demandé n'est pas reproductible
+
+update
+    recherche volontairement de nouvelles versions compatibles
+```
+
+Les noms CLI exacts sont à définir avec l'outillage.
+
+## 38.9 Intégrité — V1 REQUIS — FIGÉE EN PRINCIPE
+
+Les sources téléchargées contrôlées par Saselang (`registry`, `artifact`, archives distantes futures) doivent être verrouillées par checksum cryptographique.
+
+Git doit être verrouillé sur un commit exact.
+
+Les sources locales ne nécessitent pas de checksum dans le lockfile.
+
+Les bibliothèques `system`/`native` peuvent être découvertes localement sans inscrire leur chemin absolu dans le lock.
+
+## 38.10 Identité nominale des symboles externes — V1 REQUIS — FIGÉE
+
+L'identité nominale interne d'un symbole externe inclut l'instance de package résolue :
+
+```text
+resolved-package-instance
++ namespace
++ symbol
+```
+
+Ainsi :
+
+```text
+acme/foo@1.0.0 :: data.Node
+acme/foo@2.0.0 :: data.Node
+```
+
+sont deux types distincts, même s'ils possèdent la même représentation structurelle.