Ce que Sapphire 3 stocke vraiment

1 · Principe et périmètre

L'interface est une vue sur un document. Un module est une portée ; une carte est la représentation d'un module ; une ligne d'arbre est la représentation d'un nœud. Supprimer la carte ne supprime pas l'AST, et deux interfaces différentes pourraient lire la même source.

2 · La source JSON v1

Un projet logique tient en quatre collections : une version, un identifiant, des modules, des nœuds dans un tableau global à plat. Les listes rootNodeIds et les slots ordonnés portent l'ordre syntaxique ; l'ordre du tableau nodes n'a aucune signification.

{
  "formatVersion": 1,
  "id": "projet-demo",
  "modules": [
    {
      "id": "mod-affichage",
      "name": "Affichage",
      "kind": "module",
      "rootNodeIds": ["n-principal"],
      "imports": [
        { "id": "imp-double",
          "moduleId": "mod-calculs",
          "nodeId": "n-double",
          "localName": "Double" }
      ],
      "exports": []
    }
  ],
  "nodes": [ /* tous les nœuds, à plat */ ]
}

{
  "id": "n-double",
  "moduleId": "mod-calculs",
  "kind": "FunctionDeclaration",
  "properties": {
    "name": "Double",
    "type": { "kind": "primitive", "name": "int" },
    "entryPoint": false
  },
  "children": {
    "parameters": ["n-param"],
    "body": "n-corps"
  },
  "references": {}
}

Ce qui n'est pas dans cette source

L'AST analysé, les diagnostics, l'index des symboles, les caches et toute la présentation sont recalculés, jamais enregistrés avec le modèle logique. La mise en page vit dans une enveloppe distincte, qui emballe la source et y ajoute les cartes :

{
  "application": "Sapphire 3",
  "workspaceVersion": 1,
  "project": { "formatVersion": 1, "id": "…", "modules": [], "nodes": [] },
  "presentation": {
    "cards": [],
    "camera": { "x": 0, "y": 0, "zoomLevel": 0 },
    "selected": null
  }
}

Une carte module partage l'identifiant et le nom de son module source — exactement une carte par module. Les cartes comment et image n'existent que dans presentation : elles ne passent jamais dans project, jamais dans l'AST, jamais dans les commentaires du code généré. Une image est intégrée en Data URL ; les URL distantes et les chemins locaux sont refusés avant remplacement. Le lecteur accepte aussi une source logique v1 seule, sans présentation : il crée alors une disposition déterministe, tout replié, vue à l'origine.

3 · Trois relations indépendantes

C'est le point le plus facile à confondre, donc le plus explicitement séparé.

Une référence se donne par {kind:'name', name}, {kind:'node', nodeId} ou {kind:'import', importId}. Une cible par identifiant reste soumise à l'accessibilité lexicale ; un import peut être visé par son identifiant indépendamment de son alias local. Les relations reads, writes, calls et type des vues d'analyse proviennent de cette seule relation symbolique, résolue par l'analyse sémantique.

4 · Constructions et slots

Vingt-huit sortes de nœuds, toutes décrites dans un seul objet figé, nodeSchema. Ce schéma pilote la validation, le typage et les propositions du menu d'ajout : il n'existe aucune liste d'actions codée en dur ailleurs.

Le schéma porte aussi, pour chaque construction, un group stable (variable, type, function, parameter, condition, loop, return, block, statement, operator, value, array, incomplete). Ce champ sert à l'interface seulement — couleur de bordure des lignes d'arbre et regroupement des propositions du menu. Il n'intervient ni dans la validation ni dans le typage, et reste distinct de category, qui elle, détermine la compatibilité syntaxique d'un slot.

declaresType marque les constructions autorisées à porter une annotation ; declaresElementType celles qui portent un type d'élément de tableau. Une annotation posée sur un opérateur ou une référence est une erreur structurelle : elle ne peut pas forcer un type.

1. Ce que la page appelle ReturnStatement s'affiche « Retour » ; le libellé est une vue, la sorte est une donnée.
2. Un BinaryExpression : aucun properties.type dans la source, un type dérivé par l'analyse.
3. Un ArrayLiteral qui déclare le type de ses éléments, pas le sien.
4. Un ExpressionStatement portant un CallExpression : la référence qui relie les deux modules.

