Add SSSE3 decode prototype evidence

Author: eldryoth

docs/RELEASE_EVIDENCE.md

@@ -119,7 +119,8 @@ The release gate runs:
   Rust targets are installed
 - backend evidence capture for runtime backend reporting, admitted AVX-512
   VBMI, AVX2, SSSE3/SSE4.1, or NEON encode dispatch when supported, and
-  inactive SIMD prototype scalar-equivalence output for remaining candidates
+  inactive SIMD prototype scalar-equivalence output for remaining candidates,
+  including the SSSE3/SSE4.1 fixed-block decode prototype
 - SIMD admission policy for the current release series, with AVX-512 VBMI,
   AVX2, SSSE3/SSE4.1, and NEON encode admitted only for std x86/x86_64 or std
   aarch64 Standard and URL-safe alphabets, no decode acceleration, and no SIMD

docs/SIMD.md

@@ -253,7 +253,8 @@ may show admitted encode acceleration as active. On 32-bit ARM, NEON remains
 scaffold evidence. The script also writes
 `target/release-evidence/backend/MANIFEST.txt` with toolchain metadata,
 commands, status values, artifact checksums, and explicit
-`prototype_state=real-non-dispatchable` labels for prototype-only backends and
+`prototype_state=real-non-dispatchable` labels for prototype-only backends,
+including the non-dispatchable SSSE3/SSE4.1 fixed-block decode prototype, and
 `active_backend_admitted=avx512-vbmi-or-avx2-or-ssse3-sse4.1-or-neon-encode` for admitted encode
 backends.
 

docs/SIMD_ADMISSION.md

@@ -88,7 +88,7 @@ State labels are intentionally strict:
 | --- | --- | --- | --- |
 | AVX-512 VBMI | admitted backend | `avx512f`, `avx512bw`, `avx512vl`, `avx512vbmi` | std x86/x86_64 runtime-dispatched encode for Standard and URL-safe alphabet families; fixed 48-byte blocks use vector code only when at least one full block is present; shorter inputs, tails, unsupported alphabets, in-place encode, line-ending insertion, `no_std`, and decode use scalar fallback |
 | AVX2 | admitted backend | `avx2` | std x86/x86_64 runtime-dispatched encode for Standard and URL-safe alphabet families; fixed 24-byte blocks use vector code only when at least one full block is present; shorter inputs, tails, unsupported alphabets, in-place encode, line-ending insertion, `no_std`, and decode use scalar fallback |
-| SSSE3/SSE4.1 | admitted backend | `ssse3`, `sse4.1` | std x86/x86_64 runtime-dispatched encode for Standard and URL-safe alphabet families; fixed 12-byte blocks use vector code only when at least one full block is present; shorter inputs, tails, unsupported alphabets, in-place encode, line-ending insertion, `no_std`, and decode use scalar fallback |
+| SSSE3/SSE4.1 | admitted backend | `ssse3`, `sse4.1` | std x86/x86_64 runtime-dispatched encode for Standard and URL-safe alphabet families; fixed 12-byte encode blocks use vector code only when at least one full block is present; a fixed 16-byte decode block prototype exists for tests and evidence only; public decode, shorter inputs, tails, unsupported alphabets, in-place encode, line-ending insertion, and `no_std` use scalar fallback |
 | NEON | admitted backend | `neon` | std aarch64 runtime-dispatched encode for Standard and URL-safe alphabet families; fixed 12-byte blocks use vector code only when at least one full block is present; shorter inputs, tails, unsupported alphabets, 32-bit ARM, in-place encode, line-ending insertion, `no_std`, and decode use scalar fallback |
 | wasm `simd128` | real non-dispatchable prototype | `simd128` | real fixed-block encode prototype for Standard and URL-safe alphabets; test-binary compile evidence only; non-dispatchable |
 

docs/UNSAFE.md

@@ -673,6 +673,61 @@ Safety argument:
   six-bit Base64 value.
 - The helper is private to the Standard-family SSSE3/SSE4.1 encode path.
 
