Admit AVX-512 strict decode dispatch

Author: eldryoth

README.md

@@ -84,12 +84,12 @@ Implemented now:
   encode helpers can use admitted fixed-block encode for their unwrapped
   encoding step; unsupported CPUs, `no_std`, custom alphabets, tails, padding,
   in-place encode, and line-ending insertion stay scalar.
-- Runtime-dispatched std `x86`/`x86_64` AVX2 fixed-block strict decode,
-  falling back to SSSE3/SSE4.1 and then scalar, in the `1.3.0` working line,
-  limited to Standard and URL-safe alphabets after whole-input scalar
-  validation. Unsupported CPUs, `no_std`, custom alphabets, short inputs,
-  tails, wrapped decode, legacy decode, in-place decode, and CT secret decode
-  stay scalar.
+- Runtime-dispatched std `x86`/`x86_64` AVX-512 VBMI fixed-block strict
+  decode, falling back to AVX2, then SSSE3/SSE4.1, and then scalar, in the
+  `1.3.0` working line, limited to Standard and URL-safe alphabets after
+  whole-input scalar validation. Unsupported CPUs, `no_std`, custom alphabets,
+  short inputs, tails, wrapped decode, legacy decode, in-place decode, and CT
+  secret decode stay scalar.
 - Optional `base64-ng-sanitization` companion crate for applications that
   already admit `sanitization` and want direct CT decode helpers into
   clear-on-drop secret containers.
@@ -102,13 +102,13 @@ Implemented now:
 
 Planned behind admission evidence:
 
-- Additional SIMD decode acceleration beyond AVX2 and SSSE3/SSE4.1 strict
-  Standard and URL-safe decode only after separate `1.3.0` admission evidence
-  is complete. The frozen first scope remains padded and unpadded strict
-  decode only: no line wrapping, no legacy whitespace, no custom alphabets, no
-  bcrypt/crypt profiles, and no constant-time-oriented secret decode. Default
-  builds, unsupported runtime CPUs, `no_std`, and all out-of-scope decode
-  surfaces remain scalar.
+- Additional SIMD decode acceleration beyond AVX-512 VBMI, AVX2, and
+  SSSE3/SSE4.1 strict Standard and URL-safe decode only after separate
+  `1.3.0` admission evidence is complete. The frozen first scope remains
+  padded and unpadded strict decode only: no line wrapping, no legacy
+  whitespace, no custom alphabets, no bcrypt/crypt profiles, and no
+  constant-time-oriented secret decode. Default builds, unsupported runtime
+  CPUs, `no_std`, and all out-of-scope decode surfaces remain scalar.
 - Additional admitted wasm `simd128`, custom alphabet, and in-place encode
   fast paths only after separate SIMD admission evidence is complete. Default
   builds and unsupported runtime CPUs remain scalar.

docs/RELEASE_EVIDENCE.md

@@ -124,9 +124,10 @@ The release gate runs:
   prototypes
 - 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, AVX2 and SSSE3/SSE4.1 strict decode
