Admit SSSE3 encode backend

Author: eldryoth

CHANGELOG.md

@@ -2,9 +2,19 @@
 
 ## Unreleased
 
+- Admitted std `x86`/`x86_64` SSSE3/SSE4.1 encode dispatch for Standard and
+  URL-safe alphabet families. The admitted path processes fixed 12-byte blocks
+  with vector code after runtime CPU probing and falls back to scalar for
+  unsupported CPUs, `no_std`, custom alphabets, tails, padding, in-place encode,
+  and every decode path.
+- Updated runtime reporting, backend evidence, SIMD admission validation,
+  unsafe inventory, and user documentation so SSSE3/SSE4.1 encode is reported
+  as an admitted backend while AVX2, AVX-512 VBMI, NEON, wasm `simd128`,
+  custom-alphabet, in-place, and decode acceleration remain prototype-only or
+  scalar.
 - Added a real non-dispatchable AVX-512 VBMI fixed-block encode prototype that
   uses the provided alphabet table for all alphabets. The prototype remains
-  test-only and active runtime backend selection remains scalar-only.
+  test-only and is not reachable from runtime backend selection.
 - Added AVX-512 SIMD equivalence coverage for patterned blocks, all 64 emitted
   six-bit Base64 values, and a non-standard custom alphabet.
 - Added `scripts/generate_simd_asm_evidence.sh` to capture release
@@ -19,12 +29,12 @@
   Standard and URL-safe alphabets. Custom alphabets remain on the scalar
   scaffold path because portable wasm SIMD has no direct 64-byte lookup.
 - Added wasm `simd128` test-binary compile evidence to the SIMD feature-bundle
-  check while keeping wasm cleanup/JIT caveats and scalar-only runtime dispatch.
+  check while keeping wasm cleanup/JIT caveats and scalar runtime dispatch.
 - Hardened SIMD admission tooling and backend evidence manifests to distinguish
   real non-dispatchable prototypes from admitted active backends.
 - Added a draft SIMD encode admission package for future `1.2.0` activation,
   including runtime-report expectations, benchmark record shape, and release
-  note wording rules while keeping `1.1.x` scalar-only.
+  note wording rules for the remaining encode backends.
 - Added `scripts/validate-simd-encode-admission-draft.sh` and wired it into the
   standard checks so the future encode-dispatch admission contract remains
   packaged and machine-checked.
@@ -37,17 +47,16 @@
 - Inlined the test-only AArch64 NEON register cleanup macro into the prototype
   path so callee-saved `v8..v15` are not restored by a separate helper frame.
 - Added a real non-dispatchable AVX2 fixed-block encode prototype for Standard
-  and URL-safe alphabets. The prototype remains test-only and active runtime
-  backend selection remains scalar-only.
+  and URL-safe alphabets. The prototype remains test-only and is not reachable
+  from runtime backend selection.
 - Added AVX2 SIMD equivalence coverage for patterned blocks, all 64 emitted
   six-bit Base64 values, and custom alphabets that must fall back to scalar
   encoding.
 - Updated the SIMD unsafe inventory for the AVX-512, AVX2, and AArch64 NEON
   prototypes, including staged stack-copy wiping and vector-register cleanup.
 - Refreshed the SIMD roadmap, admission manifest, and backend evidence output
   so `1.1.x` checkpoint tags consistently describe the current state as real
-  non-dispatchable prototype evidence while active runtime dispatch remains
-  scalar-only until a future `1.2.0` admission package.
+  non-dispatchable prototype evidence for backends that are not yet admitted.
 - Hardened the workspace publish helper so real crates.io publishing requires
   `HEAD` to match a verified signed `v<version>` tag, and documented the
   `git tag -v` release check.
@@ -63,8 +72,7 @@
   `1.1.12` checkpoints leading to that release.
 - Added a scalar-forced encode backend boundary and routed public slice,
   clear-tail, wrapped, alloc, and in-place encode paths through it, giving
-  future SIMD encode admission one audited integration point while preserving
-  scalar-only runtime behavior.
+  future SIMD encode admission one audited integration point.
 - Added the matching scalar-forced decode backend boundary for future decode
   admission symmetry, changed the scalar in-place encode invariant to return an
   error instead of panicking in release builds, tightened panic-policy scanning

