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

package/docs/concepts/04-tests/01-unit/10-either.ts

@@ -0,0 +1,136 @@
+/**
+ * @title Tester un résultat Either
+ *
+ * Vérification des branches, des valeurs et du typage d’un contrat Either.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DEither from "@duplojs/lang/either";
+
+// Dans les tests du monorepo, Vitest expose ces globals directement.
+// Ces déclarations rendent uniquement l'exemple typable dans la documentation d'AgentKit.
+declare const describe: (title: string, body: () => void) => void;
+declare const it: (title: string, body: () => void | Promise<void>) => void;
+declare const expect: (value: unknown) => {
+	toBe(expected: unknown): void;
+	toStrictEqual(expected: unknown): void;
+};
+
+interface User {
+	id: number;
+	email: string;
+}
+
+declare function findUserByEmail(
+	email: string,
+): (
+	| DEither.Result<"user.found", User>
+	| DEither.Left<"user.notfound", string>
+	| DEither.Error<Error>
+);
+
+// L'unwrap exprime la branche attendue avant l'assertion sur la donnée.
+// `unwrapByInformationOrThrow` sélectionne l’information visée et extrait sa
+// valeur. Une information différente provoque une exception et fait échouer le test.
+// L’assertion vérifie ensuite la donnée ; `ExpectType` vérifie son type à la compilation.
+describe("findUserByEmail", () => {
+	it("returns the found user", () => {
+		const result = findUserByEmail("jane@duplo.dev");
+
+		const user = DEither.unwrapByInformationOrThrow(
+			result,
+			"user.found",
+		);
+
+		expect(user).toStrictEqual({
+			id: 1,
+			email: "jane@duplo.dev",
+		});
+
+		type _CheckUser = DCommon.ExpectType<
+			typeof user,
+			User,
+			"strict"
+		>;
+	});
+
+	it("returns the not found email", () => {
+		const result = findUserByEmail("missing@duplo.dev");
+
+		const email = DEither.unwrapByInformationOrThrow(
+			result,
+			"user.notfound",
+		);
+
+		expect(email).toBe("missing@duplo.dev");
+	});
+});
+
+// La sélection rend explicites les branches acceptées par ce test.
+// `unwrapSelectionOrThrow` lève aussi une exception si le résultat appartient
+// à une branche exclue, ici `error`.
+describe("findUserByEmail selection", () => {
+	it("accepts only the business results handled by this test", () => {
+		const result = findUserByEmail("jane@duplo.dev");
+
+		const value = DEither.unwrapSelectionOrThrow(
+			result,
+			{
+				"user.found": true,
+				"user.notfound": true,
+				error: false,
+			},
+		);
+
+		type _CheckValue = DCommon.ExpectType<
+			typeof value,
+			User | string,
+			"strict"
+		>;
+
+		if (typeof value === "string") {
+			expect(value).toBe("jane@duplo.dev");
+		} else {
+			expect(value).toStrictEqual({
+				id: 1,
+				email: "jane@duplo.dev",
+			});
+		}
+	});
+});
+
+// `DEither.expect` matérialise dans le type qu'une valeur est déjà un `Either`.
+describe("DEither.expect", () => {
+	it("keeps the exact either type", () => {
+		const input = DEither.success(42);
+		const result = DEither.expect(input);
+
+		expect(result).toBe(input);
+
+		type _CheckResult = DCommon.ExpectType<
+			typeof result,
+			DEither.Success<42>,
+			"strict"
+		>;
+
+		// @ts-expect-error input must be an Either
+		DEither.expect("plain value");
+	});
+});
+
+// Tester une API curifiée dans son contexte réel conserve l'inférence utile.
+describe("curried Either helpers", () => {
+	it("preserves inference in a pipe", () => {
+		const result = DCommon.pipe(
+			findUserByEmail("jane@duplo.dev"),
+			DEither.unwrapByInformationOrThrow("user.found"),
+		);
+
+		expect(result.email).toBe("jane@duplo.dev");
+
+		type _CheckResult = DCommon.ExpectType<
+			typeof result,
+			User,
+			"strict"
+		>;
+	});
+});

package/docs/concepts/04-tests/01-unit/20-server-mocking.ts

@@ -0,0 +1,53 @@
+/**
+ * @title Remplacer les implémentations serveur
+ *
+ * Contrôle de l'environnement et des fonctions serveur pour isoler les tests.
+ */
+import * as DEither from "@duplojs/lang/either";
+// Ces deux outils sont des exports directs du package, sans sous-export dédié.
+import { TESTImplementation, setEnvironment } from "@duplojs/server";
+import * as DSCommand from "@duplojs/server/command";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// Pour les fonctions serveur exposées via `implementFunction`, privilégier
+// ce mécanisme aux mocks de modules ou d'imports et aux spies sur les exports.
+// `setEnvironment("TEST")` sélectionne les implémentations enregistrées avec
+// `TESTImplementation.set` ; leur signature est vérifiée par TypeScript.
+// Chaque fonction serveur effectivement appelée, même indirectement, doit être
+// enregistrée : une implémentation absente lève une erreur, sans repli natif.
+describe("command with controlled server dependencies", () => {
+	afterEach(() => {
+		// Le registre et l'environnement sont partagés. Nettoyer même si le test
+		// échoue ; ne pas exécuter ces tests concurremment.
+		TESTImplementation.clear();
+		// Cette suite Vitest tourne sous Node. Adapter l'environnement rétabli
+		// à celui attendu par la suite lorsqu'elle utilise Bun ou Deno.
+		setEnvironment("NODE");
+	});
+
+	it("reads the injected process arguments", async() => {
+		setEnvironment("TEST");
+
+		// `vi.fn` reste utile pour observer les appels de l'implémentation injectée.
+		const getProcessArgumentsSpy = vi.fn(() => ["--verbose"]);
+		TESTImplementation.set("getProcessArguments", getProcessArgumentsSpy);
+		const executeSpy = vi.fn(() => undefined);
+
+		const result = await DSCommand.exec(
+			{
+				displayName: "tool",
+				options: [DSCommand.createBooleanOption("verbose")],
+			},
+			executeSpy,
+		);
+
+		DEither.unwrapByInformationOrThrow(result, "ok");
+		expect(getProcessArgumentsSpy).toHaveBeenCalledTimes(1);
+		expect(executeSpy).toHaveBeenCalledWith({
+			options: { verbose: true },
+		});
+	});
+});
+
+// Les autres dépendances sans ce mécanisme peuvent toujours être observées
+// ou remplacées avec les outils de mock habituels du runner de tests.

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

