Sasedev/saselang-bible
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.14

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-12 18:12:13 +02:00
parent 18306bdc8c
commit 57ae671f88
27 changed files with 2060 additions and 623 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
chapters/001-trajectoire-dimplementation.md
View File

@@ -2,7 +2,7 @@
## 1.1 V1 — V1 REQUIS — FIGÉ
La V1 constitue le premier environnement réellement utilisable de Saselang.
V1 constitue la première implémentation cohérente et réellement utilisable de Saselang, mais reste avant tout une **base/POC d'implémentation et de validation**. Elle n'est pas la baseline publique de compatibilité durable.
Objectifs :
@@ -15,7 +15,7 @@ analyse sémantique
HIR
Sase IR
interpréteur
a backend LLVM
backend LLVM
Core V1
SDK initial
manifests et workspaces
@@ -29,6 +29,8 @@ LLVM est le premier backend compilé de V1.
La conception de Saselang ne doit cependant pas faire de LLVM une dépendance sémantique du frontend.
V1 doit être suffisamment complète pour révéler les erreurs de conception réelles du langage. Des corrections incompatibles restent possibles avant la baseline publique V3 lorsqu'elles sont motivées, documentées et répercutées de façon cohérente dans la Bible, le Core et la toolchain.
## 1.2 Couverture LLVM — V1 REQUIS — FIGÉ EN PRINCIPE
Le backend natif V1 doit rester suffisamment générique pour exploiter les architectures, formats objet et capacités que LLVM peut représenter.
@@ -42,12 +44,11 @@ représentable par le backend
mais non officiellement supportée par la toolchain Saselang
```
## 1.3 V2 — SELF-HOSTING
## 1.3 V2 — SELF-HOSTING / SECOND POC
La V2 reste également une génération interne. Elle a pour objectif principal la réécriture/self-hosting du compilateur, de l'interpréteur et des outils en Saselang. Des corrections architecturales incompatibles avec V1 restent acceptables si elles sont nécessaires et documentées.
V2 est principalement la génération de self-hosting et le second POC structurel du langage.
La V2 a pour objectif principal de réécrire progressivement en Saselang les composants réalisés en V1 :
Elle a pour objectif de réécrire progressivement en Saselang les composants réalisés en V1 :
```text
compiler frontend
@@ -59,14 +60,32 @@ package/build tooling
Core/SDK lorsque pertinent
```
La V2 est d'abord une étape de validation du langage par lui-même, pas une excuse pour redéfinir arbitrairement la sémantique V1.
Le self-hosting doit révéler les contraintes réelles d'un grand programme Saselang écrit en Saselang lui-même.
## 1.4 V3+ — FUTUR V3+
Des corrections architecturales incompatibles avec V1 restent acceptables lorsqu'un besoin concret les justifie. V2 n'est cependant pas une excuse pour ajouter des mécanismes spéculatifs ou redéfinir arbitrairement la sémantique.
La première distribution générale du compilateur et de l'écosystème Saselang est envisagée à partir de V3 ou d'une génération ultérieure. C'est à partir de cette baseline publique que la compatibilité source, binaire et de tooling devra être protégée beaucoup plus strictement.
Une fonctionnalité future peut être réservée avant son implémentation uniquement lorsqu'un besoin réel est déjà identifié et qu'il est utile de protéger son espace syntaxique ou sémantique. Saselang ne réserve pas des mécanismes purement hypothétiques « au cas où ».
## 1.4 V3+ — BASELINE PUBLIQUE
À partir de V3+, les efforts pourront se concentrer sur les autres environnements et backends :
V3 est envisagée comme la première génération réellement déterminante pour la stabilité publique du langage et de son écosystème.
À partir de cette baseline, la compatibilité :
```text
source
Core
tooling
packages
artifacts
et, lorsque défini, ABI/binaire
```
doit être protégée beaucoup plus strictement.
Les changements incompatibles deviennent alors des décisions exceptionnelles, versionnées et explicitement justifiées.
À partir de V3+, les efforts pourront également se concentrer sur les autres environnements et backends :
```text
browser runtime / extension

18
chapters/005-types-primitifs.md
View File

@@ -116,7 +116,7 @@ Le modulo euclidien sera une opération explicite du Core/SDK.
La sémantique flottante suit IEEE pour les représentations et opérations applicables. Les littéraux sont arrondis vers le type flottant cible selon les règles IEEE normales ; Saselang n'exige pas qu'un littéral décimal soit représentable exactement.
Le tableau exact des cas particuliers, conversions, NaN, infinities, division par zéro et comportement de `%` flottant doit être normatif avant implémentation finale.
Les règles de conversion, `NaN`, infinities et zéros signés déjà figées sont détaillées au chapitre 24 et dans l'annexe `A-numeric-conversions.md`. Les règles restantes des opérations flottantes, notamment division par zéro et comportement de `%`, doivent encore être fermées avant implémentation finale.
## 5.7 Littéraux numériques — V1 REQUIS — FIGÉ EN PRINCIPE
@@ -215,4 +215,20 @@ bitcast<float16>(value)
qui réinterprète les bits selon les règles de `bitcast`. Les règles de plage et d'échec des conversions sont différées au groupe casts/conversions.
## 5.8 Abstraction Core `Numeric` — V1 REQUIS — DIRECTION FIGÉE
Le Core doit fournir une véritable abstraction nominale `Numeric`.
`Numeric` n'est pas une catégorie syntaxique spéciale du compilateur et ne remplace pas les types primitifs. Elle sert à exprimer des contrats génériques réels :
```text
where T implements Numeric
```
Les primitives numériques Saselang satisfont le contrat `Numeric` via le Core.
Les types utilisateurs pourront satisfaire `Numeric` uniquement en implémentant explicitement son contrat lorsque celui-ci sera définitivement spécifié. La présence de méthodes ressemblant à des opérations numériques ne suffit jamais par duck typing.
La hiérarchie exacte de `Numeric`, ses membres et ses relations éventuelles avec `Comparable<T>` et les interfaces `Op...` restent à fermer lors de la définition exhaustive du Core.
---

