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

package/docs/concepts/05-type-driven-design/02-domains/30-repositories.md

@@ -1,41 +1,35 @@
-### Conception des repositories en Type-Driven Design
+### Repositories : capacités extérieures du domaine
 
-Contrats des opérations nécessaires au métier dont l'implémentation technique reste extérieure au domaine.
----
-
-### Déclarer une capacité à partir du besoin métier
+Définir les opérations extérieures utiles au métier, leurs résultats et leurs garanties sans exposer leur réalisation technique.
 
-Dans ce Type-Driven Design, un **repository est, conceptuellement, un agrégat dont l'implémentation ne concerne pas le domaine**. Il est déclaré dans le domaine sous forme de contrat : ses entrées, ses résultats possibles et ses garanties utilisent les types métier ; sa réalisation technique reste extérieure.
+---
 
-Son périmètre suit les capacités que le métier doit nommer : récupération de données, génération de valeurs, vérifications préalables, calculs précis ou envoi de courriels. Le domaine décrit ce qu'il attend sans exposer de requête SQL, de client de base de données ou de configuration de transport.
+### Nommer les opérations dont le métier a besoin
 
-Les fixtures donnent des contrats adaptés à plusieurs besoins :
+Un repository décrit les entrées, les issues et les garanties d'une capacité extérieure au domaine. Ce rôle couvre les lectures, les vérifications sur des collections, la génération d'identifiants, les flux d'entités ou l'envoi d'un courriel, sans exposer leur réalisation technique.
 
-| Besoin | Contrat |
+| Besoin du domaine | Contrat de la fixture |
 | --- | --- |
