@supersoniks/concorde 5.1.2 → 5.1.3-immutable.1

package/src/docs/misc/publisher-get-immutability-docs-recheck.json

@@ -0,0 +1,13 @@
+{
+  "generatedAt": "2026-10-29T14:46:01.703Z",
+  "baseA": "https://127.0.0.1:3010",
+  "baseB": "https://127.0.0.1:3011",
+  "pageCount": 43,
+  "pagesWithDiffs": 0,
+  "diffs": [],
+  "summary": {
+    "errors": [],
+    "warns": [],
+    "infos": []
+  }
+}

package/src/docs/misc/publisher-get-immutability-study.md

@@ -0,0 +1,229 @@
+# Étude — immutabilité DataProvider / `get()` (REDMINE-79567)
+
+> **Nature :** étude d’opportunité + ADR de direction.  
+> Branche : `79567_publisher_get_immutability_study`.  
+> **Recadrage (oct. 2026) :** la cible n’est plus un empilement de gardes opt-in, mais un **store immutable** clair.
+
+## 0. Décision de direction (ADR)
+
+### Contrat cible
+
+> **Le publisher possède les données. On ne mute jamais. On remplace.**
+
+| API | Comportement |
+|-----|----------------|
+| `set(value)` / `update(recipe)` | Ownership à l’entrée : copie (clone / Immer `produce`), commit, puis **freeze** (ou équivalent) de la valeur stockée |
+| `get()` | Vue **lecture seule** de la valeur commitée — muter → erreur nette |
+| Écritures | Uniquement `set` / `setIn` / `update` — plus de patch in-place de `_value_` |
+| Comportement | **Un seul** en prod (pas de mode « soft » comme design final) |
+
+### Ce qu’on ne garde pas comme design produit
+
+Empiler `DeepReadonly` + `strictGet` warn/throw + clone parfois = **pansements** autour d’un moteur encore mutable. Utile en **radar de migration**, pas comme architecture cible.
+
+### Conséquence technique
+
+Refonte du moteur `PublisherProxy` : plus de `_value_[k] = …` / `delete _value_[k]` / sync parent par mutation. Updates **immutables** (Immer ou `setIn` maison) sur tout chemin d’écriture (y compris traps Proxy / sous-proxies).
+
+---
+
+## 1. Problème (rappel)
+
+Aujourd’hui `get()` renvoie la **référence live** de `_value_`. Une mutation locale (`cart.items.push…`) contourne `set` et les listeners → état partagé / UI désynchronisés.
+
+Écritures « officielles » (`set`, sous-proxies, `publisher.clé = …`) notifient ; le trou est **get + mutation** et **réutilisation de la ref passée à `set`**.
+
+Fichier central : `src/core/utils/PublisherProxy.ts`.
+
+---
+
+## 2. Alternatives évaluées
+
+| | Approche | Verdict |
+|---|----------|---------|
+| A | Freeze live **sans** refonte `set` | **Non** — casse le moteur actuel |
+| B | Clone / Proxy readonly à chaque `get()` | **Non** comme défaut — cher, identité cassée |
+| C | Clone défensif seul sans freeze | **Insuffisant** — n’enseigne pas le contrat |
+| D | `strictGet` opt-in warn/throw | **Outil de migration** seulement |
+| E | Lint / convention seule | **Complément**, pas une garantie |
+| F | **Store immutable** (set ownership + get readonly + updates immutables) | **Cible** |
+
+### Perf (ordre de grandeur)
+
+1. Status quo / typage seul — 0 runtime  
+2. Proxy `strictGet` — faible, sur `get`  
+3. Freeze **après** commit immutable — lectures cheap ; coût sur **écritures**  
+4. Deep clone à chaque `get` — à éviter  
+5. Freeze live + mute in-place — incompatible  
+
+Le modèle F met le coût là où il est acceptable (écritures), avec une sémantique nette.
+
+---
+
+## 3. Cible — store immutable (détail)
+
+### 3.1 Moteur Concorde à réécrire
+
+- `set` / traps Proxy / sync parent-enfant : **immutable updates** uniquement.  
+- Après commit : freeze deep (ou structure déjà immutable).  
+- `get()` / `onAssign` : renvoient la valeur frozen (même ref tant que le commit n’a pas changé → `get() === get()` OK entre deux `set`).  
+- API `update(draft => { … })` (Immer) recommandée pour les updates nested ergonomiques.  
+- Valeurs non clonables (`EventSource`, instances, fonctions) : **hors store** ou wrappers documentés (ex. Mercure / laqueue).
+
+### 3.2 Surface apps
+
+- Interdit : muter après `get`, muter la ref passée à `set`, `.sort()` in-place dans `onAssign`.  
+- Obligatoire : `const next = …; set(next)` ou `update(draft => …)`.
+
+### 3.3 Rôle du spike actuel sur cette branche
+
+Déjà présent (ne pas confondre avec la cible) :
+
+- `DeepReadonly` sur `get` / `onAssign` (typage).  
+- `PublisherManager.strictGet = "off" | "warn" | "throw"` (Proxy sur le résultat de `get`, **sans** freeze de `_value_`).
+
+→ **Radar** pour lister les mutations pendant la migration vers F. Destiné à disparaître ou à se réduire une fois le moteur immutable en place.
+
+---
+
+## 4. Canal de livraison — dist-tag npm (reco)
+
+Oui : publier le chantier sur un **dist-tag npm dédié**, pas sur `latest`, le temps d’un usage approfondi.
+
+### Pourquoi c’est adapté ici
+
+- Breaking **moteur + contrat** : les apps ne doivent pas le prendre par un bump semver « normal » par erreur.  
+- Billetterie / smart-belt / lecovoit / laqueue peuvent opter **explicitement** :  
+  `"@supersoniks/concorde": "npm:@supersoniks/concorde@immutable"`  
+  ou version `5.x.x-immutable.n` + tag `immutable`.  
+- CI / smokes sur le tag sans bloquer prod `latest`.  
+- Feedback réel (perf panier, Mercure, placement) avant major.
+
+### Proposition de tags
+
+| Tag | Usage |
+|-----|--------|
+| `latest` | Ligne stable actuelle (mutable + éventuellement radar `strictGet` si un jour mergé à part) |
+| `immutable` (ou `next-immutable`) | Ligne de dev du store immutable — **usage approfondi** |
+| (plus tard) `latest` major | Quand la migration Billetterie + checklist sont vertes |
+
+Versions du type `6.0.0-immutable.1`, `.2`, … (prerelease) : claires dans le lockfile, republish fréquentes OK.
+
+### Ce qu’il ne faut pas faire
+
+- Remplacer `latest` trop tôt.  
+- Multiplier les tags flous (`test`, `julien`, …) — **un** tag métier `immutable`.  
+- Laisser `strictGet` opt-in comme « la » release : ce n’est pas le produit final.
+
+### Avis
+
+**Go dist-tag `immutable`.** C’est le bon niveau de netteté : chantier puissant isolé, adoption volontaire, mesure avant major. Le spike `strictGet` peut vivre sur la même branche/tag comme aide à la migration, documenté comme temporaire.
+
+---
+
+## 5. Impact consommateurs (rappel audit)
+
+| Projet | Volume / note | Priorité migration |
+|--------|----------------|-------------------|
+| **la-billetterie** | ~860 fichiers dp, ~216 get / ~392 set ; cart, AC, placing, forms | **P0** |
+| smart-belt-drive | Peu de get ; `onAssign` + `.sort()` in-place | P1 |
+| lecovoit | Peu de get, surtout set | P2 |
+| laqueue | Très peu ; Mercure / non-clonables à traiter | P2 |
+| link / starter | Faible | P3 |
+
+Zones Billetterie chaudes : `access-control/**`, `utils/cart.ts` + `components/cart/**`, `placing/**`, subscription / tarifs, forms, ~300 `onAssign`, legacy `lb_placement` JS.
+
+---
+
+## 6. Plan recadré
+
+```
+Phase 0  Étude + ADR direction immutable ✅
+Phase 1  Radar DeepReadonly + strictGet ✅
+Phase 2  Moteur immutable sur branche ✅ → publish npm tag `immutable`
+Phase 3  App pilote sur le tag
+Phase 4  Billetterie (puis SBD, lecovoit, laqueue) sur le tag
+Phase 5  Major Concorde sur `latest` quand go-live OK
+```
+
+### Critères go-live major
+
+- Smokes Billetterie (panier, placing, AC, forms, abonnements, submit, localStorage) verts sur le tag.  
+- Pas de régression perf au-delà du seuil convenu sur écritures panier / scan.  
+- Doc dataFlow = contrat immutable uniquement.  
+- Stratégie explicite pour non-clonables.  
+- `strictGet` retiré ou réduit à un assert interne inutile en prod.
+
+---
+
+## 7. Verdict
+
+| Question | Réponse |
+|----------|---------|
+| Problème de contrat réel ? | **Oui** |
+| Design cible ? | **Store immutable** (F), pas la pile de gardes |
+| Freeze live sans refonte ? | **Non** |
+| Clone à chaque `get` ? | **Non** |
+| `strictGet` / `DeepReadonly` ? | **Radar de migration**, pas la cible |
+| Publier sur un tag npm dédié pendant le dev ? | **Oui — `immutable`** |
+| Ce ticket 79567 | Étude + direction ; chantier moteur = ticket(s) d’implémentation + tag |
+
+## 8. Suite immédiate
+
+1. Publish dist-tag npm `immutable` depuis cette branche.  
+2. App pilote (starter / module Billetterie borné).  
+3. Migration Billetterie + smokes.  
+4. Major sur `latest` quand critères § go-live OK.
+
+## 9. Implémenté sur la branche
+
+- Helpers : `src/core/utils/immutableValue.ts` (`takeOwnership`, `deepFreeze`, `setAtKey`, `deleteAtKey`)
+- `PublisherProxy.set` : ownership + freeze ; sync parent immutable (plus de `_value_[k] =`)
+- Traps Proxy `set` / `deleteProperty` : via `set` / rebuild
+- `get()` : valeur frozen (même ref jusqu’au prochain `set`)
+- Non-clonable : warn + stocké tel quel sans freeze
+- Specs : `immutableValue.spec.ts`, `publisherImmutable.spec.ts`, etc.
+- Correctifs doc/runtime déjà livrés sur la branche : boucle `sonic-list` / `_metadata_`, clone SDUI, shallow-copy submit, `sameValueAs` en dot-notation
+
+## 10. Crawl docs rendu — branche vs `master` (29 oct. 2026)
+
+Comparaison automatisée des pages de la nav docs : **A** = branche `79567_publisher_get_immutability_study`, **B** = `master`.
+
+Métriques : `bodyChars`, sections `h2`, blocs `sonic-code` (radios/inputs/lists/sdui + hauteurs interactives), `docs-lit-demo`, erreurs console (hors bruit SW 404).
+
+Artefacts JSON (bruts) :
+
+- `src/docs/misc/publisher-get-immutability-docs-crawl.json` — 68 pages (crawl parallèle initial)
+- `src/docs/misc/publisher-get-immutability-docs-recheck.json` — 43 pages à risque (crawl séquentiel)
+
+### Résultat
+
+| Passe | Pages | Diffs structurantes (error) | Notes |
+|-------|------:|----------------------------:|-------|
+| Recheck séquentiel | 43 | **0** | Pas de contrôle disparu, pas de preview collapsée, pas d’erreur freeze |
+| Crawl parallèle 68 | 68 | **0** error | 5 pages avec diffs info/warn uniquement |
+
+### Diffs relevés (pas de régression immutable)
+
+| Page | Nature | Action |
+|------|--------|--------|
+| `/core/components/ui/form/radio` | Section **Nested keys** ajoutée sur la branche | Doc volontaire — à garder ou retirer selon review doc |
+| `/core/components/ui/form/input` | Idem Nested keys + `sameValueAs` dot-notation | Idem |
+| `/docs/directives/t` | Contenu plus riche sur A (sections Import/Usage/…) | Hors immutable — écart de contenu markdown ; vérifier si attendu sur la branche |
+| `/docs/misc/dataProviderKey` | Faux positif crawl parallèle (`bodyChars: 0`) | **Revalidé OK** au recheck / visite manuelle (2615 chars, 9 codes) |
+| `/docs/misc/html-integration` | Console `498` ponctuelle au crawl parallèle | **Revalidé OK** (même rendu A/B, 838 chars) — bruit réseau, pas un gel publisher |
+
+### Correctifs déjà faits (hors crawl, signalés avant)
+
+- `sonic-list` boucle infinie (`_metadata_`)
+- SDUI mute sur descripteur frozen
+- Submit `delete` sur `get()` frozen
+
+### À corriger ultérieurement (backlog crawl)
+
+1. **Décider** du sort des sections Nested keys radio/input (ajoutées pendant le debug) — doc only.  
+2. **Vérifier** l’écart markdown `docs/directives/t` vs `master` (pas lié au store).  
+3. Rejouer le crawl séquentiel après les prochains correctifs moteur avant publish tag `immutable`.  
+4. Optionnel : intégrer le script de crawl dans un smoke CI docs (ports dédiés + Chromium system).
+
+**Verdict crawl :** pas de régression de rendu docs imputable au store immutable sur l’échantillon recheck (43 pages). Les seuls écarts stables sont documentaires (Nested keys, éventuellement `t`).

package/src/docs/navigation/navigation.ts

@@ -26,7 +26,7 @@ export const docsNavigation: Array<string | { label: string; href: string }> = [
     href: "/docs/getting-started/dataFlow",
   },
   {
-    label: "AI agents (skills)",
+    label: "AI agents (skill)",
     href: "/docs/getting-started/ai-agents",
   },
   "Functional components",
@@ -216,6 +216,10 @@ export const docsNavigation: Array<string | { label: string; href: string }> = [
     label: "Local API demos",
     href: "/docs/misc/docs-mock-api",
   },
+  {
+    label: "get() immutability study",
+    href: "/docs/misc/publisher-get-immutability-study",
+  },
 ];
 
 const tagName = "docs-navigation"; // For Astro.build