Harden cleanup and SIMD admission docs

Author: eldryoth

docs/SIMD_ACTIVATION_CHECKLIST.md

@@ -42,9 +42,24 @@ Architecture-specific baseline requirements:
 - wasm `simd128`: document the runtime's register-retention limitations and
   provide generated-code evidence for the selected wasm toolchain/runtime.
 
-Current prototypes are exempt only because they construct zero vectors and do
-not load caller bytes into SIMD registers. That exemption ends the moment a
-prototype starts processing caller input with vector registers.
+For NEON specifically, "used registers" cannot be guessed from source-level
+local variable count. Admission evidence must include optimized generated
+assembly for the exact target and feature bundle. If the compiler allocates
+caller-derived values to callee-saved vector registers, the admission package
+must also account for any compiler-generated spill/restore slots and prove that
+those slots are wiped or never contain caller-derived data.
+
+For wasm `simd128`, source-level register cleanup is not sufficient evidence.
+The wasm runtime/JIT owns final register allocation and may rewrite the
+generated code. A wasm backend cannot be admitted until the selected runtime
+and deployment profile have generated-code/JIT evidence, or the release notes
+scope wasm SIMD out of any register-retention claim.
+
+Current prototypes are exempt from admission only because they are test-only and
+non-dispatchable. The x86 and AArch64 prototypes already load caller bytes into
+vector registers and therefore carry best-effort cleanup plus unsafe-inventory
+documentation as evidence. That evidence is not enough for active dispatch
+until the full admission package is complete.
 
 ## Source Changes
 

docs/SIMD_ENCODE_ADMISSION_DRAFT.md

@@ -40,6 +40,15 @@ Each encode backend considered for admission must provide:
 - hardware evidence from a CPU that actually supports the backend
 - benchmark output with scalar baseline on the same machine
 
+Architecture-specific admission blockers:
+
+- AArch64 NEON must include generated assembly that identifies every
+  caller-derived vector register and any callee-saved vector spill/restore slot
+  that may carry caller data.
+- wasm `simd128` must include generated-code/JIT evidence for the selected wasm
+  runtime, or the release must explicitly keep wasm SIMD candidate-only and make
+  no runtime register-retention claim.
+
 ## Runtime Report Expectations
 
 Before active encode dispatch can ship, runtime reporting must make the

docs/UNSAFE.md

@@ -859,6 +859,11 @@ Safety argument:
 - This is best-effort register-retention reduction for test evidence, not a
   guarantee that historical register, stack, cache, or microarchitectural
   copies do not exist.
+- This helper currently clears the registers used by the reviewed prototype
+  sequence. It is not an admission claim for arbitrary future NEON code. Before
+  NEON dispatch can become active, generated assembly must prove which vector
+  registers carry caller-derived data and whether any callee-saved vector
+  register spill/restore slots contain such data.
 
 ### `encode_12_bytes_wasm_simd128`
 
@@ -894,6 +899,8 @@ Limitations:
 - This is compile and codegen evidence only. Wasm engines include a runtime/JIT
   optimization layer outside Rust's compiler boundary, so this prototype does
   not claim runtime timing, register-retention, or JIT zeroization guarantees.
+  wasm `simd128` admission requires runtime/JIT-specific evidence or an
+  explicit release scope that makes no register-retention claim.
 
 ### `encode_12_bytes_wasm_standard_family`
 

src/alphabet.rs

@@ -302,6 +302,15 @@ impl Alphabet for UrlSafe {
 /// This alphabet is commonly used by bcrypt hash strings. It is provided as an
 /// alphabet/profile building block; `base64-ng` does not parse or verify full
 /// bcrypt password-hash records.
+///
+/// # Security
+///
+/// The strict [`Alphabet::decode`] implementation delegates to
+/// [`decode_alphabet_byte`]. That helper scans the full alphabet, but it is a
+/// `const fn` and does not use the additional optimizer barriers used by the
+/// [`ct`](crate::ct) module. Do not use strict `Engine<Bcrypt, _>` decode as a
+/// token, key, or password-hash verifier. Use [`crate::ct::CtEngine`] with this
+/// alphabet for secret-bearing comparison workflows.
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
 pub struct Bcrypt;
 
@@ -318,6 +327,15 @@ impl Alphabet for Bcrypt {
 ///
 /// This alphabet is provided as an explicit legacy interoperability profile.
 /// `base64-ng` does not parse or verify complete password-hash records.
+///
+/// # Security
+///
+/// The strict [`Alphabet::decode`] implementation delegates to
+/// [`decode_alphabet_byte`]. That helper scans the full alphabet, but it is a
+/// `const fn` and does not use the additional optimizer barriers used by the
+/// [`ct`](crate::ct) module. Do not use strict `Engine<Crypt, _>` decode as a
+/// token, key, or password-hash verifier. Use [`crate::ct::CtEngine`] with this
+/// alphabet for secret-bearing comparison workflows.
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
 pub struct Crypt;
 

src/cleanup.rs

@@ -94,7 +94,11 @@ fn wipe_barrier(ptr: *mut u8, len: usize) {
 
 pub(crate) fn wipe_tail(bytes: &mut [u8], start: usize) {
     debug_assert!(start <= bytes.len(), "wipe_tail start exceeds slice length");
-    let start = start.min(bytes.len());
+    if start > bytes.len() {
+        wipe_bytes(bytes);
+        return;
+    }
+
     if start < bytes.len() {
         wipe_bytes(&mut bytes[start..]);
     }