feat: initial release

Assisted-by: GLM 5.3 Flash

spmd/doc.go

@@ -0,0 +1,42 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: MIT
+
+// Package spmd runs one program on many ranks: explicit SPMD worlds
+// with the collectives of scientific distributed computing, over TCP
+// between machines or in process within one.
+//
+// # The determinism contract
+//
+// Every collective answers bit-identical results whatever the world
+// size, the machine, the worker count or the order messages arrive in.
+// The rule that buys this is one: the order of a reduction is a
+// function of the data, never of the topology. Family B reductions
+// (ReduceShards, AllReduceShards) cut the global length at the fold's
+// own block boundaries, fold each block where its elements live, and
+// combine the block partials with the same balanced tree the
+// single-array fold uses, so a sharded reduction and the single-array
+// Sum are one computation and one answer, for one rank or for fifty.
+// Family A reductions (Reduce, AllReduce) fold same-shaped arrays in
+// rank index order, which the program itself fixes. No collective
+// every combines partials in the order they happen to arrive.
+//
+// # Worlds
+//
+// Launch builds a world of size ranks in one process, one goroutine
+// per rank, over channels: the development surface, the test surface
+// and the single-machine surface. Listen and Join build the same world
+// over TCP, rank 0 listening and every other rank dialling; ranks are
+// assigned in dial order. The sharded reductions' results never
+// depend on the assignment; the same-shaped arrays' fold order is the
+// rank order the program fixes, so a program that wants bit-reproducible
+// family A runs keeps its rank assignment stable. Collectives are bulk synchronous: every rank calls the
+// same collective in the same order, as an MPI program does.
+//
+// Any failure, a deadline included, fails the whole world: the rank
+// that saw it and every rank that then touches the world or waits on
+// it receive an error, and no collective ever returns a partial
+// numeric result. A failed world stays failed.
+//
+// The package is pure Go on the standard library: no cgo, no
+// dependency, no build tag.
+package spmd