131
chapters/007-types-nominaux-et-fichiers-saseltype.md
View File

@@ -16,8 +16,137 @@ enum
union
```
Le nom du fichier doit correspondre au nom du type.
Le nom du fichier doit correspondre exactement au nom du type.
Le fichier ne contient pas d'autres types top-level ni de fonctions auxiliaires top-level.
## 7.3 Ordre source et découverte nominale — V1 REQUIS — FIGÉ
L'ordre textuel des fichiers ou des déclarations n'a pas de signification sémantique pour la résolution des types.
Le frontend doit d'abord construire un index des déclarations nominales accessibles avant de finaliser leurs dépendances sémantiques.
Saselang n'expose pas de syntaxe utilisateur de forward declaration telle que :
```text
class Foo;
struct Bar;
```
Une forward declaration manuelle serait redondante avec la collecte nominale du compilateur et réintroduirait des problèmes de cohérence inutiles.
## 7.4 États conceptuels de complétude — V1 REQUIS — FIGÉ EN PRINCIPE
La spécification distingue conceptuellement :
```text
nominalement connu
identité du type, kind et paramètres génériques connus
sémantiquement complet
déclaration, héritage, interfaces et contrats résolus
layout-complet
représentation by-value, taille et alignement calculables lorsque nécessaires
```
Ces états décrivent le travail du compilateur ; le programmeur n'a pas à gérer explicitement des « types incomplets » comme en C/C++.
Une déclaration générique peut être sémantiquement complète sans posséder un layout concret unique avant instanciation.
## 7.5 Dépendances de layout by-value — V1 REQUIS — FIGÉ
Toute dépendance récursive **par valeur** est interdite, même lorsqu'une instanciation particulière pourrait théoriquement avoir une taille nulle.
Exemples interdits :
```text
struct A {
A value;
}
```
```text
struct A {
B b;
}
struct B {
A a;
}
```
```text
struct A {
StaticArray<A, 0> values;
}
```
La longueur nulle ne crée aucune exception à la règle.
Les tuples, payloads d'enums algébriques, structs et autres composants réellement stockés inline participent au graphe de layout. `StaticArray<T,N>` participe également à ce graphe quel que soit `N`.
Le compilateur doit détecter les cycles directs et indirects du graphe by-value.
## 7.6 Classes et références — V1 REQUIS — FIGÉ EN PRINCIPE
Une valeur de type classe représente une référence d'objet et non une copie inline de l'objet complet.
Ainsi :
```text
class A {
B b;
}
class B {
A a;
}
```
ne crée pas un cycle de layout by-value.
Une classe peut néanmoins contenir des champs réellement by-value, par exemple un struct ; le layout de ces champs reste soumis aux règles normales du graphe de layout.
Le modèle mémoire exact des références sera détaillé au chapitre mémoire sans modifier cette propriété sémantique.
## 7.7 Interfaces et stockage — V1 REQUIS — FIGÉ
Une interface est un contrat et ne possède pas d'état d'instance propre.
Le fait qu'une classe, un struct ou un autre type admissible implémente une interface ne change jamais implicitement son modèle de stockage, son identité ou son mode d'indirection.
Un struct qui implémente une interface reste donc soumis exactement aux mêmes interdictions de récursivité by-value qu'un autre struct.
## 7.8 Héritage cyclique — V1 REQUIS — FIGÉ
Le graphe `extends` doit être acyclique.
Sont interdits :
```text
class A extends B
class B extends A
```
et :
```text
interface A extends B
interface B extends A
```
ainsi que tout cycle indirect.
Les diamants non cycliques restent autorisés pour les interfaces. Le fait d'atteindre un ancêtre commun par plusieurs chemins ne constitue pas un cycle.
Les diagnostics doivent identifier le graphe réellement fautif, par exemple :
```text
cyclic inheritance
recursive by-value layout
```
et non produire un message générique de « circular dependency ».
---

561
chapters/014-generics.md
View File

@@ -1,6 +1,6 @@
# 14. Generics
## 14.1 Disponibilité — V1 REQUIS — FIGÉ
## 14.1 Disponibilité et syntaxe — V1 REQUIS — FIGÉ
Les generics font partie de V1.
@@ -12,23 +12,554 @@ Result<T,E>
OpAdd<Lhs,Rhs,Out>
```
## 14.2 Points restant à fermer — V1 REQUIS — À FINALISER
Doivent encore être spécifiés précisément :
Déclarations :
```text
syntaxe des contraintes
variance ou absence de variance
contraintes multiples
specialization éventuelle
monomorphisation vs représentation partagée
contraintes sur types primitifs
const generics pour StaticArray<T,N>
generic methods
inférence éventuelle des arguments génériques à l'appel
wildcards/existentials éventuels
class Box<T> {
...
}
struct Pair<A, B> {
...
}
interface Comparable<T> {
...
}
func identity<T>(T value) -> T {
return value;
}
```
Le type de retour ne doit pas devenir un moyen de résoudre une surcharge ambiguë.
Les paramètres génériques sont toujours déclarés explicitement. Un identifiant inconnu n'est jamais transformé implicitement en paramètre générique.
Les noms de paramètres de type suivent la règle des noms de types et commencent donc par une lettre ASCII majuscule.
## 14.2 Instanciation explicite et absence de raw type — V1 REQUIS — FIGÉ
Un type générique doit être instancié avec ses arguments :
```text
Box<int32>
Pair<String, uint64>
Result<Data, ParseError>
```
La forme brute d'un type générique est invalide :
```text
Box
Result
```
Il n'existe pas en V1 de déduction du type nominal à la construction comparable à la class template argument deduction de C++.
L'identité du type générique construit doit être explicite :
```text
Box<int32> box = Box<int32>(42);
```
## 14.3 Inférence à l'appel — V1 REQUIS — FIGÉ
L'inférence des paramètres génériques est autorisée pour un appel de fonction ou de méthode lorsque les arguments fournis déterminent directement et sans ambiguïté les paramètres.
```text
func first<T>(T left, T right) -> T;
int32 a = ...;
int32 b = ...;
int32 c = first(a, b);
```
L'inférence :
- utilise les types des arguments d'appel ;
- n'utilise jamais le type de destination ou le type de retour attendu ;
- n'effectue aucune conversion implicite pour rechercher un « meilleur » type ;
- reste une commodité locale d'appel et ne déduit jamais l'identité d'un type nominal construit.
Exemple interdit :
```text
func create<T>() -> T;
String value = create(); // ERROR
```
Il faut écrire :
```text
String value = create<String>();
```
Exemple sans promotion implicite :
```text
func same<T>(T a, T b) -> bool;
int16 a = ...;
int32 b = ...;
same(a, b); // ERROR
same<int32>(a::toInt32(), b); // OK
```
## 14.4 Contraintes nominales — V1 REQUIS — FIGÉ
V1 utilise deux formes nominales de contraintes :
```text
where T extends SomeClass
where T implements SomeInterface
```
Une ligne `where` porte une contrainte.
Pour un même paramètre de type :
- au maximum une contrainte `extends` ;
- plusieurs contraintes `implements` sont autorisées ;
- toutes les contraintes sont cumulatives.
Exemple :
```text
func process<T>(T value) -> Void
where T extends Entity
where T implements Serializable
where T implements Comparable<T>
{
...
}
```
L'ordre textuel des contraintes n'a pas de sémantique. Le formatter peut choisir un ordre canonique, notamment `extends` avant `implements`.
## 14.5 Contraintes dépendantes et récursives — V1 REQUIS — FIGÉ
Un paramètre générique peut apparaître dans le contrat portant sur un autre paramètre :
```text
func compare<A, B>(A left, B right) -> Ordering
where A implements Comparable<B>
{
...
}
```
Les contraintes F-bounded sont autorisées :
```text
where T implements Comparable<T>
```
La satisfaction des contraintes est statique et nominale. Il n'existe pas de duck typing.
## 14.6 `Numeric` et absence de catégories syntaxiques — V1 REQUIS — FIGÉ EN PRINCIPE
V1 n'introduit pas de contraintes syntaxiques telles que :
```text
where T is numeric
where T is primitive
where T is struct
where T is class
```
Lorsqu'une propriété correspond à une vraie abstraction réutilisable, elle doit être représentée par un contrat Core réel.
Exemple :
```text
where T implements Numeric
```
`Numeric` est une abstraction Core nominale ; elle n'est pas un prédicat spécial du compilateur.
Des contraintes intrinsèques peuvent exister dans certaines définitions compiler/Core-known sans devenir automatiquement de nouvelles constructions de la syntaxe utilisateur.
## 14.7 Contraintes redondantes et héritées — V1 REQUIS — FIGÉ
Une contrainte nominalement redondante est interdite.
Si :
```text
interface B extends A {
}
```
alors :
```text
where T implements B
where T implements A
```
est une erreur de déclaration redondante.
Lorsqu'un type générique hérite d'un parent générique contraint, les contraintes nécessaires doivent être répétées explicitement dans le contrat du type enfant.
```text
open class Base<T>
where T implements Serializable
{
}
class Child<T> extends Base<T>
where T implements Serializable
{
}
```
Le compilateur ne rend pas silencieusement le contrat local plus contraint en important des `where` invisibles depuis le parent.
Lorsqu'un enfant ferme le paramètre sur un type concret, il suffit que ce type concret satisfasse les contraintes du parent.
## 14.8 Héritage et interfaces génériques — V1 REQUIS — FIGÉ
Les arguments génériques d'un parent ou d'une interface sont toujours explicites :
```text
class Box<T> implements Iterable<T> {
...
}
class StringList implements Iterable<String> {
...
}
class StringContainer extends Container<String> {
...
}
```
Une transformation finie des paramètres est autorisée lorsqu'elle ne constitue pas une récursivité générique interdite :
```text
class PairBox<T> implements Container<Pair<T, T>> {
...
}
```
Après substitution, les règles normales de signature et de contrat s'appliquent.
Une même interface générique peut être atteinte avec plusieurs spécialisations lorsque les contrats résultants sont compatibles.
```text
Consumer<String>
Consumer<Array<uint8>>
```
peuvent par exemple produire deux signatures distinctes.
Lorsque plusieurs chemins atteignent exactement la même spécialisation depuis la même origine, ils représentent une seule obligation :
> même contrat provenant de la même origine = une seule obligation, pas de faux conflit.
## 14.9 Overrides génériques — V1 REQUIS — FIGÉ
Une implémentation ou un override générique doit conserver une structure générique contractuellement équivalente :
```text
même nombre de paramètres génériques
même nature type/const de chaque paramètre
mêmes relations de contraintes
même contrat callable après substitution
```
Les noms des paramètres génériques peuvent être alpha-renommés.
Une implémentation ne peut pas ajouter une contrainte qui réduirait l'ensemble des appels autorisés par le contrat parent, ni supprimer une contrainte si cela modifie ce contrat.
## 14.10 Variance — V1 REQUIS — FIGÉ
Tous les paramètres génériques sont invariants en V1.
Même si :
```text
Dog extends Animal
```
cela n'implique pas :
```text
Container<Dog> -> Container<Animal>
```
V1 n'introduit pas :
```text
in T
out T
+T
-T
wildcards Java
```
La variance déclarative pourra être réévaluée après le self-hosting ou pour V3 uniquement si un besoin concret est démontré. Elle n'est pas réservée « au cas où ».
## 14.11 Spécialisation et stratégie d'implémentation — V1 REQUIS — FIGÉ
V1 n'offre aucune spécialisation sémantique des generics.
Une définition générique possède une seule sémantique visible.
Le backend reste libre d'utiliser :
```text
monomorphisation
code partagé avec metadata
stratégie hybride
```
tant que le comportement observable Saselang reste identique.
La stratégie peut varier entre LLVM, interpréteur, JVM, WASM ou futurs backends.
## 14.12 Const generics — V1 REQUIS — FIGÉ
Syntaxe :
```text
struct StaticArray<T, const uint64 N> {
...
}
struct Matrix<T, const uint64 Rows, const uint64 Columns> {
...
}
```
Les types admissibles d'un **paramètre const generic V1** sont uniquement :
```text
bool
char
uint8
uint16
uint32
uint64
uint128
uint256
enum simple sans payload
```
Les `int*` restent naturellement utilisables dans les expressions constantes générales du langage, mais ne sont pas nécessaires comme types de paramètres const generic V1.
Ne sont notamment pas admis comme types de paramètres const generic V1 :
```text
int8..int256
float16..float128
String
class
struct arbitraire
tuple
enum avec payload
```
Cette liste pourra évoluer en V2/V3 uniquement à partir de besoins concrets.
## 14.13 Expressions d'arguments const generic — V1 REQUIS — FIGÉ
Un argument const generic doit être entièrement déterminable à la compilation et produire exactement le type attendu après contextualisation normale des littéraux.
Sont admissibles directement :
```text
littéraux
const nommées déjà résolues
paramètres const generic
parenthèses
opérateurs primitifs purs autorisés sur ces valeurs
```
Exemples :
```text
StaticArray<uint8, 32>
StaticArray<uint8, PAGE_SIZE>
StaticArray<uint8, PAGE_SIZE * 2>
StaticArray<uint8, 1u64 << 12>
```
Aucun appel de callable n'est admis directement dans `<...>` :
```text
StaticArray<uint8, computeSize()> // ERROR
StaticArray<uint8, value::toUint64()> // ERROR
```
Sont également interdits directement dans l'argument const generic :
```text
fonction
méthode
constructeur
allocation
I/O
état runtime
exception
appel d'intrinsic exposé comme callable
```
S'il faut calculer une valeur par un mécanisme plus élaboré, elle doit d'abord être matérialisée dans une `const` nommée d'un type admissible, selon les règles séparées d'initialisation compile-time :
```text
const uint64 SIZE = ...;
StaticArray<uint8, SIZE>
```
La validité de l'expression qui initialise `SIZE` relève des règles des `const`, pas des const generics.
Overflow, division par zéro, shift invalide ou autre faute statiquement prouvable restent des erreurs de compilation ordinaires. Aucun wrapping, saturation ou changement de règle n'est implicite dans un contexte const generic.
## 14.14 Identité et inférence des const generics — V1 REQUIS — FIGÉ
L'identité d'une instanciation utilise la valeur constante résultante et son type, pas le texte source.
Ainsi :
```text
StaticArray<T, 2 + 2>
StaticArray<T, 4>
```
désignent la même instanciation lorsque le paramètre attendu est le même.
L'inférence d'un const generic est uniquement **structurelle**.
```text
func length<T, const uint64 N>(StaticArray<T, N> array) -> uint64
```
peut inférer `T` et `N` depuis un argument `StaticArray<int32, 32>`.
Le compilateur ne résout pas d'équation algébrique pour déduire un paramètre :
```text
func strange<const uint64 N>(StaticArray<int32, N * 2> value)
```
ne demande pas au compilateur de résoudre `N * 2 = 10`.
## 14.15 Contraintes de valeurs sur const generics — V1 REQUIS — FIGÉ
V1 n'introduit pas :
```text
where N > 0
where N <= 1024
```
`where` reste réservé aux relations nominales de types.
Les contraintes de valeur nécessaires à un type Core/compiler-known sont vérifiées par le contrat de ce type sans créer en V1 un système général de preuve ou de contraintes arithmétiques.
## 14.16 Récursivité générique régulière — V1 REQUIS — FIGÉ
Une déclaration générique peut se référencer récursivement avec exactement les mêmes arguments :
```text
class Node<T> {
Nullable<Node<T>> next;
}
```
```text
class BufferNode<T, const uint64 N> {
Nullable<BufferNode<T, N>> next;
}
```
La récursivité reste naturellement soumise aux règles générales de layout : une récursivité by-value reste interdite.
## 14.17 Récursivité générique transformante — V1 REQUIS — FIGÉ
Une auto-référence à la même déclaration générique avec des arguments transformés est interdite immédiatement en V1 :
```text
class Node<T> {
Nullable<Node<Array<T>>> next; // ERROR
}
```
```text
class BufferNode<T, const uint64 N> {
Nullable<BufferNode<T, N + 1>> next; // ERROR
}
```
Pour les cycles indirects, le compilateur rejette le cycle lorsqu'une même déclaration générique est réatteinte avec des arguments différents.
Valide :
```text
class A<T> {
Nullable<B<T>> b;
}
class B<T> {
Nullable<A<T>> a;
}
```
Invalide :
```text
class A<T> {
Nullable<B<Array<T>>> b;
}
class B<T> {
Nullable<A<T>> a;
}
```
V1 ne tente pas de prouver qu'une transformation particulière finirait éventuellement par se stabiliser.
## 14.18 Récursivité des callables génériques — V1 REQUIS — FIGÉ
La récursivité normale des fonctions et méthodes est autorisée et le compilateur ne cherche pas à prouver leur terminaison générale.
Une callable générique récursive doit cependant rappeler la même instanciation générique.
```text
func recurse<T>(T value) -> Void {
recurse<T>(value); // OK
}
```
La polymorphic recursion transformante est interdite en V1 :
```text
func recurse<T>(T value) -> Void {
recurse<Array<T>>(...); // ERROR
}
```
La même règle s'applique aux cycles mutuellement récursifs de callables génériques.
## 14.19 Parameter packs et mécanismes différés — V1 REQUIS — FIGÉ
V1 n'introduit pas :
```text
<T...>
<const uint64... N>
generic parameter packs
wildcards
specialization
variance déclarative
contraintes négatives
```
Ces mécanismes ne sont pas réservés sans besoin démontré.
---

