aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/remakes.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-17 13:50:58 +0000
committertv <tv@krebsco.de>2026-11-17 15:04:35 +0100
commit6ceaa7d464650ddef79870a94ad6e121f2955763 (patch)
tree4ced5372a72754d3e15fa08fda97d384f3d86798 /docs/guides/federation/remakes.md
parenta9d8da21897817206abd1e750395c88a7d103deb (diff)
guides: remakes under a federation
Compactions only, the electorate among the store's members, the snapshot holding the store read at the base, what a node puts again after a switch, the lower of two epochs, which epochs a node rejoins, and a swarm that never remakes.
Diffstat (limited to 'docs/guides/federation/remakes.md')
-rw-r--r--docs/guides/federation/remakes.md62
1 files changed, 62 insertions, 0 deletions
diff --git a/docs/guides/federation/remakes.md b/docs/guides/federation/remakes.md
new file mode 100644
index 0000000..ef60266
--- /dev/null
+++ b/docs/guides/federation/remakes.md
@@ -0,0 +1,62 @@
+# Remakes under a federation
+
+A remake moves a swarm to a new document, for Automerge's sake only: the store needs
+none, and its events stay what they are. A federated swarm takes compactions only. How a
+remake runs is as in any swarm ([`remakes.md`](../../remakes.md)); this guide says what is
+otherwise. The rules are the store's ([`store.md`](../../store.md), Remakes).
+
+## Proposing one
+
+```sh
+curl -u tv:secret -X POST -H 'Content-Type: application/json' \
+ --data '{"kind": "compact"}' localhost:3000/admin/remakes
+```
+
+Any other kind is refused (`400`: `a swarm holding a store takes compactions only`).
+Every user a node lets in may propose one there. The electorate is the members whose
+alive stamp is recent, as in any swarm, but only those the store names as members, with
+the party their entries name: another node's entry counts for nothing. The acks tell an
+honest coordinator when to commit, and bind nobody.
+
+## The snapshot
+
+Every node builds the snapshot itself, from the base it holds: the store as it reads the
+document up to the base, from the document's checkpoint, by its own refusals and drops.
+It holds the checkpoint the store reached there (where it isn't the root) at
+`_continuum/checkpoint`, the events that checkpoint keeps and those after it, and of
+continuum's protocol data what a compaction carries, but the entries of nodes that
+aren't members. What that checkpoint forgot, and events nobody takes, leave the
+document here. A node reading its store anew starts at the document's checkpoint.
+
+Nodes that read the store differently at the base, the sides of keys that voted twice,
+build different snapshots, and part here.
+
+## After the switch
+
+A node puts again what the new document lacks: what it holds beyond the base, and, where
+it moved to a later checkpoint since the base, what the old document holds that the new
+one's store needs to reach that checkpoint (`Of the document left, events to put again`,
+`Put again events the document lacked`). It replays no events: they are put again as they
+were.
+
+## Two epochs for one
+
+Of two epochs decided for one, by a coordinator that wrote two decisions or by remakes
+decided at once, a node follows the one with the lower ID, and a node on the other
+rejoins it.
+
+## Rejoining
+
+A node that was away, lacks the base, or is on the higher of two epochs rejoins, but only
+an epoch whose snapshot holds its document's checkpoint, one it builds from that
+document, one its operator pins (`--store-checkpoint`), or, to an empty document, the
+root; and only one with its swarm's policy. A made-up epoch can withhold events from a
+node and keep it apart from the others, but make it take nothing it wouldn't. A node
+that can't follow the others' epoch, as its snapshot holds a checkpoint it can't build,
+follows it once its operator pins that checkpoint
+([`checkpoints.md`](checkpoints.md), Nodes that weren't there).
+
+## Without remakes
+
+A swarm that never remakes holds what one that remakes all the time holds; its document
+only grows. Nothing in the federation waits on a remake.