diff --git a/Cargo.toml b/Cargo.toml index 633004a9..29a0ed6a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -52,12 +52,38 @@ libc = { version = "0.2.82", optional = true } matrixmultiply = { version = "0.3.2", default-features = false, features=["cgemm"] } -# blake3 — gated behind `hpc-extras` (integrity hashing in -# plane/seal/merkle_tree/vsa/spo_bundle/crystal_encoder/compression_curves/ -# deepnsm). Optional + opt-in because the transitive dep `constant_time_eq` -# does not declare `#![no_std]`, so unconditionally including blake3 breaks -# the `thumbv6m-none-eabi --no-default-features` nostd build with -# `error[E0463]: can't find crate for std`. +# ===================================================================== +# blake3 — DEPENDENCY OF `std` FEATURE (NOT `hpc-extras`). READ BEFORE +# TOUCHING. +# ===================================================================== +# +# blake3 is required by the cognitive substrate modules — plane, seal, +# merkle_tree, vsa, spo_bundle, crystal_encoder, compression_curves, +# deepnsm — which all live under `pub mod hpc;` (itself gated on +# `feature = "std"` in lib.rs). Those modules `use blake3;` directly +# and unconditionally; there is no #[cfg] dance inside them. +# +# Pinning blake3 to the `std` feature (rather than `hpc-extras`) means: +# * ANY consumer that enables `std` automatically gets blake3, with +# ZERO additional feature wiring. This is the default. Cargo's +# transitive feature resolution does the rest. +# * Consumers selecting `default-features = false, features = ["std"]` +# (e.g. burn-ndarray, which disables hpc-extras to shed p64/fractal) +# STILL get blake3 — no more "missing blake3" build errors that +# used to require chasing down hpc-extras. +# * Consumers selecting `default-features = false` (no std at all, +# e.g. the `thumbv6m-none-eabi` CI matrix entry) do NOT pull blake3 +# and therefore do not pull `constant_time_eq`, whose lack of +# `#![no_std]` declaration would otherwise fail the nostd link with +# `error[E0463]: can't find crate for std`. +# +# If you find yourself wanting to make blake3 unconditional (drop the +# `optional = true`), check first: does it still pass +# `cargo rustc -p ndarray --target=thumbv6m-none-eabi +# --no-default-features --features portable-atomic-critical-section`? +# If not, leave the `optional = true` + `std`-feature pinning in place. +# +# ===================================================================== blake3 = { version = "1", optional = true } # p64 + fractal — specialized convergence / manifold math. Gated behind @@ -144,7 +170,7 @@ blas = ["dep:cblas-sys", "dep:libc"] serde = ["dep:serde"] -std = ["num-traits/std", "matrixmultiply/std"] +std = ["num-traits/std", "matrixmultiply/std", "dep:blake3"] rayon = ["dep:rayon", "std"] # Portable-SIMD backend (NIGHTLY ONLY). Routes `crate::simd::*` types @@ -161,11 +187,15 @@ rayon = ["dep:rayon", "std"] # cfg-dispatch in `simd.rs` remains the production path. nightly-simd = ["std"] -# HPC extras: blake3 hashing, p64 palette/NARS bridge, fractal manifold. +# HPC extras: p64 palette/NARS bridge + fractal manifold. +# (blake3 was previously listed here; it is now part of `std` directly +# because the cognitive substrate modules under hpc/ that import blake3 +# are themselves `std`-gated. See the blake3 comment in [dependencies].) # These pull in a non-trivial dependency tree; downstream crates such as # burn-ndarray that only need the core array layer can disable this with -# `default-features = false` (and re-enable `std` explicitly if needed). -hpc-extras = ["std", "dep:p64", "dep:fractal", "fractal/std", "dep:blake3"] +# `default-features = false` (and re-enable `std` explicitly if needed — +# blake3 will come along with `std`). +hpc-extras = ["std", "dep:p64", "dep:fractal", "fractal/std"] matrixmultiply-threading = ["matrixmultiply/threading"] diff --git a/README.md b/README.md index a9c14c5d..6c52d621 100644 --- a/README.md +++ b/README.md @@ -208,6 +208,23 @@ cargo test - Optional: gcc-aarch64-linux-gnu for Pi cross-compilation - Optional: Intel MKL or OpenBLAS (feature-gated) +### Transitive dependencies of the `std` feature + +Enabling the `std` feature (the default) pulls in **`blake3`** as a hard +transitive dependency. The cognitive substrate modules under `hpc/` — +`plane`, `seal`, `merkle_tree`, `vsa`, `spo_bundle`, `crystal_encoder`, +`compression_curves`, `deepnsm` — import `blake3` directly for integrity +hashing and XOF expansion, and there is no separate feature to enable it. +This was previously gated behind `hpc-extras`, which caused recurring +"missing blake3" build errors for consumers (e.g. `burn-ndarray`) that +selected `default-features = false, features = ["std"]` to shed the +`p64` / `fractal` dependency tree. Pinning blake3 to `std` removes that +footgun: any `std`-enabled build automatically gets blake3. + +Consumers building `default-features = false` (no `std`, e.g. the +`thumbv6m-none-eabi` nostd target) skip both the `hpc` module and the +blake3 dep, so the nostd link is unaffected. + ## Ecosystem This fork is the hardware foundation for a larger architecture: diff --git a/src/lib.rs b/src/lib.rs index 7c77a07a..e0aae5f7 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -297,6 +297,17 @@ pub mod backend; /// cam_pq, reductions, blas_level*, amx_matmul, vnni_gemm) compile without /// extra deps. Cognitive/research modules (p64_bridge, crystal_encoder, /// deepnsm, etc.) are gated behind `hpc-extras` inside `hpc/mod.rs`. +/// +/// ## blake3 transitive dep +/// +/// Enabling `std` (the default) automatically pulls `blake3`, which the +/// cognitive substrate modules (`plane`, `seal`, `merkle_tree`, `vsa`, +/// `spo_bundle`, `crystal_encoder`, `compression_curves`, `deepnsm`) +/// import directly and unconditionally. There is no separate feature +/// to enable; `std` is enough. Consumers building `default-features = false` +/// without `std` (e.g. the `thumbv6m-none-eabi` nostd target) skip both +/// the `hpc` module and the blake3 dep. See the `blake3` comment block +/// in `Cargo.toml` for the rationale. #[cfg(feature = "std")] #[allow(clippy::all, unused_imports, unused_variables, unused_mut, dead_code)] pub mod hpc;