Memory architecture M0 — Know before you load (plan + identity, no runtime change)

[michalharakal]

Parent tracking issue for **M0 — Know before you load** of the SKEEP-003 memory architecture (umbrella: #932). Design docs: `docs/design/memory/memory-architecture-proposal.md` (proposal rev. 2, §-numbers below refer to it) and `docs/design/memory/memory-architecture-milestones-prd.md` (PRD, requirement IDs `Mx-Fy`/`Mx-Ay`) — both land with the SKEEP-003 docs PR; until merged they are attached to #932.

## Goal
Answer *will this model fit on this device at this context length?* from the GGUF header alone, give every weight a stable `TensorId`, and make every tensor report a coherent `Format(dtype, encoding)`. No runtime behaviour changes (existing benchmarks unchanged).

## Sample app / acceptance vehicle
`skainet-plan` CLI (`skainet-apps/skainet-plan`, JVM; planner in `commonMain` so Android/K-Native can call it): `skainet plan model.gguf --ctx 2048 --budget 1.3G` prints the resident breakdown, fit verdict and suggestions; `--list layers[3].*` prints `TensorId · Format · Shape · bytes · ← gguf name`.

## Consumes (proposal §9 phases)
P0 (two-way dtype bridge → `DType` merge, `StorageSpec` → allocation spec) · P1 partial (`Format` reported everywhere, `TensorId` + GGUF `NameMap`, `toString()` renderer).

## Acceptance criteria (PRD)
- M0-A1 plan for Llama-3.2-1B Q4_K_M @ ctx 2048 within ±10 % of measured resident memory (recorded now, verified at M1-A8)

• M0-A2 all tensors of Llama-3.2-1B, Qwen2.5-0.5B, Gemma-3-1B GGUFs map to TensorIds, zero unmapped

• M0-A3 Q4_K tensors report Format(FP32, Q4_K); no reader reports a packed tensor as Byte

• M0-A4 unit tests for plan arithmetic; golden plans for the three reference GGUFs

• M0-A5 existing benchmarks unchanged (no runtime code path touched)

  Slices (sub-issues, one feature branch each)

  Order = dependency order: docs (SKEEP-003 Accepted) → parity gate → dtype bridge → dtype witness → Format/encoding → AllocationSpec → TensorId → GGUF NameMap → MemoryPlan → skainet-plan CLI → LogicalDType deprecation → wrap-up.

  • [S0.10a] SKEEP-003 → Accepted: record the 13 decisions, commit proposal + PRD, link the roadmap #1004 (S0.10a)

• [S0.9] Golden parity gate + PR gate script + benchmark baseline (guards every memory-architecture slice) #1005 (S0.9)

• [S0.1] P0: two-way LogicalDType ↔ DType bridge (LogicalDType.toDType(), DType.toLogicalDType(), StorageSpec.dtype) #1006 (S0.1)

• [S0.2a] P0: DType carries its witness (DType.witness, fromWitness, entries); descriptors/readers report DType additively #1007 (S0.2a)

• [S0.4] P1: Format(dtype, encoding) + TensorData.encoding default member — every tensor reports its Format (Q4_K → F32/Q4_K) #1008 (S0.4)

• [S0.3] P0: AllocationSpec replaces zero-consumer StorageSpec (deprecated with ReplaceWith) #1009 (S0.3)

• [S0.5] P1: TensorId — structured identity from the module tree, canonical string, toString() renderer #1010 (S0.5)

• [S0.6] P1: GGUF NameMap — GGUF/HF names ↔ TensorId for Llama-3, Qwen2.5, Gemma-3; unmapped names listed #1011 (S0.6)

• [S0.7] P1/M0: MemoryPlan from the GGUF header — weights, KV (bf16/TurboQuant), Forward slab, headroom, budget, fit check, suggestions #1012 (S0.7)

• [S0.8] M0 sample: skainet-plan CLI (plan <gguf> --ctx --budget --list) #1013 (S0.8)

• [S0.2b] P0: deprecate LogicalDType (ReplaceWith → DType), logicalType getters; keep primary ctors until next major #1014 (S0.2b)

• [S0.10b] M0 wrap-up: record plan numbers for M1-A8, CHANGELOG, close the tracker #1015 (S0.10b)

The checklist is maintained by GitHub's sub-issue tracking on this issue.

Working rules (every slice)

• One slice = one branch feature/<this-issue#>-<slug> from develop = one PR (Closes #<this issue>), merged independently.
• develop stays usable after merge: additive API or behind façade / opt-in; no default behaviour switch without golden-parity + benchmark evidence in the PR; deprecate with ReplaceWith, never delete before a major (zero-consumer dead code may be removed with evidence in the PR). No new abstract members on TensorData/KernelProvider (defaults only); no data-class primary-constructor changes (secondary ctors only); BCV: apiDump both api/jvm and api/android, apiCheck clean.
• Test gate before the PR (JDK 25, scripts/pr-gate.sh once it exists): ./gradlew jvmTest linuxX64Test assemble, ./gradlew verifyNpmPins jsTest wasmJsTest wasmWasiTest, ./gradlew apiCheck, ./gradlew :skainet-test:skainet-test-java:test; storage/backend slices add :skainet-lang:skainet-lang-core:jvmBenchmark and :skainet-backends:benchmarks:jvm-cpu-jmh:jmh before/after when a hot path changes.
• Commits: conventional commit subject, Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> trailer. Do not edit CHANGELOG.md in slice PRs (parallel branches conflict on it; release notes are written at release time from the merged PRs).