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

package/docs/concepts/03-client/20-form/30-layout.ts

@@ -3,10 +3,13 @@
  *
  * Composition de la structure des données et des comportements d’un formulaire.
  */
-import { createForm, useCheckLayout, useDisabledLayout, useMultiLayout, useRepeatLayout, useSectionLayout, useSlotLayout, useStepLayout, useUnionLayout } from "@duplojs/form/vue";
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DEither from "@duplojs/lang/either";
+import { createForm, type DetailsError, useCheckLayout, useDisabledLayout, useMultiLayout, useRepeatLayout, useSectionLayout, useSlotLayout, useStepLayout, useUnionLayout } from "@duplojs/form/vue";
 import { templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useTextareaInput, useTextInput } from "@duplojs/form/vueDesignSystem";
 import { createGridTemplates } from "@duplojs/form/vueGrid";
 import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DString from "@duplojs/lang/string";
 import { ref } from "vue";
 
 const gridTemplates = createGridTemplates({
@@ -66,34 +69,34 @@ const { check: checkStructureForm, component: StructureForm, currentValue: curre
 	),
 );
 
-// Ref<{
-//   identity: {
-//     firstName: string;
-//     lastName: string;
-//   };
-//   contacts: [string, ...string[]];
-//   preferredContact: {
-//     readonly kind: "email" | "phone";
-//     value: string;
-//     updateKind(kind: "email" | "phone", value?: string): void;
-//   };
-//   message: string;
-// }>
+type _CheckContacts = DCommon.ExpectType<typeof currentStructureValue.value.contacts, [string, ...string[]], "strict">;
+type _CheckPreferredContactKind = DCommon.ExpectType<
+	typeof currentStructureValue.value.preferredContact.kind,
+	"email" | "phone",
+	"strict"
+>;
 void currentStructureValue;
 
-// DEither.Error<DetailsError> | DEither.Success<{
-//   identity: {
-//     firstName: string;
-//     lastName: string;
-//   };
-//   contacts: [string, ...string[]];
-//   preferredContact: {
-//     kind: "email" | "phone";
-//     value: string;
-//   };
-//   message: string | undefined;
-// }>
 const checkedStructureValue = await checkStructureForm();
+type _CheckCheckedStructureValueLine96 = DCommon.ExpectType<
+	typeof checkedStructureValue,
+	DEither.Error<DetailsError> | DEither.Success<{
+		identity: {
+			firstName: string;
+			lastName: string;
+		};
+		contacts: [string, ...string[]];
+		preferredContact: {
+			kind: "email";
+			value: string;
+		} | {
+			kind: "phone";
+			value: string;
+		};
+		message: string | undefined;
+	}>,
+	"strict"
+>;
 
 void checkedStructureValue;
 void StructureForm;
@@ -132,29 +135,21 @@ const { check: checkFlowForm, component: FlowForm, currentValue: currentFlowValu
 	),
 );
 
-// Ref<{
-//   currentStep: 0 | 1;
-//   steps: [
-//     {
-//       fullName: string;
-//       email: string;
-//     },
-//     {
-//       company: string;
-//       notes: string;
-//     },
-//   ];
-// }>
+type _CheckCurrentStep = DCommon.ExpectType<typeof currentFlowValue.value.currentStep, 0 | 1, "strict">;
 void currentFlowValue;
 
-// DEither.Error<DetailsError> | DEither.Success<[
-//   {
-//     fullName: string;
-//     email: string & Email;
-//   },
-//   {
-//     company: string | undefined;
-//     notes: string;
-//   },
-// ]>
 const checkedFlowValue = await checkFlowForm();
+type _CheckCheckedFlowValueLine160 = DCommon.ExpectType<
+	typeof checkedFlowValue,
+	DEither.Error<DetailsError> | DEither.Success<readonly [
+		{
+			fullName: string;
+			email: string & DString.Email;
+		},
+		{
+			company: string | undefined;
+			notes: string;
+		},
+	]>,
+	"strict"
+>;

package/docs/concepts/03-client/20-form/40-template.ts

@@ -6,6 +6,7 @@
 import { createForm, createTemplate, useMultiLayout, type InputTemplateProperties, type VueComponent } from "@duplojs/form/vue";
 import { templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useTextareaInput, useTextInput } from "@duplojs/form/vueDesignSystem";
 import { createGridTemplates } from "@duplojs/form/vueGrid";
+import type * as DCommon from "@duplojs/lang/common";
 
 // Un template transforme les props système et les slots en interface Vue.
 // Il reste générique : la connaissance métier appartient au formulaire.
