[ternary-f32] Final gate: licensing, REUSE & OSS-compliance close-out for the vendored NeoGPU/BitNet work

[michalharakal]

Final gate of #1136 — runs after all other sub-issues close, and is the last one to close. Nothing in the ternary effort is "done" until the licensing, attribution, and OSS-compliance story of the vendored code is verifiably in order — in the repo and in the shipped artifacts.

Why a dedicated issue

This effort introduced the repo's first vendored third-party source (hs_ml_ternary_neon.c from anjaustin/neogpu, MIT) and code written against a second MIT upstream (BitNet.cpp, vendored in NeoGPU's tree) for the I2_S wire format (#1140). MIT is permissive but not obligation-free: the copyright notice and license text must accompany "copies or substantial portions" — which includes compiled copies inside our published jars, klibs, and AARs, not just the source tree.

Repo-level compliance

• reuse lint passes on the repo (REUSE.toml precedence = "closest" + the .license sidecar under native/src/vendor/neogpu/); wire it into CI so it stays passing
• Vendored file still byte-identical to the recorded upstream commit — re-verify the SHA-256 in native/src/vendor/neogpu/README.md against anjaustin/neogpu@0846b24, and that "Local modifications: none" is still true
• LICENSES/ holds every license the tree now references; drop or justify the currently-unreferenced entries (Apache-2.0.txt, CC0-1.0.txt) so the directory reflects reality
• I2_S format knowledge ([ternary-f32] Phase 4: GGUF I2_S (type 36) import with group→sequential repack, keep-packed BITNET_B1_58 #1140): add an interpretation note crediting BitNet.cpp (MIT, microsoft/BitNet) in I2sRepack.kt / Constants.kt, following the existing llama.cpp precedent in the GGUF constants header — the layout rule was reimplemented against their sources
• Docs cross-check: the ternary tutorial and vendor README attribute NeoGPU consistently (name, license, upstream link, agreement in Porting the ternary LUT kernel into SKaiNET (Kotlin Multiplatform ML runtime) — a few questions anjaustin/neogpu#1)

Artifact-level compliance (the part reuse lint cannot see)

• skainet-backend-native-cpu (jar with bundled libskainet_kernels.*, klibs embedding the static archive) and skainet-backend-jni-cpu (AAR with both .so variants) ship compiled NeoGPU code → each published artifact must carry the NeoGPU MIT notice: a META-INF/ third-party notices file (or equivalent for AAR), listing NeoGPU (and BitNet.cpp if any of its code lands beyond format knowledge)
• Maven POM <licenses> of the affected artifacts reviewed — SKaiNET's own MIT stays, third-party notices travel with the artifact, not just the repo
• BOM / release notes: mention the vendored component and its license in the release that first ships it

Upstream courtesies (agreed in anjaustin/neogpu#1)

• Comment on Porting the ternary LUT kernel into SKaiNET (Kotlin Multiplatform ML runtime) — a few questions anjaustin/neogpu#1: port landed, link Ternary f32 LUT gemv — vendored NeoGPU kernel: exact FP32×b1.58 matmul for baseline-NEON ARM (Pi-4/A72) #1136, thank + summarize what was vendored and the fixes worth upstreaming (LUT-init race closed via adapter, code-3 note, -march pinning insight, layout-flavor findings)
• PR to NeoGPU adding SKaiNET to a "used by" note in its README (offered in the issue)
• Optionally report upstream the I2_S QK_I2_S architecture-dependence discovery (x86=128 / ARM=64) — it affects anyone consuming stock GGUFs

Close-out

• All Ternary f32 LUT gemv — vendored NeoGPU kernel: exact FP32×b1.58 matmul for baseline-NEON ARM (Pi-4/A72) #1136 sub-issues ([ternary-f32] Phase 1: vendor NeoGPU LUT kernel + adapter + CMake + JVM FFM downcall #1137–[ternary-f32] Phase 5: benchmark scenario + docs #1141, [ternary-f32] Phase 6: BITNET_PLANES encoding (multi-plane trit + FP16 row scale) + codec + lmhead-stage1 kernel pack #1150) closed or explicitly re-scoped; tracking-issue checklist ticked and a short outcome summary posted (what shipped, measured results from the [ternary-f32] Phase 5: benchmark scenario + docs #1141 benchmarks, memory numbers)
• CHANGELOG entry for the release: new kernel path, new GGUF type, the NeoGPU attribution
• Kernel-support matrix and docs current with the final state
• Verify against a real microsoft/bitnet-b1.58-2B-4T GGUF (the [ternary-f32] Phase 4: GGUF I2_S (type 36) import with group→sequential repack, keep-packed BITNET_B1_58 #1140 caveat) and record the confirmed I2sGgufLayout default in the docs

Definition of done: a third party auditing a shipped SKaiNET release can trace every vendored byte to its upstream, license, and copyright holder without asking us.

[michalharakal]

@MacOS this is a tracking issue for licenses related work.

[michalharakal]

Progress: PR #1177 covers the repo/artifact-level items (checklist status in its description).

Proposed upstream comment for anjaustin/neogpu#1 — ready to post on a maintainer's go (it goes to a third-party repo, so it is not posted automatically):

---

The port is done — thanks again for the green light. hs_ml_ternary_neon.c is vendored byte-identical (MIT, REUSE-tracked) into SKaiNET at SKaiNET#1136: the f32 proj gemv serves our kernel dispatch on JVM/FFM, Android/JNI and Kotlin/Native, and the fused 4-plane lm_head backs our BITNET_PLANES weight format. Attribution ships in the source tree and in the published artifacts' third-party notices.

A few findings that may interest you, from the port:

• The non-atomic g_lut_built guard we closed on our side with a pthread_once warm-up in the adapter — trivially upstreamable if you want it.
• On toolchains that build the surrounding library with -march=armv8.2-a+dotprod, the kernel needs pinning back to -march=armv8-a to keep its dotprod-less-A72 value — worth a note in the header.
• While implementing I2_S import we found BitNet.cpp's QK_I2_S is architecture-dependent (128 on the x86/AVX quantize pipeline, 64 on ARM/NEON) — your i2s_proj_neon reads the ARM flavor; stock x86-converted GGUFs are the 32-byte-block flavor.
• Measured through our dispatch on Apple arm64 at BitNet-2B FFN dims: 51.8 GOPS vs 0.43 for our portable int8 path — and your Pi-4 numbers reproduce in spirit on the qemu lane.

Happy to also open the "used by" README PR you offered. 🙏

---

Also still open here: the "used by" PR to NeoGPU's README, the release-cut items, and the real-GGUF verification.

[michalharakal]

Checklist update: the real-GGUF verification is done — the official microsoft/bitnet-b1.58-2B-4T I2_S file (1.19 GB) loads packed and generates coherent text through the vendored kernels in SKaiNET-transformers (transformers#336 comment has the transcript). This confirms the GROUP_128 default of the I2_S import (#1140's caveat) against the official BitNet.cpp file. Requires #1186 on the release line.

[michalharakal]

Status after the 0.49.0 release — what's done and what remains:

item	state
reuse lint in CI	✅ pre-existing (reuse-compliance.yml), green throughout
Vendored file byte-identical (sha a560ffcf… @ upstream 0846b24)	✅ re-verified
LICENSES/ audit (Apache-2.0, CC0-1.0)	✅ both referenced → justified, kept
BitNet.cpp interpretation credits (I2sRepack.kt, Constants.kt)	✅ #1177 (merged, incl. review's SPDX additions)
Artifact-level third-party notices (jar/klib/AAR)	✅ #1177, merged into release/0.49.0 → shipped in the 0.49.0 Central artifacts (verified META-INF/THIRD-PARTY-NOTICES.md in the fat jar)
Real microsoft/bitnet-b1.58-2B-4T GGUF verification	✅ generates coherent text through the packed path + vendored kernels; confirms GROUP_128 (#1140 caveat closed)
Release shipped with the licensing in	✅ tag 0.49.0, publish workflow green

Still open:

1. ⬜ CHANGELOG / GitHub-release notes naming the vendored NeoGPU component and its license — the tag exists but no release-notes text does; small PR + a GitHub Release object for 0.49.0.
2. ⬜ Upstream courtesies (agreed in Porting the ternary LUT kernel into SKaiNET (Kotlin Multiplatform ML runtime) — a few questions anjaustin/neogpu#1): the thank-you/findings comment — drafted in this issue's earlier comment, awaiting the maintainer's go to post to the third-party repo — and the "used by" README PR to NeoGPU.
3. ⬜ Final close-out summary here once 1–2 land; then this issue closes as the last of Ternary f32 LUT gemv — vendored NeoGPU kernel: exact FP32×b1.58 matmul for baseline-NEON ARM (Pi-4/A72) #1136.

[michalharakal]

CHANGELOG deliverable done: PR #1197 carries the 0.50.0 entry with an explicit Third-party section for the vendored NeoGPU kernel (upstream repo + commit 0846b24, MIT, byte-identical claim, pointer to the artifact-level notices). With that, everything in-repo for this gate is complete. Remaining before close-out: the two upstream courtesies (the drafted thank-you/findings comment on anjaustin/neogpu#1 and the "used by" README PR) — still awaiting the explicit go, since they post to a third-party repository. Say the word and they go out; then this closes, and #1136 with it.