SaneCppLibraries release/2026/09

Platform Abstraction C++ Libraries

Release notes

[September 2026 Update Blog Post](https://pagghiu.github.io/site/blog/2026-09-30-SaneCppLibrariesUpdate.html)

# Structured Result errors

The biggest change this month is the error model shared by the libraries.

Previously, `SC::Result` stored a pointer to an error message. It was small and easy to propagate, but distinguishing
failures meant inspecting English text. That also tied error identity to wording and made variable diagnostics depend
on the lifetime of a formatted buffer.

The new `Result` stores a 32-bit category and a 32-bit error value in one eight-byte object. Zero represents success.
Each library owns its error enum and category, while a small registry assigns the built-in category numbers and checks
for collisions. Applications can define their own categories too.

This makes errors useful to code as well as to people. A caller can distinguish capacity exhaustion, invalid input,
cancellation, or an unsupported operation through an explicit identity. Equivalent failures use the same primary code
on each platform; native error numbers and backend stages belong in additional context.

Some APIs return an enriched result carrying that context: an operation kind, required capacity, offset, or native
error number. Converting it to a plain `Result` preserves the category and primary error, while dropping the extra
detail. `SC_TRY` continues to propagate failures, and `SC_CO_TRY` does the same for coroutines.

Error text is now optional. Each owner has a dedicated error header and a separate opt-in formatter header. Formatters
write UTF-8 into caller-provided storage, report the required capacity, and leave applications free to supply their own
wording or translations. Core libraries do not need to carry canonical English messages when an application only wants
numeric errors. Release binary checks cover this separation for static, shared, and single-file builds on macOS,
Linux, and Windows.

The temporary compatibility bridge used during migration is gone. The old message-pointer factories and `SC_TRY_MSG`
have been removed, and all participating binaries need to be rebuilt together. This is a source and ABI change, even
though plain `Result` ends the migration at eight bytes again.

The shared definitions are Common source fragments, used by
[Foundation](https://pagghiu.github.io/SaneCppLibraries/libraries/foundation/) and the other libraries without adding a
new inter-library dependency. The architecture and formatting contracts are recorded in
[COMMON-0009](https://github.com/Pagghiu/SaneCppLibraries/blob/development/Architecture/Common/common-0009-use-library-owned-structured-result-errors.md).

**Detailed list of commits:**

- b4523826c Common: Add structured Result compatibility bridge
- 9ee948a4e Common: Add opt-in Result error formatting
- 0bc9beb36 CI: Validate Result error category registry
- c5c339a83 Architecture: Keep Result errors platform independent
- 4821eb1db Common: Initialize enriched error contexts through their active union members
- ec1bd64d8 Common: Remove the Result compatibility bridge and restore its eight-byte identity
- 6c99587ca Strings: Complete optional diagnostics and restore CLI library-error presentation
- d69ab93ca Everywhere: Isolate Result error definitions in dedicated owner headers

# The migration across libraries and tools

Most of September's commits are the work needed to make that model consistent across the repository.

The system-facing libraries now report portable operation errors and retain native details where useful:
[Threading](https://pagghiu.github.io/SaneCppLibraries/libraries/threading/),
[Process](https://pagghiu.github.io/SaneCppLibraries/libraries/process/),
[SerialPort](https://pagghiu.github.io/SaneCppLibraries/libraries/serial-port/),
[File](https://pagghiu.github.io/SaneCppLibraries/libraries/file/),
[FileSystem](https://pagghiu.github.io/SaneCppLibraries/libraries/file-system/),
[FileSystemWatch…

Share this resource