157
chapters/024-casts-et-conversions.md
View File

@@ -87,31 +87,168 @@ Une forme n'existe que si elle apporte une sémantique observable différente d'
Ainsi, lorsqu'un `toTarget()` exact et total existe, les variantes `tryToTarget()`, `saturateToTarget()` ou `wrapToTarget()` qui produiraient exactement le même résultat pour tout le domaine source sont absentes.
Règle de composition : deux opérations Core ne sont fusionnées dans un même nom que si leur séparation en opérations successives modifierait la sémantique, perdrait de l'information ou empêcherait d'exprimer le même contrat.
Lorsqu'une composition existante est strictement équivalente, aucun alias combiné n'est ajouté au Core.
## 24.6 `float -> integer` — V1 REQUIS — DIRECTION FIGÉE
Un flottant ne possède jamais un simple `toIntXX()` ou `toUintXX()`.
La politique de passage du réel à l'entier doit être explicite, par exemple :
La conversion exacte stricte utilise :
```text
tryExactToInt32()
tryFloorToInt32()
tryCeilToInt32()
tryRoundToInt32()
tryTruncateToInt32()
tryToIntXX()
tryToUintXX()
```
Les variantes saturantes ou wrapping, lorsqu'elles sont retenues, doivent également annoncer explicitement la politique mathématique appliquée.
Elle réussit uniquement si la valeur source est finie, mathématiquement entière et représentable exactement dans le type destination. Sinon elle retourne `Result::Err(NumericConversionError(...))`.
Les politiques mathématiques de traitement de la partie fractionnaire restent des opérations Core séparées :
```text
floor()
ceil()
round()
truncate()
```
Elles se composent avec la conversion :
```text
value::floor()::tryToInt32()
value::ceil()::tryToInt32()
value::round()::tryToInt32()
value::truncate()::tryToInt32()
```
Saselang n'introduit donc pas les alias redondants `tryFloorToInt32()`, `tryCeilToInt32()`, `tryRoundToInt32()` ou `tryTruncateToInt32()` lorsque ces compositions possèdent exactement la même sémantique.
Les politiques de dépassement de domaine suivent la même règle :
```text
value::floor()::trySaturateToInt32()
value::round()::tryWrapToInt32()
```
`trySaturateToIntXX()` exige une valeur finie et mathématiquement entière, puis sature aux bornes du type destination. Les échecs qui ne relèvent pas de la plage, par exemple `NaN`, une infinité ou une valeur fractionnaire, restent des `NumericConversionError`.
`tryWrapToIntXX()` exige également une valeur finie et mathématiquement entière, puis applique le wrapping entier modulo `2^N` défini par Saselang.
Une méthode combinée reste admise lorsqu'une décomposition changerait le contrat ou perdrait l'information nécessaire. C'est notamment le cas de `saturatingRoundToFloat32()` pour certains narrowings flottants : un `roundToFloat32()` séparé pourrait échouer avant que la saturation ne puisse être appliquée.
Aucun comportement de conversion ne dépend d'un profil, d'un linter ou d'un backend.
## 24.7 `NumericConversionError` — V1 REQUIS — NOM DE TRAVAIL
## 24.7 `float -> float`, valeurs IEEE spéciales — V1 REQUIS — FIGÉ
Toute conversion de valeur flottante préserve les catégories sémantiques suivantes lorsque la destination est un type flottant Saselang :
```text
NaN -> NaN
+Infinity -> +Infinity
-Infinity -> -Infinity
+0 -> +0
-0 -> -0
```
Pour `NaN`, la conversion garantit uniquement que la destination reste `NaN`.
Elle ne garantit pas lors d'une conversion de valeur :
```text
payload NaN
quiet/signaling bit
signe du NaN
représentation binaire exacte
```
Ces propriétés relèvent d'un éventuel contrat binaire distinct ; `bitcast<T>` ne peut les préserver que lorsque ses propres contraintes, notamment de taille, sont satisfaites.
`tryToFloatXX()` traite `NaN` et les infinités comme des valeurs sémantiques représentables du type flottant destination. Le mot « exact » désigne ici l'exactitude de la valeur sémantique Saselang, pas l'identité bit-à-bit d'un payload NaN.
Pour une valeur finie :
```text
tryToFloatXX()
exige une représentation exacte
tryRoundToFloatXX()
accepte l'arrondi canonique
refuse une valeur finie hors domaine fini destination
saturatingRoundToFloatXX()
accepte l'arrondi canonique
sature une valeur finie hors domaine vers +/-Target::Max
```
Les infinités ne sont pas saturées puisqu'elles sont déjà des valeurs représentables du format flottant destination.
## 24.8 `NumericConversionError` — V1 REQUIS — NOM DE TRAVAIL / CODES FIGÉS
`NumericConversionError` est retenu comme nom de travail du `ResultError` Core utilisé par les conversions numériques récupérables.
Son nom définitif, ses codes et son état minimal pourront encore être ajustés lors de la finalisation du Core sans modifier les principes de conversion de ce chapitre.
Les catégories sémantiques V1 sont :
## 24.8 Matrice exhaustive — ANNEXE NORMATIVE EN COURS DE GEL
```text
NotFinite
NotIntegral
OutOfRange
Inexact
```
Sens :
```text
NotFinite
NaN ou +/-Infinity lorsqu'une valeur finie est requise
NotIntegral
float -> integer alors que la valeur n'est pas mathématiquement entière
OutOfRange
valeur mathématique hors du domaine de la destination
Inexact
valeur dans le domaine destination mais non représentable exactement
alors que l'opération exige l'exactitude
```
`NumericConversionError` reste volontairement généraliste et minimal. Il n'ajoute pas automatiquement :
```text
sourceType
targetType
sourceValue
timestamp
backend
roundingMode
```
au-delà de l'état commun fourni par `ResultError`.
Le nom concret et la représentation numérique interne des codes pourront encore être ajustés avant stabilisation publique, mais les catégories sémantiques ci-dessus font partie du contrat V1.
## 24.9 Réduction anti-doublon par paire — V1 REQUIS — FIGÉ
La matrice examine chaque paire `Source -> Target` et n'expose que les opérations dont le comportement peut réellement être distingué sur le domaine source.
Ainsi, pour une paire `float -> integer` dont toutes les valeurs finies mathématiquement entières sont déjà dans le domaine signé destination, `trySaturateToTarget()` et `tryWrapToTarget()` seraient des doublons de `tryToTarget()` et n'existent pas.
Pour une destination non signée, les valeurs négatives suffisent généralement à rendre les politiques checked, saturating et wrapping distinctes.
La matrice exhaustive en annexe est normative sur ce point.
## 24.10 Disponibilité Core et target — V1 REQUIS — FIGÉ EN PRINCIPE
Les conversions fondamentales de la matrice sont des capacités Core obligatoires dès lors que les types source et destination sont supportés par le target.
L'absence d'une instruction matérielle native ne justifie pas l'absence d'une conversion si une émulation logicielle conforme est raisonnablement possible.
Un target réduit peut ne pas supporter un type fondamental donné. Dans ce cas l'indisponibilité porte sur le type/capacité fondamentale, pas sur une sélection arbitraire de ses méthodes de conversion.
Voir également le chapitre 40.
## 24.11 Matrice exhaustive — ANNEXE NORMATIVE EN COURS DE GEL
L'inventaire source → destination des opérations de conversion est maintenu séparément afin d'éviter les oublis, doublons et incohérences.

