@duplojs/agents-kit 0.0.0-stage → 0.1.0-beta.3

package/docs/concepts/04-tests/02-e2e/index.md

@@ -0,0 +1,3 @@
+## Tests E2E
+
+Vérification des parcours utilisateur dans une application web.

package/docs/concepts/04-tests/index.md

@@ -0,0 +1 @@
+# Tests

package/docs/concepts/05-type-driven-design/01-architecture/10-boundaries.md

@@ -0,0 +1,41 @@
+### Frontières entre domaine, application et infrastructure
+
+Déterminer les dépendances autorisées, les opérations utilisables depuis chaque couche et le traitement des données et erreurs aux frontières du système.
+---
+
+### Sens des dépendances
+
+Les couches suivent cette direction :
+
+```text
+Infrastructure → Application → Domaine
+Infrastructure → Domaine
+```
+
+Le domaine ne dépend ni de l'application ni de l'infrastructure. L'application orchestre les opérations du domaine et définit les ports dont elle a besoin. L'infrastructure fournit les implémentations concrètes et adapte les systèmes externes à ces contrats.
+
+Une dépendance vers le domaine depuis l'infrastructure est donc autorisée lorsqu'elle sert à consommer un contrat ou une capacité du logiciel. Elle ne permet pas à l'infrastructure de déplacer une règle métier dans sa propre couche.
+
+### Respecter les responsabilités aux frontières
+
+Une couche extérieure peut consommer le domaine et l'application, mais ne réalise pas leurs transitions à leur place. L'infrastructure peut :
+
+- lire des données à travers un repository, dont l'implémentation les hydrate avec `map` ou `decodeMap` ;
+- appeler une fonction pure de qualification pour établir une condition attendue par l'application ;
+- appeler un use case et adapter son résultat au point d'entrée consommé.
+
+Les lectures seules, comme `findById` ou `findMany`, peuvent servir une consultation ou préparer les entrées d'un use case sans imposer un use case de relais. Lorsqu'une opération comporte des règles métier, le domaine les exprime et l'application orchestre leur exécution, les effets et la persistance.
+
+L'infrastructure passe alors par le use case : elle n'appelle directement ni `Fact` ni agrégat et ne modifie pas une entité pour réaliser une transition. Elle n'utilise pas non plus `Flag.append` ; la qualification du domaine établit le flag après avoir constaté la condition.
+
+### Faire entrer les données dans le modèle
+
+L'implémentation qui lit une base, une API ou un fichier hydrate la donnée avant de la retourner avec le contrat prévu. Les structures du domaine servent aussi à valider les entrées externes, afin de transmettre les types métier jusqu'aux use cases.
+
+La couche qui possède la donnée établit les préconditions demandées : qualification du domaine pour un flag, opération prévue par le contrat pour une évidence de contexte. Un simple filtre technique ne suffit pas à produire ces preuves.
+
+### Adapter les résultats
+
+Un résultat métier attendu reste discriminé par son contrat, souvent avec `Either` et une `information`. La frontière le traduit ensuite vers le besoin du consommateur : réponse HTTP, sortie de commande ou autre protocole. Le code de transport ne remplace pas la règle qui a produit le résultat.
+
+Les refus prévisibles restent des résultats à traiter, qu'ils concernent le métier, la vérification d'une donnée externe ou une manipulation technique. Les exceptions de défaillance imprévue déjà émises par les dépendances ou le runtime remontent implicitement, sans ajouter de `throw` dans les fonctions réutilisables. Le code applicatif réserve ses `throw` explicites à la consommation finale du résultat par la frontière, qui décide de sa conséquence. La distinction et l'adaptation des API qui lèvent sont détaillées dans les [résultats et exceptions](../../01-fundamental/03-either/50-external-results.ts).

package/docs/concepts/05-type-driven-design/01-architecture/index.md

@@ -0,0 +1,3 @@
+## Architecture
+
+Responsabilités des couches, sens des dépendances, opérations autorisées aux frontières et exposition des résultats aux consommateurs.

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

