Problem
The API sends contradictory extensibility signals: Error and DiagnosableException have protected constructors and abstract ToException() (inviting consumer-defined categories), but PublicMessageStage<TError>'s constructor is internal (so a third-party category cannot reproduce the staged-construction discipline that is the library's headline feature), and the four concrete categories are public and unsealed yet have only internal constructors — de-facto sealed without saying so. No user document answers "can I add a category?" (ErrorTaxonomy, CoreConcepts, FAQ all grepped).
Impact
A first-time user who tries class ConfigurationError : Error gets a confusing partial success; the contract should be an explicit yes or an explicit no, and it hardens at v1.
Direction
Either:
- Close it (cheaper; matches current analyzer/GenDoc assumptions): document that the four categories are the complete taxonomy and extension happens through factories returning them; seal or constructor-privatize consistently.
- Open it: give
PublicMessageStage a protected/public creation path so a consumer category can offer the same Create(...).WithPublicMessage(...) discipline.
Either way, answer the question in ErrorTaxonomy/FAQ (EN+FR), and — if this qualifies as a lasting decision — record it as a Proposed ADR (relates #228).
Acceptance criteria
- The code's accessibility modifiers and the documentation give one consistent answer; a reader of ErrorTaxonomy or the FAQ knows whether and how to extend the taxonomy.
Context
Surfaced by the 2026-07-20 architecture, design & ecosystem audit (doc/handwritten/for-maintainers/audit/2026-07-20-firstclasserrors-architecture-and-design-audit.md, §9.3(a)/§14-HV10; branch claude/firstclasserrors-audit-83gap7).
Problem
The API sends contradictory extensibility signals:
ErrorandDiagnosableExceptionhaveprotectedconstructors and abstractToException()(inviting consumer-defined categories), butPublicMessageStage<TError>'s constructor isinternal(so a third-party category cannot reproduce the staged-construction discipline that is the library's headline feature), and the four concrete categories arepublicand unsealed yet have onlyinternalconstructors — de-facto sealed without saying so. No user document answers "can I add a category?" (ErrorTaxonomy, CoreConcepts, FAQ all grepped).Impact
A first-time user who tries
class ConfigurationError : Errorgets a confusing partial success; the contract should be an explicit yes or an explicit no, and it hardens at v1.Direction
Either:
PublicMessageStageaprotected/public creation path so a consumer category can offer the sameCreate(...).WithPublicMessage(...)discipline.Either way, answer the question in ErrorTaxonomy/FAQ (EN+FR), and — if this qualifies as a lasting decision — record it as a Proposed ADR (relates #228).
Acceptance criteria
Context
Surfaced by the 2026-07-20 architecture, design & ecosystem audit (
doc/handwritten/for-maintainers/audit/2026-07-20-firstclasserrors-architecture-and-design-audit.md, §9.3(a)/§14-HV10; branchclaude/firstclasserrors-audit-83gap7).