# Conclusion: detz safe-C++ playbook: overflow-safe parsing, cheap release hardening, a sanitizer test net, no new dependency

## Metadata

| Field | Value |
|---|---|
| Institute | Molodetz Institute — Research & Retrieval Division |
| Subject | safe-cpp-practices |
| Document type | Conclusion |
| Tier | N/A |
| Date decided | 2026-10-27 |
| Decided by | retoor, advised by tai (agent, Claude Opus 4.8) |
| Status | Active |
| Confidence | High |

## Question / problem statement

How does detz write fast, object-oriented C++ that a hostile or buggy peer can never crash or corrupt, without slowing development to a crawl or adding heavy dependencies?

## Conclusion

Four layers, cheapest first. (1) Design: parse untrusted bytes through a checked reader that validates every length against remaining bytes with overflow-safe arithmetic (`len <= size - pos`, never `pos + len <= size`), reads lengths into an unsigned type, rejects negatives, and never lets a wire value drive an allocation or slice before it is bounded; guard every varint shift against >= 64 bits; wrap every top-level read/dispatch loop so no exception escapes. RAII and the rule of zero keep resource bugs from existing. (2) Release hardening (cheap, always on): the overflow-safe checks plus libstdc++ fast assertions and fortification per the OpenSSF guide, so a residual bad index is a defined, located failure not undefined behavior. (3) Test net (free at dev time, run in CI): an ASan+UBSan+_GLIBCXX_ASSERTIONS build of the parsers plus a hostile-input and random-fuzz test, via tools/san-whatsapp.sh. (4) Capture: record the exact bytes of any frame that breaks a parser so an unreproducible wire bug becomes a one-paste deterministic fix. No GSL, no new runtime dependency; std::span-style checked views and OpenSSL/zlib already linked.

## Supporting sources

- [openssf-compiler-hardening-guide](../openssf-compiler-hardening-guide.md): the cheap release-hardening flag set (_GLIBCXX_ASSERTIONS, fortification, stack-protector).
- [integer-overflow-size-checks](../integer-overflow-size-checks.md): the `len <= size - pos` guard and validate-before-allocate rule, the root-cause cure.
- [libfuzzer-sanitizer-ci](../libfuzzer-sanitizer-ci.md): the sanitizer+fuzz test net and the regression-corpus/capture pattern.
- [sanitizer-overhead-maturity-ladder](../sanitizer-overhead-maturity-ladder.md): why sanitizers are test-only and hardening is release: the overhead numbers and the ladder.
- [cpp-core-guidelines-bounds-gsl](../cpp-core-guidelines-bounds-gsl.md): span-over-pointer+length and explicit checked narrowing instead of silent int->size_t.
- [std-span-no-default-bounds-check](../std-span-no-default-bounds-check.md): why the reader must validate itself and not trust span/subspan to bounds-check.

## Alternatives considered and rejected

Adopt GSL wholesale (span/narrow/not_null): rejected as a new dependency; CLAUDE.md says fewer moving parts, and std::span plus a small checked reader covers the need. Turn on sanitizers in release: rejected, 2-3x cost; they are the test net, not the shipping config. Rewrite the wire layer in a memory-safe language: rejected, the project is C++ and the crypto/wire core is proven; the goal is safe C++, not not-C++.

## Risks / open questions

Hardening and sanitizers catch memory and UB bugs, not logic bugs; byte-exact golden vectors and the live handshake cover correctness separately. clang-tidy (the narrowing-conversion static layer) is not wired yet, so an implicit narrowing can still be introduced between sanitizer runs; that is the named next ratchet step. ed25519 ref10 is excluded from UBSan for intentional shift idioms, a small unsanitized island.

## Action taken

Applied to detz::wa in this session: overflow-safe checks in WaBinary and WaProto (commit f16c5c6), the varint shift guard (this session, caught by the sanitizer net that this research prescribed), the frame-capture hook, tests/whatsapp_test.cpp test_hostile, and tools/san-whatsapp.sh. Documented in docs/cpp-safety.md and docs/whatsapp.md section 13, with the standing rule added to AGENTS.md. clang-tidy ratchet recorded as the next step, not yet wired.

## Changelog

| Date | Change |
|---|---|
| 2026-10-27 | Initial conclusion recorded. |