docs: define v1 error and Result contracts

[zuudevs]

Summary

Defines the v1 error model and Result<T> contract for cpp_request.

Added

• docs/api/error-model.md
  • portable ErrorCode taxonomy
  • secondary native diagnostic code
  • URL, DNS, socket, timeout, protocol, and redirect error classes
  • HTTP status codes are not library errors
  • EOF/framing semantics
  • portable layer-to-layer error propagation
  • zero-allocation diagnostic message guidance
  • Mermaid error-flow diagrams
• docs/api/result.md
  • two-state success/failure contract
  • [[nodiscard]]
  • has_value() and explicit operator bool()
  • value() / error() accessor preconditions
  • ownership/move/copy behavior
  • no mandatory heap allocation for result storage
  • std::variant<T, Error> accepted as initial C++17 candidate
  • optional future Result<void> specialization
  • no ErrorCode::None sentinel requirement
  • Mermaid state/propagation diagrams

Key decisions

• Expected network/protocol failures are returned through Result<T>, not library-specific exceptions.
• HTTP 4xx / 5xx responses are valid Response values when transport/parsing succeeded.
• ErrorCode is the portable public contract; Winsock/POSIX native codes are secondary diagnostics only.
• Connect/read/write timeout errors remain distinct.
• Success is represented by the Result<T> state; no ErrorCode::None is required.
• Wrong-state value() / error() access is a programmer precondition violation rather than an exception-based control-flow path.
• Physical Result<T> storage remains an implementation detail; C++17 std::variant should be tried before inventing custom discriminated storage.

Documentation-only PR; no runtime behavior changes.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 33cb2a84ca

ℹ️ 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]

Reconcile error() with the existing public contract

When implementing v1 from both API documents, these overloads conflict with docs/api/public-api.md:292, which still specifies Error error() const noexcept. The old contract returns an owning value and promises noexcept, while this document returns references without that guarantee; these signatures cannot coexist as overloads, so callers and implementers receive incompatible ownership and exception contracts. Update the original public API document or explicitly state which contract supersedes it.

Useful? React with 👍 / 👎.