[teeny] Phase 0: write the tensor-native boundary convention into TEENY-MIGRATION.md

[balbasty]

Agent: claude-fastfields-to-teeny

Part of the tensor-native-boundaries umbrella (#57), Phase 0. Docs-only PR on the teeny branch of this repo. This is the reference every Phase A/B implementer codes against, so it lands before Phase A.

What to write

A new section in TEENY-MIGRATION.md (living doc — this is its next chapter after the §8 pushpull entry), titled along the lines of "Tensor-native call boundaries (the umbrella-#57 convention)", containing:

1. The three-carrier table (from #57): fixed-rank teeny views kernels↔impl; typed anyrank carriers impl↔*-lib; DLTensor at the exported-ABI edge and above, unchanged. State explicitly that posdef's matrix.h and pushpull's vox:: are the existing in-tree models for tier 1, and cuda-impl's _matvec_*_k(AO, AI, …) __global__ signatures for anyrank-by-value.

2. The rules (each one sentence + the reason, so they survive being read in isolation):

• Carrier-only refactor: runtime→static dispatch (dtype, offset width, D, order, bound) stays at the *-lib layer; impl entries keep their template parameters. Never move dispatch down into impl (dispatch_rank/fixed<R> at impl level was evaluated and rejected — distance-slice review Candidate B).
• Derive, don't pass: no nbatch/nc/size[]/stride[] arguments where a carrier makes them derivable (nbatch = out.rank() - D - 1, nc = out.shape(-1)).
• Each tensor carries its own metadata — no shared size array across operands (kills the _dt_spline_* copy_if_needed-length bug class).
• Const-correctness through the boundary: read-only operands are anyrank<const T> / views of const T (probed against current teeny, both compilers: imports and peels fine, write-through is a compile error).
• D1: no int32 offset dispatch on CPU (measured a wash); GPU narrows whole-carrier host-side via anyrank: whole-carrier offset-width narrowing — index_fits/reindex on the carrier (+ optional narrowing DLPack import) balbasty/teeny#467 once shipped, autocast.h survives on the cuda-lib narrowing path only until then.
• Device carriers stay trimmed: as_anyrank<FF_*_MAX_RANK, storage::gpu_view>(..., copy_meta) — kernel-parameter budget; the existing cuda-impl pattern is the rule, not an accident.
• DLPack header include order: fastfields' vendored dlpack.h (v1.2) before <teeny/dlpack.h> (teeny vendors v1.1; the guards unify on DLPACK_DLPACK_H_, v1.2 is a pure superset, and whichever is first wins — so fastfields-first keeps both TUs on v1.2).

3. The per-phase performance gate, verbatim from #57 (byte-identical instantiations for untouched functions at -O2; disassembly diff with "no new instructions in the per-element loop" for re-skinned drivers; oracle check counts unchanged on clang++ AND g++ with a true make clean between; asan/ubsan; nvcc compile+link for CUDA).

4. Roadmap update: add the #57 phase list to the §4-style status tracking, and mark the §2 layer-mapping row for cpu-lib ("from_dlpack + dispatch_index, no autocast macros") as now actually being executed by this umbrella — it was planned in 2026-07 and never done.

Scope

TEENY-MIGRATION.md only (plus a one-line pointer from CLAUDE.md's pointers section if it doesn't already reach it). No code. Keep it lean — the umbrella carries the narrative; the doc carries the rules an implementer needs mid-PR.

---

Generated by Claude Code