// 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