96
chapters/033-imports-et-resolution-des-noms.md
View File

@@ -2,7 +2,7 @@
## 33.1 Imports — V1 REQUIS — FIGÉ
Imports file-level uniquement, après `namespace` lorsque celui-ci existe.
Les imports sont file-level uniquement, après `namespace` lorsque celui-ci existe.
Pas de wildcard `*`.
@@ -45,19 +45,99 @@ Les alias locaux doivent être uniques dans le fichier.
Pas d'alias de module.
## 33.3 Utilisation sans import — V1 REQUIS — FIGÉ
## 33.3 Import explicite même dans le même namespace — V1 REQUIS — FIGÉ
L'utilisation d'un chemin qualifié complet sans `import` est autorisée uniquement pour les symboles appartenant au **package courant**.
Appartenir au même namespace ne rend pas automatiquement les symboles visibles entre fichiers.
Avec :
```text
saselang.compiler.lexer.Token
saselang.compiler.lexer::tokenize(...)
src/foo/A.saseltype
src/foo/B.saseltype
```
`.` qualifie le chemin ; `::` accède au symbole contenu.
si `B.saseltype` utilise `A`, il doit contenir :
Un symbole provenant d'une dépendance externe ne peut pas être référencé directement par un chemin complet dans une expression ou une déclaration. Il doit d'abord être importé explicitement avec une clause `from "vendor/package@requirement"`.
```text
import type foo.A;
```
Cette règle évite d'introduire la syntaxe de coordonnées package (`/`, `@`, contraintes SemVer) dans la grammaire générale des expressions et garantit qu'un fichier énonce explicitement toutes ses provenances externes.
même si les deux fichiers déclarent :
```text
namespace foo;
```
La même règle s'applique aux autres kinds importables.
Un symbole top-level défini dans un autre fichier ne peut pas contourner cette règle en étant référencé directement par son chemin qualifié complet dans une expression ou une déclaration.
Le chemin pleinement qualifié sert notamment à identifier le symbole dans la clause `import`, pas à créer une seconde forme d'utilisation sans import.
Cette règle rend toutes les dépendances de fichier visibles localement et évite que la portée d'un namespace agisse comme un import implicite.
## 33.4 Dépendances externes — V1 REQUIS — FIGÉ EN PRINCIPE
Un symbole provenant d'une dépendance externe doit être importé explicitement avec une clause `from "vendor/package@requirement"` selon la grammaire de package à finaliser.
Les coordonnées de package (`/`, `@`, contrainte SemVer) restent confinées à la syntaxe d'import/dépendance et ne deviennent pas une syntaxe générale de qualification dans les expressions.
## 33.5 Imports déclaratifs et cycles — V1 REQUIS — FIGÉ
Un `import` Saselang est une déclaration de résolution de symbole.
Il ne signifie jamais :
```text
charger le fichier immédiatement
exécuter le fichier
initialiser le fichier
compiler ce fichier avant le fichier courant
```
Les cycles d'import sont donc autorisés :
```text
A imports B
B imports A
```
ou :
```text
A imports B
B imports C
C imports A
```
Un cycle d'import n'est pas en lui-même une erreur.
Le compilateur doit ensuite analyser les graphes sémantiques réellement concernés.
Exemples :
```text
cycle de références de classes
autorisé
cycle d'appels
autorisé
cycle d'héritage
ERROR
cycle de layout by-value
ERROR
```
Le diagnostic doit identifier la violation réelle et ne pas utiliser un générique `circular import` lorsque les imports eux-mêmes sont valides.
## 33.6 Ordre de résolution — V1 REQUIS — FIGÉ EN PRINCIPE
Les fichiers et imports organisent le source mais ne définissent pas un ordre sémantique de compilation.
Le frontend collecte les déclarations nominales accessibles avant de finaliser les relations d'héritage, contrats, layouts et corps.
Cela permet notamment à deux classes placées dans deux `.saseltype` distincts de se référencer mutuellement sans dépendre d'un ordre de chargement de fichiers.
---