@@ -0,0 +1,58 @@
+### Conception des entités en Type-Driven Design
+
+Organisation des modèles métier, de leurs invariants, qualifications et transitions dans le domaine.
+---
+
+### Placer les règles métier
+
+Concevoir une entité consiste à définir ses données, les conditions nécessaires aux opérations métier et les garanties obtenues après chaque transition. Les primitives sont documentées dans les fondamentaux : [NewType](../../01-fundamental/06-modeling/10-new-type.ts), [Entity](../../01-fundamental/06-modeling/20-entity.ts), [TaggedObject](../../01-fundamental/06-modeling/30-tagged-object.ts) et [cycle de vie avec Flag et Fact](../../01-fundamental/06-modeling/40-entity-lifecycle.ts).
+
+Les règles suivantes sont des **conventions d'architecture du domaine** :
+
+| Responsabilité | Placement et règle |
+| --- | --- |
+| Définir le modèle | Regrouper dans le namespace TypeScript de l'entité son `createEntityNamespace`, ses `NewType`, sa définition commune, ses états, ses flags et l'union de ses `Facts`. Représenter les propriétés pouvant changer de forme par des unions, notamment de `TaggedObject`. |
+| Qualifier une condition | Une fonction du namespace inspecte les données sans modifier les propriétés métier et ajoute le flag correspondant uniquement après vérification. La condition peut porter sur un état, une capacité ou une relation avec une autre entité. |
+| Créer ou modifier l'entité | Une `Fact` de son dossier `facts/` porte chaque création ou modification métier, même un simple changement de propriété. Elle peut lire plusieurs entités, mais ne modifie que sa cible. `Entity.update` est réservé aux faits ; ils ajoutent les flags dont leur transition établit les conditions. |
+| Hydrater des données existantes | Utiliser les API de mapping décrites dans [Entity](../../01-fundamental/06-modeling/20-entity.ts). Cette entrée dans le modèle ne constitue pas une création métier. |
+| Coordonner plusieurs cibles | Prévoir un fait par entité modifiée et confier leur orchestration à un [agrégat](./20-aggregates.md). |
+
+`Flag.append` est réservé aux qualifications et aux faits décrits ci-dessus. Le placement de l'appel et la vérification de sa condition relèvent de ces conventions ; la présence d'un flag dans le type ne dispense pas son producteur d'établir la garantie annoncée.
+
+### Choisir la primitive de modélisation
+
+Les propriétés d'une entité portent des types métier explicites, généralement des `NewType`, des structures ou des `TaggedObject` adaptés à leur rôle. Utiliser la primitive correspondant à l'intention évite de confondre identité, forme, état et ordre d'exécution.
+
+| Intention | Primitive | Règle |
+| --- | --- | --- |
+| Donner une identité métier à une valeur | `NewType` | Deux valeurs de même représentation mais de sens différent ne sont pas interchangeables. Les contraintes de forme sont vérifiées lors du mapping. |
+| Décrire une forme identifiée | `TaggedObject` | Son tag permet le pattern matching et le transport entre frontières. Il décrit une shape, pas un cycle de vie ; une union de tags modélise les formes possibles d'une propriété. |
+| Certifier une condition sur l'entité actuelle | `Flag` | Une qualification inspecte la valeur puis ajoute le flag correspondant. Le flag peut porter la payload de la vérification ; plusieurs flags peuvent coexister. |
+| Représenter une création ou modification métier | `Fact` | Toute transition est un événement, même si l'état final ressemble à l'état initial. Une fact peut lire plusieurs entités, mais ne modifie que sa cible. |
+| Imposer une provenance ou un ordre d'exécution | `Evidence` | La preuve identifie l'opération qui doit avoir précédé, indépendamment de la forme de la valeur. Ses contrats sont détaillés dans les [agrégats](./20-aggregates.md) et les [repositories](./30-repositories.md). |
+
+Un `Flag` et une `Evidence` peuvent sembler proches, mais leur centre de gravité diffère : le flag certifie une caractéristique ou une qualification de l'état courant d'une entité ; l'évidence certifie un passage requis par le parcours d'exécution, indépendamment de la nature de la valeur. Une condition d'état se modélise donc par un flag ; une dépendance d'ordre ou de provenance se modélise par une evidence.
+
+Une fonction de qualification peut être utilisée après l'hydratation d'une entité, y compris par l'infrastructure. Elle ne modifie pas les propriétés métier et ne réalise aucune transition ; `Flag.append` est utilisé seulement après la vérification de la condition, dans une qualification ou une `Fact`.
+
+### Distinguer invariant et précondition
+
+Un invariant doit rester vrai pour toute valeur de l'entité. Une précondition détermine si une opération particulière est possible et devient une preuve exigée par sa signature.
+
+Dans la fixture [`Client`](../fixtures/business/domains/entities/client/index.ts), `borrowedBooks` contient au maximum **cinq** identifiants. `Client.canRentBook` vérifie une limite de **quatre** avant une nouvelle location et produit un résultat `CanRentBook` portant `CanRentBookFlag`, ou `NoBookRentalSlotsAvailable`. Le fait peut ainsi ajouter un livre en préservant l'invariant. Une capacité à agir mérite une qualification même si elle ne constitue pas un état du cycle de vie.
+
+### Définir le contrat d'une transition
+
+Exiger les preuves en entrée, construire des propriétés portant les contraintes attendues, créer ou mettre à jour la cible, puis ajouter les garanties de sortie et appliquer le fait. Le [cycle de vie](../../01-fundamental/06-modeling/40-entity-lifecycle.ts) détaille les API et la reconstruction des preuves après `update`.
+
+La fixture [`BookRentalFact`](../fixtures/business/domains/entities/book/facts/rental.ts) illustre ce contrat :
+
+| Étape | Contrat |
+| --- | --- |
+| Entrée | Un `Client.Entity & Client.CanRentBookFlag` et un `Book.Entity & Book.AvailableFlag`. Pour le livre, qualifier avec [`Book.refineState`](../fixtures/business/domains/entities/book/index.ts) puis sélectionner la branche disponible. |
+| Transformation | Construire un `BorrowedState` avec l'identifiant du client et mettre à jour le livre. Le client est lu, sans être modifié par ce fait. |
+| Sortie | Ajouter `BorrowedFlag` et appliquer `BookRentalFact` avec le nouvel état comme payload. `run` enveloppe la valeur `Book.Entity & Book.BorrowedFlag & BookRentalFact` dans un `Either` droit. |
+
+Après une transition, poursuivre avec **l'entité retournée**. Les preuves d'une ancienne valeur décrivent la situation antérieure et ne doivent pas être transférées sans vérification. Les valeurs fournies à `update` doivent déjà porter le typage métier attendu : cette opération ne valide pas les nouvelles propriétés au runtime, comme précisé dans [Entity](../../01-fundamental/06-modeling/20-entity.ts).
+
+La fact portée par l'entité représente le fait courant ; conserver un historique persistant des transitions demande un mécanisme dédié. Les entités, flags et évidences sont immuables : après `update`, poursuivre avec la nouvelle valeur et ne pas transférer automatiquement les preuves de l'ancienne. Une preuve devenue fausse entre la qualification et la persistance révèle une contrainte de concurrence ou de transaction à traiter dans le contrat d'orchestration, pas une raison de rendre les preuves mutables.

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

