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

package/docs/concepts/04-tests/02-e2e/20-architecture.ts

@@ -0,0 +1,76 @@
+/**
+ * @title Architecturer une suite E2E
+ *
+ * Organisation d’une suite E2E selon les pages et les composants du site testé.
+ */
+import { createComponent, createPage } from "@duplojs/playwright";
+
+// `Website` représente l’application et son contexte global, `Page` un écran
+// navigable et `Component` une zone réutilisable de l’interface.
+// Les locators sont déclarés dans ces objets ; les specs utilisent leurs
+// éléments et leurs méthodes sans répéter les sélecteurs.
+//
+// tests/
+//   website.ts
+//   pages/
+//      home.page.ts
+//      search.page.ts
+//  components/
+//      newsletter.component.ts
+//  specs/
+//      home.spec.ts
+
+// Un composant declare son element racine et les elements utiles au test.
+export const newsletterComponent = createComponent(
+	"newsletter",
+	{
+		getMainElement({ body }) {
+			return body.locator("[data-newsletter]");
+		},
+		getElements({ mainElement }) {
+			return {
+				emailInput: mainElement.locator("input[type='email']"),
+				submitButton: mainElement.locator("button[type='submit']"),
+				feedback: mainElement.locator("[data-feedback]"),
+			};
+		},
+	},
+);
+
+// Une page ajoute un path et les composants disponibles sur cet ecran.
+export const homePage = createPage(
+	"home",
+	{
+		makePath() {
+			return "/";
+		},
+		getMainElement({ body }) {
+			return body.locator("main[data-page='home']");
+		},
+		getElements({ mainElement }) {
+			return {
+				title: mainElement.locator("h1"),
+			};
+		},
+		components: [newsletterComponent],
+	},
+);
+
+// Les parametres d'URL restent avec la definition de l'ecran.
+export const articlePage = createPage(
+	"article",
+	{
+		makePath(params: { slug: string }) {
+			return `/articles/${params.slug}`;
+		},
+		getMainElement({ body }) {
+			return body.locator("article");
+		},
+		getElements({ mainElement }) {
+			return {
+				title: mainElement.locator("h1"),
+				content: mainElement.locator("[data-content]"),
+			};
+		},
+	},
+);

package/docs/concepts/04-tests/02-e2e/30-testing.ts

