docs(skeep): SKEEP-003 amendment — deprecate-don't-delete migration rule + implementation slices (#782, #921)

[michalharakal]

Design-doc amendment for the SKEEP-003 draft (docs/modules/skeep/pages/003-unified-tensor-storage.adoc), anchoring #932. Docs-only.

The draft landed in #933 with the analysis and the two candidate end-states. This amendment adds what executing the first slice of it taught:

What changes

• Compatibility and Migration now states the binding rule explicitly: the 0.39.0 public API is preserved — deprecate, don't delete. Superseded entry points get @Deprecated + ReplaceWith (the existing GgufParametersLoader → StreamingGgufParametersLoader deprecation is the house pattern); changes to existing classes are additive-with-historical-defaults or implementation swaps behind an unchanged type. Zero-consumer dead code is the one exemption, with evidence required per PR.
• New "Implementation Slices" section making concrete how the open issues become slices of this proposal:
  • GGUF DEQUANTIZE_TO_FP32 over-allocates: 1.1B Q4_K_M needs >12 GB heap transiently (~4.4 GB legit) #782 (streaming dequant) — the staging stage of cross-cutting improvement 4, and a live demonstration of the "copy semantics are ambient" cost: the load path paid a full-size defensive copyOf for every tensor because ownership transfer isn't expressible in the creation API. Fixed concretely in the sibling PR (fix/782-dequant-overalloc).
  • Android tensor storage is ART-heap-bound: no off-heap / mmap path outside jvmMain caps practical model size (SKEEP candidate) #921 / SKEEP-002 (Android off-heap/mmap) — the mobile destination-placement stage, landing against whichever byte-owner survives the end-state decision.
  • TensorStorageFactory violates its own copy/borrow contracts: "zero-copy" borrowFloatArray copies, "borrowed" fromTensorData owns #927–Memory diagnostics: MemoryTracker.recordCopy discards the source label every caller passes; ActiveMemoryTracker is a mutable global #931 — recorded as landed (PRs fix(lang): rank-safe default TensorData.copyToFloatArray (#930) #934–fix(lang): per-source copy attribution in MemoryTracker; volatile ActiveMemoryTracker (#931) #938, shipped in 0.39.0), demonstrating the slice model.
• Motivation gains the measured copy-semantics cost from the GGUF DEQUANTIZE_TO_FP32 over-allocates: 1.1B Q4_K_M needs >12 GB heap transiently (~4.4 GB legit) #782 audit (defensive copyOf vs the wrapFloatArray borrow path; 41x boxed materialization in the legacy reader).
• Rollout plan and references updated accordingly.

The end-state question (storage-first vs data-first) remains deliberately open for maintainer discussion on #932 — this amendment only hardens the parts that are invariant under both.

Refs #932

🤖 Generated with Claude Code

[github-actions]

📖 Documentation Preview

The documentation has been built successfully for this PR.

Generated Files:

• Operator documentation: docs/modules/operators/_generated_/
• JSON schema output: operators.json

Artifacts:

• Download the documentation-preview-963 artifact to view the complete documentation locally.

This comment will be updated automatically when the PR is updated.