base64-ng 0.5.0

no_std-first Base64 encoding and decoding with strict APIs and a security-heavy release process
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

# SIMD Admission Policy

`base64-ng` is intentionally scalar-only in the `0.5.0` release. The crate uses
`#![deny(unsafe_code)]` and permits `allow(unsafe_code)` only in 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 no unsafe code.
- `scripts/validate-unsafe-boundary.sh` verifies that `allow(unsafe_code)` is
  confined to `src/simd.rs`.
- `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, and NEON 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 and is tested against scalar output only when the full AVX-512
  Base64 feature bundle is available.
- 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 expose `snapshot()` for structured audit logging
  without parsing formatted strings.
- 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
  and is tested against scalar output only on NEON-capable ARM targets.
- `runtime::backend_report()` reports the active backend, detected candidate,
  SIMD feature status, and scalar-only security posture.
- `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, and unsafe-boundary enforcement.
- 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.
- 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, and NEON 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 tests with `--nocapture`, so local CPU evidence is easy to
copy into release notes or issue discussion.

## Required Before SIMD Code Lands

Any AVX2, NEON, AVX-512, or runtime-dispatch implementation must include:

- The dedicated `src/simd.rs` boundary for all architecture-specific code.
- Crate-level `deny(unsafe_code)` must continue to reject unsafe outside the
  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.

## 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.