README.md

@@ -31,9 +31,9 @@ The crate starts conservative: a small scalar implementation, strict RFC 4648 be
 
 The current public release is `1.1.0`.
 Post-`1.1.0` GitHub checkpoint tags in the `1.1.x` line are evidence and
-integration milestones toward `1.2.0`; they keep active runtime dispatch
-scalar-only and are not intended as crates.io publishes unless a user-impacting
-fix requires it.
+integration milestones toward `1.2.0`; they may admit narrowly scoped encode
+backends after evidence review and are not intended as crates.io publishes
+unless a user-impacting fix requires it.
 
 Implemented now:
 
@@ -71,8 +71,10 @@ Implemented now:
 - Bounded Kani proof harnesses that run on Rust `1.90.0` with
   `cargo-kani 0.67.0`.
 - Constant-time assembly evidence generation for reviewer inspection.
-- Real non-dispatchable SSSE3/SSE4.1 fixed-block encode prototype for Standard
-  and URL-safe alphabets behind the SIMD admission boundary.
+- Runtime-dispatched std `x86`/`x86_64` SSSE3/SSE4.1 fixed-block encode for
+  Standard and URL-safe alphabets behind the SIMD admission boundary, with
+  scalar fallback for unsupported CPUs, `no_std`, custom alphabets, tails,
+  padding, in-place encode, and decode.
 - Optional `base64-ng-sanitization` companion crate for applications that
   already admit `sanitization` and want direct CT decode helpers into
   clear-on-drop secret containers.
@@ -85,9 +87,9 @@ Implemented now:
 
 Planned behind admission evidence:
 
-- Admitted AVX2, AVX-512, SSSE3/SSE4.1, ARM NEON, and wasm `simd128`
-  fast paths after the SIMD admission evidence is complete. The `1.1.0`
-  release remains scalar-only for active runtime dispatch.
+- Additional admitted AVX2, AVX-512, ARM NEON, wasm `simd128`, custom alphabet,
+  in-place, and decode fast paths after the SIMD admission evidence is
+  complete. Default builds and unsupported runtime CPUs remain scalar.
 - Full async streaming wrappers only after the `tokio` feature passes the
   cancellation-safety admission bar in [docs/ASYNC.md](docs/ASYNC.md). The
   `base64-ng-tokio` companion crate currently provides bounded async
@@ -104,8 +106,8 @@ Planned behind admission evidence:
 | License | `MIT OR Apache-2.0` |
 | MSRV | Rust `1.90.0` |
 | Runtime dependencies | Zero external crates |
-| Unsafe policy | Scalar encode/decode remains safe Rust; audited unsafe is limited to volatile wiping, CT comparison/barrier helpers, and test-only SIMD prototypes |
-| Active backend | Scalar only |
+| Unsafe policy | Scalar encode/decode remains safe Rust; audited unsafe is limited to volatile wiping, CT comparison/barrier helpers, and the reviewed SIMD boundary |
+| Active backend | Scalar by default; std x86/x86_64 SSSE3/SSE4.1 encode when `simd` is enabled and runtime CPU probing passes |
 | Strict decoding | Default, canonical, no whitespace |
 | Legacy compatibility | Explicit opt-in APIs |
 | Constant-time posture | Constant-time-oriented scalar validation/decode with isolated dudect-style timing evidence; no formal cryptographic guarantee |
@@ -947,7 +949,9 @@ Security commitments:
   dead-store elimination and are ordered before the cleanup boundary on
   supported native architectures. Constant-time comparison, byte accumulation,
   CT scan, and CT result-gate hardening remain audited in `src/ct/`.
-- Future unsafe SIMD remains isolated under `src/simd/`.
+- Unsafe SIMD remains isolated under `src/simd/`; the admitted SSSE3/SSE4.1
+  encode path is std runtime-probed and all non-admitted backends remain
+  prototype-only.
 - Local checks verify that `allow(unsafe_code)` is confined to the volatile
   wipe helpers and SIMD boundary, every unsafe function is inventoried, and
   every unsafe block has a nearby `SAFETY:` explanation. Architecture intrinsics,
@@ -959,9 +963,11 @@ Security commitments:
   async/Tokio API while the `tokio` feature remains inert.
 - [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md) defines the dependency
   admission bar for any future external crate.