71
chapters/040-targets-plateformes-architectures-abi-distributions-et-capabilities.md
View File

@@ -189,7 +189,76 @@ Le modèle doit aussi permettre de décrire les capacités atomiques pertinentes
Une capability statique signifie que l'environnement fournit la capacité ; elle ne garantit pas qu'une opération runtime particulière réussira.
## 40.9 Compatibilité target/dépendance — V1 REQUIS — FIGÉE EN PRINCIPE
## 40.9 Propriétaires et identifiants de capabilities — V1 REQUIS — DIRECTION FIGÉE
Les capabilities utilisent une nomenclature hiérarchique commune, ASCII, en minuscules, séparée par `.`.
Le premier segment identifie le propriétaire sémantique :
```text
language.*
core.*
target.*
platform.*
sdk.*
```
Exemples conceptuels :
```text
language.exceptions
core.numeric.float128
core.collections.array
target.atomic.int64
target.simd.float32
platform.filesystem
platform.network
sdk.logging
```
Cette organisation permet de regrouper les capacités par propriétaire et d'éviter un registre global plat.
Les noms exacts et le registre exhaustif seront stabilisés avec le Core/SDK, mais un même concept ne doit pas recevoir des conventions concurrentes telles que `hasFloat128`, `supports_float128` et `numeric-f128`.
Les packages utilisateurs ne doivent pas usurper les espaces de noms de capabilities réservés à la toolchain/Core/SDK.
## 40.10 Niveaux de capacité — V1 REQUIS — FIGÉ EN PRINCIPE
Trois niveaux conceptuels sont distingués :
```text
Language-required
sémantique nécessaire à tout compilateur Saselang conforme
Core-required-for-supported-type
contrat Core obligatoire dès que le type/capacité fondamentale existe
sur le target
Core/target optional capability
fonctionnalité réellement optionnelle ou spécifique d'un environnement
```
Exemple : si un target supporte `float128`, les conversions Core fondamentales définies par la matrice numérique pour `float128` doivent être disponibles.
Le target ne peut pas exposer `float128` tout en supprimant arbitrairement certaines conversions fondamentales simplement parce que le matériel n'offre pas une instruction native correspondante.
## 40.11 Émulation logicielle — V1 REQUIS — FIGÉ
Lorsqu'une fonctionnalité fondamentale peut raisonnablement être émulée de façon conforme, l'absence d'un support matériel natif ne la rend pas indisponible.
```text
instruction native disponible
lowering/backend direct ou optimisé
instruction native absente
implémentation logicielle conforme
```
La différence doit porter sur les performances, pas sur la sémantique visible.
Un target réellement contraint peut ne pas fournir un type/capacité fondamentale entière. Dans ce cas, le diagnostic doit porter sur cette capacité ou ce type, plutôt que sur l'absence aléatoire d'une méthode secondaire.
## 40.12 Compatibilité target/dépendance — V1 REQUIS — FIGÉE EN PRINCIPE
Un package ou une dépendance peut déclarer des contraintes de target/platform/ABI/capabilities.

