feat(apps): skainet-plan CLI — memory plan of a GGUF from its header, budget fit, suggestions, tensor list by TensorId (SKEEP-003 M0, S0.8)

[michalharakal]

Summary

SKEEP-003 slice S0.8 — the milestone M0 sample app (#1001, PRD §4.3, M0-F6 JVM): skainet plan <model.gguf> [--ctx N] [--budget 1.3G] [--kv bf16|turboquant] [--prefill-chunk N] [--list <glob>] [--no-budget].

Prints the PRD table — weights (resident), KV cache at ctx with the alternate mode, forward slab, heap headroom, total against the budget with ✔/✘ and ≥ 2 suggestions with savings — and lists tensors by TensorId (TensorId · Format · n · bytes · ← gguf name). Exit code 1 when the plan does not fit. Reads the GGUF header only.

• New Kotlin/JVM application module skainet-apps/skainet-plan (kotlinx-cli, same pattern as skainet-tensor-tools), README with sample output, unit tests (size parsing, glob matching, list renderer); stdout forced to UTF-8 for the table glyphs.
• The planner itself is commonMain (sk.ainet.lang.memory.plan, StreamingGGUFReader.planInput, feat(memory): MemoryPlan from the GGUF header — weights, KV, forward slab, budget fit, suggestions (SKEEP-003 P1, S0.7) #1056) and callable from Android / Kotlin/Native directly; a native binary is a follow-up sub-issue (no KMP app precedent in skainet-apps).

Smoke run on a synthetic 2-layer llama GGUF (header generated for the test; 20 tensors):

tiny-llama-test · llama · 2 layers · ctx 512
  weights   Mapped, packed                110 KB   resident
  kv cache  bf16 @ ctx 512                128 KB   resident   (38 KB with TurboQuant 4-bit)
  forward   prefill chunk 256               2 MB
  heap      headroom                       64 MB
  total                                    66 MB   of 128 MB  ✔ fits

tensors matching 'model.layers[0].attn.*': 4
  model.layers[0].attn.q_proj.weight  Float32/Q4_K      n=4096            2 KB   ← blk.0.attn_q.weight
  model.layers[0].attn.k_proj.weight  Float32/Q4_K      n=4096            2 KB   ← blk.0.attn_k.weight
  model.layers[0].attn.v_proj.weight  Float32/Q4_K      n=4096            2 KB   ← blk.0.attn_v.weight
  model.layers[0].attn.o_proj.weight  Float32/Q4_K      n=4096            2 KB   ← blk.0.attn_output.weight

Stacked on #1056 (S0.7 — MemoryPlan); retarget to develop after it merges.

Test plan

Full local gate (scripts/pr-gate.sh, JDK 25); results in the first comment. :skainet-apps:skainet-plan:test 3/3, installDist + the smoke run above (exit 0 when fitting, 1 otherwise).

Closes #1013

🤖 Generated with Claude Code

[michalharakal]

Local gate scripts/pr-gate.sh (JDK 25) on 223d55b (stacked on #1056):

=== pr-gate: JVM tests ===                                      BUILD SUCCESSFUL (new module + cached)
=== pr-gate: apiCheck ===                                       BUILD SUCCESSFUL
=== pr-gate: verifyNpmPins jsTest wasmJsTest wasmWasiTest ===   BUILD SUCCESSFUL
=== pr-gate: linuxX64Test ===                                   BUILD SUCCESSFUL
=== pr-gate: assemble ===                                       BUILD SUCCESSFUL
=== pr-gate: :skainet-test:skainet-test-java:test ===           BUILD SUCCESSFUL
pr-gate: all legs passed.

:skainet-apps:skainet-plan:test 3/3; installDist + smoke run on a synthetic llama GGUF (output in the description).

[michalharakal]

Rebased onto the updated base after #1053 merged into feature/1008-format-and-encoding (lang-core API dump regenerated; no source change). The chain is now: #1051 (Format + AllocationSpec) ← #1054 (TensorId) ← #1055 (NameMap) ← #1056 (MemoryPlan) ← #1057 (skainet-plan CLI); merging each into its base keeps the next one a single-commit diff.