@@ -81,9 +82,13 @@ const { component: TheForm, currentValue } = useForm(
 // `title` utilise le template global, `subtitle` le surcharge localement,
 // `summary` revient au template grid.
 //
-// Ref<{
-//   title: string;
-//   subtitle: string;
-//   summary: string;
-// }>
+type _CheckCurrentValue = DCommon.ExpectType<
+	typeof currentValue.value,
+	{
+		title: string;
+		subtitle: string;
+		summary: string;
+	},
+	"strict"
+>;
 void currentValue;

package/docs/concepts/03-client/20-form/50-integration.md

@@ -0,0 +1,11 @@
+## Intégrer un formulaire dans une page Vue
+
+Séparer la logique d'un formulaire de son rendu dans une page Vue.
+
+---
+
+Une séparation recommandée consiste à construire le formulaire et à regrouper ses opérations dans un composable. La page consomme son interface et reste centrée sur la présentation ; Form n'impose pas cette organisation.
+
+Dans [usePostModeration.ts](./examples/postModeration/usePostModeration.ts), le composable configure les champs, choisit la variante, valide la soumission et libère le formulaire à la fin du scope Vue. Il expose le composant `ModerationForm` et les seuls états et actions utiles à la page. En cas de validation réussie, il utilise la valeur validée ; les erreurs restent affichées par les templates du formulaire.
+
+[ThePage.vue](./examples/postModeration/ThePage.vue) monte ce composant, place le bouton de soumission dans son slot par défaut et relie son événement `submit` à l'opération du composable. Les boutons de décision illustrent le changement de variante depuis l'interface.

package/docs/concepts/03-client/20-form/examples/postModeration/ThePage.vue

@@ -0,0 +1,32 @@
+<script setup lang="ts">
+import { PrimaryButton, OutlineButton, DestructiveButton } from "@duplojs/form/vueDesignSystem";
+import { usePostModeration } from "./usePostModeration";
+
+const { ModerationForm, selectedDecision, submitted, selectApproval, selectRejection, submit } = usePostModeration();
+</script>
+
+<template>
+	<section>
+		<h1>Moderate post</h1>
+
+		<OutlineButton @click="selectApproval">
+			Approve
+		</OutlineButton>
+
+		<DestructiveButton @click="selectRejection">
+			Reject
+		</DestructiveButton>
+
+		<p>Selected decision: {{ selectedDecision }}</p>
+
+		<ModerationForm @submit="submit">
+			<PrimaryButton type="submit">
+				Submit decision
+			</PrimaryButton>
+		</ModerationForm>
+
+		<p v-if="submitted">
+			{{ submitted }}
+		</p>
+	</section>
+</template>

package/docs/concepts/03-client/20-form/examples/postModeration/usePostModeration.ts

@@ -0,0 +1,80 @@
+import { createForm, useMultiLayout, useUnionLayout } from "@duplojs/form/vue";
+import { templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useTextareaInput, useTextInput } from "@duplojs/form/vueDesignSystem";
+import { createGridTemplates } from "@duplojs/form/vueGrid";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+import { computed, onScopeDispose, ref } from "vue";
+
+const templates = createGridTemplates({
+	repeat: {
+		addLabel: "Add",
+		removeLabel: "Remove",
+		addButton: templateFormAddButton,
+		removeButton: templateFormRemoveButton,
+		resetButton: templateFormResetButton,
+	},
+	step: {
+		nextLabel: "Continue",
+		previousLabel: "Back",
+		nextButton: templateFormNextButton,
+		previousButton: templateFormPreviousButton,
+		resetButton: templateFormResetButton,
+	},
+	union: { selectInputKind: templateFormSelect },
+});
+
+const useForm = createForm(templates.useTemplates());
+
+export function usePostModeration() {
+	const { component: ModerationForm, currentValue, check, dispose } = useForm(
+		useUnionLayout(
+			[
+				["approve", useTextInput({ label: "Public note" })],
+				[
+					"reject",
+					useMultiLayout({
+						reason: useTextareaInput({
+							label: "Reason for rejection",
+							dataStructure: DDataStructure.string([DDataStructure.minCharacters(1)]),
+						}),
+					}),
+				],
+			],
+			{ defaultKind: "approve" },
+		),
+	);
+	const selectedDecision = computed(() => currentValue.value.kind);
+	const submitted = ref("");
+
+	function selectApproval() {
+		currentValue.value.updateKind("approve");
+	}
+
+	function selectRejection() {
+		currentValue.value.updateKind("reject");
+	}
+
+	async function submit() {
+		submitted.value = "";
+		const result = await check();
+
+		if (DEither.isRight(result)) {
+			const decision = DEither.unwrapRight(result);
+
+			submitted.value = decision.kind === "approve"
+				? `Approved: ${decision.value}`
+				: `Rejected: ${decision.value.reason}`;
+		}
+	}
+
+	onScopeDispose(dispose);
+
+	return {
+		ModerationForm,
+		selectedDecision,
+		submitted,
+		selectApproval,
+		selectRejection,
+		submit,
+	};
+}

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

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

@@ -1,3 +1,3 @@
 ## Architecture
 
-Responsabilités des couches, sens des dépendances, opérations autorisées aux frontières et exposition des résultats aux consommateurs.
+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

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

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