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

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

@@ -0,0 +1,3 @@
+## Domaines
+
+É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

@@ -0,0 +1,62 @@
+### Use cases : satisfaire les agrégats
+
+Préparer les garanties requises, raccorder les workflows aux ports applicatifs et encadrer leur exécution, notamment transactionnelle.
+
+---
+
+### Implémenter les exigences du domaine
+
+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.
+
+### Préparer les préconditions demandées
+
+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.
+
+| Fixture | Exigence et préparation |
+| --- | --- |
+| [`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. |
+
+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).
+
+### Déclarer les dépendances du use case
+
+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.
+
+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.
+
+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.
+
+### Raccorder chaque demande du workflow
+
+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.
+
+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.
+
+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é.
+
+### Exécuter une itération sans déplacer les transitions
+
+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é.
+
+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.
+
+### Propager les arrêts et respecter les garanties d'exécution
+
+Un effet qui retourne un `Left` interrompt la consommation et propage ce résultat sans exécuter les étapes suivantes du workflow.
+
+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.
+
+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.
+
+### Exécuter l'opération dans un contexte transactionnel
+
+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'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.
+
+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.
+
+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

@@ -0,0 +1,3 @@
+## Applications
+
+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

@@ -0,0 +1,47 @@
+### Infrastructure : réaliser et raccorder les contrats
+
+Implémenter les capacités techniques demandées par l'application, établir réellement leurs garanties et exposer les opérations aux consommateurs.
+
+---
+
+### Partir d'un contrat déjà déterminé
+
+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).
+
+### Implémenter les garanties des ports
+
+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.
+
+Dans une réalisation concrète, chaque méthode doit établir la garantie de son contrat avant de retourner la valeur prouvée :
+
+| 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é. |
+
+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.
+
+### Implémenter une méthode aux résultats étendus
+
+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`.
+
+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.
+
+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.
+
+### Résoudre les use cases une fois les ports fournis
+
+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.
+
+### Préparer les entrées et adapter les résultats
+
+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.
+
+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.
+
+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.
+
+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

@@ -0,0 +1,3 @@
+## Infrastructure
+
+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/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,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

@@ -0,0 +1,45 @@
+import * as DInvocation from "@duplojs/lang/invocation";
+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: 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,
+		},
+	),
+);

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

@@ -0,0 +1,31 @@
+import * as DInvocation from "@duplojs/lang/invocation";
+import { type Book, type Client, clientRentBook } from "../../domains";
+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;
+		},
+	) => 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

@@ -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) => DInvocation.consumeWorkflow(
+			createBook({
+				id: bookRepository.generateId(),
+				title,
+			}),
+			{ "commit/book": bookRepository.save },
+		),
+	),
+);

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

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

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

@@ -0,0 +1,32 @@
+import * as DInvocation from "@duplojs/lang/invocation";
+import * as DEither from "@duplojs/lang/either";
+import { type Book, withdrawBook } from "../../domains";
+import { BookRepositoryPort, WaitingListEntryRepositoryPort } from "../ports";
+
+export const WithdrawBookUseCase = DInvocation.createReader(
+	{
+		BookRepositoryPort,
+		WaitingListEntryRepositoryPort,
+	},
+	({
+		bookRepository,
+		waitingListEntryRepository,
+	}) => (
+		params: {
+			book: Book.Entity & (Book.AvailableFlag | Book.ReservedFlag);
+		},
+	) => DEither.rightAsyncPipe(
+		params.book,
+		(book) => DInvocation.consumeWorkflow(
+			withdrawBook(book),
+			{
+				"commit/withdrawn-book": bookRepository.save,
+				"iterate/active-waiting-list-entries-for-withdrawn-book": {
+					getIterator: waitingListEntryRepository.findAllActiveByBook,
+					concurrency: 5,
+				},
+				"commit/cancelled-waiting-list-entry": waitingListEntryRepository.save,
+			},
+		),
+	),
+);

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