5 · Portées, symboles, imports

• Une portée par module ; une par fonction, partagée avec ses paramètres et son bloc principal ; une par bloc imbriqué et par for.
• Un espace de noms commun aux valeurs et aux types. Les déclarations d'une portée sont collectées avant résolution : pas de temporal dead zone, pas d'analyse d'ordre d'initialisation à ce stade.
• Un nom peut masquer une déclaration d'une portée externe. Un doublon dans la même portée est une erreur, et la première déclaration reste choisie pour permettre l'inspection.
• Export : {nodeId, name}, uniquement pour une déclaration racine. Import : {id, moduleId, nodeId, localName}, uniquement vers un nœud explicitement exporté d'un autre module.
• Les imports peuvent être cycliques : aucune exécution ni analyse de cycle d'initialisation n'est engagée. Pas de réexport, pas d'import étoilé, pas de résolution de chemin physique.

Le lien visuel entre deux cartes est une agrégation de ces références résolues : getModuleLinks(index) renvoie, par couple de modules, une seule direction de l'exportateur vers le récepteur, avec la liste des exportations réellement utilisées et leur nombre d'utilisations. Un import jamais référencé ne produit aucun lien. La fonction est pure.

Le point d'entrée

Un projet valide contient zéro ou une seule fonction portant properties.entryPoint: true. Absent ou false, la fonction est ordinaire, même si elle s'appelle main. Un marqueur non booléen, ou posé sur une autre construction, donne ENTRY_POINT_INVALID ; un second marqueur donne ENTRY_POINT_DUPLICATE, localisé sur son nœud et sur le champ, y compris dans des fragments détachés. Les données invalides restent inspectables et sérialisables : aucune suppression automatique, mais canGenerate devient faux. Aucune exécution implicite n'est attachée à ce marqueur ; le simulateur l'exige simplement sans paramètres.

6 · Typage statique strict

Un seul catalogue, primitives.js. Les bornes sont celles du langage logique, pas d'un langage hôte. Aucune conversion implicite, même sans perte de précision.

number, any et unknown sont rejetés comme types logiques. Toutes les déclarations, tous les paramètres et tous les littéraux portent un type explicite ; une annotation absente ou invalide est diagnostiquée et ne produit aucun type de secours. Une déclaration ne récupère jamais le type de son initialiseur.

Trois types construits s'annotent en plus sur une variable, une constante, un paramètre ou le retour d'une fonction : le pointeur {kind:'pointer', pointee} vers un primitif non void, la signature de fonction {kind:'function', parameters, returnType} et le tableau générique en retour. & prend l'adresse d'une valeur stockable ; * relit la valeur pointée et peut servir de cible d'affectation, la simulation écrivant alors dans l'emplacement d'origine ; les pointeurs sont transpilés en JavaScript, Python et C expérimental. Une fonction nommée est une valeur de première classe : une Reference vers une fonction porte sa signature et peut être stockée, transmise puis appelée. Une lambda anonyme (LambdaExpression) possède des paramètres typés et une expression de résultat, capture lexicalement les variables visibles et peut être stockée, passée en argument ou appelée immédiatement. Une fonction peut retourner une signature concrète, ce qui permet de renvoyer une fermeture. Chaque type construit reste limité à ses emplacements autorisés, sans conversion implicite.

Généricité avancée

Une fonction peut déclarer jusqu'à huit paramètres de type nommés — T, U, Element… — dont le nom suit [A-Z][A-Za-z0-9]*. Chacun peut porter une contrainte exacte optionnelle (un type concret valide). Le paramètre s'utilise sur le retour et les paramètres de sa fonction, directement ou comme élément de tableau générique (T[]). L'inférence confronte chaque argument à son motif, lie un type réel, exige le même type pour toutes les occurrences, vérifie la contrainte et substitue le retour. T*, T[][], les génériques imbriqués, les variables/constantes génériques et l'usage de la fonction générique comme valeur de première classe restent refusés. Aucune spécialisation n'est créée : la simulation exécute la même fonction et les transpileurs émettent une fonction ordinaire, avec les types concrets publiés dans semantic.genericCalls.

Tableaux

