Beagle SCM

ABC-016: bedrock scalar/crypto hygiene: popc64, unaligned sha256, SAN.h

01.h/SHA.h/NACL.h/OK.h/PRO.h grab-bag (2026-07-07 review): advertised-but- wrong bit helpers, an unaligned u64 read of a 1-aligned record, and support headers that don't do what they claim.

Input

Context

• 01.h:172 — #define popc64(x) __builtin_popcount(x): 32-bit builtin, top 32 bits never counted. Caller-less (BIT.h calls popcountll directly) but advertised in INDEX.md. popcountll it.
• 01.h:240 — u64is2power(0) returns YES; 01.h:248 upper_log_2(0) hits clz64(0) (UB for the builtin). Guard zero.
• 01.h:154-155 — max/min double-evaluate in the most-included header (the roundup2 comment at :259 shows the codebase cares); same for $off/$cut (S.h:31,89). Statement-expression or typed forms.
• 01.h:289 — Ocopy uses assert without including <assert.h>; works only via S.h include order.
• SHA.h:11-14 sha256empty — reads u8 data[32] (alignof 1, lives at arbitrary offsets in mmapped streams by design) through u64c*: unaligned-load UB, UBSan/strict-alignment trap. Same class as PTR-001's TLV casts, distinct site. memcmp/memcpy form.
• NACL.h:35-41 — sign: slen possibly uninit when the NDEBUG-skipped assert reads it; NACLFAIL0 + ret with negative ret mints undocumented codes. Blake wrappers (:52-66) discard libsodium returns, always OK.
• PRO.h:379 / TEST.h:29,35 — MAIN/TEST return ok64 from int main: exit status truncates to the low byte; codes with low byte 0 report shell SUCCESS. Map non-OK to a fixed nonzero exit.
• SAN.h:10-20 — "sanitize the namespace" undefs 7 macros but leaves the high-collision ones (is, on, test, scan, trace, must, want, min, max, zero, …; trace() expanding to ; silently swallows a third-party call) AND #undef NULL breaks the standard macro for the rest of the TU.
• OK.h:24-25 — static char _ok64_tmp[4][16]; static int _ok64_idx; rotating static buffers in a header: per-TU state, non-thread-safe, 4-call lifetime — the pattern the canon bans (cf. PTR-001 Buf4096).
• RAP.h:26-36 — RAPMicroSeed/RAPNano/RAPNanoSeed take consumable u8cs for read-only input where their siblings correctly take u8csc.

Goals

• Per-item fixes with table tests where observable (popc64, is2power, exit codes); SAN.h completed or re-scoped; ok64str made caller-buffer or thread-local-documented.

Constraints

• 01.h/S.h are included everywhere — zero-risk mechanical fixes only, review-gated; anything with API impact (ok64str) needs a ruling.

WIP

Design decisions

• min/max/$off now GNU statement expressions — not usable in constant/file-scope contexts (zero in-tree callers of that shape; downstream unverified from the clone).

TODOs

• popc64/u64is2power/upper_log_2 + tests (BITSpow2/BITSminmax)
• sha256empty memcmp form; NACL return handling (slen init, documented NACLFAIL, Blake returns checked)
• MAIN/TEST exit mapping (EXITtest proves old macro exited 0 on 0x100); SAN.h ruling REQUESTED, untouched
• OK.h ruling REQUESTED, untouched; RAP.h u8csc; min/max/$off/$cut single-eval

Blockers and bummers

• RULING 1 (SAN.h): undef list misses is/on/test/scan/trace/must/ want/min/max/zero AND #undef NULL kills the standard macro — complete the list vs re-scope; the NULL undef is a plain bug.
• RULING 2 (OK.h ok64str): static char[4]16 rotating per-TU buffers — caller-buffer API vs documented-thread-local; API impact.
• Semantic flip: u64is2power(0) now NO — downstream (dog/beagle) alignment checks that accepted 0 will see the change.

Outcome

• Landed in work/ABC-016, NOT merged: ?467fb44b "ABC-016: scalar/ crypto hygiene". Suite 47/47 (was 46), new EXITtest + BITSpow2/ BITSminmax/offtest/SHAemptytest tables; orchestrator re-verified.