9
chapters/048-inventaire-des-points-v1-encore-ouverts.md
View File

@@ -13,21 +13,18 @@ Restent à fermer :
- matrice finale des préfixes de littéraux combinables (`i`, `r`, `b`, `c`, `u8/u16/u32`, `t`, etc.) et leur disponibilité V1/V2 ;
- limite normative éventuelle du nombre de `#` des raw strings ;
- grammaire syntaxique complète au-delà des blocs/statements déjà figés ;
- syntaxe exacte des generics et contraintes ;
- syntaxe exacte des annotations/métadonnées de code lorsqu'elles seront retenues.
## 48.2 Types
- domaine exact des types admissibles à `Nullable<T>` avec le modèle mémoire/FFI ;
- finalisation de la matrice exhaustive des conversions numériques Core et de ses noms composés ;
- règles de sous-typage interface/class ;
- generics complets ;
- const generics ;
- audit mécanique final de la surface Core des conversions numériques à partir de la matrice désormais largement figée ;
- règles de sous-typage interface/class au-delà des règles génériques déjà fixées ;
- callable/function types ;
- lambdas/closures ;
- variadiques (un seul variadique prévu) ;
- String/index Unicode ;
- exact float semantics.
- exact float semantics hors conversions déjà figées (opérations arithmétiques IEEE restantes, `%`, division par zéro, etc.).
## 48.3 Mémoire

