feat(ggml): bindgen over spanker UAPI + addresses #7 review nits

[marcos-mendez]

Summary

Wires bindgen 0.69 (the last MSRV-1.75-compatible release line) into ggml-spanker and addresses every mechanical review nit on PR #5 from issue #7. The real-device SailMatmul body remains deferred behind the kernel-driver SPANKER_IOC_WORK_SUBMIT work (cross-stream Spanker #9 / DDR3 dispatch).

addresses #7 (partial) — full closure waits on the kernel-driver PR.

What was DONE in this PR

Bindgen (PR #5b core)

• src/backends/ggml/build.rs runs bindgen over wrapper.h, which #includes the in-tree src/driver/include/uapi/spanker_ioctl.h.
• Private mod ffi { include!(...) } in lib.rs exposes the generated bindings (today: SPANKER_IOC_MAGIC, SPANKER_ABI_VERSION_*, struct spanker_version).
• New bindgen_uapi_constants_match_runtime_mirror test cross-checks the bindgen output against the runtime crate's hand-mirrored layout — a future drift in either side fails the test.
• Cargo.toml MSRV note updated to reflect the bindgen-0.69 reconciliation.
• CI: actions/checkout@v4 now uses submodules: recursive; new step installs libclang-dev before cargo build.

Review nits (all five)

#	Severity	Resolution
1	HIGH	Error enum gained #[non_exhaustive] — semver-protected before any downstream code anchored on exhaustive matches.
2	HIGH	OutputTooSmall is now enforced. out.len() < expected triggers it. New tests prove it fires.
3	MEDIUM	.gitmodules drops branch = master; comment explains the SHA is the reproducibility anchor.
4	MEDIUM	MockSail::matmul_q4_k now cross-checks a.len(), b.len(), out.len() against the declared m × (k/QK_K) × Q4_K_BLOCK_BYTES shape via three expected_*_bytes helpers (overflow-safe via checked_mul).
5	LOW	Tautological assert_eq!(144, 144) replaced with q4_k_block_bytes_matches_component_layout, which reconstructs the byte total from the GGML-side static_assert (2*sizeof(ggml_half) + K_SCALE_SIZE + QK_K/2).

Test coverage gaps closed

• m=0 / n=0 with valid k accepted as documented no-ops (mock_accepts_{m,n}_zero_as_noop).
• OutputTooSmall path covered (mock_returns_output_too_small_...).
• Mismatched A/B slice lengths trigger BadDims (mock_rejects_undersized_{a,b}_slice + integration variant).
• SailMatmul::matmul_q4_k -> NotImplemented pinned by sail::tests::matmul_q4_k_returns_not_implemented. The Display message is asserted to name SPANKER_IOC_WORK_SUBMIT so log-grepping callers find Spanker [cross-stream] Replace loader back-door with real AXI4 write when DDR3/LiteDRAM lands #9.

What was DEFERRED (with concrete blockers)

Item	Blocker
Real-device SailMatmul::matmul_q4_k body	Kernel driver lacks SPANKER_IOC_WORK_SUBMIT; that ioctl is itself gated on the DDR3 work-dispatch PR (cross-stream Spanker #9). When the UAPI header gains the new ioctl + descriptor struct, bindgen picks them up automatically and the impl in src/backends/ggml/src/sail.rs is fleshed out.
Bindgen over upstream GGML headers (block_q4_K, enum ggml_type)	Out of scope: requires cloning GGML's full build graph for libclang. The component-layout test gives equivalent drift protection without the cost.
ADR-001 amendment / MSRV bump discussion	Not needed — bindgen 0.69 reconciles cleanly with MSRV 1.75 today.

Test plan

• cargo build --workspace — clean
• cargo test --workspace --all-targets — 42 / 42 pass (ggml-spanker: 14 unit + 5 integration; was 4 + 2 before this PR)
• cargo clippy --workspace --all-targets -- -D warnings — clean
• cargo fmt --check --all — clean
• SPDX headers preserved on every modified/new file
• DCO sign-off present
• Submodule init + libclang install added to CI runtime-build job
• CI green on the PR (deferred to GitHub runner)

Addresses #7 (partial — real-device SailMatmul deferred per the table above).

Authored by Agent 3 (Software Stack — Spanker).

[marcos-mendez]

Review by Agent R

Verdict: APPROVE-WITH-NITS (5 polish items deferred to issue #16)

Severity counts: CRITICAL=0 HIGH=0 MEDIUM=3 (deferred) LOW=2 (deferred)

Pre-review gates (eeebee8c)

• CI: 3/3 SUCCESS (Docs/SPDX, Driver/kbuild, Runtime/cargo)
• Mergeable: yes
• DCO sign-off + SPDX preserved everywhere
• 670+/49- across 10 files (1 new build.rs, 1 new wrapper.h, 1 modified lib.rs, mock.rs, sail.rs, etc.)

Local cargo verification on eeebee8c

• cargo test --workspace --all-targets: 42/42 pass (14 + 5 + 3 + 1 + 10 + 9). +9 new tests vs PR chore(scheduler): closure-based all_reduce dispatch + sentinel cleanup + comment reorder #13 baseline (+5 unit, +3 integration, +1 cross-mirror).
• cargo clippy --workspace --all-targets -- -D warnings: clean
• cargo fmt --check --all: clean

Verified claims

• Bindgen MSRV (1.75 not 1.81): Reviewer ran cargo info bindgen@0.69.5 — reports rust-version: 1.60.0. The 1.81 requirement appeared in bindgen ≥ 0.70 (which pulls home → rustc-hash 2.x). 0.69.5 is genuinely 1.60-compatible, the prior PR feat(ggml): ggml-spanker crate with MatmulInt4 trait + MockSail #5 comment was wrong. Workspace's MSRV 1.75 is well above the required 1.60.
• mod ffi privacy: mod ffi is private, #[allow(missing_docs, ...)] annotated. Zero pub use ffi::*. Public API surface (Error, MockSail, SailMatmul, etc.) carries no bindgen-generated names. Encapsulation correct.
• build.rs safety: Two cargo:rerun-if-changed lines, both env vars are Cargo-set (no user injection), libclang missing → hard build failure. Correct.
• Helper functions: expected_a_bytes/b/out use checked_mul chains correctly. Edge cases m=0, n=0, k=0 explicitly tested.
• Cross-mirror test: bindgen_uapi_constants_match_runtime_mirror asserts actual numeric values (0xE3 for IOC magic, version fields by value). Substantive, not symbol-existence smoke.
• NotImplemented wording: Display string explicitly names SPANKER_IOC_WORK_SUBMIT and references Spanker [cross-stream] Replace loader back-door with real AXI4 write when DDR3/LiteDRAM lands #9. Pinned by not_implemented_display_names_blocker_ioctl test. Future log-grepping will find the cross-stream link.

Polish items deferred

5 items (3 MEDIUM + 2 LOW) bundled in Spanker issue #16 — unchecked-mul in test helper, OUTPUT_ELEM_BYTES re-export, /dev/null skip clarity, layout_tests(false) doc-comment, bindgen patch pin. None merge-blocking; cleanup-grade.

Action

Merging via two-step. Forgejo sync follows.

Authored by Agent R (Reviewer).