Add SSSE3 SSE4.1 encode prototype

Author: eldryoth

CHANGELOG.md

@@ -9,6 +9,8 @@
   feature-bundle compile check while keeping scalar as the only active backend.
 - Added SSSE3/SSE4.1 candidate reporting and reserved feature-bundle compile
   evidence for older x86 CPUs before any active SIMD admission.
+- Added an inactive SSSE3/SSE4.1 fixed-block encode prototype with
+  scalar-equivalence tests while keeping runtime dispatch scalar-only.
 - Added reserved SIMD feature-bundle compile checks to the normal local
   `scripts/checks.sh` gate so day-to-day checks match release expectations.
 

docs/PLAN.md

@@ -354,6 +354,8 @@ the zero-runtime-dependency stance.
   checks while keeping scalar as the only active backend.
 - Add SSSE3/SSE4.1 candidate reporting and reserved feature-bundle compile
   checks for older x86 CPUs before active SIMD admission.
+- Add an inactive SSSE3/SSE4.1 fixed-block encode prototype with scalar
+  equivalence tests before any runtime admission.
 - Replace inactive SIMD encode prototypes with real AVX2, AVX-512, NEON,
   SSSE3/SSE4.1, and wasm `simd128` candidate implementations only when scalar
   differential tests, fuzz evidence, target-feature checks, unsafe inventory

docs/RELEASE_EVIDENCE.md