@@ -0,0 +1,74 @@
+import * as DInvocation from "@duplojs/lang/invocation";
+import { ClientGiveBackBook, ReturnBookFact, ReserveBookFact, PrepareWaitingListEntryFact } from "../entities";
+import * as DEither from "@duplojs/lang/either";
+import { type BookRepository, type WaitingListEntryRepository } from "../repositories";
+import * as DCommon from "@duplojs/lang/common";
+import { type refineLinkBetweenClientAndBorrowedBook } from "../refinements";
+
+export const clientGiveBackBook = DInvocation.createWorkflow(
+	({ commit, resolve }) => function *(
+		clientWithBorrowedBook: DInvocation.GetEvidenceResult<
+			typeof refineLinkBetweenClientAndBorrowedBook,
+			"client-with-borrowed-book"
+		>,
+	) {
+		const givenBackBook = DCommon.pipe(
+			clientWithBorrowedBook,
+			ReturnBookFact.run,
+			DEither.unwrapRight,
+		);
+
+		const clientGivenBackBook = DCommon.pipe(
+			clientWithBorrowedBook,
+			ClientGiveBackBook.run,
+			DEither.unwrapRight,
+		);
+
+		const selection: DInvocation.GetEvidenceResult<
+			WaitingListEntryRepository["findNextPendingForBook"],
+			"next-pending-waiting-list-entry" | "no-pending-waiting-list-entry"
+		> = yield *resolve("next-pending-waiting-list-entry", givenBackBook);
+
+		if (selection.waitingListEntry === null) {
+			yield *commit("book-and-client", {
+				givenBackBook,
+				clientGivenBackBook,
+			});
+
+			yield *commit("rank-availability", givenBackBook)
+				.withSignature<BookRepository["rankAvailability"]>();
+
+			return DEither.result("book-returned-without-waiting-list-entry", {
+				book: givenBackBook,
+				client: clientGivenBackBook,
+			});
+		}
+
+		const reservedBook = DCommon.pipe(
+			selection,
+			ReserveBookFact.run,
+			DEither.unwrapRight,
+		);
+
+		const readyWaitingListEntry = DCommon.pipe(
+			selection.waitingListEntry,
+			PrepareWaitingListEntryFact.run,
+			DEither.unwrapRight,
+		);
+
+		yield *commit("book-client-and-waiting-list-entry", {
+			reservedBook,
+			clientGivenBackBook,
+			readyWaitingListEntry,
+		});
+
+		yield *commit("rank-availability", reservedBook)
+			.withSignature<BookRepository["rankAvailability"]>();
+
+		return DEither.result("book-returned-and-reserved", {
+			book: reservedBook,
+			client: clientGivenBackBook,
+			waitingListEntry: readyWaitingListEntry,
+		});
+	},
+);

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

@@ -0,0 +1,42 @@
+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";
+import * as DCommon from "@duplojs/lang/common";
+
+export const clientRentBook = DInvocation.createWorkflow(
+	({ commit }) => function *(
+		params: {
+			client: Client.Entity & Client.CanRentBookFlag;
+			book: Book.Entity & Book.AvailableFlag;
+		},
+	) {
+		const clientWithBorrowedBook = DCommon.pipe(
+			params,
+			ClientRentBookFact.run,
+			DEither.unwrapRight,
+		);
+
+		const borrowedBook = DCommon.pipe(
+			params,
+			BookRentalFact.run,
+			DEither.unwrapRight,
+		);
+
+		yield *commit("book-and-client", {
+			borrowedBook,
+			clientWithBorrowedBook,
+		});
+
+		yield *commit("send-informational-email", {
+			book: borrowedBook,
+			client: clientWithBorrowedBook,
+		})
+			.withSignature<EmailRepository["sendRentInformationalEmail"]>();
+
+		return {
+			book: borrowedBook,
+			client: clientWithBorrowedBook,
+		};
+	},
+);

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

@@ -0,0 +1,33 @@
+import * as DInvocation from "@duplojs/lang/invocation";
+import { type BookRepository } from "../repositories";
+import { CreateBookFact } from "../entities";
+import * as DCommon from "@duplojs/lang/common";
+import * as DEither from "@duplojs/lang/either";
+
+export const createBook = DInvocation.createWorkflow(
+	({ commit }) => function *(
+		params: {
+			id: DInvocation.GetEvidenceResult<
+				BookRepository["generateId"],
+				"generated"
+			>;
+			title: DInvocation.GetEvidenceResult<
+				BookRepository["titleIsAlreadyRegistered"],
+				"title-not-registered"
+			>;
+		},
+	) {
+		const createdBook = DCommon.pipe(
+			{
+				id: params.id,
+				title: params.title,
+			},
+			CreateBookFact.run,
+			DEither.unwrapRight,
+		);
+
+		yield *commit("book", createdBook);
+
+		return createdBook;
+	},
+);

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

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

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

@@ -0,0 +1,37 @@
+import * as DInvocation from "@duplojs/lang/invocation";
+import * as DCommon from "@duplojs/lang/common";
+import * as DEither from "@duplojs/lang/either";
+import { type Book, WithdrawBookFact, CancelWaitingListEntryFact } from "../entities";
+import { type WaitingListEntryRepository } from "../repositories";
+
+export const withdrawBook = DInvocation.createWorkflow(
+	({ commit, iterate }) => function *(book: Book.Entity & (Book.AvailableFlag | Book.ReservedFlag)) {
+		const withdrawnBook = DCommon.pipe(
+			book,
+			WithdrawBookFact.run,
+			DEither.unwrapRight,
+		);
+
+		yield *commit("withdrawn-book", withdrawnBook);
+
+		yield *iterate("active-waiting-list-entries-for-withdrawn-book", withdrawnBook)(function *(
+			linkedWaitingListEntry: DInvocation.GetEvidenceResult<
+				WaitingListEntryRepository["findAllActiveByBook"],
+				"active-waiting-list-entry-for-withdrawn-book"
+			>,
+		) {
+			const cancelledWaitingListEntry = DCommon.pipe(
+				{
+					waitingListEntry: linkedWaitingListEntry.waitingListEntry,
+					reason: "book-withdrawn",
+				},
+				CancelWaitingListEntryFact.run,
+				DEither.unwrapRight,
+			);
+
+			yield *commit("cancelled-waiting-list-entry", cancelledWaitingListEntry);
+		});
+
+		return withdrawnBook;
+	},
+);