feat: build on Windows via portable *os.File positional I/O

The core write/read paths imported golang.org/x/sys/unix (unix.Pwrite/Pread
on cached raw int fds), as did platform_other.go, so the library failed to
compile on Windows — breaking any downstream module that imports it on a
Windows runner.

Replace the raw-fd syscalls with *os.File.WriteAt/ReadAt, which map to
pwrite/pread on Unix and OVERLAPPED I/O on Windows and preserve the lock-free
concurrent positioned-write property (Go's internal/poll uses incref, not a
write lock, for positional I/O). Change preallocFile to take *os.File and route
the !linux && !darwin fallback through os.File.Truncate, which needs no unix
import and also covers Windows, so no dedicated platform_windows.go is required.
Only platform_linux.go (fallocate) and platform_darwin.go (F_PREALLOCATE) still
use x/sys/unix.

Result: the sorted builder and all query/read paths build and work on Windows.
The unsorted builder still relies on the POSIX unlink-while-open idiom for its
temp files, which Windows rejects, so NewUnsortedBuilder is unsupported there.

Benchmarks (10M keys, ptrhash, 7 iters, before/after) show build throughput
unchanged within noise: sorted +1.8%, unsorted +1.3%, unsorted cw=4 +3.0%
medians — all within the ~5% band. The added WriteAt/ReadAt cost is a couple of
atomic refcount ops per syscall, dwarfed by the ~µs syscall.

Windows compilation verified via GOOS=windows cross-compile; CI still runs
ubuntu + macos only.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tamirms

CLAUDE.md

@@ -25,9 +25,13 @@ Three build paths: `NewSortedBuilder` (sorted input), `NewUnsortedBuilder`
 
 ## Platform
 
-Unix-only: `platform_{linux,darwin,other}.go` all import `golang.org/x/sys/unix`
-(for `fallocate`/`fcntl`), so the library does **not** build on Windows. CI runs
-on ubuntu + macos only.
+`platform_linux.go` and `platform_darwin.go` use `golang.org/x/sys/unix` (for
+`fallocate`/`fcntl`); the `platform_other.go` fallback (`!linux && !darwin`,
+which also covers Windows) uses only `os.File.Truncate`. The library compiles
+for Windows (cross-compile verified; **not** yet exercised in CI), and the
+sorted builder plus all query/read paths work there. The unsorted builder
+(`NewUnsortedBuilder`) relies on the POSIX unlink-while-open idiom, which Windows
+rejects, so it is unsupported there. CI runs on ubuntu + macos only.
 
 ## Concurrency
 

builder_unsorted.go

@@ -12,8 +12,6 @@ import (
 	"sync/atomic"
 	"unsafe"
 
-	"golang.org/x/sys/unix"
-
 	intbits "github.com/stellar/streamhash/internal/bits"
 	"github.com/stellar/streamhash/internal/sherr"
 )