-- `runtime::backend_report()` exposes the active backend, detected candidate,
-  candidate detection mode, SIMD feature status, scalar-only security posture,
-  and a conservative unsafe-boundary posture flag for audit logging. The
+- `runtime::backend_report()` exposes the active admitted backend, detected
+  candidate, candidate detection mode, SIMD feature status, security posture,
+  and a conservative unsafe-boundary posture flag for audit logging. In the
+  `1.1.x` line, non-scalar active values describe admitted encode dispatch;
+  decode remains scalar. The
   unsafe-boundary flag is true only when the reserved `simd` feature is
   disabled; SIMD-enabled builds must rely on the release evidence scripts for
   boundary validation. On `no_std` and non-x86 targets, candidate detection is

docs/PLAN.md

@@ -674,14 +674,15 @@ Current `1.1.x` checkpoint state:
   Follow-up review also added the matching scalar-forced decode backend
   boundary so future decode acceleration has a symmetric admission point, and
   tightened panic-policy checks for production `assert_eq!`/`assert_ne!` sites.
+- `1.1.6`: admitted std-only x86/x86_64 SSSE3/SSE4.1 encode dispatch for
+  Standard and URL-safe alphabet families. The active path uses runtime CPU
+  probing, fixed 12-byte vector blocks, XMM cleanup, and scalar fallback for
+  unsupported CPUs, `no_std`, custom alphabets, tails, padding, in-place encode,
+  and decode. Runtime reports and admission evidence now identify
+  SSSE3/SSE4.1 encode as the admitted backend.
 
 Planned checkpoints to reach `1.2.0` fully working encode acceleration:
 
-- `1.1.6`: admit std-only x86/x86_64 SSSE3/SSE4.1 encode dispatch for Standard
-  and URL-safe alphabets if scalar parity, fallback, generated assembly,
-  unsafe inventory, and runtime-report evidence are complete. Unsupported CPUs,
-  custom alphabets, tails, wrapping, legacy profiles, and `no_std` builds must
-  remain scalar.
 - `1.1.7`: admit std-only x86/x86_64 AVX2 encode dispatch with the same public
   API coverage and fallback requirements. Runtime priority must be explicit
   and tested, for example AVX2 above SSSE3/SSE4.1 when both are available.

docs/RELEASE_EVIDENCE.md

@@ -113,11 +113,13 @@ The release gate runs:
 - reserved SIMD feature-bundle compile checks for AVX2, AVX-512 VBMI,
   SSSE3/SSE4.1, NEON, and wasm `simd128` under `no_std` when the corresponding
   Rust targets are installed
-- backend evidence capture for runtime backend reporting and inactive SIMD
-  prototype scalar-equivalence output
-- scalar-only SIMD admission policy for the current release series, with no
-  active accelerated dispatch and no SIMD performance claims unless a complete
-  backend admission evidence package lands
+- backend evidence capture for runtime backend reporting, admitted SSSE3/SSE4.1
+  encode dispatch when supported, and inactive SIMD prototype scalar-equivalence
+  output for remaining candidates
+- SIMD admission policy for the current release series, with SSSE3/SSE4.1
+  encode admitted only for std x86/x86_64 Standard and URL-safe alphabets, no
+  decode acceleration, and no SIMD performance claims without complete local
+  benchmark evidence
 - unsafe-boundary validation that confines `allow(unsafe_code)` to the audited
   cleanup helpers in `src/cleanup.rs`, CT barrier/comparison helpers in
   `src/ct/`, and the SIMD boundary in `src/simd/`
