@duplojs/agents-kit 0.1.0-beta.7 → 0.1.0-beta.9

package/skills/fundamental/SKILL.md

@@ -17,64 +17,64 @@ Si le chemin du routeur manque, le retrouver depuis le projet consommateur :
 node --input-type=module -e 'import { fileURLToPath } from "node:url"; console.log(fileURLToPath(import.meta.resolve("@duplojs/agents-kit/docs/concepts.llms.md")))'
 ```
 
-## Utiliser DuploJS pour coder
+## Utiliser les API DuploJS
 
-Utiliser obligatoirement les API et l'écosystème DuploJS dès qu'un équivalent existe, y compris dans les tests. Avant d'utiliser une API native ou tierce ou de créer un utilitaire, chercher l'équivalent DuploJS.
+Utiliser obligatoirement l'équivalent DuploJS avant une API native, tierce ou un nouvel utilitaire, y compris dans les tests. Chercher dans `lang` pour les primitives indépendantes de la plateforme, dans `server` pour les interactions avec l'environnement, puis dans les packages spécialisés.
 
-- `@duplojs/lang` : primitives et manipulations JavaScript indépendantes de la plateforme.
-- `@duplojs/server` : interactions avec l'environnement d'exécution serveur, notamment le système de fichiers. Par exemple, calculer un chemin avec `lang/path` et lire un fichier avec `server/file`.
-- Pour un besoin spécialisé, rechercher le package et les API adaptés dans l'écosystème à partir de la documentation.
+Importer le sous-export du domaine avec son namespace long, comme dans les exemples des références.
 
-Importer le sous-export du domaine avec son namespace long lorsqu'il est exposé, comme dans les exemples liés depuis les références.
+## Modifier à l'endroit responsable
 
-## Laisser les types s'inférer
+Lire les contrats, définitions et appelants concernés ; intégrer le besoin dans la fonction, le modèle ou le module responsable. Limiter le remaniement au besoin, adapter les usages et vérifier les garanties conservées.
 
-Dans les implémentations, laisser TypeScript inférer les retours des fonctions et les valeurs issues des appels pour que leurs types suivent le code et ses dépendances. Ne pas reconstituer manuellement un type que l'expression ou l'API peut inférer. Annoter un type de retour uniquement pour résoudre une récursivité. Les signatures d'interfaces et les déclarations de fonctions des exemples décrivent des contrats à implémenter ; elles ne demandent pas d'annoter le retour de leur implémentation.
+Privilégier fonctions pures, immutabilité et transformations explicites ; isoler les interactions avec l'environnement.
 
-## Faire évoluer le code à l'endroit responsable
+## Laisser les types s'inférer
 
-Lire les définitions, les contrats et les appelants concernés, puis intégrer le besoin dans la fonction, le modèle ou le module responsable. Si les adaptations se multiplient dans le traitement ou chez ses appelants, réexaminer cette responsabilité et simplifier la partie concernée.
+Laisser TypeScript inférer les valeurs et les retours des implémentations. Annoter un retour uniquement pour résoudre une récursivité ; les signatures d'interfaces et les déclarations de fonctions décrivent des contrats, pas cette annotation dans l'implémentation.
 
-Privilégier les fonctions pures, l'immutabilité et des transformations explicites. Isoler les interactions avec l'environnement et représenter les échecs prévisibles dans les types de retour. Recomposer les étapes ou extraire une responsabilité lorsque cela clarifie le traitement, en conservant les garanties métier et le rôle de chaque couche.
+## Composer les transformations
 
-Limiter le remaniement au besoin demandé, puis relire la partie modifiée avec ses usages : déroulement compréhensible, absence de duplication et complexité proportionnée. Adapter les appelants concernés et vérifier les contrats ainsi que le comportement attendu.
+Si la fonction retournée par une forme curifiée ne déclare pas ses propres génériques, écrire l'appel de configuration directement dans l'étape de `DCommon.pipe` ou `asyncPipe` : son contexte permet l'inférence. Ne pas préparer cette étape dans une variable ni forcer son typage par génériques, annotations ou casts. Lire [Composition](references/composition.md) lors de l'emploi d'une forme curifiée pour distinguer les deux niveaux de génériques.
 
-## Composer les transformations
+Écrire chaque argument du pipe sur sa propre ligne, avec virgule finale et fermeture séparée, même pour une donnée et une seule étape. Un appel simple peut rester direct ; préparer séparément les données de sources indépendantes avant de les combiner.
 
-De nombreuses fonctions proposent une forme curifiée pour `DCommon.pipe` : fournir les paramètres fixes directement dans l'étape du pipe, puis laisser celui-ci transmettre la donnée.
+Choisir `DCommon.asyncPipe` pour attendre les étapes, ou `DEither.rightPipe` / `rightAsyncPipe` pour transmettre les valeurs des `Right` et arrêter au premier `Left`. À toute étape produisant des états à sélectionner, composer production et sélection dans un pipe interne à sa callback, avant le déballage par le pipe extérieur. Lire [Composition](references/composition.md) pour ces enchaînements de résultats.
 
-Lorsque la fonction retournée par la forme curifiée ne déclare pas ses propres génériques, ses types sont fixés lors de l'appel de configuration. Écrire cet appel directement comme argument de `pipe` ou `asyncPipe` : le contexte doit être disponible au moment de configurer l'étape. Préparer la fonction dans une variable puis passer cette variable à un pipe reste une préparation isolée ; l'ajout du pipe ne corrige pas cet usage. Ne pas ajouter des génériques explicites, annotations ou casts pour le forcer. L'[exemple de composition](references/examples/composition.ts) montre l'appel dans le pipe et la préparation à éviter ; [Composition](references/composition.md) explique les deux niveaux de signature.
+## Remplacer les boucles impératives
 
-Toujours écrire les appels de pipe sur plusieurs lignes : chaque argument sur sa propre ligne, une virgule après le dernier et la parenthèse de fermeture sur une ligne séparée. Appliquer ce format même avec seulement deux arguments, une donnée et une étape ; écrire l'appel curifié lui-même à la ligne de cette étape.
+Ne pas écrire de `for`, de `while` ni leurs variantes. Utiliser :
 
-Un appel simple peut rester direct. Préparer séparément les données issues de sources indépendantes avant de les combiner ; les appels curifiés des étapes restent dans le pipe. Pour plusieurs étapes asynchrones, `DCommon.asyncPipe` attend chaque étape ; un seul `await` sur le résultat final suffit.
+- `DArray.reduce` pour parcourir un tableau avec un accumulateur ; `DGenerator.reduce` pour un autre itérable.
+- `DGenerator.asyncReduce` pour un parcours asynchrone, y compris sur un tableau.
+- `DCommon.loop` pour une répétition conditionnelle ; `DCommon.asyncLoop` en asynchrone.
+- `DCommon.loopAccumulator` et `DCommon.asyncLoopAccumulator` pour transporter un accumulateur entre les tours d’une répétition conditionnelle.
+- `DGenerator.loop` et `DGenerator.asyncLoop` pour produire une séquence ; leurs variantes `loopAccumulator` transportent aussi un accumulateur.
 
-Lorsque les étapes doivent s'arrêter sur un `Left`, utiliser `DEither.rightPipe` ou `DEither.rightAsyncPipe` : chaque étape reçoit la valeur du `Right` précédent et le premier `Left` arrête la suite. Lire [Composition](references/composition.md) avant de construire ou modifier un tel enchaînement ; l'[exemple direct et curifié](references/examples/composition.ts) montre le cas synchrone sans échec.
+Dans les variantes `loopAccumulator`, transmettre l'état avec `next(nouvelAccumulateur)` ; `DGenerator.loop` et `DGenerator.asyncLoop` utilisent `next` pour émettre des valeurs. Dans `DCommon.loop` et `DCommon.asyncLoop`, `next` poursuit la boucle sans transmettre son argument au tour suivant. Terminer avec `exit`. Avant de créer ou remplacer une boucle, lire [Itérations](references/iterations.md) pour les contrats de ces callbacks. Pour une simple transformation ou sélection, utiliser directement `DArray.map` ou `DArray.filter`.
 
 ## Valider les entrées et conserver les garanties
 
-Aux frontières du logiciel, valider les données externes avec une `DDataStructure`, qui porte leur contrat au runtime et dans les types. Utiliser l'intégration prévue par le module récepteur lorsqu'elle existe. Dans les traitements internes, exploiter les garanties déjà établies, sans refaire une validation pour le seul passage d'une fonction à une autre.
-
-Préciser les contraintes utiles : bornes, entier, format, longueur minimale, maximale ou exacte. Une contrainte enrichit le type ; sa seule déclaration ne valide rien au runtime.
+Valider les données externes avec une `DDataStructure`, via l'intégration du module récepteur lorsqu'elle existe. Décrire les contraintes utiles : bornes, entier, format ou longueur. Une contrainte déclarée ne valide rien au runtime ; dans les traitements internes, réutiliser les garanties établies.
 
-Choisir la construction selon les informations disponibles :
+Choisir selon la preuve disponible :
 
-1. **Littéral ou garantie compatible** : déclaration sûre ou calcul de compatibilité avec `DCommon.cast` ; utiliser `DCommon.infer` si le littéral doit être conservé.
-2. **Valeur runtime sans preuve** : validation ou fabrique sûre renvoyant un `Either` à traiter ou propager.
-3. **Refus du compilateur** : vérifier l'inférence et l'origine de la garantie attendue ; ne pas la fabriquer avec `as`, `!` ou un helper sans preuve.
+- **Littéral ou garantie compatible** : déclaration sûre ou `DCommon.cast` ; `DCommon.infer` pour conserver aussi le littéral. Ces fonctions calculent une compatibilité statique, sans validation runtime.
+- **Valeur runtime sans preuve** : validation ou fabrique sûre, puis traitement du `Either`.
+- **Refus du compilateur** : vérifier l'inférence et l'origine de la garantie ; ne pas la fabriquer avec `as`, `!` ou un helper sans preuve.
 
-`cast` et `infer` calculent une compatibilité de types, sans validation runtime. Pour écrire un contrat de validation, construire une valeur contrainte ou résoudre un refus de compatibilité, lire [Contraintes et validation](references/constraints-and-validation.md). L'[exemple de validation](references/examples/input-validation.ts) montre l'acquisition de garanties depuis une entrée inconnue.
+Lire [Contraintes et validation](references/constraints-and-validation.md) pour construire un contrat, une valeur contrainte ou résoudre un refus de compatibilité. Après chaque transformation, suivre les garanties restantes et exploiter les accès garantis sans garde redondante.
 
-Après chaque transformation, suivre le type du résultat : une garantie peut avoir été préservée, renforcée ou perdue. Exploiter les accès garantis aux collections sans garde redondante. Si la cible de `cast` n'est pas inférée dans un appel générique, lire la difficulté d'inférence de la référence avant de modifier les types.
+## Représenter les résultats et propager les erreurs
 
-## Distinguer les résultats des défaillances d'environnement
+Utiliser `DEither.result` lorsqu'une fonction doit établir des états sans décider de leur caractère favorable ou défavorable. L'information distingue les états ; la valeur porte leur contexte. Tous ces `Result` sont des `Right` : `isRight` ne choisit pas un état particulier.
 
-Une issue prévisible et exploitable par le traitement appartient au contrat de résultat : réussite en `Right`, refus en `Left`. Cela comprend les validations de données externes, les absences et les manipulations impossibles, y compris techniques. L'information du résultat identifie le cas ; sa valeur transporte les données ou les détails du refus.
+Lorsque la fonction décide d'une réussite ou d'un refus prévisible, les exprimer en `Right` ou `Left`, y compris pour les absences et refus techniques. Si une branche renvoie un `Either`, toutes en renvoient un ; utiliser `DEither.ok()` pour une réussite sans valeur.
 
-Dès qu'une branche d'une fonction renvoie un `Right` ou un `Left`, toutes ses branches renvoient un `Either`. Envelopper les valeurs de réussite dans un `Right`, y compris avec `DEither.ok()` pour une réussite sans valeur ; ne pas mélanger des `Either` et des valeurs brutes dans le contrat de retour.
+Chez le consommateur, sélectionner les issues qui autorisent la suite avec `keepAsRightByInformation` ; les autres deviennent des `Left` en conservant information et valeur. Utiliser un sélecteur exhaustif comme `keepAsRightSelection` ou `matchInformation` lorsqu'une nouvelle variante doit obliger à réexaminer la décision.
 
-Les exceptions de défaillance imprévue émises par les dépendances ou le runtime remontent implicitement. Les fonctions réutilisables n'ajoutent pas de `throw` ; elles propagent ou adaptent leurs `Left`. Discriminer le résultat avant de le déballer.
+`unwrapRight` extrait les valeurs des `Right` et conserve les `Left` : le pattern sélection → `unwrapRight` → garde `isLeft` permet un retour anticipé sûr. Propager ou adapter les refus dans les fonctions réutilisables. Lire [Résultats et erreurs](references/results-and-errors.md) pour choisir la sélection et l'extraction.
 
-Réserver les `throw` explicites et `OrThrow` à la consommation finale du résultat par la frontière d'exécution : réponse, fin du programme ou exception adaptée. Être appelé depuis cette frontière ne suffit pas à autoriser un `throw`. La rareté ou le coût de propagation d'un refus prévisible ne changent pas cette règle.
+Les exceptions imprévues des dépendances ou du runtime remontent implicitement. Réserver les `throw` explicites et `OrThrow` à la consommation finale du résultat par la frontière d'exécution. Une fonction réutilisable n'ajoute pas de `throw`, même appelée depuis cette frontière. La rareté du refus ou son coût de propagation ne changent pas cette règle.
 
-Avant d'adapter une API qui lève sur un refus prévisible ou d'introduire `OrThrow`, lire [Résultats et erreurs](references/results-and-errors.md) pour choisir le traitement selon la responsabilité de l'appelant. Préférer les déclarations sûres pour les constantes connues ; l'[exemple de propagation](references/examples/error-propagation.ts) conserve les erreurs d'une opération dans le contrat de retour.
+Avant d'adapter une API qui lève sur un refus prévisible ou d'introduire `OrThrow`, lire [Résultats et erreurs](references/results-and-errors.md). Préférer les déclarations sûres pour les constantes connues.

package/skills/fundamental/references/composition.md

@@ -1,35 +1,19 @@
-# Composer une opération
+# Composition
 
-## Forme directe et forme curifiée
+## Configurer dans le contexte du pipe
 
-La forme directe reçoit la donnée et les paramètres. La forme curifiée reçoit les paramètres dans l'étape du pipe, puis retourne la fonction qui recevra la donnée.
+La forme directe reçoit donnée et paramètres ; la forme curifiée configure les paramètres puis reçoit la donnée. Une fonction déjà unaire peut être passée directement.
 
-Lire la surcharge curifiée en distinguant les génériques de l'appel de configuration de ceux de la fonction retournée. Quand cette dernière ne déclare pas ses propres génériques, ses types sont déjà fixés à la configuration ; un appel ultérieur avec la donnée ne les infère pas à nouveau. Les génériques présents sur la surcharge extérieure ne rendent pas la fonction retournée générique.
+Si la fonction retournée ne déclare pas ses propres génériques, ses types sont fixés à la configuration. Écrire cet appel dans l'étape du pipe apporte le contexte d'inférence ; passer ensuite une variable déjà configurée à un pipe ne le rétablit pas. Ne pas forcer cette préparation par génériques, annotations ou casts.
 
-Cette signature indique un usage directement dans `DCommon.pipe` ou `DCommon.asyncPipe`, dont le contexte fournit le type de la donnée lors de la configuration. Écrire l'appel de la forme curifiée à l'intérieur des arguments du pipe. Une fonction préparée dans une variable reste hors de ce contexte, même si cette variable est ensuite utilisée comme étape d'un pipe. Ne pas ajouter annotations, génériques explicites ou casts pour rendre cette préparation typable. Pour réutiliser le traitement, écrire une fonction qui reçoit la donnée et construit son pipe, ou utiliser la forme directe avec cette donnée.
+Pour réutiliser le traitement, écrire une fonction recevant la donnée et construisant son pipe, ou utiliser la forme directe. L'[exemple de composition](examples/composition.ts) montre les deux formes, le format multiligne et une préparation à éviter.
 
-Comparer les formes directe et curifiée dans [cet exemple de transformation](examples/composition.ts). Les vérifications de type montrent l'inférence lorsque les appels sont écrits dans le pipe. Le cas à éviter utilise des génériques explicites pour préparer une fonction, puis la passe à un pipe : ce code peut compiler tout en contredisant l'usage attendu.
-
-Le pipe suit ici une même donnée : utilisateurs, utilisateurs actifs, noms. Une fonction déjà unaire de l'API peut être passée directement, comme `DString.trim`. Pour une forme curifiée, écrire son appel de configuration dans l'étape. Ne pas supposer que toutes les fonctions exposent les mêmes surcharges.
-
-## Mise en forme des pipes
-
-Écrire tous les appels de pipe sur plusieurs lignes, avec chaque argument sur sa propre ligne, une virgule après le dernier argument et la parenthèse de fermeture sur une ligne séparée. Ce format s'applique aussi à une donnée suivie d'une seule étape, comme dans le premier pipe de l'exemple. L'appel qui configure la forme curifiée occupe la ligne de l'étape ; une variable préparée auparavant ne le remplace pas.
-
-## Plusieurs sources indépendantes
-
-Quand plusieurs données indépendantes demandent chacune leur propre préparation, les nommer avant de les combiner. Cette préparation concerne les données ; les appels curifiés restent écrits dans les étapes de leur pipe.
-
-Voir [la préparation de deux arguments indépendants](examples/independent-inputs.ts).
-
-Le résultat de cet appel peut ensuite devenir l'entrée d'un autre pipe si plusieurs transformations se suivent.
+Préparer les données de sources indépendantes avant de les combiner ; les configurations curifiées restent dans leur pipe. Voir [deux sources indépendantes](examples/independent-inputs.ts).
 
 ## Asynchronisme et résultats
 
-`DCommon.asyncPipe` attend chaque étape avant la suivante. Un seul `await` sur le pipe suffit pour obtenir le résultat final.
-
-Voir [un enchaînement asynchrone](examples/async-composition.ts).
+`DCommon.asyncPipe` attend chaque étape ; un seul `await` final suffit. Voir l'[exemple asynchrone](examples/async-composition.ts).
 
-Si chaque étape peut renvoyer un `Either`, utiliser `DEither.rightPipe` ou `DEither.rightAsyncPipe` pour propager automatiquement le premier `Left`. Un pipe ordinaire ne décide pas à lui seul comment traiter un `Left`. Les pipes de `DEither` transmettent la valeur du `Right` à l'étape suivante, et non son wrapper.
+`DEither.rightPipe` et `rightAsyncPipe` transmettent les valeurs des `Right` et arrêtent au premier `Left`. Un pipe ordinaire ne s'arrête pas automatiquement sur un `Left`. Pour sélectionner un état produit par une étape, composer production et sélection dans un `innerPipe` ou `asyncInnerPipe`, avant de rendre le résultat au pipe extérieur. Une callback construisant un `pipe` ou `asyncPipe` convient aussi.
 
-Pour approfondir, rechercher la currification et la composition des `Either` dans `docs/concepts.llms.md`, depuis la racine AgentKit indiquée dans les instructions du projet.
+Ce montage s'applique à toute étape ou callback imbriquée. À l'étape extérieure suivante, le `Right` serait déjà déballé, sans son information. Voir la [sélection intermédiaire](examples/result-selection.ts).

package/skills/fundamental/references/constraints-and-validation.md

@@ -1,61 +1,24 @@
-# Contraintes, déclarations et validation
+# Contraintes et validation
 
-## Une garantie doit avoir une origine
+## Établir la garantie
 
-Une contrainte exprime dans le typage une propriété de la valeur : entier, borne, longueur ou format. Une intersection cumule les garanties, par exemple `number & DNumber.Integer & DNumber.LessThan<25>`.
+Une contrainte exprime une propriété dans les types : borne, longueur ou format. Les intersections cumulent ces garanties ; leur déclaration seule ne valide ni ne transforme une valeur.
 
-Déclarer ce type ne valide rien et ne transforme pas la valeur. La garantie vient d'une validation runtime, d'un prédicat qui affine le type, d'une fonction qui préserve cette propriété ou d'un calcul de compatibilité sur une information déjà connue statiquement.
+Aux frontières, décrire le contrat complet avec une `DDataStructure` et les contraintes du besoin. Fournir cette structure au module récepteur lorsqu'il propose une intégration ; sinon, valider explicitement et traiter le `Either`. Réutiliser ensuite les garanties établies. Voir [le contrat d'entrée](examples/input-validation.ts).
 
-## Entrées : décrire le contrat complet
+## Choisir la construction
 
-Une donnée reçue à une frontière externe passe par un data parser avant d'être considérée fiable. Une `DDataStructure` porte un schéma commun au runtime et au typage ; ses contraintes précisent le contrat au-delà de la nature de la donnée. Dans les fonctions internes, réutiliser les garanties déjà établies et suivre celles que les transformations conservent.
+- **Valeur connue statiquement ou garantie compatible** : `DCommon.cast` calcule les implications statiques que TypeScript ne déduit pas seul. La cible vient du type attendu ; aucune validation runtime n'est effectuée. Voir [les conversions](examples/cast.ts).
+- **Littéral à conserver** : `DCommon.infer` conserve aussi le type littéral et exige une entrée littérale. Voir [une propriété littérale](examples/infer.ts).
+- **Valeur runtime sans preuve** : validation par une structure, un prédicat ou une fabrique sûre. Une simple `string` ou un simple `number` ne prouve pas de contrainte.
+- **Constante spécialisée** : chercher une déclaration sûre du domaine avant `OrThrow`. Vérifier la surcharge : selon l'argument, elle peut retourner une valeur ou un `Either`. Voir [les chemins et Chrono](examples/safe-declarations.ts).
 
-Voir [un contrat et sa validation](examples/input-validation.ts).
+Un refus de `cast` indique une compatibilité non établie : vérifier l'inférence ou le support du calcul pour une contrainte personnalisée, puis choisir une validation si nécessaire. Ne pas fabriquer la preuve avec une assertion ou un helper.
 
-Choisir les contraintes selon les règles du besoin : bornes inclusives ou exclusives des nombres, minimum, maximum ou longueur exacte des chaînes et tableaux, formats, etc. Chaque contrainte d'une structure doit être compatible avec le type de donnée décrit.
+Si un paramètre générique direct ne fournit pas la cible de `cast` ou `infer`, l'expliciter avec `satisfies` après l'appel. Ce contexte ne valide rien et n'est pas nécessaire partout : comparer [le paramètre générique](examples/generic-inference.ts) et [la propriété littérale](examples/infer.ts).
 
-Pour les entrées gérées par l'écosystème, chercher comment le module qui les reçoit accepte des structures et lui fournir le contrat. Exploiter ensuite les valeurs déjà validées. À une frontière qui n'offre pas cette intégration, appeler explicitement la validation et traiter son `Either`.
+## Exploiter les garanties restantes
 
-Exemples d'intégrations : `DSCommand.createArgument` et `DSCommand.createOption` pour une commande ; `.extract(...)` pour une route `@duplojs/http`. La règle s'applique à tout module qui reçoit des données externes.
+Suivre ce que chaque transformation préserve ou perd. Une longueur minimale garantit certains accès ; l'exploiter sans garde redondante. Elle ne garantit pas les indices au-delà du minimum, et n'enlève pas `undefined` du type propre aux éléments. Un filtre peut perdre cette garantie de longueur.
 
-## `cast` : compatibilité calculée par TypeScript
-
-`DCommon.cast` restitue la valeur sans validation runtime. Le type attendu donne la cible du calcul. Une garantie plus forte peut impliquer une garantie plus faible ; un littéral peut aussi fournir assez d'information.
-
-Voir [les conversions de contraintes et les déclarations littérales](examples/cast.ts).
-
-Ce calcul de types comble les implications que TypeScript ne déduit pas de lui-même. Il n'y a pas de calcul dynamique de validité lors de l'exécution. Une simple `string` ou un simple `number` provenant du runtime ne prouve pas une longueur, un format ou une borne.
-
-Si `cast` émet une erreur, considérer que la compatibilité n'est pas établie. Une règle personnalisée peut ne pas avoir de support de calcul enregistré. Ne pas remplacer ce refus par `as`, une double assertion ou un helper qui fabrique la contrainte sans preuve. Vérifier l'inférence, valider par une structure ou un prédicat adapté, ou utiliser une autre construction sûre.
-
-## `infer` : conserver également le littéral
-
-Préférer `cast` dans le cas courant. Utiliser `DCommon.infer` lorsqu'une valeur connue statiquement doit garder son type littéral en plus des contraintes calculées. Cette fonction exige une entrée littérale ; elle ne sert pas à valider une donnée runtime.
-
-Voir [la conservation du littéral dans une propriété](examples/infer.ts).
-
-## Difficulté d'inférence : cible d'un paramètre générique direct
-
-Lorsque `cast` ou `infer` est passé à un paramètre lui-même générique, TypeScript peut ne pas fournir une cible assez précise au calcul. Si le type attendu n'est pas inféré dans cette situation, l'expliciter avec `satisfies` immédiatement après l'appel. Ce traitement répond à une difficulté de contexte ; il n'est pas nécessaire à chaque utilisation de ces fonctions.
-
-Voir [le calcul des contraintes avec un paramètre générique direct](examples/generic-inference.ts).
-
-`satisfies` fournit le contexte du calcul ; il ne contourne pas la validation. Une propriété contrainte d'un objet générique peut déjà fournir ce contexte, comme dans [l'exemple de propriété littérale](examples/infer.ts) : ne pas ajouter ce contournement d'inférence partout.
-
-## Déclarations spécialisées et Chrono
-
-Les domaines proposent aussi des helpers pour les valeurs connues. Préférer ces déclarations sûres à `OrThrow`.
-
-Voir [les déclarations de chemins et de valeurs Chrono](examples/safe-declarations.ts).
-
-Vérifier la surcharge réellement utilisée : le type de l'argument détermine si la fonction retourne directement la valeur ou un `Either`.
-
-## Les contraintes simplifient les opérations suivantes
-
-Voir [les accès garantis après validation du tableau](examples/guaranteed-array-access.ts).
-
-`MinElements<2>` garantit les indices `0` et `1` et l'existence du dernier élément. L'indice `2` reste incertain : un minimum de deux n'impose pas un maximum de deux. Les éléments garantis sont retournés directement, sans `Maybe` ni `undefined` ajouté pour une éventuelle absence. Une borne maximale ou une longueur exacte peut aussi permettre de prouver qu'un indice est absent.
-
-Exploiter ces garanties sans garde redondante ni assertion. Respecter cependant le type propre aux éléments : un tableau dont les éléments peuvent eux-mêmes être `undefined` conserve cette possibilité. Après une transformation, suivre les contraintes du résultat ; un filtre peut supprimer des éléments et perdre une garantie de minimum.
-
-Pour approfondir, rechercher les contraintes, les data structures, Chrono ou l'intégration du module concerné dans `docs/concepts.llms.md`, depuis la racine AgentKit indiquée par les instructions du projet.
+Voir [les accès garantis](examples/guaranteed-array-access.ts) pour distinguer présence prouvée et accès incertain.

package/skills/fundamental/references/examples/iterations.ts

@@ -0,0 +1,112 @@
+/**
+ * @title Remplacer les boucles par les primitives DuploJS.
+ *
+ * Accumulateurs immuables, sortie anticipée et répétitions conditionnelles.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+import * as DNumber from "@duplojs/lang/number";
+
+interface RunningTotals {
+	readonly total: number;
+	readonly subtotals: readonly number[];
+}
+
+const runningTotals = DCommon.pipe(
+	[2, -1, 4],
+	DArray.reduce(
+		DArray.reduceFrom<RunningTotals>({
+			total: 0,
+			subtotals: [],
+		}),
+		({ element, lastValue, nextWithObject }) => {
+			const total = DNumber.sum([lastValue.total, element]);
+			return nextWithObject(lastValue, {
+				total,
+				subtotals: DArray.push(lastValue.subtotals, total),
+			});
+		},
+	),
+);
+
+// Résultat : { total: 5, subtotals: [2, 1, 5] }. Chaque étape dépend du total précédent.
+// L'accumulateur initial et la source ne sont pas mutés.
+type _CheckRunningTotals = DCommon.ExpectType<typeof runningTotals, RunningTotals, "strict">;
+
+const totalOrStop = DCommon.pipe(
+	[2, -1, 4],
+	DArray.reduce(
+		0,
+		({ element, lastValue, next, exit }) => element < 0
+			? exit("negative-value")
+			: next(DNumber.sum([lastValue, element])),
+	),
+);
+
+// Résultat : "negative-value" ; 4 n'est pas traité. exit peut changer le type du résultat.
+type _CheckTotalOrStop = DCommon.ExpectType<typeof totalOrStop, number | string, "strict">;
+
+declare function loadAmount(id: string): Promise<number>;
+
+const loadedTotal = await DCommon.asyncPipe(
+	["first", "second"],
+	DGenerator.asyncReduce(
+		0,
+		async({ item, lastValue, next }) => {
+			const amount = await loadAmount(item);
+			return next(DNumber.sum([lastValue, amount]));
+		},
+	),
+);
+
+// Chaque chargement est attendu avant le suivant ; la source peut aussi être un AsyncIterable.
+type _CheckLoadedTotal = DCommon.ExpectType<typeof loadedTotal, number, "strict">;
+
+const reachedValue = DCommon.loopAccumulator(0, ({ accumulator, next, exit }) => {
+	// La condition est vérifiée avant le traitement, comme dans un while.
+	if (accumulator >= 3) {
+		return exit(accumulator);
+	}
+
+	return next(DNumber.sum([accumulator, 1]));
+});
+
+// Résultat : 3. L'état circule dans l'accumulateur de la boucle.
+type _CheckReachedValue = DCommon.ExpectType<typeof reachedValue, number, "strict">;
+
+declare function readBatchSize(index: number): Promise<number>;
+
+const processedTotal = await DCommon.asyncLoopAccumulator(0, async({
+	count,
+	accumulator,
+	next,
+	exit,
+}) => {
+	const size = await readBatchSize(count);
+
+	// La première taille nulle termine la lecture ; exit retourne le total accumulé.
+	if (size === 0) {
+		return exit(accumulator);
+	}
+
+	return next(DNumber.sum([accumulator, size]));
+});
+
+type _CheckProcessedTotal = DCommon.ExpectType<typeof processedTotal, number, "strict">;
+
+const emitted = DArray.from(DGenerator.loop(({ count, next, exit }) => count === 3
+	? exit("done")
+	: next(count)));
+
+// DGenerator.loop émet les sorties de next puis celles de exit.
+type _CheckEmitted = DCommon.ExpectType<typeof emitted, readonly (number | "done")[], "strict">;
+
+const emittedWithAccumulator = DArray.from(
+	DGenerator.loopAccumulator(0, ({ accumulator, count, next, exit }) => count === 3
+		? exit(accumulator)
+		: next(accumulator + 1, accumulator)),
+);
+
+// Chaque sortie peut être produite au même moment que le nouvel accumulateur est choisi.
+type _CheckEmittedWithAccumulator = DCommon.ExpectType<typeof emittedWithAccumulator, readonly number[], "strict">;

package/skills/fundamental/references/examples/result-selection.ts

@@ -0,0 +1,65 @@
+/**
+ * @title Sélectionner les résultats selon l'opération.
+ *
+ * Constater un état, sélectionner les issues utiles et conserver les refus.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DEither from "@duplojs/lang/either";
+
+interface Item {
+	id: string;
+	enabled: boolean;
+}
+
+function classifyItem(item: Item) {
+	if (item.enabled) {
+		return DEither.result("ready", item);
+	}
+
+	return DEither.result("blocked", item);
+}
+
+function prepareItem(item: Item) {
+	const selected = DCommon.pipe(
+		item,
+		classifyItem,
+		DEither.keepAsRightByInformation("ready"),
+		DEither.unwrapRight,
+	);
+
+	// unwrapRight conserve le Left : la garde peut suivre l'extraction.
+	if (DEither.isLeft(selected)) {
+		return selected;
+	}
+
+	return DEither.right("prepared", selected);
+}
+
+type _CheckPrepared = DCommon.ExpectType<
+	ReturnType<typeof prepareItem>,
+	DEither.Left<"blocked", Item> | DEither.Right<"prepared", Item>,
+	"strict"
+>;
+
+declare function loadItem(id: string): Promise<DEither.Maybe<Item>>;
+declare function saveItem(item: Item): Promise<DEither.Right<"saved", Item>>;
+
+const saved = await DEither.rightAsyncPipe(
+	loadItem("item"),
+	// L'inner pipe intervient après la recherche, à une étape intermédiaire.
+	DCommon.innerPipe(
+		classifyItem,
+		DEither.keepAsRightSelection({
+			ready: true,
+			blocked: false,
+		}),
+	),
+	// L'étape extérieure reçoit l'Item déballé ; un Left évite cet appel.
+	(item) => saveItem(item),
+);
+
+type _CheckSaved = DCommon.ExpectType<
+	typeof saved,
+	DEither.None | DEither.Left<"blocked", Item> | DEither.Right<"saved", Item>,
+	"strict"
+>;

package/skills/fundamental/references/iterations.md

@@ -0,0 +1,24 @@
+# Itérations
+
+## Parcourir une collection
+
+Configurer `DArray.reduce(initial, callback)` dans l'étape d'un `DCommon.pipe` recevant le tableau. La callback reçoit `element`, `index` et `lastValue`, initialement égal à l'accumulateur de départ :
+
+- `next(nouvelÉtat)` poursuit ; `next(lastValue)` ignore l'élément.
+- `exit(résultat)` arrête immédiatement et peut changer le type de sortie.
+
+Sans `exit`, le résultat est le dernier accumulateur ; une source vide retourne l'initial. Pour un état structuré, utiliser `DArray.reduceFrom<Type>(valeur)` et construire les nouveaux états sans mutation.
+
+Pour un autre itérable, utiliser `DGenerator.reduce`. `DGenerator.asyncReduce` accepte tableaux, itérables synchrones ou asynchrones et attend chaque étape. Leurs callbacks reçoivent `item` ; initialiser leurs états structurés avec `DGenerator.reduceFrom`.
+
+## Répéter jusqu'à une condition
+
+`DCommon.loop` fournit `count` depuis zéro. `next()` continue et `exit(valeur)` retourne le résultat final. La donnée optionnelle de `next` n'est pas transmise au tour suivant ; utiliser `DCommon.loopAccumulator(initial, callback)` lorsque les tours doivent partager un état. Sa callback reçoit `accumulator`, `count`, `next(nouvelAccumulateur)` et `exit(résultat)`. `DCommon.asyncLoop` et `DCommon.asyncLoopAccumulator` offrent les mêmes comportements en attendant la callback asynchrone.
+
+`DGenerator.loop(callback)` produit une séquence : chaque `next(...valeurs)` émet les valeurs définies et poursuit la boucle ; `exit(...valeurs)` émet sa dernière séquence puis termine. La callback reçoit `count`, pas la valeur du tour précédent. `DGenerator.asyncLoop` attend les callbacks et résout les valeurs promises avant de les émettre.
+
+Les variantes `DGenerator.loopAccumulator(initial, callback)` et `DGenerator.asyncLoopAccumulator(initial, callback)` font circuler un accumulateur avec `next(nouvelAccumulateur, ...valeursÀÉmettre)`. `exit(...valeursÀÉmettre)` termine en émettant les dernières valeurs. Utiliser `DGenerator.loopAccumulatorFrom<Type>(valeur)` pour préserver un type d'accumulateur structuré ou une union.
+
+Conserver la condition avant le traitement d'un `while`, après celui d'un `do...while`. Pour une répétition par compteur, utiliser aussi `loop`, sans fabriquer un tableau.
+
+Voir les [exemples typés](examples/iterations.ts), avec accumulateurs, sorties anticipées et variantes asynchrones.

package/skills/fundamental/references/results-and-errors.md

@@ -1,59 +1,34 @@
-# Résultats typés et exceptions
+# Résultats et erreurs
 
-## Choisir selon la place de l'échec dans le traitement
+## Choisir le contrat
 
-Identifier les issues prévisibles que l'appelant doit pouvoir exploiter, puis les exprimer dans le contrat `Either`. Un refus peut concerner une règle métier, une vérification ou une manipulation technique. Une opération sur l'environnement ne justifie donc pas à elle seule une exception. Pour la distinction conceptuelle avec une défaillance de l'environnement, lire « Conversion des absences et exceptions en résultats » depuis le routeur du package installé.
+Une fonction qui établit des états sans décider lesquels conviennent à l'appelant produit des `DEither.Result` nommés. Tous sont des `Right` ; les distinguer par leur information.
 
-Lorsqu'une fonction renvoie un `Either` dans une branche, toutes ses branches renvoient un `Either` : `DEither.Right` pour la réussite et `DEither.Left` pour le refus. Envelopper aussi une réussite sans valeur avec `DEither.ok()`, plutôt que retourner `undefined` à côté d'un `Left`. L'information identifie le cas ; la valeur associée transporte les détails utiles. Voir [une fonction qui propage les échecs de lecture](examples/error-propagation.ts).
+Une fonction qui décide d'une réussite ou d'un refus prévisible les exprime en `Right` ou `Left`, y compris pour les absences et refus techniques. Toutes ses branches renvoient un `Either` ; `DEither.ok()` représente une réussite sans valeur.
 
-Le `Left` de lecture reste visible dans le type de retour. Une autre fonction peut le propager, l'adapter ou tenter une récupération. Une absence de ressource exploitable par l'algorithme ne devient pas une panne d'environnement parce qu'elle provient d'une I/O. Ne pas la masquer par un `throw` ou un unwrap qui lève.
+## Sélectionner et poursuivre
 
-`DEither.rightPipe` et `DEither.rightAsyncPipe` composent les étapes sur les valeurs de réussite et arrêtent au premier `Left`. `DEither.isRight` et `DEither.isLeft` permettent une discrimination explicite avant `unwrapRight` ou `unwrapLeft`.
-
-Pour une API qui lève sur un refus prévisible, adapter ses erreurs documentées en résultats. `DEither.safeCallback` et `DEither.asyncSafeCallback` capturent les exceptions ; examiner ensuite la cause pour distinguer le refus attendu d'une défaillance imprévue. Conserver une cause technique capturée dans le résultat jusqu'à sa consommation finale, sans la requalifier en refus métier ni la relancer depuis l'adaptation réutilisable. Préférer d'abord l'API DuploJS sûre si elle existe ; ne pas capturer systématiquement les exceptions des dépendances.
-
-## Le consommateur final décide de l'effet
-
-La frontière d'exécution consomme le résultat après le retour des fonctions appelées et décide de sa conséquence finale. C'est à ce stade que le code applicatif peut écrire un `throw` ou utiliser `OrThrow` pour interrompre l'exécution. Déclarer une fonction au niveau d'un module ou l'appeler depuis un point d'entrée ne lui donne pas cette responsabilité.
-
-Exemples : initialisation du programme, callback d'une commande ou handler d'une route.
-
-```text
-entrée externe
-  → validation par les schémas du module
-  → point d'entrée du traitement
-    → fonction applicative
-      → sous-fonction : renvoie les issues prévues en Right ou Left
-    ← résultat typé
-  ← résultat typé
-  → le point d'entrée décide de l'effet final
-```
-
-Les fonctions applicatives et leurs sous-fonctions renvoient les refus prévisibles dans leur contrat de retour, sans créer leurs propres `throw`. Les exceptions déjà émises par les dépendances ou le runtime remontent implicitement à travers ces appels ; cette propagation ne demande pas d'ajouter un `throw`.
-
-À cette frontière, interpréter le `Left` selon le contrat d'exécution : par exemple produire une réponse HTTP, un diagnostic de commande ou une exception adaptée. Le fait qu'un appelant ignore le retour d'une fonction ne suffit pas à autoriser cette fonction à lever une exception.
+| Intention du consommateur | Outil |
+| --- | --- |
+| Autoriser certaines informations et refuser toutes les autres, même futures | `keepAsRightByInformation` |
+| Décider explicitement du statut de chaque variante | `keepAsRightSelection` |
+| Décider explicitement des variantes d'une garde | `isSelected` |
+| Traiter chaque information | `matchInformation` |
 
-## Choisir entre version sûre et `OrThrow`
+Les sélecteurs exhaustifs imposent de revoir la décision lorsqu'une variante apparaît. Une sélection partielle ou un repli exprime au contraire un comportement commun voulu.
 
-Préférer une déclaration sûre pour une valeur connue. Pour une opération qui peut échouer, examiner les branches que `OrThrow` convertirait en exceptions avant de choisir cette variante.
+Le reclassement conserve information et valeur. `unwrapRight` extrait les valeurs acceptées et conserve les `Left` : une garde `isLeft` peut ensuite retourner le refus. Si le contrat garantit uniquement des `Right` admis, l'extraction peut être directe. Voir [la sélection et le retour anticipé](examples/result-selection.ts).
 
-| Situation | Choix |
-| --- | --- |
-| Constante dont la validité est prouvable | `cast`, `infer`, helper de déclaration ou surcharge littérale sûre |
-| Vérification d'une donnée externe ou valeur runtime sans preuve | Validation ou fabrique sûre, puis traitement du `Either` |
-| Refus prévisible d'une fonction réutilisable, métier ou technique | Renvoyer, propager ou adapter le `Left` |
-| Exception de défaillance imprévue émise par une dépendance ou le runtime | La laisser remonter implicitement ; propager le résultat si elle a été capturée |
-| Point d'entrée décidant de l'effet final d'un résultat | Interpréter le `Left`, puis produire la réponse, la fin d'exécution ou l'exception adaptée |
-| Test affirmant un résultat attendu | `OrThrow` permet de faire échouer le test si le résultat diffère |
+Pour sélectionner à une étape d'un `rightPipe` avant son déballage automatique, lire [Composition](composition.md#asynchronisme-et-résultats).
 
-La commodité de l'extraction, la rareté supposée d'un refus ou la complexité de propagation ne changent pas sa nature. Une variante qui lève sur une absence exploitable ne convient pas à une fonction réutilisable qui doit transmettre ce cas.
+## Propager ou adapter un refus
 
-## Démarrage et tests : interpréter le résultat
+Une fonction réutilisable transmet ses refus à l'appelant, qui peut les propager, les adapter ou récupérer. Une absence exploitable reste un résultat, même issue d'une I/O. Voir [la propagation d'une erreur de lecture](examples/error-propagation.ts).
 
-Au démarrage, l'initialisation peut décider qu'une configuration invalide empêche l'exécution. `environmentVariableOrThrow` valide d'abord par la version sûre, puis traduit son `Left` en exception. Cet usage exprime la décision finale du point d'entrée ; une fonction qui doit transmettre le refus utilise `environmentVariable`.
+Préférer une API sûre. Si une API lève sur un refus documenté, `safeCallback` ou `asyncSafeCallback` permettent sa capture ; examiner la cause avant de la traduire. Une défaillance imprévue déjà levée remonte implicitement. Si elle est capturée, conserver sa cause dans le résultat jusqu'à la consommation finale, sans la requalifier en refus métier ni la relancer dans l'adaptation.
 
-Voir [la validation de l'environnement au démarrage](examples/environment-initialization.ts). Pour les entrées reçues pendant le fonctionnement du logiciel, conserver les résultats de validation jusqu'à leur interprétation par la frontière concernée.
+## Consommer le résultat final
 
-En tests, `OrThrow` peut extraire le résultat attendu ou préparer une fixture : une issue différente doit interrompre le test. Une déclaration sûre reste adaptée aux constantes connues, comme dans [les déclarations sûres](examples/safe-declarations.ts). Le code testé conserve ses résultats ; ces assertions ne justifient pas de le faire lever sur ses refus prévisibles.
+Réserver `throw` et `OrThrow` au code qui décide de la conséquence finale : réponse, diagnostic ou interruption du programme. Une fonction appelée depuis cette frontière reste responsable de transmettre ses résultats.
 
-Pour approfondir, rechercher les `Either`, l'environnement ou le contexte d'exécution concerné dans `docs/concepts.llms.md`, depuis la racine AgentKit indiquée par les instructions du projet.
+Au démarrage, une configuration invalide peut empêcher l'exécution : voir [l'initialisation](examples/environment-initialization.ts). Dans un test, `OrThrow` peut affirmer un résultat ou préparer une fixture ; le code testé conserve ses refus typés. Pour les constantes prouvables, préférer les [déclarations sûres](examples/safe-declarations.ts).