4
chapters/049-elements-v1-reserves-mais-non-obligatoires-a-implementer-immediatement.md
View File

@@ -17,4 +17,8 @@ noms nécessaires pour éviter collisions futures
Un élément réservé ne doit pas être réutilisé pour une fonctionnalité incompatible.
Une réservation doit correspondre à un besoin déjà identifié ou à une compatibilité future concrètement anticipée. Saselang ne réserve pas de syntaxe, de types ou de mécanismes purement spéculatifs « au cas où ».
V1 et V2 servent de bases/POC permettant encore de corriger les choix du langage avant la baseline publique V3.
---

4
chapters/051-invariants-de-conception.md
View File

@@ -19,5 +19,9 @@ Les futures décisions doivent respecter les invariants suivants :
15. **Les opérateurs utilisateur passent uniquement par les contrats Core `Op...`.**
16. **Les interfaces fournissent l'héritage multiple de contrats/comportements sans introduire un second système de traits.**
17. **Le modèle mémoire V1 doit fournir performances, sûreté et destruction déterministe sans imposer des lifetimes explicites partout.**
18. **L'ordre des fichiers et des imports n'est pas un ordre d'exécution ou de résolution sémantique.**
19. **Un cycle n'est interdit que par la règle du graphe concerné : héritage et layout by-value doivent être acycliques ; références de classes, imports et appels peuvent être cycliques.**
20. **Une fonctionnalité n'est réservée que lorsqu'un besoin réel est identifié ; pas de réservation spéculative « au cas où ».**
21. **Une opération Core combinée n'existe pas lorsqu'une composition d'opérations existantes exprime strictement la même sémantique.**
---

