From a953b8682b5b65b636447891649590a430b112fd Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 6 Jul 2026 09:42:21 +0000 Subject: [PATCH 1/3] docs(faq): clarify that FCE enriches the error, not the exception The 'Why not just use normal exceptions?' answer said the library 'turns exceptions from technical signals into documented knowledge units', which conflates the exception (the mechanism that signals and propagates a failure) with the error it carries. Reword so the exception stays the signaling/handling mechanism and the *error* is what becomes a documented knowledge unit, matching the rest of the model (Error as a first-class concept, exceptions obtained via error.ToException()). Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Vd5W4xp6DiJdNUsRTmKXpu --- doc/FAQ.en.md | 2 +- doc/FAQ.fr.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/FAQ.en.md b/doc/FAQ.en.md index 5d45a27..041866c 100644 --- a/doc/FAQ.en.md +++ b/doc/FAQ.en.md @@ -14,7 +14,7 @@ The difference is that this library adds: * linked documentation * a consistent model -It turns exceptions from *technical signals* into *documented knowledge units*. +The exception stays what it has always been: the mechanism that signals and propagates a failure — the library doesn’t replace it. What it transforms is the **error** the exception carries: from a mere *technical signal*, it becomes a *documented knowledge unit*. ## ❓ Why not use `Result` instead? diff --git a/doc/FAQ.fr.md b/doc/FAQ.fr.md index d5dcf47..c190236 100644 --- a/doc/FAQ.fr.md +++ b/doc/FAQ.fr.md @@ -14,7 +14,7 @@ La différence est que cette bibliothèque ajoute : * une documentation liée * un modèle cohérent -Elle transforme les exceptions de *signaux techniques* en *unités de connaissance documentées*. +L’exception reste le mécanisme qui signale et propage une défaillance — la bibliothèque ne la remplace pas. Ce qu’elle transforme, c’est l’**erreur** portée par l’exception : d’un simple *signal technique*, celle-ci devient une *unité de connaissance documentée*. ## ❓ Pourquoi ne pas utiliser `Result` à la place ? From 12646de0c5e1262a518c3a6433cd080edd164911 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 6 Jul 2026 20:14:34 +0000 Subject: [PATCH 2/3] docs(core-concepts): align intro with the exception/error distinction The opening sentence said the library 'treats exceptions as structured knowledge', reusing the same conflation just fixed in the FAQ. Reword so the exception stays the mechanism that signals and propagates a failure, and the *error* it carries is what becomes structured knowledge. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Vd5W4xp6DiJdNUsRTmKXpu --- doc/CoreConcepts.en.md | 2 +- doc/CoreConcepts.fr.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/CoreConcepts.en.md b/doc/CoreConcepts.en.md index 6b035bc..2ca0730 100644 --- a/doc/CoreConcepts.en.md +++ b/doc/CoreConcepts.en.md @@ -6,7 +6,7 @@ FirstClassErrors is not just a utility library. It introduces a different way to think about application errors. -Instead of treating exceptions as technical incidents, it treats them as **structured knowledge about what went wrong**. +Instead of reducing a failure to a mere technical incident, it turns the **error** behind it into **structured knowledge about what went wrong** — while the exception stays the mechanism that signals and propagates that failure. ## 🧠 An error is not just a message diff --git a/doc/CoreConcepts.fr.md b/doc/CoreConcepts.fr.md index 0a64a5d..fd8d570 100644 --- a/doc/CoreConcepts.fr.md +++ b/doc/CoreConcepts.fr.md @@ -5,7 +5,7 @@ FirstClassErrors n’est pas simplement une bibliothèque utilitaire. Il introduit une autre manière de penser les erreurs applicatives. -Au lieu de considérer les exceptions comme des incidents techniques, elles sont vues comme **une connaissance structurée sur ce qui s’est mal passé**. +Au lieu de réduire une défaillance à un simple incident technique, elle fait de l’**erreur** qui la sous-tend **une connaissance structurée sur ce qui s’est mal passé** — l’exception restant le mécanisme qui la signale et la propage. ## 🧠 Une erreur n’est pas juste un message From 0e80640bb4bc2216d886bad4a5131c6763da41d2 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 6 Jul 2026 20:20:21 +0000 Subject: [PATCH 3/3] docs(readme,design-principles): stop conflating exceptions with errors Corpus-wide pass following the FAQ/CoreConcepts fixes. Same conflation appeared in three more spots, where the *exception* (the throwing/ transport mechanism) was made the subject of a semantic claim that belongs to the *error*: - README (fr/en) tagline: 'Turn your exceptions into ... knowledge' -> 'Turn your errors into ...'. The error is the knowledge unit. - README (fr/en) 'Exception or not?' callout: reworded so the same *error* is what you either throw as a runtime signal or transport as structured data via Outcome (the Outcome path throws no exception). - DesignPrinciples (fr/en): 'allowing exceptions to be used as structured error information through Outcome' -> 'allowing errors to be carried as structured data through Outcome instead of thrown'. This also removes a contradiction with the preceding paragraph, which states the library separates semantics from mechanics. Reviewed the rest of doc/ (UsagePatterns, BestPractices, Comparison, OperationalIntegration, pipeline, renderers, i18n, analyzers): the error/exception distinction already holds there. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Vd5W4xp6DiJdNUsRTmKXpu --- README.md | 8 ++++---- doc/DesignPrinciples.en.md | 2 +- doc/DesignPrinciples.fr.md | 2 +- doc/README.fr.md | 8 ++++---- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 27e2e31..51f8ecf 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ --- -**Turn your exceptions into structured, living knowledge about your system.** +**Turn your errors into structured, living knowledge about your system.** ![FirstClassErrors](./doc/images/first-class-errors.png "FirstClassErrors") @@ -134,10 +134,10 @@ The library supports both: * **throwing errors** (traditional exception flow) * **transporting errors without throwing** via `Outcome` and `Outcome` -This allows you to use exceptions as: +This lets you treat the same error either way: -> runtime signals -> or structured error data +> as a runtime signal you throw +> or as structured data you transport depending on the context (domain logic, validation, pipelines, etc.). diff --git a/doc/DesignPrinciples.en.md b/doc/DesignPrinciples.en.md index 890ab2e..7637329 100644 --- a/doc/DesignPrinciples.en.md +++ b/doc/DesignPrinciples.en.md @@ -13,7 +13,7 @@ Diagnostics are not post-mortem analysis; they are structured hypotheses. The go The library also separates semantics from mechanics. Throwing, catching, logging, or transporting errors are mechanical concerns. The meaning of an error — what rule was violated, what situation occurred, what might explain it — belongs to the domain of knowledge. FirstClassErrors focuses on preserving that meaning, regardless of how the error travels through the system. -Finally, the design acknowledges that not every failure should be exceptional in the runtime sense. Some errors are expected parts of normal flow, such as validation failures or parsing issues. By allowing exceptions to be used as structured error information through `Outcome`, the model supports both throwing and non-throwing flows without losing semantic richness. +Finally, the design acknowledges that not every failure should be exceptional in the runtime sense. Some errors are expected parts of normal flow, such as validation failures or parsing issues. By allowing errors to be carried as structured data through `Outcome` instead of thrown, the model supports both throwing and non-throwing flows without losing semantic richness. In essence, the library encourages teams to treat errors as first-class knowledge artifacts. When errors are explicit, documented, and structured, they improve communication between developers, support teams, and the system itself. diff --git a/doc/DesignPrinciples.fr.md b/doc/DesignPrinciples.fr.md index b750705..16bdbda 100644 --- a/doc/DesignPrinciples.fr.md +++ b/doc/DesignPrinciples.fr.md @@ -13,7 +13,7 @@ Les diagnostics ne sont pas une analyse post-mortem ; ce sont des hypothèses st La bibliothèque sépare également la sémantique de la mécanique. Lever, intercepter, logger ou transporter des erreurs sont des préoccupations mécaniques. Le sens d’une erreur — quelle règle a été violée, quelle situation s’est produite, ce qui pourrait l’expliquer — appartient au domaine de la connaissance. FirstClassErrors se concentre sur la préservation de ce sens, indépendamment de la manière dont l’erreur circule dans le système. -Enfin, la conception reconnaît que tous les échecs ne doivent pas être exceptionnels au sens runtime. Certaines erreurs font partie du flux normal, comme les échecs de validation ou les problèmes de parsing. En permettant d’utiliser les exceptions comme information d’erreur structurée via `Outcome`, le modèle supporte à la fois les flux avec et sans levée d’exception, sans perdre la richesse sémantique. +Enfin, la conception reconnaît que tous les échecs ne doivent pas être exceptionnels au sens runtime. Certaines erreurs font partie du flux normal, comme les échecs de validation ou les problèmes de parsing. En permettant de transporter les erreurs comme données structurées via `Outcome` plutôt que de les lever, le modèle supporte à la fois les flux avec et sans levée d’exception, sans perdre la richesse sémantique. En essence, la bibliothèque encourage les équipes à considérer les erreurs comme des artefacts de connaissance de premier plan. Lorsque les erreurs sont explicites, documentées et structurées, elles améliorent la communication entre les développeurs, les équipes de support et le système lui-même. diff --git a/doc/README.fr.md b/doc/README.fr.md index 504706e..42e6761 100644 --- a/doc/README.fr.md +++ b/doc/README.fr.md @@ -7,7 +7,7 @@ --- -**Transformez vos exceptions en connaissance structurée et vivante sur votre système.** +**Transformez vos erreurs en connaissance structurée et vivante sur votre système.** ![FirstClassErrors](./images/first-class-errors.png "FirstClassErrors") @@ -134,10 +134,10 @@ La bibliothèque supporte à la fois : * **les erreurs levées** (flux classique par exceptions) * **les erreurs transportées sans être levées** via `Outcome` et `Outcome` -Cela vous permet d’utiliser les exceptions : +Cela vous permet de traiter la même erreur, au choix : -> comme signaux d’exécution -> ou comme données d’erreur structurées +> comme un signal d’exécution que vous levez +> ou comme une donnée structurée que vous transportez selon le contexte (domaine, validation, pipelines, etc.).