feat: add portable liblecore ABI-0 kernel

[atimics]

Summary

• define the product requirements, semantic boundary, engineering plan, and phased backlog for liblecore
• add a portable C11 ABI-0 kernel for the frozen HRR algebra in f64 and f32, with direct and opt-in radix-2 backends
• add batch and mixed-precision scoring, cleanup, a versioned checksummed interchange codec, and caller-owned allocation contracts
• ship static/shared CMake and pkg-config packages, a deterministic single-file amalgamation, C/C++ examples, and Python and Rust adapters
• add cross-platform native CI, conformance fixtures, sanitizers, fuzz smoke, WebAssembly checks, installed-consumer tests, ABI symbol manifests, and a paired public-ABI performance regression gate
• optimize the ordered direct kernels, radix transform setup, fixed-role FFT reuse, and repeated-query scoring without changing profile semantics

Why

leCore already had frozen Python HRR semantics, while related projects maintained separate native kernels with different normalization, numeric, and packaging behavior. This introduces one clean-room MIT C implementation whose behavior is defined by the existing ISA/reference rather than by adopter-specific policy.

The native layer remains optional. Existing Python behavior and persisted formats are unchanged unless a consumer explicitly adopts liblecore.

Developer impact

• ABI 0 is an implementation preview, not the stable ABI-1 release.
• ABI-0 shared libraries use package major.minor as their preview SONAME/install-name; this 0.1.x line uses 0.1.
• AUTO deliberately remains on the direct reference backend; radix-2 must be selected explicitly until adopter workloads justify a portable crossover policy.
• atom generation, encoders, schedulers, associative-memory policy, and adopter persistence remain outside the C ABI.
• consumers can pin the CMake package, pkg-config package, Rust crate source, Python adapter, or checked-in amalgamation.

Optimization review

The final Apple-arm64 Release comparison loads the optimized build and pre-optimization commit bd8da06 together, uses identical inputs and iteration counts, and alternates candidate/base order for ten paired samples per cell.

Profile	Dimension	Direct before → now	Direct improvement	Radix-2 before → now
f64	256	34.05 → 6.86 µs	4.97x	3.26 → 3.18 µs
f64	512	161.57 → 28.96 µs	5.60x	6.83 → 6.61 µs
f64	1024	712.05 → 113.73 µs	6.26x	14.76 → 14.18 µs
f32	256	34.66 → 4.18 µs	8.29x	3.33 → 3.13 µs
f32	512	161.48 → 14.01 µs	11.50x	6.97 → 6.46 µs
f32	1024	708.79 → 62.52 µs	11.36x	14.31 → 13.43 µs

Direct results remain bit-for-bit equal to the ordered reference. Maximum radix/direct disagreement was 1.665e-16 for f64 and 1.192e-7 for f32. Focused local probes measured about 1.5x for fixed-role bind/unbind and about 1.1–1.2x for repeated-query scoring/cleanup, with exact outputs and decisions.

Performance gate

The Linux Release job times a pre-resolved public C ABI call rather than the checked Python adapter. Candidate and exact base-commit libraries run in one process as aligned, alternating pairs; the checker gates the median of per-pair slowdown ratios at 1.35x for direct and radix-2 independently.

The harness uses three pilots, calibrates from the fastest observation, and requires final samples to meet the duration target. If either side has an undersized sample, it discards and symmetrically reacquires the whole pair with more work, bounded to three attempts and 1,000,000 calls. There is one policy evaluation and no asymmetric “retry until pass.” Raw JSON is uploaded and the scorecard is written to the job summary.

Because main does not yet contain liblecore, this introductory PR takes the documented bootstrap path and makes no hosted candidate/base speed claim. The local paired report above is the pre/post evidence; after merge, every relevant PR automatically compares against its exact base commit. Specialized batch/scoring performance cells are explicitly tracked as LC-047.

Validation

• strict static CMake suite: 11/11
• strict shared CMake suite: 13/13
• ASan/UBSan suite: 6/6
• Python direct and forced-radix conformance: 11/11 each
• performance policy tests: 22/22 on Python 3.9 and 3.14
• exact bootstrap performance gate: PASS; minimum of 120 samples was 36.58 ms
• paired pre/post performance gate: PASS; minimum sample was 37.03 ms
• Rust vendored debug/release, installed-prefix tests, strict Clippy, and compile-fail thread-safety docs
• deterministic fixture and amalgamation regeneration checks
• C/C++ installed consumers, feature-on/off symbol manifests, format/radix variants, and WebAssembly smoke coverage
• modified native workflow passes actionlint

Follow-ups

• run shadow adoption against Signal replay decisions and NoSQLite mixed-precision reranking
• add the LC-047 paired batch/scoring performance cells and consumer-level benchmarks
• use adopter evidence to decide whether an automatic backend crossover belongs in a later ABI

[atimics]

Optimized performance regression gate

Commit 8a803ae optimizes the kernels and replaces the original wrapper-level benchmark with a calibration-hardened public-ABI paired gate.

Final local comparison: Apple arm64, Apple Clang 17 Release, Python 3.14.5, NumPy 2.4.4, deterministic inputs, ten aligned candidate/base samples per cell. Candidate is 8a803ae; baseline is pre-optimization bd8da06.

Profile	Dimension	Direct before	Direct now	Improvement	Radix-2 before	Radix-2 now	Max delta
f64	256	34.05 µs	6.86 µs	4.97x	3.26 µs	3.18 µs	1.665e-16
f64	512	161.57 µs	28.96 µs	5.60x	6.83 µs	6.61 µs	1.388e-16
f64	1024	712.05 µs	113.73 µs	6.26x	14.76 µs	14.18 µs	1.665e-16
f32	256	34.66 µs	4.18 µs	8.29x	3.33 µs	3.13 µs	1.192e-7
f32	512	161.48 µs	14.01 µs	11.50x	6.97 µs	6.46 µs	8.941e-8
f32	1024	708.79 µs	62.52 µs	11.36x	14.31 µs	13.43 µs	1.043e-7

All six paired regimes pass the 1.35x candidate/base slowdown policy for both direct and radix-2. Direct remains bit-for-bit equal to the ordered reference, and AUTO remains direct.

The gate now:

• times a pre-resolved public C ABI call instead of Context.bind;
• stores and validates every raw elapsed sample;
• uses three pilots and symmetric bounded reacquisition when a sample is too short;
• gates the median of aligned candidate/base ratios once, with no asymmetric pass retry; and
• uploads raw JSON while publishing the scorecard in the job summary.

The exact bootstrap run also passes; its shortest sample was 36.58 ms. The current PR is bootstrap-only on GitHub because main has no liblecore artifact yet. Specialized batch/scoring cells are tracked as LC-047.