+### `decode_16_bytes_ssse3_sse41`
+
+Location: `src/simd/x86/mod.rs`
+
+Status: non-dispatchable std x86/x86_64 SSSE3/SSE4.1 decode prototype for
+Standard and URL-safe alphabet families. It is reachable only from SIMD tests
+and backend evidence capture. Runtime decode dispatch remains scalar.
+
+Purpose:
+
+- Establish the first fixed-block SIMD decode admission boundary without
+  changing public decode behavior.
+- Exercise SSSE3/SSE4.1 6-bit-value packing for a 16-byte encoded block that
+  decodes to at most 12 bytes.
+- Verify error agreement, padding behavior, canonical trailing-bit rejection,
+  and rejected-input output retention before any later dispatch admission.
+
+Preconditions:
+
+- Caller must prove SSSE3 and SSE4.1 are available on the current CPU.
+- Input is exactly 16 encoded bytes.
+- Output is exactly 12 bytes.
+- The vectorized packing path is used only for Standard-family alphabets
+  (`A-Z`, `a-z`, `0-9`, and either `+/` or `-_`). Other alphabets use the
+  staged scalar fallback inside the prototype.
+
+Unsafe operation:
+
+- `_mm_loadu_si128` loads sixteen 6-bit values from a local staging array.
+- `_mm_maddubs_epi16` and `_mm_madd_epi16` pack groups of four 6-bit values
+  into 24-bit decoded quanta.
+- `_mm_shuffle_epi8` compacts the packed quanta into byte order.
+- `_mm_storeu_si128` stores the packed prototype output into a local 16-byte
+  staging array.
+- `clear_xmm_registers_after_encode_block` clears XMM registers before return
+  to reduce register retention in the vector decode prototype.
+
+Safety argument:
+
+- Scalar strict decode validation runs into a private 12-byte staging buffer
+  before any byte is copied to the caller output. If validation fails, the
+  caller output is left untouched and the staging buffer is wiped.
+- The input and output array types provide fixed readable and writable bounds.
+- The SIMD load and store operate only on local 16-byte arrays and use
+  unaligned intrinsics, so no alignment precondition is required.
+- The SSSE3/SSE4.1 target-feature contract enables every intrinsic used by
+  the prototype.
+- The prototype copies only the validated decoded length to caller output and
+  wipes local value, packed, and scalar-validation staging buffers before
+  returning.
+- Runtime decode dispatch does not call this function. Future admission must
+  update this inventory, generated-code evidence, fuzzing, backend reporting,
+  benchmarks, and release notes in the same commit that makes any decode SIMD
+  path reachable.
+
 ### `clear_xmm_registers_after_encode_block`
 
 Location: `src/simd/x86/cleanup.rs`

scripts/check_backend_evidence.sh

@@ -15,7 +15,7 @@ cat "$runtime_output"
 
 echo "backend evidence: SIMD prototype scalar-equivalence tests"
 prototype_status=0