32
chapters/052-priorite-de-specification-apres-0-2-9.md
View File

@@ -1,23 +1,27 @@
# 52. Priorité de spécification après 0.2.12
# 52. Priorité de spécification après 0.2.14
Pour transformer cette Bible en spécification V1 directement implémentable, l'ordre recommandé est :
Pour transformer cette Bible en spécification V1 directement implémentable, l'ordre recommandé devient :
```text
1. terminer casts/conversions numériques + matrice Core
2. generics + contraintes + const generics
3. String/Unicode + collections + Range
4. lambdas/closures + callable model
5. async/concurrency décision V1
6. modèle mémoire + allocator + pointers + unsafe
7. fautes runtime + construction/destruction cleanup
8. Core V1 exact et capacités target
9. SDK V1 initial et frontières Core/SDK
10. FFI C exacte
11. reflection/metadata/tests/tooling
12. grammaire syntaxique complète et audit lexical final
1. String/Unicode + collections + Range
2. lambdas/closures + callable model
3. async/concurrency décision V1
4. modèle mémoire + allocator + pointers + unsafe
5. fautes runtime + construction/destruction cleanup
6. Core V1 exact : Numeric, collections, erreurs, TypeInfo et autres contrats
7. capacités target et registre canonique des capability identifiers
8. SDK V1 initial et frontières Core/SDK
9. FFI C exacte
10. reflection/metadata/tests/tooling
11. grammaire syntaxique complète et audit lexical final
12. audit mécanique des generics/const generics/récursivité et conversions
13. audit complet de toutes les sections V1 REQUIS — À FINALISER
14. consolidation examples / DO-DON'T / conformance tests
15. plan d'implémentation du compilateur/interpréteur V1
```
Les generics, const generics, règles principales de récursivité, casts/conversions et matrice numérique sont désormais suffisamment fermés pour quitter leur phase de conception principale. Ils devront naturellement être réaudités pendant l'implémentation et la préparation de la baseline publique V3.
La Bible ne doit être déclarée « V1 specification complete » qu'après fermeture de tous les points V1 REQUIS — À FINALISER qui affectent la grammaire ou la sémantique observable.
---