@@ -274,25 +276,25 @@ Capture local runtime backend and prototype evidence with:
 scripts/check_backend_evidence.sh
 ```
 
-The script runs the runtime backend-report test and the gated SIMD prototype
-scalar-equivalence scaffolding tests with `--nocapture`. The runtime report
-records `candidate_detection_mode`, which distinguishes x86/x86_64 `std`
-runtime CPU probing from compile-time target-feature reporting used by
-`no_std` and other compile-time-only targets. 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
-x86 prototypes exercise real fixed-block vector encode logic when the required
-CPU feature bundles are available. On AArch64 NEON-capable hosts, the NEON test
-exercises the inactive fixed-block vector prototype for Standard and URL-safe
-alphabets; 32-bit ARM remains scaffold evidence. Wasm `simd128` evidence is
-kept in `scripts/check_simd_feature_bundles.sh` as compile/test-binary evidence
-only because runtime JIT behavior is outside the crate's release gate. The
+The script runs the runtime backend-report test and the gated SIMD
+scalar-equivalence tests with `--nocapture`. The runtime report records
+`candidate_detection_mode`, which distinguishes x86/x86_64 `std` runtime CPU
+probing from compile-time target-feature reporting used by `no_std` and other
+compile-time-only targets. On CPUs with SSSE3/SSE4.1, the admitted encode path
+may be active for Standard and URL-safe alphabets. AVX2 and AVX-512 tests still
+execute inactive prototype bodies and compare them against scalar output. On
+AArch64 NEON-capable hosts, the NEON test exercises the inactive fixed-block
+vector prototype for Standard and URL-safe alphabets; 32-bit ARM remains
+scaffold evidence. Wasm `simd128` evidence is kept in
+`scripts/check_simd_feature_bundles.sh` as compile/test-binary evidence only
+because runtime JIT behavior is outside the crate's release gate. The
 script writes
 `target/release-evidence/backend/MANIFEST.txt`, `runtime-backend-report.txt`,
 and `simd-prototype-equivalence.txt` so local CPU evidence can be archived. The
-manifest labels prototype evidence as `real-non-dispatchable` and separately
-records `active_backend_admitted=false`, so audit logs do not confuse fixed
-block prototype execution with active dispatch admission.
+manifest labels prototype-only evidence as `real-non-dispatchable` and
+separately records `active_backend_admitted=ssse3-sse4.1-encode`, so audit logs
+do not confuse remaining fixed-block prototype execution with active dispatch
+admission.
 
 The release gate also runs:
 
@@ -301,10 +303,10 @@ scripts/validate-simd-admission.sh
 scripts/validate-simd-encode-admission-draft.sh
 ```
 
-That validator keeps active SIMD dispatch scalar-only until the release includes
-the required scalar differential tests, fuzz evidence, unsafe inventory updates,
-architecture evidence, benchmark evidence, release-note wording, and an updated
-`docs/SIMD_ADMISSION.md` manifest.
+That validator keeps active SIMD dispatch limited to admitted backends until a
+release includes the required scalar differential tests, fuzz evidence, unsafe
+inventory updates, architecture evidence, benchmark evidence, release-note
+wording, and an updated `docs/SIMD_ADMISSION.md` manifest.
 
 For a future encode-dispatch release, use
 [`SIMD_ENCODE_ADMISSION_DRAFT.md`](SIMD_ENCODE_ADMISSION_DRAFT.md) as the
@@ -367,20 +369,19 @@ review focus, and artifact checksums. The LTO artifact exists so reviewers can
 check that cleanup primitives such as `wipe_bytes` and `wipe_barrier` remain
 visible call boundaries under aggressive optimization.
 
-Capture generated assembly evidence for the inactive x86 SIMD encode
-prototypes with:
+Capture generated assembly evidence for x86 SIMD encode paths with:
 
 ```sh
 scripts/generate_simd_asm_evidence.sh
 ```
 
 On x86/x86_64 hosts, the script emits release test-harness assembly for the
-SSSE3/SSE4.1, AVX2, and AVX-512 VBMI feature bundles and checks for the
-expected byte-shuffle, byte-permute, vector-register, and cleanup instructions.
-On non-x86 hosts it records a skip manifest. The generated files are written to
-`target/release-evidence/simd-asm/` and are inactive prototype evidence only;
-runtime dispatch remains scalar-only until the SIMD admission manifest is
-updated in a future release.
+admitted SSSE3/SSE4.1 encode path and the AVX2 and AVX-512 VBMI prototype
+feature bundles, then checks for the expected byte-shuffle, byte-permute,
+vector-register, and cleanup instructions. On non-x86 hosts it records a skip
+manifest. The generated files are written to
+`target/release-evidence/simd-asm/`. AVX2 and AVX-512 remain inactive prototype
+evidence until the SIMD admission manifest names them as admitted backends.
 
 ## Performance Evidence