@@ -0,0 +1,90 @@
+/**
+ * @title Ecrire un parcours de test
+ *
+ * Scénarios utilisateur, interactions et vérifications avec les objets du site.
+ */
+import { Actions, Assertions, createComponent, createPage, type Website } from "@duplojs/playwright";
+
+interface TestFixtures {
+	website: Website;
+}
+
+declare const testClient: (title: string, body: (fixtures: TestFixtures) => Promise<void>) => void;
+
+const newsletterComponent = createComponent(
+	"newsletter",
+	{
+		getMainElement({ body }) {
+			return body.locator("[data-newsletter]");
+		},
+		getElements({ mainElement }) {
+			return {
+				emailInput: mainElement.locator("input[type='email']"),
+				submitButton: mainElement.locator("button[type='submit']"),
+				feedback: mainElement.locator("[data-feedback]"),
+			};
+		},
+		getMethods({ elements }) {
+			return {
+				async subscribe(email: string) {
+					await elements!.emailInput.fill(email);
+					await elements!.submitButton.click();
+				},
+			};
+		},
+	},
+);
+
+const homePage = createPage(
+	"home",
+	{
+		makePath() {
+			return "/";
+		},
+		getMainElement({ body }) {
+			return body.locator("main[data-page='home']");
+		},
+		getElements({ mainElement }) {
+			return {
+				title: mainElement.locator("h1"),
+			};
+		},
+		components: [newsletterComponent],
+	},
+);
+
+// Les actions parcourent l'interface, les assertions vérifient son état.
+// Les clés passées aux helpers viennent des éléments nommés dans `getElements`.
+// `Actions` et `Assertions` limitent ces clés aux éléments déclarés sur l’objet ciblé.
+// Le scénario navigue vers une page, récupère son composant, agit sur ses
+// éléments puis vérifie le résultat ; une méthode nommée peut regrouper les actions.
+testClient("visitor subscribes to the newsletter", async({ website }) => {
+	const home = await website.iNavigateTo(homePage);
+
+	await website.iExpectTitleIs(/Home/);
+	await Assertions.toHaveText(home, "title", "Welcome");
+
+	const newsletter = await home.iWantToSeeComponent("newsletter");
+
+	await Assertions.toHaveText(newsletter, "feedback", "No email submitted yet.");
+	await Actions.fill(newsletter, "emailInput", "jane@duplo.dev");
+	await Actions.click(newsletter, "submitButton");
+	await Assertions.toContainText(newsletter, "feedback", "jane@duplo.dev");
+	await Assertions.toHaveValue(newsletter, "emailInput", "jane@duplo.dev");
+});
+
+testClient("visitor cannot submit an empty newsletter form", async({ website }) => {
+	const home = await website.iNavigateTo(homePage);
+	const newsletter = await home.iWantToSeeComponent("newsletter");
+
+	await Actions.click(newsletter, "submitButton");
+	await Assertions.toHaveText(newsletter, "feedback", "Email is required.");
+});
+
+testClient("component methods can express repeated intentions", async({ website }) => {
+	const home = await website.iNavigateTo(homePage);
+	const newsletter = await home.iWantToSeeComponent("newsletter");
+
+	await newsletter.methods.subscribe("jane@duplo.dev");
+	await Assertions.toContainText(newsletter, "feedback", "jane@duplo.dev");
+});

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,44 @@
+### Frontières entre domaine, application et infrastructure
+
+Responsabilités des couches, sens des dépendances et préparation des garanties aux frontières du système.
+
+---
+
+### Faire du domaine le contrat de l'opération
+
+Le domaine traduit les exigences du monde réel en états, préconditions, transitions et opérations coordonnées. Il définit ce qui doit se passer et les garanties nécessaires pour continuer.
+
+| Couche | Responsabilité | Exemple du retour d'un livre |
+| --- | --- | --- |
+| Domaine | Définir les états autorisés, les faits, leur enchaînement et les capacités extérieures requises. | Exiger le lien client-livre, rendre le livre, demander la prochaine inscription en attente et réserver le livre si une inscription existe. |
+| Application | Satisfaire les préconditions et les effets de l'agrégat avec des ports abstraits. | Fournir le résultat de sélection attendu, sauvegarder les entités transmises et propager une indisponibilité. |
+| Infrastructure | Réaliser les ports et adapter les points d'entrée aux contrats applicatifs. | Interroger le stockage, hydrater les entités et convertir le résultat en réponse HTTP. |
+
+Une règle encore à décider dans un use case ou un adaptateur indique un contrat métier incomplet. Les couches techniques conservent leurs choix d'implémentation, mais ces choix doivent respecter les garanties définies dans le domaine.
+
+### Sens des dépendances
+
+```text
+Infrastructure → Application → Domaine
+Infrastructure → Domaine
+```
+
+Le domaine n'importe ni l'application ni l'infrastructure. Il décrit ses besoins extérieurs par des [repositories](../02-domains/30-repositories.md) et ses demandes d'effets par des [workflows](../02-domains/20-aggregates.md). Il n'appelle aucune implémentation technique.
+
+L'application définit les ports de ses use cases ; l'infrastructure les implémente. Changer de base de données ou de protocole d'entrée ne change donc pas les transitions du domaine.
+
+### Respecter les responsabilités aux frontières
+
+Un point d'entrée peut lire des données par un repository et appeler les qualifications pures du domaine pour préparer les paramètres d'un use case. Une lecture seule, comme `findById`, ne demande pas un use case de relais.
+
+Dès que l'opération conduit un cycle de vie ou des effets métier, le point d'entrée passe par un use case. Il n'appelle directement ni fait ni agrégat, et ne modifie pas une entité pour réaliser une transition. Les fonctions du domaine restent responsables de la vérification qui établit un flag ou une preuve combinatoire.
+
+La signature du use case indique les [préconditions à préparer](../03-applications/10-use-case.md#préparer-les-préconditions-demandées) par le point d'entrée.
+
+### Faire circuler les garanties et les résultats
+
+Les structures du domaine valident les entrées externes et hydratent les données existantes. Les qualifications, refinements et repositories établissent les garanties exigées par l'opération.
+
+Le domaine distingue les issues qui ont un sens pour son raisonnement. L'application sélectionne celles qui permettent de poursuivre et propage les refus, y compris les résultats techniques ajoutés par ses ports. L'infrastructure adapte le résultat final au consommateur : statut HTTP, sortie de commande ou autre protocole.
+
+Le traitement des refus prévisibles et des défaillances imprévues suit les [règles des 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
+
+Répartir la décision métier, la satisfaction des contrats et la réalisation technique entre domaine, application et infrastructure.

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

@@ -0,0 +1,50 @@
+### Entités, qualifications et faits
+
+Modéliser les données et leurs invariants, certifier leurs conditions actuelles et rendre explicites les préconditions des transitions métier.
+
+---
+
+### Décrire les valeurs possibles
+
+Une entité porte une identité et une forme métier stable. Ses propriétés utilisent les types qui expriment leur sens et leurs contraintes : identifiants distincts, titres bornés, collections limitées ou variantes d'état. Regrouper dans son namespace les types, structures, états, flags et l'union de ses faits permet de retrouver son cycle de vie.
+
+Les propriétés propres à un état appartiennent à une variante de cet état. Dans [`Book`](../fixtures/business/domains/entities/book/index.ts), `state` est une union de `TaggedObject` : disponible, emprunté, réservé ou retiré. Le client emprunteur existe dans `BorrowedState` ; `ReservedState` référence l'entrée de liste d'attente concernée. Ces informations ne deviennent pas des propriétés facultatives communes à tous les livres.
+
+Chaque [`WaitingListEntry`](../fixtures/business/domains/entities/waitingListEntry/index.ts) représente une inscription individuelle. Plusieurs inscriptions peuvent concerner un livre, mais son état `ReservedState` n'en référence qu'une : la réservation effective. Le client reste porté par cette entrée, sans duplication de son `clientId` dans le livre.
+
+Les primitives et leurs API sont présentées dans les fondamentaux : [NewType](../../01-fundamental/06-modeling/10-new-type.ts), [Entity](../../01-fundamental/06-modeling/20-entity.ts) et [TaggedObject](../../01-fundamental/06-modeling/30-tagged-object.ts).
+
+### Qualifier une condition actuelle
+
+Une qualification observe une entité sans modifier ses propriétés métier. Elle vérifie une condition puis retourne la valeur avec le `Flag` correspondant. Un flag peut certifier un état nommé ou une capacité ; plusieurs flags compatibles peuvent coexister.
+
+[`Book.refineState`](../fixtures/business/domains/entities/book/index.ts) reconnaît l'état du livre et produit notamment `AvailableFlag` ou `BorrowedFlag`. Dans [`Client`](../fixtures/business/domains/entities/client/index.ts), l'invariant limite `borrowedBooks` à cinq identifiants. La qualification `canRentBook` vérifie que le client en possède au plus quatre avant une nouvelle location et produit `CanRentBookFlag`. Cette capacité permet au fait de préserver l'invariant en ajoutant un emprunt.
+
+| Besoin | Modélisation |
+| --- | --- |
+| Décrire les données propres à une variante | État sous forme de `TaggedObject`. |
+| Certifier une condition sur l'entité actuelle | Qualification et `Flag`. |
+| Certifier une combinaison de plusieurs valeurs | [Refinement](./40-refinements.md) produisant une évidence sur le contexte. |
+| Exiger une vérification extérieure ou une provenance | [Evidence](./20-aggregates.md#exiger-les-preuves-utiles-au-parcours) issue du contrat qui établit cette garantie. |
+
+`Flag.append` appartient aux qualifications et aux faits qui établissent réellement sa condition. L'appelant consomme leur résultat ; il ne fabrique pas un flag pour contourner une précondition.
+
+### Définir le contrat d'une transition
+
+Une `Fact` représente une création ou une modification métier. Elle peut lire plusieurs entités, mais ne modifie qu'une seule cible. Chaque changement métier passe par un fait, y compris un changement de propriété qui conserve le même état nommé. Un [agrégat](./20-aggregates.md) coordonne les faits lorsque l'opération touche plusieurs cibles.
+
+La signature du fait exige les états nécessaires à sa transition. [`BookRentalFact`](../fixtures/business/domains/entities/book/facts/rental.ts) reçoit un client portant `CanRentBookFlag` et un livre portant `AvailableFlag`. Il construit l'état emprunté, met à jour le livre, ajoute `BorrowedFlag` et applique le fait. Le client est lu ; sa modification appartient à [`ClientRentBookFact`](../fixtures/business/domains/entities/client/facts/rentBook.ts).
+
+Une évidence appartient au contrat d'un fait si sa garantie est intrinsèque à la transition ; une provenance propre à un parcours relève de l'agrégat. Ainsi, [`PrepareWaitingListEntryFact`](../fixtures/business/domains/entities/waitingListEntry/facts/prepare.ts) exige une entrée en attente, sans imposer sa sélection lors d'un retour. [`CancelWaitingListEntryFact`](../fixtures/business/domains/entities/waitingListEntry/facts/cancel.ts) accepte une entrée en attente ou prête et un motif, pour servir aussi bien le retrait d'un livre qu'une annulation par le client.
+
+### Distinguer l'événement et l'état produit
+
+La payload du fait décrit l'événement ; celle du flag porte les informations de la condition certifiée. Elles peuvent différer. [`ReserveBookFact`](../fixtures/business/domains/entities/book/facts/reserve.ts) conserve `waitingListEntryId` et `clientId` dans sa payload. L'état réservé et son flag ne conservent que `waitingListEntryId`, suffisant pour référencer la réservation effective.
+
+Le fait courant porté par une entité ne constitue pas à lui seul un historique persistant. Si le métier demande cet historique, sa conservation doit être prévue par un contrat dédié.
+
+### Poursuivre avec la nouvelle entité
+
+`Entity.update` est réservé aux faits. Il reconstruit l'entité à partir de ses propriétés déclarées et ne conserve pas automatiquement les anciens flags ni le fait précédent. La transition établit les garanties de la nouvelle valeur, puis les opérations suivantes utilisent cette valeur retournée.
+
+Les propriétés fournies à `update` doivent déjà satisfaire les types métier : cette opération ne réalise pas une validation runtime. Ne pas transférer les preuves de l'ancienne valeur par un spread ou un cast. Le [cycle de vie avec Flag et Fact](../../01-fundamental/06-modeling/40-entity-lifecycle.ts) détaille ces mécanismes.

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

@@ -0,0 +1,65 @@
+### Agrégats, preuves et workflows
+
+Définir le déroulement d'une opération métier, les preuves qui l'autorisent et les demandes commit, resolve et iterate que l'application doit satisfaire.
+
+---
+
+### Porter l'opération métier entière
+
+Dans ce Type-Driven Design, un **agrégat est une fonction qui conduit une opération métier**. Il exige ses préconditions, coordonne les [faits](./10-entities.md#définir-le-contrat-dune-transition), relie leurs entrées et leurs sorties et détermine le résultat final.
+
+[`clientRentBook`](../fixtures/business/domains/aggregates/clientRentBook.ts) coordonne ainsi le fait qui ajoute un emprunt au client et celui qui passe le livre à l'état emprunté.
+
+L'agrégat fixe aussi les exigences propres à l'opération. [`CreateBookFact`](../fixtures/business/domains/entities/book/facts/create.ts) reçoit un identifiant et un titre. L'agrégat [`createBook`](../fixtures/business/domains/aggregates/createBook.ts) exige en plus que l'identifiant ait été généré et que le titre ait été vérifié comme absent du catalogue. Le fait reste réutilisable ; ce parcours de création porte ses propres preuves.
+
+Un agrégat reste pur. Il n'appelle ni repository ni callback impure injectée : il transforme les valeurs disponibles et déclare les besoins extérieurs. À entrées et résultats fournis identiques, son raisonnement métier est identique. Un agrégat sans effet à demander peut retourner directement une valeur ou un `Either`.
+
+### Exiger les preuves utiles au parcours
+
+Une [Evidence](../../01-fundamental/06-modeling/50-evidence.ts) rend exigible dans les types une garantie de contexte, une relation entre valeurs ou une provenance.
+
+Un `Book.Title` satisfait ses contraintes de forme, mais ne prouve pas que le catalogue ne contient pas déjà ce titre. Le résultat `title-not-registered` du [repository](../fixtures/business/domains/repositories/book.ts) apporte cette garantie contextuelle. De même, le [refinement client-livre](./40-refinements.md) certifie une combinaison que ni le client seul ni un livre simplement qualifié comme emprunté ne suffisent à établir.
+
+`GetEvidenceResult` permet d'exiger la valeur portant une évidence précise parmi les résultats d'une fonction ou d'une méthode, y compris à travers une promesse, un `Either` ou un générateur. L'agrégat se rattache ainsi au contrat qui définit le résultat attendu sans reprendre l'ensemble de ses issues. Les noms d'évidence distinguent les garanties : deux méthodes annonçant le même type et la même évidence restent compatibles. Une identité d'opération particulière se représente avec une [SignedFunction](../../01-fundamental/06-modeling/60-signed-function.ts).
+
+L'agrégat peut exiger la provenance d'une sélection ou d'un flux, puis transmettre aux faits les entités qualifiées selon leurs propres préconditions.
+
+### Faire du workflow le contrat du déroulement
+
+Le workflow exprime les endroits où l'opération transmet une donnée, attend un contexte supplémentaire ou applique un cycle de vie à une collection. Il précise ce que l'application doit fournir et à quel moment. Les branches métier restent dans l'agrégat ; les appels techniques restent dans l'application.
+
+| Demande | Ce que le domaine impose | Liberté de réalisation technique |
+| --- | --- | --- |
+| `commit` | Prendre en charge une donnée à cette étape du déroulement. | Réaliser la sauvegarde ou l'action prévue par le contrat. |
+| `resolve` | Fournir le résultat qualifié nécessaire pour poursuivre le raisonnement. | Obtenir ce résultat par l'opération extérieure appropriée. |
+| `iterate` | Fournir les éléments du périmètre demandé et exécuter le workflow métier pour chacun. | Lire le flux progressivement et organiser son exécution. |
+
+Les fixtures déclarent ces demandes avec `createWorkflow` ; l'[application](../03-applications/10-use-case.md) les satisfait avec `consumeWorkflow`.
+
+### Transmettre une donnée avec commit
+
+Un `commit` indique que la donnée a atteint le point où l'agrégat veut la confier à une opération extérieure. La persistance est un usage fréquent. Le commit peut aussi demander une action, par exemple l'envoi d'un courriel. Sa valeur de retour n'alimente pas le raisonnement métier du générateur.
+
+Dans [`clientRentBook`](../fixtures/business/domains/aggregates/clientRentBook.ts), les faits produisent les nouvelles valeurs du client et du livre. Le premier commit les transmet ensemble ; le suivant demande le courriel d'information. L'application attend la prise en charge du premier avant de poursuivre avec le second.
+
+Si l'identité de l'action importe, `withSignature<EmailRepository["sendRentInformationalEmail"]>()` exige la fonction signée correspondante. Un commit qui transmet simplement une entité laisse au use case le raccordement à sa sauvegarde.
+
+### Obtenir un contexte extérieur avec resolve
+
+Un `resolve` intervient lorsque les données disponibles ne permettent pas de poursuivre la décision métier. Une qualification pure suffit si toute l'information est déjà présente. Quand la réponse dépend d'une collection extérieure potentiellement volumineuse, le domaine exige le résultat utile sans charger cette collection dans ses paramètres.
+
+[`clientGiveBackBook`](../fixtures/business/domains/aggregates/clientGiveBackBook.ts) applique les faits de retour, puis demande la prochaine inscription en attente du livre rendu. Il exige les résultats de `WaitingListEntryRepository.findNextPendingForBook` : une entrée sélectionnée ou la preuve qu'aucune entrée n'est en attente.
+
+Ces deux issues permettent de continuer. Sans inscription, l'agrégat transmet le livre disponible et le client. Avec une inscription, il applique les faits de réservation du livre et de préparation de l'entrée, puis transmet les trois entités. La décision de réserver appartient entièrement au domaine ; l'application fournit le contexte qui la rend possible.
+
+Le [repository](./30-repositories.md#décrire-la-garantie-au-delà-de-la-forme) précise les garanties de sélection ; l'[application](../03-applications/10-use-case.md#propager-les-arrêts-et-respecter-les-garanties-dexécution) traite l'impossibilité de satisfaire la résolution.
+
+### Faire vivre chaque élément d'un flux avec iterate
+
+Un `iterate` exprime qu'une même opération métier doit s'appliquer à chaque élément d'un ensemble. Il permet de parcourir un volume non borné sans réunir toutes les entités en mémoire et de conserver les transitions du domaine pour chacune.
+
+[`withdrawBook`](../fixtures/business/domains/aggregates/withdrawBook.ts) reçoit un livre disponible ou réservé : il est encore à la bibliothèque. Après le fait de retrait et le commit du livre, il demande toutes les entrées actives de sa liste d'attente. Chaque élément doit porter la preuve du résultat de `WaitingListEntryRepository.findAllActiveByBook` et contenir une entrée en attente ou prête.
+
+Le workflow imbriqué applique `CancelWaitingListEntryFact` avec le motif `book-withdrawn`, puis transmet l'entrée annulée par un commit. Une mise à jour globale en base contournerait ces faits et leurs préconditions. Le domaine conserve le choix de la transition et de son motif ; l'application fournit la génératrice asynchrone et le degré de concurrence.
+
+Le résultat final est le livre retiré ; le workflow n'accumule pas les entrées traitées. Le [use case de retrait](../fixtures/business/applications/useCases/withdrawBook.ts) montre le raccordement du flux et des commits. Les conséquences d'un arrêt après des effets déjà exécutés sont décrites dans la [consommation applicative](../03-applications/10-use-case.md#propager-les-arrêts-et-respecter-les-garanties-dexécution).

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

@@ -0,0 +1,35 @@
+### Repositories : capacités extérieures du domaine
+
+Définir les opérations extérieures utiles au métier, leurs résultats et leurs garanties sans exposer leur réalisation technique.
+
+---
+
+### Nommer les opérations dont le métier a besoin
+
+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 du domaine | Contrat de la fixture |
+| --- | --- |
+| 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). |
+
+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.
+
+### Décrire la garantie, au-delà de la forme
+
+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.
+
+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.
+
+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.
+
+### Exiger un résultat sans appeler l'implémentation
+
+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).
+
+### Laisser les contraintes techniques à l'application
+
+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

@@ -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>();