@@ -124,7 +122,6 @@ type unsortedBuffer struct {
 	numWriters    int        // total writer count (from config)
 	regionSize    int64      // bytes per partition region per writer file
 	writerFiles   []*os.File // [numWriters]
-	writerFds     []int      // [numWriters] fd cache for pwrite/pread
 	writerCursors [][]int64  // [numWriters][numPartitions] byte offset within region
 	nextWriterID  int        // next writerID to assign
 	writerMu      sync.Mutex // protects nextWriterID
@@ -206,7 +203,6 @@ func newUnsortedBuffer(cfg *buildConfig, numBlocks uint32, numWriters int) (*uns
 		numWriters:       numWriters,
 		regionSize:       regionSize,
 		writerFiles:      make([]*os.File, numWriters),
-		writerFds:        make([]int, numWriters),
 		writerCursors:    make([][]int64, numWriters),
 	}
 	for w := range numWriters {
@@ -240,20 +236,21 @@ func (u *unsortedBuffer) createWriterFiles(tempDir string) error {
 			os.RemoveAll(dir)
 			return fmt.Errorf("create writer %d: %w", w, err)
 		}
-		if err := preallocFile(int(f.Fd()), fileSize); err != nil {
+		if err := preallocFile(f, fileSize); err != nil {
 			f.Close()
 			u.closeWriterFiles()
 			os.RemoveAll(dir)
 			return fmt.Errorf("fallocate writer %d (%d bytes): %w", w, fileSize, err)
 		}
+		// Unlink while open (POSIX anonymous-file idiom): the handle keeps the
+		// data reachable. Windows rejects this, so unsorted is unsupported there.
 		if err := os.Remove(path); err != nil {
 			f.Close()
 			u.closeWriterFiles()
 			os.RemoveAll(dir)
 			return fmt.Errorf("unlink writer %d: %w", w, err)
 		}
 		u.writerFiles[w] = f
-		u.writerFds[w] = int(f.Fd())
 	}
 
 	// All files are unlinked — remove the now-empty temp directory.
@@ -399,9 +396,9 @@ func (ws *writerState) doFlush(bufIdx int) error {
 			return fmt.Errorf("partition %d overflow in writer %d: region capacity exceeded", p, ws.writerID)
 		}
 
-		_, err := unix.Pwrite(u.writerFds[ws.writerID], buf[:needed], off)
+		_, err := u.writerFiles[ws.writerID].WriteAt(buf[:needed], off)
 		if err != nil {
-			return fmt.Errorf("pwrite partition %d writer %d: %w", p, ws.writerID, err)
+			return fmt.Errorf("write partition %d writer %d: %w", p, ws.writerID, err)
 		}
 
 		u.writerCursors[ws.writerID][p] = cursor + int64(needed)
@@ -429,10 +426,8 @@ func (ws *writerState) flushAll() error {
 }
 
 // drainFlush waits for any in-flight background flush goroutine to finish.
-// Abort paths (Close/cleanupAll) must call this before closing the writer's fd:
-// doFlush issues unix.Pwrite on the cached fd from a background goroutine, so
-// closing the fd while that goroutine is mid-write races a closed (and possibly
-// recycled) descriptor. The normal Finish path drains via flushAll instead.
+// Abort paths (Close/cleanupAll) must drain before closing the file, or a
+// background WriteAt aborts with ErrClosed and drops its data.
 func (ws *writerState) drainFlush() {
 	ws.flushWg.Wait()
 }

builder_unsorted_finish.go

@@ -5,12 +5,11 @@ import (
 	"encoding/binary"
 	"errors"
 	"fmt"
+	"io"
 	"math/bits"
 	"sync"
 	"unsafe"
 
-	"golang.org/x/sys/unix"
-
 	intbits "github.com/stellar/streamhash/internal/bits"
 	"github.com/stellar/streamhash/internal/sherr"
 )
@@ -93,7 +92,7 @@ func (u *unsortedBuffer) readPartition(p int, slot *readSlot) ([][]routedEntry,
 		if regionBytes == 0 {
 			continue
 		}
-		if err := u.readRegion(u.writerFds[w], regionStart, regionBytes, readBuf, entrySize,
+		if err := u.readRegion(u.writerFiles[w], regionStart, regionBytes, readBuf, entrySize,
 			func(data []byte) {
 				k0 := binary.LittleEndian.Uint64(data[0:8])
 				k1 := binary.LittleEndian.Uint64(data[8:16])
@@ -113,21 +112,18 @@ func (u *unsortedBuffer) readPartition(p int, slot *readSlot) ([][]routedEntry,
 	return blockEntries, nil
 }
 
-// readRegion reads regionBytes from fd at offset using pread, calling fn for
-// each entry. Uses pread (not seek+read) for concurrent reader safety.
-func (u *unsortedBuffer) readRegion(fd int, offset, regionBytes int64, readBuf []byte, entrySize int, fn func([]byte)) error {
+// readRegion reads regionBytes from r at offset and invokes fn for each
+// fixed-size entry. ReadAt is positional, so readers can share one source.
+func (u *unsortedBuffer) readRegion(r io.ReaderAt, offset, regionBytes int64, readBuf []byte, entrySize int, fn func([]byte)) error {
 	pos := offset
 	remaining := regionBytes
 	leftoverN := 0
 
 	for remaining > 0 {
 		toRead := min(int64(len(readBuf)-leftoverN), remaining)
-		nr, err := unix.Pread(fd, readBuf[leftoverN:leftoverN+int(toRead)], pos)
-		if nr == 0 {
-			if err != nil {
-				return err
-			}
-			return fmt.Errorf("pread: unexpected zero read at offset %d with %d remaining", pos, remaining)
+		nr, err := r.ReadAt(readBuf[leftoverN:leftoverN+int(toRead)], pos)
+		if int64(nr) != toRead {
+			return fmt.Errorf("readRegion: short read at offset %d: got %d of %d bytes (%d remaining): %w", pos, nr, toRead, remaining, err)
 		}
 		pos += int64(nr)
 		remaining -= int64(nr)
@@ -143,10 +139,6 @@ func (u *unsortedBuffer) readRegion(fd int, offset, regionBytes int64, readBuf [
 		if len(data) > 0 {
 			leftoverN = copy(readBuf, data)
 		}
-
-		if err != nil {
-			return err
-		}
 	}
 	return nil
 }

index_writer.go

@@ -8,14 +8,12 @@ import (
 	"os"
 
 	"github.com/cespare/xxhash/v2"
-	"golang.org/x/sys/unix"
 )
 
-// indexWriter handles writing index data to disk using pwrite-based writes.
+// indexWriter writes index data to disk via positional *os.File.WriteAt calls.
 // File layout: [Header 64B][UserMetaLen 4B][UserMeta][AlgoConfigLen 4B][AlgoConfig][RAM Index (N+1)×10B][Payload Region][Metadata Region][Footer 32B]
 type indexWriter struct {
 	file *os.File
-	fd   int // cached file descriptor for pwrite syscalls
 
 	// Region offsets (computed upfront for separated layout)
 	payloadRegionOffset  uint64
@@ -84,14 +82,13 @@ func newIndexWriter(path string, cfg *buildConfig, numBlocks uint32, algo blockB
 	metadataRegionOffset := payloadRegionOffset + payloadRegionSize
 
 	// Pre-allocate disk blocks for space reservation
-	if err := preallocFile(int(file.Fd()), int64(estimatedSize)); err != nil {
+	if err := preallocFile(file, int64(estimatedSize)); err != nil {
 		primaryErr := fmt.Errorf("failed to allocate disk space: %w", err)
 		return nil, errors.Join(primaryErr, file.Close())
 	}
 
 	iw := &indexWriter{
 		file:                 file,
-		fd:                   int(file.Fd()),
 		payloadRegionOffset:  payloadRegionOffset,
 		metadataRegionOffset: metadataRegionOffset,
 		userMetadataOffset:   userMetadataOffset,
@@ -136,7 +133,7 @@ func (iw *indexWriter) writePayloadsDirect(data []byte, offset uint64) error {
 	if absoluteOffset+uint64(len(data)) > iw.metadataRegionOffset {
 		return fmt.Errorf("writePayloadsDirect: write exceeds payload region boundary")
 	}
-	_, err := unix.Pwrite(iw.fd, data, int64(absoluteOffset))
+	_, err := iw.file.WriteAt(data, int64(absoluteOffset))
 	return err
 }
 
@@ -165,7 +162,7 @@ func (iw *indexWriter) recordAndWriteMetadata(metadata []byte) error {
 	})
 
 	if len(metadata) > 0 {
-		if _, err := unix.Pwrite(iw.fd, metadata, int64(iw.metadataWriteOffset)); err != nil {
+		if _, err := iw.file.WriteAt(metadata, int64(iw.metadataWriteOffset)); err != nil {
 			return err
 		}
 		if _, err := iw.metadataHasher.Write(metadata); err != nil {
@@ -202,7 +199,7 @@ func (iw *indexWriter) commitBlockWithData(metadata []byte, payloads []byte, num
 	entrySize := iw.cfg.payloadSize + iw.cfg.fingerprintSize
 	if entrySize > 0 && numKeys > 0 {
 		payloadOffset := iw.payloadRegionOffset + iw.keyCount*uint64(entrySize)
-		if _, err := unix.Pwrite(iw.fd, payloads, int64(payloadOffset)); err != nil {
+		if _, err := iw.file.WriteAt(payloads, int64(payloadOffset)); err != nil {
 			return err
 		}
 		iw.foldPayloadHash(xxhash.Sum64(payloads))
@@ -245,7 +242,7 @@ func (iw *indexWriter) finalize() error {
 	// Write header at offset 0
 	var headerBuf [headerSize]byte
 	iw.header.encodeTo(headerBuf[:])
-	if _, err := unix.Pwrite(iw.fd, headerBuf[:], 0); err != nil {
+	if _, err := iw.file.WriteAt(headerBuf[:], 0); err != nil {
 		primaryErr := fmt.Errorf("write header failed: %w", err)
 		return errors.Join(primaryErr, iw.close())
 	}
@@ -255,7 +252,7 @@ func (iw *indexWriter) finalize() error {
 	userMetaBuf := make([]byte, 4+len(iw.userMetadata))
 	binary.LittleEndian.PutUint32(userMetaBuf, uint32(len(iw.userMetadata)))
 	copy(userMetaBuf[4:], iw.userMetadata)
-	if _, err := unix.Pwrite(iw.fd, userMetaBuf, int64(iw.userMetadataOffset)); err != nil {
+	if _, err := iw.file.WriteAt(userMetaBuf, int64(iw.userMetadataOffset)); err != nil {
 		primaryErr := fmt.Errorf("write user metadata failed: %w", err)
 		return errors.Join(primaryErr, iw.close())
 	}
@@ -267,7 +264,7 @@ func (iw *indexWriter) finalize() error {
 	if algoConfigLen > 0 {
 		iw.algo.EncodeGlobalConfigInto(algoConfigBuf[4:])
 	}
-	if _, err := unix.Pwrite(iw.fd, algoConfigBuf, int64(iw.algoConfigOffset)); err != nil {
+	if _, err := iw.file.WriteAt(algoConfigBuf, int64(iw.algoConfigOffset)); err != nil {
 		primaryErr := fmt.Errorf("write algo config failed: %w", err)
 		return errors.Join(primaryErr, iw.close())
 	}
@@ -278,7 +275,7 @@ func (iw *indexWriter) finalize() error {
 		offset := i * int(ramIndexEntrySize)
 		encodeRAMIndexEntryTo(entry, ramIndexBuf[offset:])
 	}
-	if _, err := unix.Pwrite(iw.fd, ramIndexBuf, int64(iw.ramIndexOffset)); err != nil {
+	if _, err := iw.file.WriteAt(ramIndexBuf, int64(iw.ramIndexOffset)); err != nil {
 		primaryErr := fmt.Errorf("write RAM index failed: %w", err)
 		return errors.Join(primaryErr, iw.close())
 	}
@@ -290,7 +287,7 @@ func (iw *indexWriter) finalize() error {
 	}
 	var footerBuf [footerSize]byte
 	ftr.encodeTo(footerBuf[:])
-	if _, err := unix.Pwrite(iw.fd, footerBuf[:], int64(iw.metadataWriteOffset)); err != nil {
+	if _, err := iw.file.WriteAt(footerBuf[:], int64(iw.metadataWriteOffset)); err != nil {
 		primaryErr := fmt.Errorf("write footer failed: %w", err)
 		return errors.Join(primaryErr, iw.close())
 	}

platform_darwin.go

@@ -2,7 +2,11 @@
 
 package streamhash
 
-import "golang.org/x/sys/unix"
+import (
+	"os"
+
+	"golang.org/x/sys/unix"
+)
 
 // preallocFile pre-allocates disk blocks without changing the file size.
 // On macOS, uses fcntl F_PREALLOCATE to reserve contiguous blocks.
@@ -11,12 +15,12 @@ import "golang.org/x/sys/unix"
 // on sparse pre-allocated files. ftruncate would be slightly faster (~1.7μs)
 // but causes page cache pressure proportional to file size, which thrashes
 // under memory pressure.
-func preallocFile(fd int, size int64) error {
+func preallocFile(f *os.File, size int64) error {
 	fst := unix.Fstore_t{
 		Flags:   unix.F_ALLOCATEALL,
 		Posmode: unix.F_PEOFPOSMODE,
 		Offset:  0,
 		Length:  size,
 	}
-	return unix.FcntlFstore(uintptr(fd), unix.F_PREALLOCATE, &fst)
+	return unix.FcntlFstore(f.Fd(), unix.F_PREALLOCATE, &fst)
 }

platform_linux.go

@@ -2,9 +2,13 @@
 
 package streamhash
 
-import "golang.org/x/sys/unix"
+import (
+	"os"
+
+	"golang.org/x/sys/unix"
+)
 
 // preallocFile pre-allocates disk blocks and extends the file to the given size.
-func preallocFile(fd int, size int64) error {
-	return unix.Fallocate(fd, 0, 0, size)
+func preallocFile(f *os.File, size int64) error {
+	return unix.Fallocate(int(f.Fd()), 0, 0, size)
 }

platform_other.go

@@ -2,11 +2,11 @@
 
 package streamhash
 
-import "golang.org/x/sys/unix"
+import "os"
 
-// preallocFile extends the file to the given size.
-// Fallback for platforms without fallocate: uses ftruncate to set file size
-// so pwrite has allocated blocks to write into.
-func preallocFile(fd int, size int64) error {
-	return unix.Ftruncate(fd, size)
+// preallocFile extends the file to the given size. Fallback for platforms
+// without a specialized prealloc syscall (other Unixes, Windows); unlike
+// fallocate, Truncate leaves the file sparse rather than reserving blocks.
+func preallocFile(f *os.File, size int64) error {
+	return f.Truncate(size)
 }