cpp20-api-guidelines

# C++20 API Guidelines ## Workflow 1. Read `docs/cpp_design_recommendations.md` (project root) before producing code or recommendations. This is the authoritative design guide with rationale, examples, and library usage. 2. Apply the rules as hard constraints (`MUST`/`MUST NOT`) and preferences (`SHOULD`). 3. If existing project conventions conflict with a `SHOULD`, follow project conventions and note the tradeoff. 4. Run `references/review-checklist.md` as a final self-check before returning code. 5. Keep output concise: propose the simplest valid API that prevents common misuse. ## Key References (project root) - `docs/cpp_design_recommendations.md` -- Design guide (rules, examples, rationale, parameter passing, container selection) - `.clang-tidy` -- Reference clang-tidy config (bugprone-*, modernize-*, etc.) ## Output Requirements - Prefer small, intention-revealing APIs. - Prefer free functions over classes unless state/invariants/lifecycle require a class. - Keep ownership, lifetime, side effects, and error semantics explicit. - **Error handling:** - Use `PJ::Expected<T>` (recoverable error with value), `PJ::Status` (recoverable error, no return value), `PJ::Span<T>` (non-owning view). - Success: `PJ::okStatus()`. Error: `PJ::unexpected(msg)`. Check: `.has_value()`. - Use `tsl::robin_map` for hash containers in `.cpp` files, `std::unordered_map` in headers. Use `fmt::format` for string formatting. - Include minimal code examples only when they clarify contracts or misuse prevention.