-cargo test --all-features simd::tests:: -- --nocapture >"$prototype_output" 2>&1 || prototype_status="$?"
+cargo test --all-features simd:: -- --nocapture >"$prototype_output" 2>&1 || prototype_status="$?"
 cat "$prototype_output"
 
 {
@@ -36,7 +36,7 @@ cat "$prototype_output"
     echo
     echo "commands:"
     echo "cargo test --test rfc4648 --all-features runtime_backend_report_matches_admission_state -- --nocapture"
-    echo "cargo test --all-features simd::tests:: -- --nocapture"
+    echo "cargo test --all-features simd:: -- --nocapture"
     echo
     echo "status:"
     echo "runtime_backend_report=$runtime_status"
@@ -47,6 +47,7 @@ cat "$prototype_output"
     echo "prototype_avx512_vbmi=admitted-encode-backend"
     echo "prototype_avx2=admitted-encode-backend"
     echo "prototype_ssse3_sse41=admitted-encode-backend"
+    echo "prototype_ssse3_sse41_decode=real-non-dispatchable"
     echo "prototype_neon=admitted-encode-backend-aarch64-standard-family"
     echo "prototype_wasm_simd128=real-non-dispatchable-compile-evidence-only"
     echo "wasm_simd128_evidence=compile-test-binary-only"
@@ -62,6 +63,7 @@ cat "$prototype_output"
     echo
     echo "interpretation:"
     echo "This evidence records runtime backend reporting, admitted AVX-512 VBMI, AVX2, SSSE3/SSE4.1, or NEON encode dispatch when supported, and remaining inactive SIMD prototype scalar-equivalence results for this machine."
+    echo "The SSSE3/SSE4.1 decode prototype is fixed-block, non-dispatchable evidence only; public decode APIs still report scalar execution."
     echo "Wasm results are prototype evidence; they are not active backend admission evidence."
     echo "The admitted x86 AVX-512 VBMI, AVX2, and SSSE3/SSE4.1 paths exercise real fixed-block vector encode logic for Standard and URL-safe alphabets when the required CPU feature bundle is available."
     echo "On AArch64 hosts, the admitted NEON path exercises real fixed-block vector encode logic for Standard and URL-safe alphabets; 32-bit ARM remains scaffold evidence."

scripts/validate-panic-policy.sh

@@ -81,7 +81,7 @@ test -s docs/PANIC_POLICY.md
 
 find src -name '*.rs' | sort | while IFS= read -r source_file; do
     case "$source_file" in
-        src/kani_proofs.rs|src/tests.rs|src/simd/tests.rs|src/simd/wasm.rs)
+        src/kani_proofs.rs|src/tests.rs|src/simd/tests.rs|src/simd/wasm.rs|src/simd/x86_decode_tests.rs)
             continue
             ;;
     esac

src/simd/mod.rs

@@ -43,9 +43,18 @@ pub(crate) use neon::neon_supports_alphabet;
 ))]
 mod x86;
 #[cfg(all(test, any(target_arch = "x86", target_arch = "x86_64")))]
-pub(super) use x86::{encode_12_bytes_ssse3_sse41, encode_24_bytes_avx2, encode_48_bytes_avx512};
+pub(super) use x86::{
+    decode_16_bytes_ssse3_sse41, encode_12_bytes_ssse3_sse41, encode_24_bytes_avx2,
+    encode_48_bytes_avx512,
+};
 #[cfg(all(test, target_arch = "wasm32"))]
 mod wasm;
+#[cfg(all(
+    feature = "std",
+    test,
+    any(target_arch = "x86", target_arch = "x86_64")
+))]
+mod x86_decode_tests;
 
 /// Backend currently allowed to execute.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]

src/simd/x86/mod.rs

@@ -2,6 +2,8 @@
 
 mod cleanup;
 
