HLO: IrpaWriter accepts FileBacked mmap handles on JVM/Android (PR E of #523)

[michalharakal]

Summary

• Wires BufferHandle.FileBacked into IrpaWriter. JVM and Android use FileChannel.map for zero-copy mmap transfer to the .irpa storage segment. Other targets throw with a pointer to follow-up work.
• The full ingestion pipeline is now zero-copy end-to-end: source file (GGUF / safetensors) → FileBacked handle (already produced by existing loadTensorStorageMapped methods) → IrpaWriter → .irpa bytes.

What's here

• expect fun writeFileBackedBytes in commonMain.
• JVM and Android actuals: RandomAccessFile + FileChannel.map + chunked copy into the kotlinx.io Sink. Kept as separate files until this module adopts a hierarchical jvmAndroidMain source set.
• Native / wasmJs / wasmWasi actuals: explicit NotImplementedError with a pointer to Design: externalize weights via IREE parameter archive (supersedes #519) #523 follow-up. Callers on those targets should resolve the handle to Owned / Borrowed before writing.
• IrpaWriter.writeBufferHandle dispatches FileBacked to the new seam.

Guardrails

• Rejects FileBacked.sizeInBytes > Int.MAX_VALUE — FileChannel.map can't return a single region larger than ~2 GiB. Multi-window streaming is a separate follow-up once a real model hits the limit.
• Zero-byte FileBacked is a no-op and does not open the source file.

What's NOT here

• No loader changes: both skainet-io-gguf and skainet-io-safetensors already expose loadTensorStorageMapped(filePath) that returns BufferHandle.FileBacked. The agent exploration showed this path existed; PR E only had to wire the consumer side.
• No multi-window mmap for >2 GiB tensors: guarded with a clear diagnostic, deferred.
• No Native mmap via cinterop: JVM/Android are the targets that matter for the current whisper deployment; native is a cleanup item.

Test plan

• FileBackedIrpaRoundTripTest.testFileBackedEntryBytesLandInStorageSegment — writes a known byte pattern to a temp file at a non-aligned offset, constructs a FileBacked ref over a sub-range, runs through IrpaWriter, verifies the .irpa storage segment contains source bytes verbatim.
• testFileBackedRejectsOversizedMap — pins the Int.MAX_VALUE guard.
• testFileBackedZeroLengthIsNoOp — pins that 0-byte refs don't open the file (uses a non-existent path to prove it).
• ./gradlew allTests green — 1047 tasks across jvm / android / ios / macos / linux / wasmJs / wasmWasi.

Part of #523. With this, PRs A–C + E are complete on the SKaiNET side. PR D (skainet-whisper caller wiring to flip policy → ExternalAlways → IrpaWriter) lives in the skainet-whisper repo and is the remaining step to actually close #519 end-to-end.

🤖 Generated with Claude Code