Un tableau est un type construit {kind:'array', elementType}, annotable sur une variable, une constante ou un paramètre. Un retour de fonction ne peut être un tableau que si son élément est un paramètre de type générique ; un alias ou une conversion tableau reste refusé (TYPE_INVALID). L'élément est un primitif non void, ou un paramètre de type dans une signature générique ; les tableaux imbriqués restent refusés. Trois constructions portent properties.elementType : ArrayLiteral, ArrayCreation, ArrayAccess. Une case jamais remplie ne reçoit aucune valeur inventée : sa lecture échoue comme une variable sans initialiseur, et les éléments d'une constante ne sont pas modifiables.

Opérateurs

Les conditions de if, while et for exigent boolean. Le nombre et les types des arguments d'un appel doivent correspondre exactement à la signature ; un appel invalide n'obtient pas le type de retour comme secours. Une fonction non void doit retourner la bonne valeur sur tous les chemins démontrés par un vérificateur simple — retour direct, séquence de blocs, deux branches d'un if ; les boucles ne prouvent rien seules, et les cas non prouvés sont refusés conservativement, sans exécuter aucune condition.

Conversions explicites

CastExpression porte le type cible et son argument. Les conversions entre les six primitifs numériques sont permises, ainsi que l'identité d'un primitif non vide ; pas de conversion chaîne/nombre, booléen/nombre ou char/string. Vers un entier : troncature vers zéro puis contrôle exact du domaine — une négative ne passe pas en non signé, une réduction de largeur ne reboucle pas. Vers un flottant : la perte de précision est acceptée parce que demandée, mais dépassement et sous-flux vers zéro restent des erreurs.

7 · Diagnostics

Un diagnostic est un enregistrement sérialisable, jamais une exception : il peut être affiché, conservé dans un fichier, comparé dans un test.

{
  "code": "TYPE_MISMATCH",
  "severity": "error",
  "message": "Les types doivent être strictement identiques ; une conversion explicite est nécessaire.",
  "location": { "projectId": "…", "moduleId": "…", "nodeId": "…", "field": "children.right" }
}

severity vaut error, warning ou info ; seul error bloque génération et simulation. Les identifiants inapplicables valent null. Les messages techniques sont en français ; l'interface traduit le code, sans jamais analyser le texte du message, ce qui garde le moteur indépendant de la langue affichée.

Une source incomplète reste représentable : un littéral sans valeur, un appel partiel, un retour sans argument, un Hole sont acceptés comme document, signalés comme bloquants pour la production, et en aucun cas supprimés pour « faire propre ». La séparation est volontaire : le droit d'inspecter un programme invalide ne doit pas dépendre du droit de produire du code.

8 · De la source aux résultats

analyzeProgram(source) enchaîne trois passes pures et cumulatives, puis décide :

Les vues dérivées consomment ce résultat sans jamais le recomposer à leur façon : le graphe de contrôle et le graphe de dépendances réutilisent les références déjà résolues, l'atteignabilité repart de l'initialisation globale et du point d'entrée en suivant les cibles d'appels (imports et récursion comprise), et l'agrégation des liens entre modules lit le même index.

9 · Simulation, débogage et transpilation

Un même calcul arithmétique sert les chemins de génération : les opérations numériques embarquées dans le code généré proviennent de la même fabrique que celles du simulateur — BigInt pour les entiers, arrondi binaire32, conversions, dépassements, sous-flux et division par zéro identiques. Le fichier produit n'embarque pas les budgets du simulateur et n'est jamais exécuté automatiquement par l'application.

Opérations natives SP3

PrintStatement ajoute la représentation textuelle d'une valeur à la sortie. MathCall désigne une opération du registre pur mathNatives.js — mathématiques, texte et longueur de tableau — typée sans conversion implicite. La simulation les exécute localement, avec des codes stables pour un résultat non fini ou des bornes Unicode dépassées. JavaScript et Python les transpilent avec l'équivalent natif le plus direct et de petits helpers lorsque la sémantique SP3 l'exige ; le C expérimental les refuse encore. Aucun effet système, aucun réseau.

10 · Invariants et refus

Ce modèle est la partie stable du projet. L'interface, les cartes, les thèmes et les panneaux changent plus vite que lui : c'est exactement le but. Une capacité nouvelle qui n'arrive pas à s'écrire dans ces enregistrements-là n'est pas une fonctionnalité à brancher sur un affichage, c'est une extension du modèle à décider, discuter et documenter d'abord.