docs(skeep): SKEEP-003 draft — unifying the tensor storage model (#932) - #933
Merged
Merged
Conversation
TensorData (live, marker-downcast dispatch, heap arrays) and TensorStorage (designed descriptor layer: BufferHandle ownership variants, Placement, TensorEncoding, MemoryPlanner) are parallel abstractions; the second has almost no production consumers. The draft lays out the costs of the split (unenforced ownership after the documented arena-OOM retreat, two disconnected view systems, three type representations with packed tensors erasing their logical dtype, placement machinery never consulted) and two candidate end-states — storage-first vs data-first — deliberately without a recommendation; the trade-off is left to maintainer discussion. Cross-cutting improvements proposed under either outcome: scoped lifetimes keyed off the existing Residency vocabulary, one view mechanism, explicit logical-dtype + encoding pairs, IO/staging as one pipeline (including a Kotlin Multiplatform feasibility assessment of a ZML-style userland file-system layer over the existing RandomAccessSource seam), and placement consulted at creation. Hard constraint: the packed-encoding system and its StableHLO metadata export must survive bit-identically. Registered in nav.adoc and the index proposal table as Draft. Refs #932
|
📖 Documentation Preview The documentation has been built successfully for this PR. Generated Files:
Artifacts:
This comment will be updated automatically when the PR is updated. |
Resolve nav.adoc and index.adoc conflicts with the merged SKEEP-002 (PR #926): keep both proposal entries in numeric order.
|
📖 Documentation Preview The documentation has been built successfully for this PR. Generated Files:
Artifacts:
This comment will be updated automatically when the PR is updated. |
aharakal
approved these changes
Aug 10, 2026
This was referenced Aug 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design proposal (Status: Draft) anchoring the discussion in #932. Docs-only: the SKEEP + registration in
nav.adocand the index table.What it addresses
TensorData(live: everyTensorholds one, backends dispatch by downcasting to concrete classes, all common-code storage is heap arrays) andTensorStorage(designed:BufferHandle.{Owned,Borrowed,Aliased,FileBacked,DeviceResident},Placement,TensorEncoding,MemoryPlanner) are parallel layers — the second directs new code to target it, but noTensorever holds one and most of it has no production consumer. The draft documents the recurring costs: ownership recorded but never enforced (with the arena-OOM history rediagnosed as a missing weights-vs-activations lifetime split), two disconnected view systems, three type representations with packed tensors erasing their logical dtype (Q4_KTensorData : TensorData<DType, Byte>), and placement machinery never consulted at allocation.What it proposes
TensorDataas typed views, dispatch on dtype+encoding) vs data-first (absorb the useful vocabulary, retire the parallel layer). The trade-off is explicitly a maintainer decision; both share two small prerequisites (two-wayLogicalDTypebridge; settleStorageSpec's fate).Residency), one view mechanism, logical-dtype + encoding coherence, IO/staging as one pipeline — including a Kotlin Multiplatform feasibility assessment of a userland file-system layer (verdict: read path feasible over the existingRandomAccessSourceseam; direct-IO is platform-gated with no Apple equivalent; DMA-pinned staging has no portable form and is deferred; JS/Wasm force asuspendsource variant) — and placement consulted at creation.skainet.tensor_encodingsexport) is ahead of comparable frameworks and must survive bit-identically.Mechanical bugs found in the same audit are filed independently (#927–#931) and are fixable under either end-state.
Sibling: SKEEP-002 (PR #926) is the mobile/mmap slice of the IO pipeline improvement; the two proposals compose but neither depends on the other.
Refs #932