# SIMD Admission Policy
`base64-ng` is intentionally scalar-only in the `1.0.7` release. Future SIMD
dispatch remains gated unless a complete SIMD admission evidence package lands
in a later release series. The crate uses `#![deny(unsafe_code)]` and permits
reviewed `allow(unsafe_code)` exceptions only for audited cleanup in
`src/cleanup.rs`, CT comparison, byte accumulation, CT scan, and CT result-gate helpers in
`src/ct.rs`, and the private `src/simd.rs` boundary. The `simd` feature
remains reserved until architecture-specific code has enough evidence to
justify enabling it.
This is a security decision, not a rejection of hardware acceleration. SIMD
must be added only when it can be isolated, tested, and reviewed without
weakening the scalar trust base.
## Current Status
- Default builds compile audited unsafe cleanup, CT barrier, and comparison
helpers; scalar encode/decode remains safe Rust.
- `scripts/validate-unsafe-boundary.sh` verifies that `allow(unsafe_code)` is
confined to the reviewed cleanup, CT, and SIMD helper files.
- `docs/UNSAFE.md` inventories every current unsafe site and its invariants.
- The scalar implementation is the reference behavior.
- Encode and decode entry points already pass through an internal backend
boundary, currently backed only by the scalar implementation.
- With the `simd` feature enabled, the private dispatch scaffold detects
AVX-512 VBMI, AVX2, SSSE3/SSE4.1, NEON, and wasm `simd128` candidates but
still activates only the scalar backend.
- AVX-512 VBMI detection is reporting-only until an implementation has scalar
differential tests, fuzz coverage, and benchmark evidence. Detection requires
the full planned feature bundle: `avx512f`, `avx512bw`, `avx512vl`, and
`avx512vbmi`.
- An inactive AVX-512 fixed-block encode prototype exists behind the SIMD
boundary as test-only scaffolding and is tested against scalar output only
when the full AVX-512 Base64 feature bundle is available. It currently zeroes
the destination with SIMD and then overwrites the block with scalar encoding;
this is scaffolding, not vectorized Base64 correctness evidence, and it is
not compiled into release library builds.
- Runtime backend identifiers expose their required CPU feature bundles through
`runtime::Backend::required_cpu_features()`.
- Runtime backend reports include `candidate_required_cpu_features=[...]` in
their stable key/value display output for audit logs.
- Runtime backend reports include `candidate_detection_mode=...` so logs show
whether a SIMD candidate came from runtime CPU feature probing or from
compile-time target features.
- Runtime backend reports expose `snapshot()` for structured audit logging
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 as test-only scaffolding and is tested against scalar output only
when SSSE3/SSE4.1 is available. It currently zeroes the destination with SIMD
and then overwrites the block with scalar encoding; this is scaffolding, not
vectorized Base64 correctness evidence, and it is not compiled into release
library builds.
- An inactive AVX2 fixed-block encode prototype exists behind the SIMD boundary
as test-only scaffolding and is tested against scalar output only when AVX2
is available. It currently zeroes the destination with SIMD and then
overwrites the block with scalar encoding; this is scaffolding, not vectorized
Base64 correctness evidence, and it is not compiled into release library
builds.
- An inactive NEON fixed-block encode prototype exists behind the same boundary
as test-only scaffolding and is tested against scalar output only on
NEON-capable ARM targets. It currently zeroes the destination with SIMD and
then overwrites the block with scalar encoding; this is scaffolding, not
vectorized Base64 correctness evidence, and it is not compiled into release
library builds.
- wasm `simd128` detection is reporting-only when `wasm32` is compiled with
`target-feature=+simd128`; no wasm accelerated backend is active.
- `runtime::backend_report()` reports the active backend, detected candidate,
detection mode, SIMD feature status, scalar-only security posture, and a
conservative unsafe-boundary posture flag. The flag is true only when the
reserved `simd` feature is disabled; SIMD-enabled builds include additional
private prototype boundaries and must use the release evidence scripts for
boundary validation.
- On `x86`/`x86_64` with `std`, candidate detection uses
`std::is_x86_feature_detected!` runtime CPU probing. On `no_std`, wasm, and
current ARM builds, candidate detection is compile-time target-feature
reporting. A binary compiled with `-C target-feature=+avx2` can therefore
report an AVX2 candidate even if it is deployed on a CPU that cannot execute
AVX2 instructions. No SIMD dispatch is active today; any future `no_std`
SIMD activation must require an explicit caller-side CPU contract or remain
disabled where runtime probing is unavailable.
- `runtime::require_backend_policy()` allows deployments to enforce scalar
execution, disabled SIMD features, or no detected SIMD candidate.
- `BackendPolicy::HighAssuranceScalarOnly` combines scalar execution, disabled
SIMD features, no detected SIMD candidate, unsafe-boundary enforcement, and a
CT result gate classified as an attested hardware speculation barrier. It
rejects targets that report an unattested hardware barrier, ordering fence,
or compiler fence. On AArch64, the crate emits `isb sy` plus CSDB hint code
but reports `hardware-speculation-barrier-unattested` because deployments
must attest whether that hint is effective on their specific core. On RISC-V,
the reported CT gate is intentionally only `ordering-fence`; the base ISA
does not provide a canonical Spectre-v1 speculation barrier, so
platform-level mitigations are required for that threat model.
- Runtime backend, posture, and policy enums provide stable string identifiers
for logs and release evidence.
- Runtime backend reports and policy failures format as stable key/value
strings suitable for CI and audit logs.
- Unit tests compare dispatch behavior against the scalar reference for
canonical inputs, malformed inputs, and undersized output buffers.
- The `simd` feature does not enable accelerated code yet.
- Current `1.0` development remains scalar-only unless the SIMD admission
manifest, scalar differential tests, fuzz evidence, unsafe inventory,
architecture evidence, benchmark evidence, and release wording are updated
together.
- CI checks the reserved `simd` feature in `no_std` mode for x86_64, aarch64,
FreeBSD, wasm32, and Cortex-M targets.
- Performance claims must be backed by local benchmark evidence, not roadmap
language.
Run the same target check locally for every installed target:
```sh
scripts/check_targets.sh
```
Run a specific target:
```sh
scripts/check_targets.sh aarch64-unknown-linux-gnu
```
Compile-check the reserved SIMD feature bundles:
```sh
scripts/check_simd_feature_bundles.sh
```
This does not execute accelerated code. It proves the reserved AVX2,
AVX-512, SSSE3/SSE4.1, NEON, and wasm `simd128` feature-gated code still
compiles under `no_std` when the corresponding Rust targets are installed.
Capture local backend and prototype evidence:
```sh
scripts/check_backend_evidence.sh
```
This prints the runtime backend-report test and runs the gated SIMD prototype
scalar-equivalence scaffolding tests with `--nocapture`, so local CPU evidence
is easy to copy into release notes or issue discussion. These prototype tests
do not prove vectorized Base64 correctness; they only exercise target-feature
gating, unsafe isolation, and fixed-block plumbing until real vector logic is
admitted. The script also writes
`target/release-evidence/backend/MANIFEST.txt` with toolchain metadata,
commands, status values, and artifact checksums.
## Required Before SIMD Code Lands
Any AVX2, NEON, AVX-512, wasm `simd128`, or runtime-dispatch implementation
must include:
- Completion of
[SIMD_ACTIVATION_CHECKLIST.md](SIMD_ACTIVATION_CHECKLIST.md) before the
backend is wired into dispatch.
- The dedicated `src/simd.rs` boundary for all architecture-specific code.
- Crate-level `deny(unsafe_code)` must continue to reject unsafe outside the
volatile wipe helpers and SIMD module.
- A local safety comment for every unsafe block.
- Deterministic differential tests against scalar encode/decode behavior.
- Fuzz differential coverage for strict and legacy-compatible inputs where
applicable.
- Runtime dispatch tests that prove unsupported CPUs fall back to scalar.
- Miri coverage for scalar and dispatch-level code that Miri can execute.
- Architecture-specific CI evidence or documented local evidence for each
enabled target.
- Benchmark evidence that reports hardware, OS, Rust version, command, and raw
output.
## Admission Gate
`scripts/validate-simd-admission.sh` keeps SIMD dispatch scalar-only until the
admission evidence is deliberately updated. The gate currently requires:
- `ActiveBackend` to expose only the `Scalar` variant.
- `active_backend()` to return `ActiveBackend::Scalar`.
- No accelerated `ActiveBackend::Avx*`, `ActiveBackend::Neon`,
`ActiveBackend::Sse*`, `ActiveBackend::Wasm*`, or generic SIMD dispatch
variants in source.
- `docs/SIMD_ADMISSION.md` to record that no accelerated backend is admitted.
- Documentation for benchmark evidence, release-note restrictions, and
vector-register retention cleanup strategy to remain packaged.
When an accelerated backend is ready for admission, update this gate in the
same commit as the scalar differential tests, fuzz evidence, unsafe inventory,
benchmark evidence, and release notes.
## Dispatch Rules
- Scalar remains the fallback for every build.
- Candidate detection must not imply activation; a detected candidate may still
execute scalar until the accelerated backend is admitted.
- Prototype functions may exercise target-feature and unsafe plumbing without
being eligible for dispatch.
- Runtime CPU detection may be used only behind `std`.
- Compile-time target-feature paths must be explicit and documented.
- Unsupported CPU features must never panic at runtime.
- SIMD paths must preserve strict error indexes, canonical padding rejection,
and output sizing behavior.
## Release Rule
Do not advertise SIMD acceleration in release notes until accelerated code is
actually enabled, tested, and measured for that release.