01 · Problem
What is it for?
Broadcast work must not discard successful responses when one endpoint fails.
02 · Mental model
How should you think about it?
A manager owns uniquely identified endpoints; transport is an adapter around each endpoint's execution contract.
Broadcasts to bounded, uniquely identified local worker endpoints and preserves partial success. The verified core is local orchestration. Remote execution, authentication, retries and heartbeats require a network adapter.
03 · Control flow
What happens in which order?
- Register a uniquely named endpoint.
- Reject duplicates and capacity overflow.
- Dispatch a payload to the current endpoints.
- Collect successes and failures independently.
- Unregister stopped endpoints.
04 · Building blocks
The important contracts
Manager.registerNode / unregisterNodeMaintain a bounded unique endpoint registry.Manager.broadcastCollect per-endpoint successes and errors.Worker.executeRun a local typed handler.05 · Build it yourself
Implement a small core
Start with this small independent implementation, then use the steps below to make its contract explicit.
- Register a uniquely named endpoint.
- Reject duplicates and capacity overflow.
- Dispatch a payload to the current endpoints.
- Collect successes and failures independently.
- Unregister stopped endpoints.
type Node = { id: string; send(message: Uint8Array): Promise<Uint8Array> };
class Swarm {
private nodes = new Map<string, Node>();
connect(node: Node) { this.nodes.set(node.id, node); }
disconnect(id: string) { this.nodes.delete(id); }
broadcast(message: Uint8Array) {
return Promise.allSettled(
[...this.nodes.values()].map((node) => node.send(message)),
);
}
}06 · Verify
What should you test?
- Preserve one success when another worker rejects.
- Reject duplicate worker IDs and excess capacity.
- Test unregistering and broadcasting to an empty group.
Try it yourself
Turn the first verification claim into a failing test, implement the smallest fix, then add a boundary case.
Preserve one success when another worker rejects.
Compare your approach
Your check should fail when the stated invariant is deliberately broken, and pass again after the fix. Keep setup deterministic and assert an observable result.
07 · Limits
Trade-offs and failure modes
- This core does not provide remote execution.
- A network transport needs authentication, framing and heartbeats.
- Retries need task identity and idempotence.
The verified core is local orchestration. Remote execution, authentication, retries and heartbeats require a network adapter.
08 · Keep exploring
Source code and related ideas
yarn tsx packages/swarm/examples/basic.ts