[S1.11] M1 sample: decide the home of `skainet-decode` (SKaiNET core vs SKaiNET-transformers), then build the CLI + Android activity

[michalharakal]

Sub-issue of #1002 · Phase M1 · Milestone M1 · PRD: M1-A1, M1-A2, M1-A3, M1-A5, M1-A7 · Proposal: PRD §5.3
Branch: feature/1032-decode-sample-home

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.

Task

• Decision first: the Llama decode loop, MultiHeadAttention, PreTransposed* weights live in SKaiNET-transformers; SKaiNET core has no transformer model. Options: (a) skainet-decode + Android activity in SKaiNET-transformers llm-apps against a SKaiNET snapshot (cross-repo issue), (b) a minimal Llama decode sample inside skainet-apps (duplicates layer code), (c) both (core synthetic-model harness + transformers end-to-end). Record the decision here and on the M1 tracker.
• Then: prefill on a fixed prompt, N decode tokens, before/after table (peak RSS during load, RSS@1000, allocations/step, rank-1 decode on Q4_K, adapters/step, TTFT, tok/s, effective bandwidth), Perfetto trace; Android: Compose activity with one text field + button (first Compose usage — new pattern).

Acceptance

M1-A1/A2/A3/A5/A7 measured and posted in the release notes table.

Depends on

#1021 (S1.2), #1024 (S1.4b), S1.7c, #1025 (S1.5b), #1030 (S1.9).

Keeps develop green by

Sample app / cross-repo; no core behaviour change.

Working rules (every slice)

• One slice = one branch feature/1032-<slug> from develop = one PR (Closes #1032), 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).

[michalharakal]

Decision (2026-08-23): both homes — option (c)

The constraint: SKaiNET core has no transformer model. The Llama/Qwen/Gemma layer stacks, the generation loop, PreTransposedQ4_K and KLlamaJava live in SKaiNET-transformers. M1's acceptance criteria need a model running, but the memory code they exercise changes here.

So the sample is split by what each half is for:

1. skainet-decode-harness in SKaiNET core (this repo, first). A synthetic decode loop — a Llama-shaped stack of matmuls over the real memory machinery: mapped/packed weights in Scope.Model, activations from a recycled ForwardScope, dispatch through KernelDispatch, events into a RecordingTraceSink. It has no tokenizer, no sampling and no real checkpoint, so it can run on every PR and assert the criteria that are about memory behaviour:

• M1-A1 flat RSS: live bytes at step 1000 within 1 % of step 50 (from the event stream, plus RSS where the platform exposes it);
• M1-A3 zero forward-scope allocations per step after warm-up;
• M1-A8 plan-vs-actual within 10 % (feat(memory): plan-vs-actual — reconstruct a run's memory from the event stream and fail on drift (SKEEP-003 P2, S1.9) #1074);
• M1-A7 a Perfetto trace with one track per scope and a flat live-bytes counter (feat(memory): trace exporters — Perfetto/Chrome JSON, JFR events, android.os.Trace (SKEEP-003 P2, S1.5b) #1073).

2. skainet-decode in SKaiNET-transformers (follow-up, cross-repo). The real thing: a GGUF Llama-3.2-1B, prefill + N decode tokens, the before/after table (peak load RSS, RSS@1000, allocations/step, adapters/step, TTFT, tok/s, effective bandwidth) and the Perfetto screenshot for the release notes — i.e. M1-A2, A5 and the published numbers, produced in the repo that owns the model, against a SKaiNET snapshot.

Rationale: the CI gate belongs where the memory code lives, the headline benchmark belongs where the model lives, and neither repo has to duplicate the other's code. The Android activity goes with (2).

This issue tracks (1); a cross-repo issue will be filed for (2) once (1) lands and pins the API the sample uses.