-| Obtenir un identifiant issu de la génération prévue | [`BookRepository.generateId`](../fixtures/business/domains/repositories/book.ts) retourne un `Book.Id` portant l'évidence `generated`. |
-| Vérifier une condition du catalogue | `BookRepository.titleIsAlreadyRegistered` retourne une promesse de résultat portant `title-already-registered` ou `title-not-registered`, avec le titre concerné. |
-| Retrouver une entité | `BookRepository.findById` et [`ClientRepository.findById`](../fixtures/business/domains/repositories/client.ts) retournent une promesse de `Maybe` contenant l'entité ou représentant son absence. |
-| Demander un traitement de disponibilité | `BookRepository.rankAvailability` décrit une fonction signée recevant le livre. |
-| Envoyer un courriel de location | [`EmailRepository.sendRentInformationalEmail`](../fixtures/business/domains/repositories/email.ts) décrit une fonction signée recevant le client et le livre. |
-
-Voir [les preuves de passage](../../01-fundamental/06-modeling/50-evidence.ts) et [l'identité des fonctions dans les dépendances](../../01-fundamental/06-modeling/60-signed-function.ts) pour les mécanismes de typage utilisés par ces contrats.
+| Disposer d'un identifiant généré | [`BookRepository.generateId`](../fixtures/business/domains/repositories/book.ts). |
+| Savoir si un titre figure déjà au catalogue | `BookRepository.titleIsAlreadyRegistered`. |
+| Retrouver une entité existante | `BookRepository.findById` et [`ClientRepository.findById`](../fixtures/business/domains/repositories/client.ts). |
+| Choisir la prochaine inscription ou parcourir les inscriptions actives | [`WaitingListEntryRepository`](../fixtures/business/domains/repositories/waitingListEntry.ts). |
+| Envoyer le courriel d'information de location | [`EmailRepository.sendRentInformationalEmail`](../fixtures/business/domains/repositories/email.ts). |
 
-### Relier le contrat aux transactions
+Un nom d'opération métier et une signature précise rendent le besoin implémentable. Une méthode générique qui laisse à chaque appelant le choix des filtres ou de l'ordre peut laisser des décisions métier hors du domaine.
 
-Un repository intervient de deux façons auprès des [agrégats](./20-aggregates.md) :
+### Décrire la garantie, au-delà de la forme
 
-- **Avant la transaction**, son opération fournit des données ou établit une précondition extérieure que l'agrégat exige en entrée. `createBook` utilise ainsi les garanties de génération d'identifiant et de vérification du titre. Pour une recherche, la couche appelante gère l'absence de l'entité et la qualifie selon les besoins de l'opération.
-- **Pour les effets attendus**, son contrat définit une dépendance du résolveur retourné par l'agrégat. `clientRentBook` utilise ainsi la signature de `EmailRepository.sendRentInformationalEmail`.
+Le contrat doit expliquer ce que le résultat certifie. Pour `findNextPendingForBook`, il s'agit de l'entrée en attente du livre fourni ayant la date de demande la plus ancienne ; l'identifiant départage les dates égales. Le résultat contient le livre disponible et cette entrée qualifiée. L'autre issue certifie l'absence d'entrée en attente pour ce livre.
 
-L'application orchestre les appels techniques et la résolution des effets. L'agrégat exploite les résultats préparés ou déclare les effets attendus, sans exécuter l'implémentation du repository.
+Les deux issues normales sont `next-pending-waiting-list-entry` et `no-pending-waiting-list-entry`. Elles utilisent [EvidenceResult](../../01-fundamental/06-modeling/50-evidence.ts) pour associer leur information à l'évidence de même nom sur leur valeur.
 
-Lorsqu'une recherche retourne une entité, le repository l'hydrate avant de la transmettre. Une requête peut filtrer sur un état, mais elle ne suffit pas à ajouter le flag : appeler ensuite la qualification du domaine. Si elle révèle un autre état, le repository doit signaler l'incohérence comme une erreur technique.
+Pour `findAllActiveByBook`, le résultat est un générateur asynchrone : il fournit une fois chaque entrée active du livre retiré, encore en attente ou déjà prête. Les entrées annulées sont exclues. Chaque élément contient le livre et l'entrée qualifiée, avec l'évidence `active-waiting-list-entry-for-withdrawn-book`. Le contrat porte sur chaque élément et sur le périmètre complet du flux ; le type de l'élément ne suffit pas à prouver l'exhaustivité de sa lecture.
 
-Une opération de repository peut établir un contexte transactionnel ou une autre garantie d'exécution. Si elle reçoit une callback, son contrat doit préciser que celle-ci est exécutée dans le contexte requis ; l'implémentation ne produit l'évidence associée qu'après avoir réellement établi et exécuté ce contexte. Le domaine peut exiger cette preuve dans une `Fact`, un agrégat ou une étape intermédiaire.
+### Exiger un résultat sans appeler l'implémentation
 
-### Respecter les garanties annoncées
+Le contrat peut fournir une précondition, comme le titre vérifié de `createBook`, ou le contexte d'un `resolve` ou d'un `iterate`. L'agrégat exige ces résultats avec [GetEvidenceResult](./20-aggregates.md#exiger-les-preuves-utiles-au-parcours). Pour demander une opération identifiée, comme le courriel de location ou `BookRepository.rankAvailability`, il utilise un [commit signé](./20-aggregates.md#transmettre-une-donnée-avec-commit).
 
-**L'implémentation doit réellement établir une condition avant de produire sa preuve.** Le contrat exige la garantie dans le typage ; ajouter une évidence ne réalise pas la vérification technique.
+### Laisser les contraintes techniques à l'application
 
-Changer de base de données, de générateur ou de service de courriel préserve les transactions métier tant que les opérations conservent leurs entrées, leurs résultats et le sens des garanties annoncées. La seule compatibilité TypeScript ne suffit pas à respecter ce contrat.
+Le [port applicatif](../03-applications/20-ports.md#ajouter-les-résultats-propres-à-lexécution-technique) ajoute les refus techniques aux résultats métier. L'[infrastructure](../04-infrastructure/10-implementation.md#implémenter-les-garanties-des-ports) établit les garanties annoncées : une autre technologie peut satisfaire le même contrat si elle en respecte le sens, au-delà de la compatibilité TypeScript.

package/docs/concepts/05-type-driven-design/02-domains/40-refinements.md

@@ -0,0 +1,30 @@
+### Refinements : qualifier un contexte métier
+
+Vérifier une combinaison d'entités ou de valeurs et produire la preuve de cet état commun sans réaliser de transition.
+
+---
+
+### Affiner plusieurs valeurs ensemble
+
+Un refinement est une fonction pure du domaine qui vérifie une condition sur plusieurs valeurs et retourne ce contexte avec une preuve, sans modifier les entités. Un livre emprunté et un client existant peuvent chacun satisfaire leurs qualifications sans être liés : leur association exige une vérification supplémentaire.
+
+### Produire une preuve exploitable
+
+La fixture [`refineLinkBetweenClientAndBorrowedBook`](../fixtures/business/domains/refinements/refineLinkBetweenClientAndBorrowedBook.ts) reçoit un client et un livre portant déjà `BorrowedFlag`. Elle vérifie que l'identifiant du livre figure dans `client.borrowedBooks` et que l'emprunteur déclaré par le livre correspond à ce client.
+
+| Condition constatée | Résultat |
+| --- | --- |
+| Le client référence le livre et le livre désigne ce client comme emprunteur | `client-with-borrowed-book`, avec le couple client-livre portant cette évidence. |
+| Au moins l'une de ces conditions manque | `client-and-book-without-link`, avec le même contexte et l'évidence de cette autre condition. |
+
+L'agrégat [`clientGiveBackBook`](../fixtures/business/domains/aggregates/clientGiveBackBook.ts) exige uniquement la combinaison `client-with-borrowed-book` avec [GetEvidenceResult](./20-aggregates.md#exiger-les-preuves-utiles-au-parcours). L'appelant sélectionne cette issue avant de lancer l'opération.
+
+### Choisir entre refinement et repository
+
+Le refinement convient lorsque les valeurs présentes suffisent à vérifier la relation. Le [repository](./30-repositories.md) établit les garanties dépendant d'une opération extérieure, par exemple une sélection dans une liste d'attente absente de la mémoire. Les deux peuvent produire des évidences.
+
+### Consommer le contexte qualifié
+
+L'application ou le [point d'entrée](../04-infrastructure/10-implementation.md#préparer-les-entrées-et-adapter-les-résultats) peut appeler le refinement pour préparer les paramètres du use case.
+
+La preuve vaut pour les valeurs vérifiées. Si une transition produit de nouvelles entités, leur combinaison doit à nouveau satisfaire les conditions nécessaires aux étapes suivantes. Conserver artificiellement l'évidence du contexte précédent ne démontre pas ces conditions.

package/docs/concepts/05-type-driven-design/02-domains/index.md

@@ -1,3 +1,3 @@
 ## Domaines
 
-Modélisation du métier et contrats de ses opérations : entités, invariants, transitions, agrégats et repositories.
+États et transitions des entités, orchestration par les agrégats, capacités des repositories et preuves de contexte produites par les refinements.

package/docs/concepts/05-type-driven-design/03-applications/10-use-case.md

@@ -1,69 +1,62 @@
-### Conception des use cases en Type-Driven Design
+### Use cases : satisfaire les agrégats
 
-Orchestration applicative des agrégats, sélection et propagation des résultats Either, ports et injection avec Reader, résolution des effets et persistance.
----
-
-### Rôle de la couche applicative
+Préparer les garanties requises, raccorder les workflows aux ports applicatifs et encadrer leur exécution, notamment transactionnelle.
 
-La couche applicative se situe sous le domaine et au-dessus de l'infrastructure. Un **use case orchestre techniquement les agrégats** : préparer leurs entrées et leurs preuves, sélectionner les résultats permettant de poursuivre, appeler les agrégats, traiter leurs sorties, exécuter les résolveurs et sauvegarder les données.
+---
 
-Les règles et les transitions métier restent dans le [domaine](../02-domains/20-aggregates.md). L'application décide de l'enchaînement des opérations et de la persistance à travers des ports abstraits ; l'infrastructure implémente ces ports avec les outils concrets. Les use cases peuvent être transportés avec le domaine dans une autre application si les implémentations respectent ces contrats.
+### Implémenter les exigences du domaine
 
-Un agrégat reste une fonction pure : les mêmes entrées produisent le même résultat métier et les mêmes besoins d'effets. Un use case équipé de ports impurs dépend aussi de l'état extérieur ; les mêmes paramètres ne garantissent donc pas le même résultat. Les frontières et les opérations autorisées entre les couches sont décrites dans [l'architecture](../01-architecture/10-boundaries.md).
+Un use case prépare ou reçoit les entrées d'un agrégat, l'appelle, satisfait les demandes de son workflow avec des ports et restitue son résultat. Il conduit cette exécution technique selon les [frontières de l'architecture](../01-architecture/10-boundaries.md), sans importer les implémentations d'infrastructure.
 
-### Composer les résultats avec Either
+### Préparer les préconditions demandées
 
-Les opérations utilisées par les use cases renvoient souvent des monades `Either`. Leur statut et leur information permettent de sélectionner les résultats souhaités, de poursuivre le cas positif et de propager les échecs.
+La signature détermine la préparation : un identifiant demande encore une recherche ; une entité qualifiée ou un contexte prouvé supposent ces garanties déjà établies. Le use case peut effectuer cette préparation ou la demander à son appelant.
 
-| Besoin | Outil |
+| Fixture | Exigence et préparation |
 | --- | --- |
-| Enchaîner les étapes du cas positif | `DEither.rightPipe` transmet la valeur des `Right` aux étapes suivantes ; dès qu'un `Left` apparaît, il le retourne sans exécuter la suite. `rightAsyncPipe` attend également les étapes asynchrones. |
-| Choisir quels résultats autorisent la poursuite | `keepAsRightByInformation` ou `keepAsRightSelection` classe les variantes souhaitées à droite et les autres à gauche. |
-| Réunir plusieurs résultats nécessaires à une étape | `group` ou `asyncGroup` rassemble les valeurs des `Right` dans un `Success`, ou retourne le premier `Left`. Fournir des getters permet de ne pas exécuter les opérations suivantes après un échec. |
-| Traiter un résultat précis | Les fonctions de discrimination, comme `whenHasInformation` et `matchInformation`, permettent de définir la suite selon l'information du résultat. |
+| [`CreateBookUseCase`](../fixtures/business/applications/useCases/createBook.ts) | Reçoit un titre, appelle sa vérification et sélectionne `title-not-registered`. Fournit ensuite à l'agrégat ce titre prouvé et l'identifiant généré. |
+| [`ClientRentBookUseCase`](../fixtures/business/applications/useCases/clientRentBook.ts) | Reçoit directement le client capable de louer et le livre disponible, avec leurs flags. |
+| [`ClientGiveBackBookUseCase`](../fixtures/business/applications/useCases/clientGiveBackBook.ts) | Reçoit le contexte client-livre portant la preuve produite par le refinement. |
+| [`WithdrawBookUseCase`](../fixtures/business/applications/useCases/withdrawBook.ts) | Reçoit un livre disponible ou réservé, selon la précondition du retrait. |
 
-Un refus prévisible reste un résultat à gérer par les couches appelantes, y compris lorsqu'il provient d'une opération technique. Les exceptions techniques déjà émises par les dépendances ou le runtime remontent implicitement ; le use case n'ajoute pas ses propres `throw`, conformément aux [résultats et exceptions](../../01-fundamental/03-either/50-external-results.ts). `unwrapRight` intervient seulement après la discrimination, lorsqu'une seule branche pertinente reste à poursuivre.
+Dans la création, `keepAsRightByInformation("title-not-registered")` classe `title-already-registered` à gauche. Le `rightAsyncPipe` le propage sans générer d'identifiant, appeler l'agrégat ou sauvegarder de livre. Voir les [outils de composition](../../01-fundamental/03-either/30-composition.ts) et d'[adaptation Either](../../01-fundamental/03-either/40-result-adaptation.ts).
 
-Voir les fondamentaux : [composition et propagation des échecs](../../01-fundamental/03-either/30-composition.ts), [adaptation des résultats](../../01-fundamental/03-either/40-result-adaptation.ts), [discrimination](../../01-fundamental/03-either/10-discrimination.ts) et [traitement exhaustif](../../01-fundamental/03-either/20-exhaustive-handling.ts).
+### Déclarer les dépendances du use case
 
-### Préparer les préconditions de l'agrégat
+Le use case déclare les capacités dont il a besoin avec `createReader`. Celui-ci reçoit les références des ports puis une fonction qui, à partir de leurs implémentations, construit la fonction du use case. Les paramètres métier sont fournis à cette dernière lors de chaque appel.
 
-Dans [`CreateBookUseCase`](../fixtures/business/applications/useCases/createBook.ts), `bookRepository.titleIsAlreadyRegistered` retourne le résultat de la vérification du titre. `keepAsRightByInformation("title-not-registered")` conserve le cas souhaité à droite et classe `title-already-registered` à gauche.
+La déclaration des contrats, leurs extensions techniques et le nommage des dépendances injectées sont décrits dans le [chapitre des ports](./20-ports.md). Le use case consomme ces contrats sans connaître les adaptateurs qui les réalisent.
 
-Le `rightAsyncPipe` fournit alors à l'[agrégat `createBook`](../fixtures/business/domains/aggregates/createBook.ts) le titre portant la preuve `title-not-registered` et l'identifiant généré portant `generated`, puis sauvegarde le livre produit. Si le titre est déjà enregistré, le résultat à gauche est retourné sans génération d'identifiant, appel d'agrégat ni sauvegarde.
+Reader fournit les dépendances ; `consumeWorkflow` satisfait les effets de l'agrégat. Un Reader peut aussi dépendre d'autres Readers ; leurs ports font alors partie des dépendances à fournir. L'[infrastructure](../04-infrastructure/10-implementation.md#résoudre-les-use-cases-une-fois-les-ports-fournis) résout cet ensemble pour exposer les fonctions applicatives.
 
-La sélection conserve les preuves et rend l'appel type-safe. L'implémentation du repository doit réellement établir les garanties qu'elle annonce. Voir [les repositories](../02-domains/30-repositories.md) et [les évidences](../../01-fundamental/06-modeling/50-evidence.ts).
+### Raccorder chaque demande du workflow
 
-Les garanties peuvent aussi être exigées de l'appelant : [`ClientRentBookUseCase`](../fixtures/business/applications/useCases/clientRentBook.ts) reçoit déjà un client portant `CanRentBookFlag` et un livre portant `AvailableFlag`, qualifiés dans la [route de location](../fixtures/infrastructure/http/routes/clientRentBook.ts).
+La consommation associe une implémentation à chaque [demande du workflow](../02-domains/20-aggregates.md#faire-du-workflow-le-contrat-du-déroulement), selon les données et résultats exigés, y compris leurs évidences et signatures.
 
-### Déclarer les ports et construire le Reader
+Dans le [use case de location](../fixtures/business/applications/useCases/clientRentBook.ts), `commit/book-and-client` sauvegarde les deux entités transmises et `commit/send-informational-email` reçoit la fonction signée du port de courriel.
 
-Un **port décrit une capacité nécessaire à l'application**. Il peut reprendre un contrat de repository du domaine et le compléter : [`BookRepositoryPort`](../fixtures/business/applications/ports/book.ts) étend `BookRepository` avec `save`, car la décision de sauvegarder appartient à l'application.
+Dans le [use case de retour](../fixtures/business/applications/useCases/clientGiveBackBook.ts), `resolve/next-pending-waiting-list-entry` appelle le repository et sélectionne ses deux issues normales comme `Right` ; le refus technique reste à gauche. Les commits sont raccordés aux sauvegardes correspondantes et à l'opération signée de disponibilité.
 
-`save` n'est pas une obligation générale des repositories. Cette méthode appartient au port applicatif lorsque le domaine ne fixe pas lui-même le moment, le contexte ou les garanties de la sauvegarde. Si le métier exige une sauvegarde particulière, la dépendance doit être exprimée dans le contrat et, si nécessaire, par une `Evidence`.
+### Exécuter une itération sans déplacer les transitions
 
-Le port associe une interface TypeScript à une constante créée avec `DInvocation.createPort<Interface>()`. L'interface décrit les signatures ; la constante représente la dépendance au runtime. Dans l'infrastructure, la constante du port, par exemple `BookRepositoryPort`, expose `createImplementation` et reçoit une implémentation compatible avec ce contrat.
+Le [use case de retrait](../fixtures/business/applications/useCases/withdrawBook.ts) raccorde `commit/withdrawn-book` et `commit/cancelled-waiting-list-entry` aux sauvegardes du livre et des inscriptions. Pour l'itération, il fournit `waitingListEntryRepository.findAllActiveByBook` comme `getIterator` et règle `concurrency` à cinq. Le même consommateur satisfait ainsi les commits du workflow imbriqué.
 
-Le use case utilise la monade **Reader** de `@duplojs/lang/invocation`. `DInvocation.createReader` reçoit les ports nécessaires et une fonction qui reçoit leurs implémentations, puis retourne la fonction du cas d'utilisation. Les dépendances sont injectées lors de la résolution du Reader ; les paramètres métier sont fournis ensuite à la fonction obtenue.
+La concurrence reste un choix technique compatible avec le contrat métier. Si les traitements doivent respecter un ordre ou partager une garantie particulière, le contrat doit l'exprimer ; une configuration de concurrence ne l'établit pas.
 
-Pour un port, Reader met la première lettre de la clé de dépendance en minuscule et retire le suffixe final `Port` : `BookRepositoryPort` correspond à `bookRepository`. **L'injection doit respecter ce nom et la signature du port.** Un Reader peut aussi dépendre d'autres Readers, résolus à partir des ports fournis.
+### Propager les arrêts et respecter les garanties d'exécution
 
-Dans l'infrastructure, `Reader.run` résout un use case isolé ; `DInvocation.resolveReaders` résout un ensemble avec tous les ports nécessaires. La [fixture de résolution](../fixtures/infrastructure/useCases/index.ts) produit ainsi `useCases.clientRentBookUseCase`, appelable depuis n'importe quel point d'entrée respectant sa signature.
+Un effet qui retourne un `Left` interrompt la consommation et propage ce résultat sans exécuter les étapes suivantes du workflow.
 
-Un use case peut dépendre d'un autre `Reader` ; ses dépendances sont alors incluses dans celles du reader courant. Le même port peut être partagé par plusieurs readers.
+Cet arrêt n'annule pas les effets déjà exécutés. Dans le retrait, le livre a été transmis au premier commit avant l'ouverture du flux. Si celle-ci échoue, cette prise en charge a déjà eu lieu. Avec une itération concurrente, des traitements déjà engagés peuvent également avoir produit des effets.
 
-### Résoudre les effets et décider de la persistance
+Les sauvegardes parallèles d'un même commit ne constituent pas non plus une transaction. Si l'opération exige l'atomicité, une protection contre des modifications concurrentes ou une autre garantie d'exécution, cette exigence doit être prévue dans les contrats puis établie par les implémentations. Une évidence seule ne maintient pas une garantie dans le temps.
 
-**Reader fournit les dépendances du use case ; Resolver exécute les effets déclarés par l'agrégat.** L'[agrégat `clientRentBook`](../fixtures/business/domains/aggregates/clientRentBook.ts) retourne les nouvelles entités et le besoin `sendInformationalEmail`, sans envoyer lui-même de courriel.
+### Exécuter l'opération dans un contexte transactionnel
 
-Le [use case de location](../fixtures/business/applications/useCases/clientRentBook.ts) fournit `emailRepository.sendRentInformationalEmail` à `resolver.resolve`, puis sauvegarde le client et le livre. Le [use case de retour](../fixtures/business/applications/useCases/clientGiveBackBook.ts) résout de même `rankBookAvailability` avant de sauvegarder.
+Le risque de modifications partielles concerne toute opération logicielle qui coordonne plusieurs écritures, indépendamment des workflows. Lorsque ces données doivent évoluer ensemble, prévoir une exécution transactionnelle dans les contrats. Le domaine peut exiger une capacité transactionnelle de repository et des évidences attestant que ses entrées ont été obtenues dans ce contexte ; ces preuves ne créent pas la transaction.
 
-L'ordre appartient au use case selon le besoin de l'opération. Si la sauvegarde doit précéder les effets, `Resolver.runAndResolve` permet d'attendre cette étape avant de les déclencher. Si un effet doit réussir avant la sauvegarde, arrêter la composition lorsqu'il renvoie un `Left`. Une transaction peut être coordonnée par un port ; l'application en définit le périmètre et l'infrastructure fournit le mécanisme. `promiseObject` exécute plusieurs sauvegardes en parallèle, sans fournir d'atomicité par lui-même.
+L'application demande cette capacité ; l'infrastructure ouvre la transaction et fournit les repositories liés à son contexte technique. Y appeler le workflow et attendre toute sa consommation, y compris ses itérations et sauvegardes, avant de valider la transaction. Les lectures qui établissent les préconditions doivent aussi utiliser ce contexte, ou leurs garanties doivent être réétablies à l'écriture. Tous les accès concernés passent par le même client ou gestionnaire transactionnel.
 
-### Démarche d'implémentation
+L'adaptateur doit demander l'annulation des écritures de cette transaction sur une exception ou un `Left` qui interrompt l'opération. Un `Left` est une valeur de retour normale : l'ORM ne le reconnaît pas automatiquement comme un motif de rollback. Le contrat transactionnel doit prévoir ce cas et restituer le refus après l'annulation ; la réussite n'est restituée qu'après validation de la transaction.
 
-1. Lire les contrats des agrégats : entrées, preuves, résultats et effets attendus.
-2. Définir les paramètres du use case et les ports nécessaires, puis créer le Reader.
-3. Préparer les entrées et composer les résultats Either pour poursuivre les branches souhaitées et propager ou traiter les autres.
-4. Appeler les agrégats, résoudre leurs effets et sauvegarder leurs résultats dans l'ordre requis.
-5. Fournir les implémentations de ports et résoudre les use cases dans l'infrastructure.
+Cette atomicité porte sur les accès à la base participant à la transaction. Elle n'annule ni un courriel envoyé ni un appel HTTP déjà exécuté : leur coordination peut demander un envoi après validation ou l'enregistrement transactionnel d'une intention d'envoi à traiter ensuite. Les invariants soumis à la concurrence exigent également des contraintes de base, un niveau d'isolation ou des verrous adaptés. Un flux volumineux peut allonger la transaction ; son périmètre et ses limites doivent rester compatibles avec le contrat métier et les capacités du stockage.

package/docs/concepts/05-type-driven-design/03-applications/20-ports.md

@@ -0,0 +1,49 @@
+### Ports : contrats des dépendances applicatives
+
+Définir les capacités requises par l'application, étendre les résultats des contrats du domaine et rendre leurs implémentations injectables sans dépendre d'une technologie.
+
+---
+
+### Définir ce dont l'application dépend
+
+Un port appartient à l'application et décrit une capacité extérieure requise par ses use cases : opérations, données acceptées et résultats possibles. Plusieurs use cases peuvent le partager ; chacun déclare seulement les dépendances dont il a besoin. Sa réalisation est fournie par l'infrastructure selon les [frontières de l'architecture](../01-architecture/10-boundaries.md).
+
+### Prolonger les besoins exprimés par le domaine
+
+Le port peut reprendre un [repository du domaine](../02-domains/30-repositories.md) et le compléter pour l'exécution des agrégats :
+
+| Besoin applicatif | Construction illustrée par les fixtures |
+| --- | --- |
+| Utiliser une capacité déjà entièrement décrite par le domaine | [`EmailRepositoryPort`](../fixtures/business/applications/ports/email.ts) reprend `EmailRepository`, y compris la signature de l'opération de courriel. |
+| Prendre en charge les entités transmises par les commits | [`BookRepositoryPort`](../fixtures/business/applications/ports/book.ts) et [`ClientRepositoryPort`](../fixtures/business/applications/ports/client.ts) étendent leurs repositories avec `save`. |
+| Représenter les refus propres à l'exécution technique | [`WaitingListEntryRepositoryPort`](../fixtures/business/applications/ports/waitingListEntry.ts) complète les résultats de certaines méthodes et ajoute la sauvegarde des entrées. |
+
+Reprendre un repository conserve une source unique pour ses entrées, ses résultats métier, ses évidences et ses fonctions signées. Le port n'en recopie pas les signatures pour les faire évoluer séparément. Un port peut aussi décrire un besoin purement applicatif sans repository correspondant dans le domaine.
+
+La persistance générique peut rester applicative lorsque l'agrégat transmet une donnée par un commit. Dans la fixture de livre, `save` exige une entité portant un fait et conserve son type précis dans le résultat. Les garanties particulières, comme l'[exécution transactionnelle](./10-use-case.md#exécuter-lopération-dans-un-contexte-transactionnel), doivent être prévues par le contrat.
+
+### Ajouter les résultats propres à l'exécution technique
+
+L'application représente aussi l'impossibilité technique de fournir un résultat demandé par le domaine.
+
+`AddAdditionalResultOnFunction` associe la fonction d'origine à une branche sans paramètres qui retourne le résultat supplémentaire. Cette branche retourne une promesse lorsque le résultat d'origine est une promesse ou un flux asynchrone. L'union conserve la signature d'origine, y compris ses génériques, au lieu de la reconstruire pour élargir son retour.
+
+`AddAdditionalResultOnMethods` applique cette extension aux méthodes nommées dans une correspondance avec leurs résultats supplémentaires ; les autres gardent leur contrat. L'[implémentation d'une méthode aux résultats étendus](../04-infrastructure/10-implementation.md#implémenter-une-méthode-aux-résultats-étendus) utilise `withAdditionalResult` pour produire les différentes issues depuis une même fonction.
+
+Dans `WaitingListEntryRepositoryPort`, `findNextPendingForBook` peut ainsi produire le `Left` `waiting-list-selection-unavailable`, et `findAllActiveByBook` le `Left` `waiting-list-stream-unavailable`. Ces refus transportent l'identifiant du livre concerné, sans changer les preuves exigées par l'agrégat pour continuer.
+
+Le refus du flux porte sur l'obtention du flux lui-même : ce n'est pas une entrée supplémentaire à parcourir. Les éléments fournis par une lecture réussie conservent leur contrat métier et leur évidence.
+
+L'absence d'inscription reste une issue normale de la sélection, distincte de l'impossibilité de chercher. Le [use case](./10-use-case.md#raccorder-chaque-demande-du-workflow) sélectionne les réponses qui satisfont l'agrégat et propage les refus.
+
+### Associer le contrat à une référence de dépendance
+
+La déclaration comporte deux éléments portant le même nom : l'interface TypeScript décrit les capacités et la constante créée par `createPort<Interface>()` représente le port au runtime. La fixture [`BookRepositoryPort`](../fixtures/business/applications/ports/book.ts) montre cette association.
+
+Le use case déclare cette constante parmi les dépendances de `createReader`. Reader lui fournit alors une implémentation typée par l'interface. Pour une clé de port, le nom injecté commence par une minuscule et perd son suffixe final `Port` : la clé `BookRepositoryPort` donne accès à `bookRepository`. Le même nom est utilisé lors de la résolution.
+
+Les paramètres métier du use case restent séparés de ces dépendances. Le port fournit une capacité partagée ; les entités, titres ou contextes qualifiés sont les valeurs propres à chaque appel.
+
+### Confier la réalisation à l'infrastructure
+
+`createImplementation` reçoit une implémentation compatible avec l'interface. L'[infrastructure](../04-infrastructure/10-implementation.md#implémenter-les-garanties-des-ports) établit les garanties du contrat puis fournit les implémentations aux Readers ; la compatibilité de typage ne vérifie pas leur réalisation au runtime.

package/docs/concepts/05-type-driven-design/03-applications/index.md

@@ -1,3 +1,3 @@
 ## Applications
 
-Orchestration des agrégats, ports de capacités, injection des dépendances, effets et persistance.
+Use cases pour satisfaire les agrégats et ports pour définir leurs capacités extérieures, leurs extensions techniques et leurs dépendances injectables.

package/docs/concepts/05-type-driven-design/04-infrastructure/10-implementation.md

@@ -1,56 +1,47 @@
-### Assembler l'application dans l'infrastructure
+### Infrastructure : réaliser et raccorder les contrats
 
-Fournir les dépendances concrètes de l'application et raccorder ses capacités aux points d'entrée du système.
----
-
-### Rôle de l'infrastructure
+Implémenter les capacités techniques demandées par l'application, établir réellement leurs garanties et exposer les opérations aux consommateurs.
 
-L'infrastructure assemble l'application dans un contexte concret : base de données, services externes, génération d'identifiants, envoi de messages ou point d'entrée. Elle dépend des contrats exposés par le domaine et l'application ; le domaine et les use cases ne dépendent pas d'une technologie d'infrastructure.
+---
 
-Le sens des dépendances et les responsabilités aux frontières sont définis dans [les frontières de l'architecture](../01-architecture/10-boundaries.md). Ce chapitre se concentre sur leur mise en œuvre : fournir les ports demandés par l'application, résoudre les use cases et les rendre accessibles aux consommateurs.
+### Partir d'un contrat déjà déterminé
 
-### Implémenter les ports applicatifs
+L'infrastructure réalise le stockage, la génération d'identifiants, le transport de messages, les services externes et les points d'entrée. Elle choisit les technologies et les modalités d'accès selon les contrats et les [frontières de l'architecture](../01-architecture/10-boundaries.md).
 
-Un port applicatif exprime une capacité dont un use case a besoin. Son implémentation appartient à l'infrastructure, qui choisit la technologie concrète tout en préservant le contrat du port : signatures, résultats, preuves et autres garanties annoncées.
+### Implémenter les garanties des ports
 
-La déclaration des capacités et l'extension d'un contrat de domaine par un port applicatif sont expliquées dans [les repositories](../02-domains/30-repositories.md) et [les use cases](../03-applications/10-use-case.md). L'infrastructure fournit ensuite une implémentation compatible avec ce contrat ; elle ne déduit pas une garantie du seul typage et ne remplace pas une transition métier par un traitement technique.
+Le [chapitre des ports](../03-applications/20-ports.md) définit le contrat à réaliser et sa déclaration avec `createImplementation`. Les [fixtures d'implémentation](../fixtures/infrastructure/ports/index.ts) fournissent les repositories de livres, clients, courriels et inscriptions. Ce sont des squelettes de raccordement : leurs valeurs de démonstration ne constituent pas une implémentation de stockage ni de service de courriel.
 
-Les [implémentations des ports de la fixture](../fixtures/infrastructure/ports/index.ts) construisent ainsi `bookRepository`, `clientRepository` et `emailRepository` depuis les ports applicatifs. Un même port peut être partagé par plusieurs use cases ; il n'est pas nécessaire de créer une implémentation différente pour chaque scénario.
+Dans une réalisation concrète, chaque méthode doit établir la garantie de son contrat avant de retourner la valeur prouvée :
 
-### Résoudre les use cases
+| Contrat | Travail de l'implémentation |
+| --- | --- |
+| Recherche d'une entité | Lire puis hydrater les données avec les structures du domaine ; représenter l'absence selon le résultat prévu. |
+| Sélection de la prochaine inscription | Appliquer les [critères et l'ordre du repository](../02-domains/30-repositories.md#décrire-la-garantie-au-delà-de-la-forme), puis retourner la branche prouvée. |
+| Flux des inscriptions actives | Lire progressivement le périmètre complet défini par ce contrat, hydrater et qualifier les entrées, puis fournir les éléments avec leur évidence. |
+| Sauvegarde d'une entité issue d'un fait | Persister la valeur transmise en respectant les garanties du port. |
+| Action signée | Fournir l'opération identifiée et réaliser effectivement le traitement annoncé. |
 
-Les use cases décrivent leurs dépendances avec `Reader`, puis reçoivent leurs implémentations au moment de la résolution. Le fonctionnement de l'injection, des ports et des `Reader` est documenté dans [la couche applicative](../03-applications/10-use-case.md) ; l'infrastructure en réalise l'assemblage.
+Une requête filtrée sur un état ne remplace pas la qualification du domaine. L'implémentation hydrate puis qualifie l'entité pour obtenir le flag exigé. Si les données contredisent le contrat attendu, elle traite cette incohérence selon le contrat technique ; elle ne fabrique pas le flag ou l'évidence manquante.
 
-`DInvocation.resolveReaders` associe un ensemble de use cases à un même jeu d'implémentations. Dans la [fixture de résolution](../fixtures/infrastructure/useCases/index.ts), l'infrastructure injecte les repositories concrets et expose notamment `useCases.clientRentBookUseCase`.
+### Implémenter une méthode aux résultats étendus
 
-La résolution ne réimplémente pas l'orchestration métier et ne reconstruit pas les dépendances dans chaque point d'entrée. Elle produit des fonctions prêtes à être consommées avec leurs paramètres métier.
+Placer `withAdditionalResult` autour de la callback dans l'objet passé à `createImplementation` pour implémenter une [méthode aux résultats étendus](../03-applications/20-ports.md#ajouter-les-résultats-propres-à-lexécution-technique). La [fixture des inscriptions](../fixtures/infrastructure/ports/waitingListEntry.ts) l'utilise sur `findAllActiveByBook` pour fournir le générateur asynchrone ou une promesse du refus `waiting-list-stream-unavailable`.
 
-### Raccorder les points d'entrée
+Le helper reconstruit une signature de travail depuis l'union : la branche sans paramètres ne rend pas les arguments métier facultatifs et les retours promis sont réunis en une promesse des différentes issues. Au runtime, il restitue la même fonction, sans exécution ni validation.
 
-Un point d'entrée adapte un moyen de consommation aux capacités de l'application : valider les données externes avec les structures du domaine, préparer les paramètres exigés par le use case résolu, l'appeler puis traduire son résultat pour le consommateur. Les opérations autorisées pour cette préparation sont définies dans [les frontières de l'architecture](../01-architecture/10-boundaries.md#respecter-les-responsabilités-aux-frontières).
+Le contrat public est restitué par une assertion : les relations génériques ne sont plus vérifiées dans la callback. Si la méthode promet le type précis de l'entité reçue, l'implémentation doit le conserver ; retourner seulement les propriétés communes ne respecte pas ce contrat, même si la signature reconstruite l'accepte.
 
-La nature du protocole ne change pas cette responsabilité. Une route HTTP, une commande ou un autre client peuvent consommer le même use case résolu ; chacun possède sa propre documentation de protocole et son propre contrat de sortie.
+### Résoudre les use cases une fois les ports fournis
 
-La [fixture HTTP de location](../fixtures/infrastructure/http/routes/clientRentBook.ts) et la [fixture de commande de location](../fixtures/infrastructure/command/clientRentBook.ts) utilisent ainsi `Client.Id` et `Book.Id` pour valider les entrées, récupèrent les entités puis les qualifient pour satisfaire la signature du même use case. Le [checker de livre](../fixtures/infrastructure/http/checkers/bookExist.ts) illustre l'étape de lecture et le traitement de l'absence du livre.
+Fournir les implémentations selon les [noms d'injection des ports](../03-applications/20-ports.md#associer-le-contrat-à-une-référence-de-dépendance), puis résoudre les Readers avec `Reader.run` pour un use case isolé ou `resolveReaders` pour un ensemble. La [fixture de résolution](../fixtures/infrastructure/useCases/index.ts) expose ainsi les fonctions applicatives partagées par les points d'entrée.
 
-Les détails de construction d'une route sont documentés dans [les routes HTTP](../../02-server/20-http/20-route.ts), ceux des vérifications réutilisables dans [les routines HTTP](../../02-server/20-http/30-routine.ts), et ceux des commandes dans [la définition d'une commande](../../02-server/40-command/10-use.ts). La composition des résultats est documentée dans [les fondamentaux `Either`](../../01-fundamental/03-either/30-composition.ts) ; l'adaptation au protocole reste documentée par chaque moyen de consommation.
+### Préparer les entrées et adapter les résultats
 
-L'assemblage suit donc ce parcours :
+Un point d'entrée valide les données externes avec les structures du domaine, prépare les paramètres demandés par le use case, l'appelle puis traduit son résultat pour le consommateur.
 
-```text
-Port applicatif
-  ↓ implémentation concrète
-Use case résolu par Reader
-  ↓ consommation par un point d'entrée
-Point d'entrée
-  ↓ adaptation au protocole
-Contrat du consommateur
-```
+La [route HTTP de location](../fixtures/infrastructure/http/routes/clientRentBook.ts) et la [commande de location](../fixtures/infrastructure/command/clientRentBook.ts) valident les identifiants, recherchent les entités et obtiennent les flags nécessaires pour appeler le même use case. Le protocole change, le contrat applicatif reste identique.
 
-### Démarche d'implémentation
+La [route de retour](../fixtures/infrastructure/http/routes/clientGiveBackBook.ts) qualifie le livre comme emprunté, puis appelle le refinement client-livre. Elle transmet le contexte accepté au use case et adapte ses deux issues métier en succès HTTP, ou `waiting-list-selection-unavailable` en réponse 503.
 
-1. Lire les contrats des [ports applicatifs](../03-applications/10-use-case.md#déclarer-les-ports-et-construire-le-reader) et identifier les systèmes capables de les implémenter.
-2. Fournir une implémentation par port en conservant les signatures et les garanties du contrat.
-3. Résoudre les Readers avec `DInvocation.resolveReaders`.
-4. Raccorder chaque point d'entrée au use case résolu et à son contrat de consommation.
-5. Consulter la documentation du protocole concerné pour implémenter ses mécanismes propres.
+Les mécanismes propres aux transports sont documentés dans les [routes HTTP](../../02-server/20-http/20-route.ts), les [routines de vérification](../../02-server/20-http/30-routine.ts) et les [commandes](../../02-server/40-command/10-use.ts).

package/docs/concepts/05-type-driven-design/04-infrastructure/index.md

@@ -1,3 +1,3 @@
 ## Infrastructure
 
-Assemblage concret de l'application : implémentation des ports, résolution des use cases et raccordement aux points d'entrée.
+Réaliser les garanties des ports, résoudre les use cases et adapter leurs entrées et résultats aux systèmes concrets.

package/docs/concepts/05-type-driven-design/fixtures/business/applications/ports/index.ts

@@ -1,3 +1,4 @@
 export * from "./book";
 export * from "./client";
 export * from "./email";
+export * from "./waitingListEntry";

package/docs/concepts/05-type-driven-design/fixtures/business/applications/ports/waitingListEntry.ts

@@ -0,0 +1,17 @@
+import * as DInvocation from "@duplojs/lang/invocation";
+import type * as DEither from "@duplojs/lang/either";
+import { type Book, type WaitingListEntry, type WaitingListEntryRepository } from "../../domains";
+
+export interface WaitingListEntryRepositoryPort extends DInvocation.AddAdditionalResultOnMethods<
+	WaitingListEntryRepository,
+	{
+		findNextPendingForBook: DEither.Left<"waiting-list-selection-unavailable", Book.Id>;
+		findAllActiveByBook: DEither.Left<"waiting-list-stream-unavailable", Book.Id>;
+	}
+> {
+	save<
+		GenericEntity extends WaitingListEntry.Entity & WaitingListEntry.Facts,
+	>(entity: GenericEntity): Promise<GenericEntity>;
+}
+
+export const WaitingListEntryRepositoryPort = DInvocation.createPort<WaitingListEntryRepositoryPort>();

package/docs/concepts/05-type-driven-design/fixtures/business/applications/useCases/clientGiveBackBook.ts

@@ -1,27 +1,45 @@
 import * as DInvocation from "@duplojs/lang/invocation";
-import { type Client, clientGiveBackBook } from "../../domains";
-import * as DEither from "@duplojs/lang/either";
-import { BookRepositoryPort, ClientRepositoryPort } from "../ports";
+import { clientGiveBackBook, type refineLinkBetweenClientAndBorrowedBook } from "../../domains";
+import { BookRepositoryPort, ClientRepositoryPort, WaitingListEntryRepositoryPort } from "../ports";
 import * as DCommon from "@duplojs/lang/common";
+import * as DEither from "@duplojs/lang/either";
 
 export const ClientGiveBackBookUseCase = DInvocation.createReader(
 	{
 		BookRepositoryPort,
 		ClientRepositoryPort,
+		WaitingListEntryRepositoryPort,
 	},
 	({
 		bookRepository,
 		clientRepository,
+		waitingListEntryRepository,
 	}) => (
-		params: {
-			client: Client.Entity & Client.HaveBookFlag;
+		params: DInvocation.GetEvidenceResult<
+			typeof refineLinkBetweenClientAndBorrowedBook,
+			"client-with-borrowed-book"
+		>,
+	) => DInvocation.consumeWorkflow(
+		clientGiveBackBook(params),
+		{
+			"resolve/next-pending-waiting-list-entry": (book) => DCommon.asyncPipe(
+				waitingListEntryRepository.findNextPendingForBook(book),
+				DEither.keepAsRightByInformation(["next-pending-waiting-list-entry", "no-pending-waiting-list-entry"]),
+			),
+			"commit/book-and-client": ({ clientGivenBackBook, givenBackBook }) => DCommon.promiseObject({
+				client: clientRepository.save(clientGivenBackBook),
+				book: bookRepository.save(givenBackBook),
+			}),
+			"commit/book-client-and-waiting-list-entry": ({
+				reservedBook,
+				clientGivenBackBook,
+				readyWaitingListEntry,
+			}) => DCommon.promiseObject({
+				book: bookRepository.save(reservedBook),
+				client: clientRepository.save(clientGivenBackBook),
+				waitingListEntry: waitingListEntryRepository.save(readyWaitingListEntry),
+			}),
+			"commit/rank-availability": bookRepository.rankAvailability,
 		},
-	) => DEither.rightAsyncPipe(
-		clientGiveBackBook(params.client),
-		(resolver) => resolver.resolve({ rankBookAvailability: bookRepository.rankAvailability }),
-		({ client, book }) => DCommon.promiseObject({
-			client: clientRepository.save(client),
-			book: bookRepository.save(book),
-		}),
 	),
 );

package/docs/concepts/05-type-driven-design/fixtures/business/applications/useCases/clientRentBook.ts

@@ -1,6 +1,5 @@
 import * as DInvocation from "@duplojs/lang/invocation";
 import { type Book, type Client, clientRentBook } from "../../domains";
-import * as DEither from "@duplojs/lang/either";
 import { BookRepositoryPort, ClientRepositoryPort, EmailRepositoryPort } from "../ports";
 import * as DCommon from "@duplojs/lang/common";
 
@@ -19,12 +18,14 @@ export const ClientRentBookUseCase = DInvocation.createReader(
 			client: Client.Entity & Client.CanRentBookFlag;
 			book: Book.Entity & Book.AvailableFlag;
 		},
-	) => DEither.rightAsyncPipe(
-		clientRentBook(params.client, params.book),
-		(resolver) => resolver.resolve({ sendInformationalEmail: emailRepository.sendRentInformationalEmail }),
-		({ client, book }) => DCommon.promiseObject({
-			client: clientRepository.save(client),
-			book: bookRepository.save(book),
-		}),
+	) => DInvocation.consumeWorkflow(
+		clientRentBook(params),
+		{
+			"commit/book-and-client": ({ clientWithBorrowedBook, borrowedBook }) => DCommon.promiseObject({
+				client: clientRepository.save(clientWithBorrowedBook),
+				book: bookRepository.save(borrowedBook),
+			}),
+			"commit/send-informational-email": emailRepository.sendRentInformationalEmail,
+		},
 	),
 );

package/docs/concepts/05-type-driven-design/fixtures/business/applications/useCases/createBook.ts

@@ -21,12 +21,12 @@ export const CreateBookUseCase = DInvocation.createReader(
 				"title-not-registered",
 			),
 		),
-		(title) => createBook({
-			id: bookRepository.generateId(),
-			title,
-		}),
-		(book) => DCommon.promiseObject({
-			book: bookRepository.save(book),
-		}),
+		(title) => DInvocation.consumeWorkflow(
+			createBook({
+				id: bookRepository.generateId(),
+				title,
+			}),
+			{ "commit/book": bookRepository.save },
+		),
 	),
 );

package/docs/concepts/05-type-driven-design/fixtures/business/applications/useCases/index.ts

@@ -1,2 +1,4 @@
 export * from "./clientGiveBackBook";
 export * from "./clientRentBook";
+export * from "./createBook";
+export * from "./withdrawBook";