-  admitted only for std x86/x86_64 Standard and URL-safe alphabets, and no
-  SIMD performance claims without complete local benchmark evidence
+  aarch64 Standard and URL-safe alphabets, AVX-512 VBMI, AVX2, and
+  SSSE3/SSE4.1 strict decode admitted only for std x86/x86_64 Standard and
+  URL-safe alphabets, 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/`

docs/SECURITY_CONTROLS.md

@@ -271,11 +271,12 @@ buffering unbounded frames. For secrets, collect one complete protocol frame
 under an application size limit and decode it with `ct::CtEngine`.
 Normal SIMD decode admission is not a secret-decoding claim. The `1.3.0`
 decode acceleration scope is limited to strict Standard and URL-safe
-interoperability decode. The admitted decode backends are std x86/x86_64 AVX2
-for full 32-byte encoded blocks and SSSE3/SSE4.1 for full 16-byte encoded
-blocks after scalar whole-input validation; every other decode backend and the
-`base64_ng::ct` constant-time-oriented decode path remain scalar unless a
-separate formal side-channel evidence package admits otherwise.
+interoperability decode. The admitted decode backends are std x86/x86_64
+AVX-512 VBMI for full 64-byte encoded blocks, AVX2 for full 32-byte encoded
+blocks, and SSSE3/SSE4.1 for full 16-byte encoded blocks after scalar
+whole-input validation; every other decode backend and the `base64_ng::ct`
+constant-time-oriented decode path remain scalar unless a separate formal
+side-channel evidence package admits otherwise.
 Deployments that require the most conservative side-channel posture should
 combine `base64_ng::ct` with
 `runtime::BackendPolicy::HighAssuranceScalarOnly` so sensitive decode paths

docs/SIMD.md

@@ -73,12 +73,13 @@ The SIMD roadmap separates implementation evidence from active acceleration:
 - `1.3.0` is the first release that may activate SIMD decode acceleration if
   the `1.2.x` decode evidence line is complete and the encode acceleration line
   has remained stable.
-- The admitted `1.3.0` decode backends are std `x86`/`x86_64` AVX2 first,
-  then SSSE3/SSE4.1 strict decode for Standard and URL-safe alphabet families.
-  They validate the complete input with the scalar decoder first so public
-  error shape and indexes remain scalar-compatible, then use fixed 32-byte
-  AVX2 or fixed 16-byte SSSE3/SSE4.1 encoded blocks where possible. Tails and
-  every unsupported decode surface remain scalar.
+- The admitted `1.3.0` decode backends are std `x86`/`x86_64` AVX-512 VBMI
+  first, then AVX2, then SSSE3/SSE4.1 strict decode for Standard and URL-safe
+  alphabet families. They validate the complete input with the scalar decoder
+  first so public error shape and indexes remain scalar-compatible, then use
+  fixed 64-byte AVX-512 VBMI, fixed 32-byte AVX2, or fixed 16-byte
+  SSSE3/SSE4.1 encoded blocks where possible. Tails and every unsupported
+  decode surface remain scalar.
 
 The `1.3.0` decode scope is frozen before implementation starts: strict
 Standard and URL-safe decode only, padded and unpadded, through the normal
@@ -108,8 +109,9 @@ runtime behavior for that line.
 - The scalar implementation is the reference behavior.
 - Encode and normal strict decode entry points pass through internal backend
   boundaries. In-place encode remains scalar-only. Strict decode may use the
-  admitted AVX2 or SSSE3/SSE4.1 backend on std x86/x86_64 builds with the
-  `simd` feature; every unsupported decode surface still falls back to scalar.
+  admitted AVX-512 VBMI, AVX2, or SSSE3/SSE4.1 backend on std x86/x86_64
+  builds with the `simd` feature; every unsupported decode surface still falls
+  back to scalar.
 - With the `simd` feature enabled, the private dispatch scaffold detects
   AVX-512 VBMI, AVX2, SSSE3/SSE4.1, NEON, and wasm `simd128` candidates.
   Only std `x86`/`x86_64` AVX-512 VBMI, AVX2, SSSE3/SSE4.1, and std
@@ -123,11 +125,11 @@ runtime behavior for that line.
   admitted encode boundary. For wrapped encode, SIMD applies only to the
   unwrapped Base64 staging step; line-ending insertion remains scalar.
 - Public strict `decode_slice`, `decode_slice_clear_tail`, `decode_buffer`, and
-  alloc strict decode helpers route through the decode boundary. AVX2 decode
-  applies only to full 32-byte encoded blocks after scalar whole-input
-  validation and falls back to SSSE3/SSE4.1 or scalar for shorter inputs.
-  Legacy decode, wrapped decode, in-place decode, CT secret decode, custom
-  alphabets, short inputs, and tails remain scalar.
+  alloc strict decode helpers route through the decode boundary. AVX-512 VBMI
+  decode applies only to full 64-byte encoded blocks after scalar whole-input
+  validation and falls back to AVX2, SSSE3/SSE4.1, or scalar for shorter
+  inputs. Legacy decode, wrapped decode, in-place decode, CT secret decode,
+  custom alphabets, short inputs, and tails remain scalar.
 - AVX-512 VBMI encode is admitted for std `x86`/`x86_64` Standard and URL-safe
   alphabet families. It uses AVX-512 lane-local byte shuffling, vector
   shifts/masks, and VBMI byte permutes over the alphabet table for fixed
@@ -136,7 +138,7 @@ runtime behavior for that line.
   `avx512bw`, `avx512vl`, and `avx512vbmi`; unsupported CPUs fall back to
   AVX2, SSSE3/SSE4.1, or scalar. Custom alphabets, tails, padding, `no_std`,
   in-place encode, line-ending insertion, and every decode surface outside the
-  separate AVX2/SSSE3/SSE4.1 strict decode admission stay scalar.
+  separate AVX-512/AVX2/SSSE3/SSE4.1 strict decode admission stay scalar.
 - Runtime backend identifiers expose their required CPU feature bundles through
   `runtime::Backend::required_cpu_features()`.
 - Runtime backend reports include `candidate_required_cpu_features=[...]` in
@@ -152,23 +154,23 @@ runtime behavior for that line.
   clears XMM registers before returning. Runtime dispatch uses
   `std::is_x86_feature_detected!`; unsupported CPUs execute scalar code.
   Custom alphabets, tails, padding, `no_std`, in-place encode, line-ending
-  insertion, and every decode surface outside the separate AVX2/SSSE3/SSE4.1
-  strict decode admission stay scalar.
+  insertion, and every decode surface outside the separate
+  AVX-512/AVX2/SSSE3/SSE4.1 strict decode admission stay scalar.
 - AVX2 encode is admitted for std `x86`/`x86_64` Standard and URL-safe alphabet
   families. It uses AVX2 lane-local byte shuffling, vector shifts/masks, and
   byte blending for fixed 24-byte input blocks, then clears XMM/YMM state
   before returning. Runtime dispatch uses `std::is_x86_feature_detected!`;
   unsupported CPUs fall back to SSSE3/SSE4.1 or scalar. Custom alphabets, tails,
   padding, `no_std`, in-place encode, line-ending insertion, and every decode
-  surface outside the separate AVX2/SSSE3/SSE4.1 strict decode admission stay
-  scalar.
+  surface outside the separate AVX-512/AVX2/SSSE3/SSE4.1 strict decode
+  admission stay scalar.
 - AArch64 NEON encode is admitted for std `aarch64` Standard and URL-safe
   alphabet families. It uses NEON table lookup, vector shifts/masks, and
   byte-select alphabet mapping for fixed 12-byte input blocks, then clears used
   NEON registers before returning. NEON is mandatory for the admitted AArch64
   target. Custom alphabets, tails, padding, 32-bit `arm+neon`, `no_std`,
   in-place encode, line-ending insertion, and every decode surface outside the
-  separate AVX2/SSSE3/SSE4.1 strict decode admission stay scalar.
+  separate AVX-512/AVX2/SSSE3/SSE4.1 strict decode admission stay scalar.
 - An inactive wasm `simd128` fixed-block encode prototype exists behind the
   same boundary as real non-dispatchable vector encode evidence for Standard
   and URL-safe alphabets. It uses wasm byte shuffling, vector shifts/masks, and
@@ -277,7 +279,7 @@ fixed-block decode prototypes, and
 `active_backend_admitted=avx512-vbmi-or-avx2-or-ssse3-sse4.1-or-neon-encode`
 for admitted encode backends. The runtime report also exposes
 `BackendReport::active_decode_backend()` so release evidence can distinguish
-the narrower AVX2/SSSE3/SSE4.1 strict decode admission from the active encode
+the narrower AVX-512/AVX2/SSSE3/SSE4.1 strict decode admission from the active encode
 backend.
 
 Capture generated assembly evidence for x86 encode paths:
@@ -354,8 +356,8 @@ remain pending.
 - The active non-scalar backends in the `1.2.x` encode line are std
   x86/x86_64 AVX-512 VBMI encode, AVX2 encode, SSSE3/SSE4.1 encode, and std
   aarch64 NEON encode for Standard and URL-safe alphabet families. The
-  `1.3.0` decode admission is separate: std x86/x86_64 AVX2 first, then
-  SSSE3/SSE4.1 strict decode only.
+  `1.3.0` decode admission is separate: std x86/x86_64 AVX-512 VBMI first,
+  then AVX2, then SSSE3/SSE4.1 strict decode only.
 - Prototype functions may exercise target-feature and unsafe plumbing without
   being eligible for dispatch.
 - Runtime CPU detection may be used only behind `std`.

docs/SIMD_ADMISSION.md

@@ -7,25 +7,27 @@ only for backends named in this file and the release gate.
 ## Current Admission State
 
 - Admitted backends: AVX-512 VBMI encode, AVX2 encode, SSSE3/SSE4.1 encode,
-  NEON encode, AVX2 strict decode, and SSSE3/SSE4.1 strict decode for std
-  `x86`/`x86_64` or std `aarch64` where applicable.
+  NEON encode, AVX-512 VBMI strict decode, AVX2 strict decode, and
+  SSSE3/SSE4.1 strict decode for std `x86`/`x86_64` or std `aarch64` where
+  applicable.
 - Active backend priority: AVX-512 VBMI, then AVX2, then SSSE3/SSE4.1 on
   x86/x86_64; NEON on aarch64; scalar otherwise.
 - Runtime activation scope: std x86/x86_64 and std aarch64 dispatch only.
-- Gate summary: Admitted backends: AVX-512 VBMI encode, AVX2 encode, SSSE3/SSE4.1 encode, NEON encode, AVX2 strict decode, and SSSE3/SSE4.1 strict decode.
+- Gate summary: Admitted backends: AVX-512 VBMI encode, AVX2 encode, SSSE3/SSE4.1 encode, NEON encode, AVX-512 VBMI strict decode, AVX2 strict decode, and SSSE3/SSE4.1 strict decode.
 - Gate priority: Active backend priority: AVX-512 VBMI, then AVX2, then SSSE3/SSE4.1 on x86/x86_64; NEON on aarch64.
 - Public performance claims: none without local benchmark evidence.
 - Release status: `1.2.3`; `1.2.0` admitted conservative active encode
   dispatch, and `1.2.3` is a dependency-sync patch for the optional
   sanitization companion. Active encode dispatch admits AVX-512 VBMI above
   AVX2 above SSSE3/SSE4.1 on x86/x86_64 and NEON on aarch64 for Standard and
-  URL-safe alphabet families. In the `1.3.0` working line, AVX2 strict decode
-  is admitted above SSSE3/SSE4.1 strict decode for std `x86`/`x86_64`
-  Standard and URL-safe alphabet families when a full 32-byte encoded block is
-  present; SSSE3/SSE4.1 covers full 16-byte encoded blocks. AVX-512 VBMI,
-  NEON, custom alphabets, in-place decode, wrapped decode, legacy decode, CT
-  secret decode, `no_std`, and wasm `simd128` decode remain scalar or
-  prototype-only. Wrapped encode may use admitted fixed-block encode for its
+  URL-safe alphabet families. In the `1.3.0` working line, AVX-512 VBMI strict
+  decode is admitted above AVX2 and SSSE3/SSE4.1 strict decode for std
+  `x86`/`x86_64` Standard and URL-safe alphabet families when a full 64-byte
+  encoded block is present; AVX2 covers full 32-byte encoded blocks and
+  SSSE3/SSE4.1 covers full 16-byte encoded blocks. NEON, custom alphabets,
+  in-place decode, wrapped decode, legacy decode, CT secret decode, `no_std`,
+  and wasm `simd128` decode remain scalar or prototype-only. Wrapped encode
+  may use admitted fixed-block encode for its
   unwrapped staging step; line-ending insertion remains scalar.
 
 ## `1.3.0` Decode Admission Scope Freeze
@@ -91,7 +93,7 @@ State labels are intentionally strict:
 
 | Backend | State | Required CPU features | Evidence |
 | --- | --- | --- | --- |
-| 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 encode blocks use vector code only when at least one full block is present; a fixed 64-byte decode block prototype exists for tests and evidence only; public decode through AVX-512 remains prototype-only, while shorter inputs, tails, unsupported alphabets, in-place encode, line-ending insertion, and `no_std` use scalar fallback |
+| AVX-512 VBMI | admitted backend | `avx512f`, `avx512bw`, `avx512vl`, `avx512vbmi` | std x86/x86_64 runtime-dispatched encode and strict decode for Standard and URL-safe alphabet families; encode uses fixed 48-byte input blocks, and decode uses fixed 64-byte encoded blocks only after whole-input scalar validation preserves public error shape; shorter inputs fall back to AVX2, SSSE3/SSE4.1, or scalar, tails use scalar, and unsupported alphabets, in-place encode/decode, wrapped decode, legacy decode, CT secret decode, line-ending insertion, and `no_std` use scalar fallback |
 | AVX2 | admitted backend | `avx2` | std x86/x86_64 runtime-dispatched encode and strict decode for Standard and URL-safe alphabet families; encode uses fixed 24-byte input blocks, and decode uses fixed 32-byte encoded blocks only after whole-input scalar validation preserves public error shape; shorter inputs fall back to SSSE3/SSE4.1 or scalar, tails use scalar, and unsupported alphabets, in-place encode/decode, wrapped decode, legacy decode, CT secret decode, line-ending insertion, and `no_std` use scalar fallback |
 | SSSE3/SSE4.1 | admitted backend | `ssse3`, `sse4.1` | std x86/x86_64 runtime-dispatched encode and strict decode for Standard and URL-safe alphabet families; encode uses fixed 12-byte input blocks, and decode uses fixed 16-byte encoded blocks only after whole-input scalar validation preserves public error shape; shorter inputs, tails, unsupported alphabets, in-place encode/decode, wrapped decode, legacy decode, CT secret decode, 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 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 through NEON remains prototype-only, while shorter inputs, tails, unsupported alphabets, 32-bit ARM, in-place encode, line-ending insertion, and `no_std` use scalar fallback |
@@ -100,7 +102,7 @@ State labels are intentionally strict:
 ## Release Rule
 
 Advertise SIMD acceleration only with the admitted backend name and scope. Do
-not claim wasm `simd128`, custom alphabet, in-place, AVX-512/NEON decode, or
-any broader decode acceleration until this manifest names those backends or API
+not claim wasm `simd128`, custom alphabet, in-place, NEON decode, or any
+broader decode acceleration until this manifest names those backends or API
 surfaces and links to the matching differential, fuzz, unsafe, benchmark, and
 release-note evidence.