@@ -0,0 +1,3 @@
+## Tests unitaires
+
+Vérification du comportement et du typage des unités de code.

package/docs/concepts/04-tests/02-e2e/10-init.ts

@@ -0,0 +1,80 @@
+/**
+ * @title Initialiser le client E2E
+ *
+ * Configuration de l’environnement de test et intégration du site aux fixtures Playwright.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DSCommon from "@duplojs/server/common";
+import { createWebsite, type Website } from "@duplojs/playwright";
+import test, { defineConfig, devices } from "playwright/test";
+
+const envs = await DSCommon.environmentVariableOrThrow(
+	{
+		BASE_URL: DDataStructure.string([DDataStructure.url()]),
+		CI: DDataStructure.boolean(),
+		RETRIES: DDataStructure.number([DDataStructure.integer()]),
+		WORKERS: DDataStructure.number([DDataStructure.integer()]),
+	},
+	{
+		justRead: true,
+		includedEnvironmentFiles: [DCommon.infer(".env")],
+	},
+);
+
+// La configuration reste une configuration Playwright normale.
+export default defineConfig({
+	testDir: "./tests",
+	fullyParallel: true,
+	forbidOnly: envs.CI,
+	retries: envs.RETRIES,
+	workers: envs.WORKERS,
+	reporter: [
+		[
+			"html",
+			{
+				open: "never",
+				outputFolder: "playwright-report",
+			},
+		],
+		["list"],
+	],
+	use: {
+		headless: true,
+		trace: "retain-on-failure",
+		screenshot: "only-on-failure",
+	},
+	projects: [
+		{
+			name: "chromium",
+			use: { ...devices["Desktop Chrome"] },
+		},
+	],
+});
+
+interface TestFixtures {
+	website: Website;
+}
+
+// La fixture ajoute `website` aux tests et centralise le contexte du site.
+// Elle crée un `Website` par test à partir de la `page` et du `BrowserContext`
+// fournis par Playwright. `baseUrl` fixe l’adresse du site ; le hook attend la
+// fin du chargement réseau après chaque navigation.
+export const testClient = test.extend<TestFixtures>({
+	async website({ page, context }, use) {
+		const website = createWebsite({
+			playwrightPage: page,
+			playwrightBrowserContext: context,
+			envConfig: {
+				baseUrl: envs.BASE_URL,
+			},
+			hooks: {
+				async afterNavigateOnPage() {
+					await page.waitForLoadState("networkidle");
+				},
+			},
+		});
+
+		await use(website);
+	},
+});

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.