+#[cfg(test)]
+use crate::DecodeError;
 use crate::{Alphabet, EncodeError, checked_encoded_len, encode_base64_value, scalar};
 
 use cleanup::{
@@ -170,6 +172,8 @@ use core::arch::x86::{
     _mm512_loadu_si512, _mm512_or_si512, _mm512_permutexvar_epi8, _mm512_set1_epi32,
     _mm512_shuffle_epi8, _mm512_slli_epi32, _mm512_srli_epi32, _mm512_storeu_si512,
 };
+#[cfg(all(test, target_arch = "x86"))]
+use core::arch::x86::{_mm_madd_epi16, _mm_maddubs_epi16};
 #[cfg(target_arch = "x86_64")]
 use core::arch::x86_64::{
     __m128i, __m256i, __m512i, _mm_add_epi8, _mm_and_si128, _mm_blendv_epi8, _mm_cmpeq_epi8,
@@ -181,6 +185,8 @@ use core::arch::x86_64::{
     _mm512_loadu_si512, _mm512_or_si512, _mm512_permutexvar_epi8, _mm512_set1_epi32,
     _mm512_shuffle_epi8, _mm512_slli_epi32, _mm512_srli_epi32, _mm512_storeu_si512,
 };
+#[cfg(all(test, target_arch = "x86_64"))]
+use core::arch::x86_64::{_mm_madd_epi16, _mm_maddubs_epi16};
 
 #[expect(
     clippy::cast_ptr_alignment,
@@ -326,6 +332,78 @@ where
     crate::wipe_bytes(&mut staged);
 }
 
+#[expect(
+    clippy::cast_ptr_alignment,
+    reason = "_mm_loadu_si128 and _mm_storeu_si128 accept unaligned pointers"
+)]
+#[cfg(test)]
+#[target_feature(enable = "ssse3,sse4.1")]
+pub(crate) unsafe fn decode_16_bytes_ssse3_sse41<A, const PAD: bool>(
+    input: &[u8; 16],
+    output: &mut [u8; 12],
+) -> Result<usize, DecodeError>
+where
+    A: Alphabet,
+{
+    let mut scalar_output = [0; 12];
+    let written = match scalar::decode_slice::<A, PAD>(input, &mut scalar_output) {
+        Ok(written) => written,
+        Err(error) => {
+            crate::wipe_bytes(&mut scalar_output);
+            return Err(error);
+        }
+    };
+
+    if !is_standard_or_url_safe_family::<A>() {
+        output[..written].copy_from_slice(&scalar_output[..written]);
+        crate::wipe_bytes(&mut scalar_output);
+        return Ok(written);
+    }
+
+    let mut values = [0; 16];
+    fill_decode_values::<A>(input, &mut values);
+    let mut packed = [0; 16];
+
+    // SAFETY: Fixed arrays back the unaligned loads and stores, the
+    // target-feature contract enables SSSE3/SSE4.1, and scalar validation
+    // above proves the 16-byte block is canonical for the selected padding
+    // policy before any bytes are copied to the caller output.
+    unsafe {
+        let values_vec = _mm_loadu_si128(values.as_ptr().cast::<__m128i>());
+        let merged_pairs = _mm_maddubs_epi16(values_vec, _mm_set1_epi32(0x0140_0140));
+        let merged_quads = _mm_madd_epi16(merged_pairs, _mm_set1_epi32(0x0001_1000));
+        let shuffle = _mm_setr_epi8(
+            2, 1, 0, 6, 5, 4, 10, 9, 8, 14, 13, 12, -128, -128, -128, -128,
+        );
+        let decoded = _mm_shuffle_epi8(merged_quads, shuffle);
+        _mm_storeu_si128(packed.as_mut_ptr().cast::<__m128i>(), decoded);
+        clear_xmm_registers_after_encode_block();
+    }
+
+    debug_assert_eq!(&packed[..written], &scalar_output[..written]);
+    output[..written].copy_from_slice(&packed[..written]);
+    crate::wipe_bytes(&mut values);
+    crate::wipe_bytes(&mut packed);
+    crate::wipe_bytes(&mut scalar_output);
+    Ok(written)
+}
+
+#[cfg(test)]
+fn fill_decode_values<A>(input: &[u8; 16], values: &mut [u8; 16])
+where
+    A: Alphabet,
+{
+    let mut index = 0;
+    while index < input.len() {
+        values[index] = if input[index] == b'=' {
+            0
+        } else {
+            A::decode(input[index]).unwrap_or(0)
+        };
+        index += 1;
+    }
+}
+
 fn is_standard_or_url_safe_family<A>() -> bool
 where
     A: Alphabet,

src/simd/x86_decode_tests.rs

