Rename TryOutcome to Outcome and refactor error factory pattern

[Reefact]

Summary

This PR consolidates the error handling API by renaming TryOutcome<T> to Outcome<T> and refactoring the error factory pattern from exception-based classes to static error factory classes. The changes align the library's public API with a more cohesive error modeling approach where errors are first-class values that can be transported without throwing.

Key Changes

API Consolidation

• Renamed TryOutcome<T> to Outcome<T> — The generic outcome type now has a clearer, more concise name that better reflects its dual purpose (success/failure transport)
• Introduced non-generic Outcome — Added a non-generic variant for operations that don't return a value, enabling consistent chaining patterns across both variants
• Comprehensive test coverage — Migrated all tests from TryOutcomeTests.cs to new OutcomeTests.cs with expanded test cases covering both generic and non-generic variants

Error Factory Pattern Refactoring

• Static error factory classes — Replaced exception-based factory methods (e.g., InvalidAmountOperationException.CurrencyMismatch()) with static error factory classes (e.g., InvalidAmountOperationError.CurrencyMismatch())
• [ProvidesErrorsFor] attribute — Error factory classes are now annotated with [ProvidesErrorsFor(nameof(Model))] to declare ownership of errors for a given domain model
• Error-first design — Factory methods now return Error instances (or subtypes like DomainError) rather than exceptions, with .ToException() available when throwing is needed
• Cleaner separation of concerns — Error creation, documentation, and exception wrapping are now explicitly separated

Documentation Pipeline Updates

• Assembly scanning refinement — AssemblyErrorDocumentationReader now scans for classes annotated with [ProvidesErrorsFor] instead of exception types
• Improved opt-in logic — Project filtering now properly distinguishes between explicit opt-out (property present and falsy) and absence of the property
• Error taxonomy documentation — Added explicit documentation of the error hierarchy (DomainError, InfrastructureError, PrimaryPortError, SecondaryPortError)

Supporting Changes

• ErrorContext improvements — Added ReadOnlyDictionary wrapper for safer exposure of context values
• ErrorDocumentation refinement — Made Code property internal setter to enforce immutability
• Test reorganization — Renamed DiagnosableExceptionTests to ErrorTests to reflect the shift from exception-centric to error-centric testing
• Documentation updates — Updated all usage examples, best practices, and getting started guides to reflect the new API

Implementation Details

• The Outcome<T> type maintains full backward compatibility in behavior while providing a clearer API surface
• Error factories can now be composed with Then(), To(), Recover(), and Finally() methods for fluent error handling pipelines
• The [ProvidesErrorsFor] attribute serves as the primary anchor for the documentation model, replacing exception type scanning
• All existing diagnostics, context, and error code functionality is preserved and integrated with the new error factory pattern

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d73fc0aaaf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Evaluate opt-out properties before skipping projects

When IncludeProjectsWithoutOptIn is true, this branch now turns any falsy occurrence of the opt-in property into a hard skip, but TryReadOptInFromProjectFile only scans the raw XML and does not evaluate MSBuild conditions or the selected options.Configuration. A project that has GenerateErrorDocumentation=false in a Release-only property group, for example, will be omitted during Debug solution-wide generation instead of falling back to the global include, so its errors silently disappear from the generated catalog. Please evaluate the property through MSBuild for the active configuration before treating false as an explicit opt-out.

Useful? React with 👍 / 👎.