@@ -0,0 +1,49 @@
+### Conception des agrégats en Type-Driven Design
+
+Contrats des transactions métier, préconditions et orchestration de faits réutilisables.
+---
+
+### Délimiter une transaction métier
+
+Dans ce Type-Driven Design, un **agrégat est une fonction pure de transaction métier**. Son nom exprime l'opération prise en charge. Il exige ses préconditions dans sa signature, choisit les faits nécessaires, relie leurs entrées et leurs sorties et rassemble les résultats métier.
+
+Les [faits](./10-entities.md) portent les transitions de chaque cible et restent réutilisables dans plusieurs agrégats. Un agrégat peut appeler un seul fait : ses exigences peuvent déjà différer de celles de cette transition.
+
+Pour concevoir l'opération, déterminer ses entrées et leurs preuves, choisir les faits, organiser leur enchaînement selon leurs dépendances, puis restituer les entités produites et les éventuels besoins d'effets. Les couches appelantes fournissent les entrées qualifiées et gèrent les situations où les préconditions ne peuvent pas être établies. La décision de créer un agrégat vient du besoin métier ; elle ne se déduit pas seulement du nombre d'entités dans les paramètres.
+
+Un agrégat n'appelle jamais un repository et n'exécute jamais une dépendance fournie par l'extérieur. Il reste pur : pour les mêmes entrées, il produit le même résultat métier et les mêmes besoins déclarés. L'application appelle les repositories, prépare les entrées puis appelle l'agrégat.
+
+### Coordonner plusieurs entités
+
+La fixture [`clientRentBook`](../fixtures/business/domains/aggregates/clientRentBook.ts) exige un `Client.Entity & Client.CanRentBookFlag` et un `Book.Entity & Book.AvailableFlag`.
+
+Elle appelle [`ClientRentBookFact`](../fixtures/business/domains/entities/client/facts/rentBook.ts) pour ajouter le livre aux emprunts du client et [`BookRentalFact`](../fixtures/business/domains/entities/book/facts/rental.ts) pour passer le livre à l'état emprunté. Les deux faits reçoivent ici les mêmes entrées qualifiées et produisent chacun la nouvelle valeur de leur cible.
+
+Si plusieurs faits modifient successivement **la même entité**, transmettre à chaque étape la valeur retournée par la précédente, avec les preuves exigées. Réutiliser l'entrée initiale ferait perdre les modifications intermédiaires.
+
+Une `Fact` représente l'événement du cycle de vie d'une seule entité. Lorsque le métier coordonne plusieurs entités dans la même opération, l'agrégat orchestre les faits correspondants. Si cette coordination n'est pas une exigence du métier, les transitions peuvent rester dans des opérations distinctes.
+
+### Ajouter les exigences propres à la transaction
+
+La fixture [`createBook`](../fixtures/business/domains/aggregates/createBook.ts) distingue le contrat de création de l'entité et celui de la transaction :
+
+| Contrat | Préconditions |
+| --- | --- |
+| [`CreateBookFact`](../fixtures/business/domains/entities/book/facts/create.ts) | Un `Book.Id` et un `Book.Title`. |
+| Agrégat `createBook` | Un identifiant portant la preuve `generated` et un titre portant la preuve `title-not-registered`, exigés avec `GetEvidenceResult`. |
+
+Ces garanties proviennent du contrat de [`BookRepository`](../fixtures/business/domains/repositories/book.ts). Les contraintes de `Book.Title` décrivent sa forme ; l'absence du titre dans le catalogue dépend d'une vérification extérieure. Un titre seul ne satisfait donc pas le contrat de l'agrégat. Voir [les preuves de passage](../../01-fundamental/06-modeling/50-evidence.ts) pour le mécanisme `Evidence` et [les repositories](./30-repositories.md) pour les opérations qui les produisent.
+
+Un autre agrégat peut réutiliser le même fait avec d'autres préconditions. **Les exigences de la transaction appartiennent à l'agrégat ; la création ou modification de l'entité appartient au fait.**
+
+Le niveau d'exigence dépend de l'orchestration choisie. Une `Fact` peut exiger directement une évidence lorsqu'une transition impose une provenance, tandis que l'agrégat ou une étape intermédiaire peut l'exiger lorsque la contrainte concerne le parcours complet. Ne pas ajouter cette exigence à une transition qui autorise volontairement plusieurs provenances.
+
+### Déclarer les effets attendus
+
+Lorsqu'une transaction nécessite des effets, retourner un `Resolver` contenant les résultats métier et le contrat des opérations attendues. Sa construction déclare ces besoins sans les exécuter : l'agrégat reste pur.
+
+Le `Resolver` est optionnel. Un agrégat sans effet peut retourner directement sa valeur ou son `Either`; l'utiliser sert à rassembler plusieurs résultats et à déclarer les effets nécessaires, sans les exécuter.
+
+Dans `clientRentBook`, le résolveur rassemble `client` et `book` et exige `sendInformationalEmail`, typé par `EmailRepository["sendRentInformationalEmail"]`. L'[application](../03-applications/10-use-case.md) fournit les implémentations, exécute le résolveur et décide de l'ordre des effets et de la persistance.
+
+Le résolveur décrit les conséquences attendues de l'événement métier ; l'application décide de leur ordre, de leur criticité et de leur stratégie d'exécution. Si un effet doit réussir avant de poursuivre, la composition du use case doit arrêter les étapes suivantes lorsqu'il renvoie un `Left`.

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