@@ -0,0 +1,108 @@
+use super::*;
+use crate::{Alphabet, DecodeError, Engine, Standard, UrlSafe};
+
+fn fill_pattern(output: &mut [u8], seed: usize) {
+    for (index, byte) in output.iter_mut().enumerate() {
+        let value = (index * 73 + seed * 19) % 256;
+        *byte = u8::try_from(value).unwrap();
+    }
+}
+
+#[test]
+fn ssse3_sse41_decode_block_matches_scalar_when_available() {
+    if !ssse3_sse41_available() {
+        println!("skipped: SSSE3/SSE4.1 decode block test requires ssse3 and sse4.1");
+        return;
+    }
+
+    let mut raw = [0; 12];
+    for seed in 0..64 {
+        fill_pattern(&mut raw, seed);
+        assert_ssse3_decode_case::<Standard, true>(&encoded_block::<Standard, true>(&raw));
+        assert_ssse3_decode_case::<UrlSafe, true>(&encoded_block::<UrlSafe, true>(&raw));
+        assert_ssse3_decode_case::<Standard, false>(&encoded_block::<Standard, false>(&raw));
+        assert_ssse3_decode_case::<UrlSafe, false>(&encoded_block::<UrlSafe, false>(&raw));
+    }
+
+    for len in [10, 11] {
+        fill_pattern(&mut raw, len);
+        assert_ssse3_decode_case::<Standard, true>(&encoded_block::<Standard, true>(&raw[..len]));
+        assert_ssse3_decode_case::<UrlSafe, true>(&encoded_block::<UrlSafe, true>(&raw[..len]));
+    }
+
+    assert_ssse3_decode_error_matches_scalar::<Standard, true>(mutated_block(
+        encoded_block::<Standard, true>(&raw),
+        5,
+        b'!',
+    ));
+    assert_ssse3_decode_error_matches_scalar::<Standard, true>(mutated_block(
+        encoded_block::<Standard, true>(&raw),
+        3,
+        b'=',
+    ));
+    assert_ssse3_decode_error_matches_scalar::<UrlSafe, true>(mutated_block(
+        encoded_block::<UrlSafe, true>(&raw),
+        8,
+        b'/',
+    ));
+
+    let non_canonical = *b"AAAAAAAAAAAAAB==";
+    assert_ssse3_decode_error_matches_scalar::<Standard, true>(non_canonical);
+    assert_ssse3_decode_error_matches_scalar::<UrlSafe, true>(non_canonical);
+}
+
+fn encoded_block<A, const PAD: bool>(input: &[u8]) -> [u8; 16]
+where
+    A: Alphabet,
+{
+    let mut encoded = [0; 16];
+    let written = Engine::<A, PAD>::new()
+        .encode_slice(input, &mut encoded)
+        .unwrap();
+    assert_eq!(written, encoded.len());
+    encoded
+}
+
+fn mutated_block(mut input: [u8; 16], index: usize, byte: u8) -> [u8; 16] {
+    input[index] = byte;
+    input
+}
+
+fn assert_ssse3_decode_case<A, const PAD: bool>(input: &[u8; 16])
+where
+    A: Alphabet,
+{
+    let mut ssse3 = [0x55; 12];
+    let mut scalar = [0xaa; 12];
+    // SAFETY: The caller checked SSSE3/SSE4.1 availability before invoking
+    // this helper.
+    let ssse3_len = unsafe { decode_16_bytes_ssse3_sse41::<A, PAD>(input, &mut ssse3) }.unwrap();
+    let scalar_len = Engine::<A, PAD>::new()
+        .decode_slice(input, &mut scalar)
+        .unwrap();
+    assert_eq!(ssse3_len, scalar_len);
+    assert_eq!(&ssse3[..ssse3_len], &scalar[..scalar_len]);
+}
+
+fn assert_ssse3_decode_error_matches_scalar<A, const PAD: bool>(input: [u8; 16])
+where
+    A: Alphabet,
+{
+    let mut ssse3 = [0x55; 12];
+    let mut scalar = [0xaa; 12];
+    // SAFETY: The caller checked SSSE3/SSE4.1 availability before invoking
+    // this helper.
+    let ssse3_error = unsafe { decode_16_bytes_ssse3_sse41::<A, PAD>(&input, &mut ssse3) }
+        .expect_err("malformed block must be rejected by SSSE3/SSE4.1 prototype");
+    let scalar_error = Engine::<A, PAD>::new()
+        .decode_slice(&input, &mut scalar)
+        .expect_err("malformed block must be rejected by scalar decoder");
+    assert_eq!(ssse3_error, scalar_error);
+    assert_eq!(ssse3, [0x55; 12]);
+    assert!(matches!(
+        ssse3_error,
+        DecodeError::InvalidByte { .. }
+            | DecodeError::InvalidPadding { .. }
+            | DecodeError::InvalidLength
+    ));
+}