@@ -155,9 +155,9 @@ scripts/check_backend_evidence.sh
 ```
 
 The script runs the runtime backend-report test and the gated SIMD prototype
-scalar-equivalence tests with `--nocapture`. On CPUs with AVX2 or the AVX-512
-candidate bundle, those prototype tests execute the inactive prototype body and
-compare it against scalar output.
+scalar-equivalence tests with `--nocapture`. On CPUs with SSSE3/SSE4.1, AVX2,
+or the AVX-512 candidate bundle, those prototype tests execute the inactive
+prototype body and compare it against scalar output.
 
 The release gate also runs:
 

docs/SIMD.md

@@ -39,6 +39,9 @@ weakening the scalar trust base.
   without parsing formatted strings.
 - SSSE3/SSE4.1 detection is reporting-only until an implementation has scalar
   differential tests, fuzz coverage, and benchmark evidence.
+- An inactive SSSE3/SSE4.1 fixed-block encode prototype exists behind the SIMD
+  boundary and is tested against scalar output only when SSSE3/SSE4.1 is
+  available.
 - An inactive AVX2 fixed-block encode prototype exists behind the SIMD boundary
   and is tested against scalar output only when AVX2 is available.
 - An inactive NEON fixed-block encode prototype exists behind the same boundary

docs/UNSAFE.md

@@ -122,6 +122,38 @@ Safety argument:
 - The function is guarded by an AVX2 target-feature contract.
 - The prototype then overwrites the block with scalar-equivalent Base64 output.
 
+### `encode_12_bytes_ssse3_sse41`
+
+Location: `src/simd.rs`
+
+Status: inactive prototype, not dispatchable.
+
+Purpose:
+
+- Exercise lower-tier x86 target-feature plumbing.
+- Validate the unsafe boundary.
+- Provide scalar-equivalence test coverage before any real vector path is
+  admitted.
+
+Preconditions:
+
+- Caller must prove SSSE3 and SSE4.1 are available on the current CPU.
+- Input is exactly 12 bytes.
+- Output is exactly 16 bytes.
+
+Unsafe operation:
+
+- `_mm_storeu_si128` stores one 128-bit zero vector into the output buffer.
+
+Safety argument:
+
+- The output type is `&mut [u8; 16]`, so the store has enough initialized,
+  writable memory.
+- The intrinsic is the unaligned store variant, so no stronger alignment is
+  required.
+- The function is guarded by an SSSE3/SSE4.1 target-feature contract.
+- The prototype then overwrites the block with scalar-equivalent Base64 output.
+
 ### `encode_12_bytes_neon`
 
 Location: `src/simd.rs`

src/simd.rs

@@ -24,13 +24,13 @@ use core::arch::aarch64::{uint8x16_t, vdupq_n_u8, vst1q_u8};
 use core::arch::arm::{uint8x16_t, vdupq_n_u8, vst1q_u8};
 #[cfg(target_arch = "x86")]
 use core::arch::x86::{
-    __m256i, __m512i, _mm256_setzero_si256, _mm256_storeu_si256, _mm512_setzero_si512,
-    _mm512_storeu_si512,
+    __m128i, __m256i, __m512i, _mm_setzero_si128, _mm_storeu_si128, _mm256_setzero_si256,
+    _mm256_storeu_si256, _mm512_setzero_si512, _mm512_storeu_si512,
 };
 #[cfg(target_arch = "x86_64")]
 use core::arch::x86_64::{
-    __m256i, __m512i, _mm256_setzero_si256, _mm256_storeu_si256, _mm512_setzero_si512,
-    _mm512_storeu_si512,
+    __m128i, __m256i, __m512i, _mm_setzero_si128, _mm_storeu_si128, _mm256_setzero_si256,
+    _mm256_storeu_si256, _mm512_setzero_si512, _mm512_storeu_si512,
 };
 
 /// Backend currently allowed to execute.
@@ -249,6 +249,54 @@ where
     }
 }
 
+/// Encodes one 12-byte block into 16 bytes through the inactive SSSE3/SSE4.1 prototype.
+///
+/// This is not an admitted fast path. It exists to exercise lower-tier x86
+/// target-feature plumbing, unsafe isolation, and scalar equivalence before a
+/// real vector encoder is allowed to participate in dispatch.
+///
+/// # Safety
+///
+/// The caller must execute this function only when SSSE3 and SSE4.1 are
+/// available on the current CPU. The input and output sizes are fixed by their
+/// array types.
+#[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
+#[allow(dead_code, reason = "inactive prototype is not dispatchable yet")]
+#[expect(
+    clippy::cast_ptr_alignment,
+    reason = "_mm_storeu_si128 accepts unaligned pointers"
+)]
+#[target_feature(enable = "ssse3,sse4.1")]
+pub(super) unsafe fn encode_12_bytes_ssse3_sse41<A>(input: &[u8; 12], output: &mut [u8; 16])
+where
+    A: Alphabet,
+{
+    let zeros = _mm_setzero_si128();
+    // SAFETY: `output` is a valid 16-byte mutable array. SSSE3/SSE4.1
+    // availability is guaranteed by this function's target-feature
+    // precondition, and the unaligned store does not require stronger pointer
+    // alignment.
+    unsafe {
+        _mm_storeu_si128(output.as_mut_ptr().cast::<__m128i>(), zeros);
+    }
+
+    let mut read = 0;
+    let mut write = 0;
+    while read < input.len() {
+        let b0 = input[read];
+        let b1 = input[read + 1];
+        let b2 = input[read + 2];
+
+        output[write] = encode_base64_value::<A>(b0 >> 2);
+        output[write + 1] = encode_base64_value::<A>(((b0 & 0b0000_0011) << 4) | (b1 >> 4));
+        output[write + 2] = encode_base64_value::<A>(((b1 & 0b0000_1111) << 2) | (b2 >> 6));
+        output[write + 3] = encode_base64_value::<A>(b2 & 0b0011_1111);
+
+        read += 3;
+        write += 4;
+    }
+}
+
 /// Encodes one 12-byte block into 16 bytes through the inactive NEON prototype.
 ///
 /// This is not an admitted fast path. It exists to exercise ARM intrinsic
@@ -386,6 +434,46 @@ mod tests {
         }
     }
 
+    #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
+    #[test]
+    fn ssse3_sse41_encode_prototype_matches_scalar_when_available() {
+        if !ssse3_sse41_available() {
+            return;
+        }
+
+        let mut input = [0; 12];
+        for seed in 0..64 {
+            fill_pattern(&mut input, seed);
+
+            let mut ssse3_standard = [0x55; 16];
+            let mut scalar_standard = [0xaa; 16];
+            // SAFETY: The feature check above uses runtime SSSE3/SSE4.1
+            // detection on std builds and compile-time target-feature
+            // detection otherwise.
+            unsafe {
+                encode_12_bytes_ssse3_sse41::<Standard>(&input, &mut ssse3_standard);
+            }
+            let scalar_len = Engine::<Standard, true>::new()
+                .encode_slice(&input, &mut scalar_standard)
+                .unwrap();
+            assert_eq!(scalar_len, ssse3_standard.len());
+            assert_eq!(ssse3_standard, scalar_standard);
+
+            let mut ssse3_url_safe = [0x55; 16];
+            let mut scalar_url_safe = [0xaa; 16];
+            // SAFETY: The feature check above proves SSSE3/SSE4.1
+            // availability for this test invocation.
+            unsafe {
+                encode_12_bytes_ssse3_sse41::<UrlSafe>(&input, &mut ssse3_url_safe);
+            }
+            let scalar_len = Engine::<UrlSafe, true>::new()
+                .encode_slice(&input, &mut scalar_url_safe)
+                .unwrap();
+            assert_eq!(scalar_len, ssse3_url_safe.len());
+            assert_eq!(ssse3_url_safe, scalar_url_safe);
+        }
+    }
+
     #[cfg(any(
         target_arch = "aarch64",
         all(target_arch = "arm", target_feature = "neon")