@@ -0,0 +1,41 @@
+### Conception des repositories en Type-Driven Design
+
+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
+
+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.
+
+Les fixtures donnent des contrats adaptés à plusieurs besoins :
+
+| Besoin | Contrat |
+| --- | --- |
+| 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.
+
+### Relier le contrat aux transactions
+
+Un repository intervient de deux façons auprès des [agrégats](./20-aggregates.md) :
+
+- **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`.
+
+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.
+
+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.
+
+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.
+
+### Respecter les garanties annoncées
+
+**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.
+
+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.

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

@@ -0,0 +1,3 @@
+## Domaines
+
+Modélisation du métier et contrats de ses opérations : entités, invariants, transitions, agrégats et repositories.

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

@@ -0,0 +1,69 @@
+### Conception des use cases en Type-Driven Design
+
+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
+
+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.
+
+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).
+
+### Composer les résultats avec Either
+
+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.
+
+| Besoin | Outil |
+| --- | --- |
+| 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. |
+
+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.
+
+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).
+
+### Préparer les préconditions de l'agrégat
+
+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.
+
+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.
+
+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).
+
+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).
+
+### Déclarer les ports et construire le Reader
+
+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.
+
+`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`.
+
+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 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.
+
+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.
+
+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 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.
+
+### Résoudre les effets et décider de la persistance
+
+**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.
+
+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.
+
+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.
+
+### Démarche d'implémentation
+
+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.

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

@@ -0,0 +1,3 @@
+## Applications
+
+Orchestration des agrégats, ports de capacités, injection des dépendances, effets et persistance.

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

@@ -0,0 +1,56 @@
+### Assembler l'application dans l'infrastructure
+
+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
+
+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.
+
+### Implémenter les ports applicatifs
+
+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.
+
+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.
+
+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.
+
+### Résoudre les use cases
+
+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.
+
+`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`.
+
+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.
+
+### Raccorder les points d'entrée
+
+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).
+
+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.
+
+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.
+
+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.
+
+L'assemblage suit donc ce parcours :
+
+```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
+```
+
+### Démarche d'implémentation
+
+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.

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

@@ -0,0 +1,3 @@
+## Infrastructure
+
+Assemblage concret de l'application : implémentation des ports, résolution des use cases et raccordement aux points d'entrée.

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

@@ -0,0 +1,2 @@
+export * from "./ports";
+export * from "./useCases";

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

@@ -0,0 +1,10 @@
+import * as DInvocation from "@duplojs/lang/invocation";
+import { type Book, type BookRepository } from "../../domains";
+
+export interface BookRepositoryPort extends BookRepository {
+	save<
+		GenericEntity extends Book.Entity & Book.Facts,
+	>(entity: GenericEntity): Promise<GenericEntity>;
+}
+
+export const BookRepositoryPort = DInvocation.createPort<BookRepositoryPort>();

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

@@ -0,0 +1,10 @@
+import * as DInvocation from "@duplojs/lang/invocation";
+import { type Client, type ClientRepository } from "../../domains";
+
+export interface ClientRepositoryPort extends ClientRepository {
+	save<
+		GenericEntity extends Client.Entity & Client.Facts,
+	>(entity: GenericEntity): Promise<GenericEntity>;
+}
+
+export const ClientRepositoryPort = DInvocation.createPort<ClientRepositoryPort>();

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

@@ -0,0 +1,7 @@
+import * as DInvocation from "@duplojs/lang/invocation";
+import { type EmailRepository } from "../../domains";
+
+export interface EmailRepositoryPort extends EmailRepository {
+}
+
+export const EmailRepositoryPort = DInvocation.createPort<EmailRepositoryPort>();

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

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

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

@@ -0,0 +1,27 @@
+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 * as DCommon from "@duplojs/lang/common";
+
+export const ClientGiveBackBookUseCase = DInvocation.createReader(
+	{
+		BookRepositoryPort,
+		ClientRepositoryPort,
+	},
+	({
+		bookRepository,
+		clientRepository,
+	}) => (
+		params: {
+			client: Client.Entity & Client.HaveBookFlag;
+		},
+	) => 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

@@ -0,0 +1,30 @@
+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";
+
+export const ClientRentBookUseCase = DInvocation.createReader(
+	{
+		BookRepositoryPort,
+		ClientRepositoryPort,
+		EmailRepositoryPort,
+	},
+	({
+		bookRepository,
+		clientRepository,
+		emailRepository,
+	}) => (
+		params: {
+			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),
+		}),
+	),
+);

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

@@ -0,0 +1,32 @@
+import * as DInvocation from "@duplojs/lang/invocation";
+import { createBook, type Book } from "../../domains";
+import * as DEither from "@duplojs/lang/either";
+import { BookRepositoryPort } from "../ports";
+import * as DCommon from "@duplojs/lang/common";
+
+export const CreateBookUseCase = DInvocation.createReader(
+	{
+		BookRepositoryPort,
+	},
+	({
+		bookRepository,
+	}) => (
+		params: {
+			title: Book.Title;
+		},
+	) => DEither.rightAsyncPipe(
+		DCommon.asyncPipe(
+			bookRepository.titleIsAlreadyRegistered(params.title),
+			DEither.keepAsRightByInformation(
+				"title-not-registered",
+			),
+		),
+		(title) => createBook({
+			id: bookRepository.generateId(),
+			title,
+		}),
+		(book) => DCommon.promiseObject({
+			book: bookRepository.save(book),
+		}),
+	),
+);

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

@@ -0,0 +1,2 @@
+export * from "./clientGiveBackBook";
+export * from "./clientRentBook";

package/docs/concepts/05-type-driven-design/fixtures/business/domains/aggregates/clientGiveBackBook.ts

@@ -0,0 +1,15 @@
+import * as DInvocation from "@duplojs/lang/invocation";
+import { ClientGiveBackBook, ReturnBookFact, type Client } from "../entities";
+import * as DEither from "@duplojs/lang/either";
+import { type BookRepository } from "../repositories";
+
+export function clientGiveBackBook(
+	client: Client.Entity & Client.HaveBookFlag,
+) {
+	return DInvocation.createResolver({
+		client: DEither.unwrapRight(ClientGiveBackBook.run(client)),
+		book: DEither.unwrapRight(ReturnBookFact.run(client)),
+	})<{
+		rankBookAvailability: BookRepository["rankAvailability"];
+	}>();
+}

package/docs/concepts/05-type-driven-design/fixtures/business/domains/aggregates/clientRentBook.ts

@@ -0,0 +1,16 @@
+import * as DInvocation from "@duplojs/lang/invocation";
+import { BookRentalFact, ClientRentBookFact, type Book, type Client } from "../entities";
+import * as DEither from "@duplojs/lang/either";
+import { type EmailRepository } from "../repositories/email";
+
+export function clientRentBook(
+	client: Client.Entity & Client.CanRentBookFlag,
+	book: Book.Entity & Book.AvailableFlag,
+) {
+	return DInvocation.createResolver({
+		client: DEither.unwrapRight(ClientRentBookFact.run(client, book)),
+		book: DEither.unwrapRight(BookRentalFact.run(client, book)),
+	})<{
+		sendInformationalEmail: EmailRepository["sendRentInformationalEmail"];
+	}>();
+}

package/docs/concepts/05-type-driven-design/fixtures/business/domains/aggregates/createBook.ts

@@ -0,0 +1,21 @@
+import type * as DInvocation from "@duplojs/lang/invocation";
+import { type BookRepository } from "../repositories";
+import { CreateBookFact } from "../entities";
+
+export function createBook(
+	params: {
+		id: DInvocation.GetEvidenceResult<
+			BookRepository["generateId"],
+			"generated"
+		>;
+		title: DInvocation.GetEvidenceResult<
+			BookRepository["titleIsAlreadyRegistered"],
+			"title-not-registered"
+		>;
+	},
+) {
+	return CreateBookFact.run({
+		id: params.id,
+		title: params.title,
+	});
+}

package/docs/concepts/05-type-driven-design/fixtures/business/domains/aggregates/index.ts

@@ -0,0 +1,3 @@
+export * from "./clientGiveBackBook";
+export * from "./clientRentBook";
+export * from "./createBook";

package/docs/concepts/05-type-driven-design/fixtures/business/domains/entities/book/facts/create.ts

@@ -0,0 +1,34 @@
+import * as DModeling from "@duplojs/lang/modeling";
+import { Book } from "..";
+import * as DCommon from "@duplojs/lang/common";
+
+export type CreateBookFact = DModeling.Fact<
+	"CreateBook",
+	{
+		id: Book.Id;
+		state: Book.AvailableState;
+	}
+>;
+export const CreateBookFact = DModeling.createFact<
+	CreateBookFact,
+	typeof Book.Entity
+>("CreateBook")(
+	({ applyFact }) => (
+		params: {
+			id: Book.Id;
+			title: Book.Title;
+		},
+	) => {
+		const payload = {
+			id: params.id,
+			title: params.title,
+			state: Book.AvailableState.new({}),
+		};
+
+		return DCommon.pipe(
+			Book.Entity.new(payload),
+			Book.AvailableFlag.append(payload.state),
+			applyFact(payload),
+		);
+	},
+);

package/docs/concepts/05-type-driven-design/fixtures/business/domains/entities/book/facts/index.ts

@@ -0,0 +1,3 @@
+export * from "./create";
+export * from "./rental";
+export * from "./returnBook";