aboutsummaryrefslogtreecommitdiffstats
path: root/docs/remakes.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-18 12:48:29 +0000
committertv <tv@krebsco.de>2026-11-18 13:59:42 +0100
commitd130c0612b4c63f2d30da65ebcc231018c1f2606 (patch)
tree8700f2d53351cbbecbe772ea7701bf6240d5210c /docs/remakes.md
parent0bfe07af92a775b0e896e0fc5a989a1d9b65f7b3 (diff)
docs: references to another document's section linked to it
Where a document names a section of another after linking to it ("([`store.md`](store.md), Pinned checkpoints)"), the name links to that section too, by the id both GitHub and cgit's about filter give its heading; paragraphs that grew past the width are wrapped anew, links and code kept on one line each.
Diffstat (limited to 'docs/remakes.md')
-rw-r--r--docs/remakes.md40
1 files changed, 22 insertions, 18 deletions
diff --git a/docs/remakes.md b/docs/remakes.md
index 94d50dc..5156905 100644
--- a/docs/remakes.md
+++ b/docs/remakes.md
@@ -9,9 +9,9 @@ A remake moves the whole swarm to a new document, the next *epoch*. Use one to:
* **import** (`import`): new content from an Automerge document, e.g. a backup made
with `GET /admin/document`. Unlike `replace`, Automerge types survive (text,
counters, bytes, timestamps, floats).
-* **strict** (`strict`): the same as `compact`, turning the swarm strict, keeping only
- the signed values an operator's manifest names ([`access.md`](access.md), Turning a
- swarm strict).
+* **strict** (`strict`): the same as `compact`, turning the swarm strict, keeping only the
+ signed values an operator's manifest names ([`access.md`](access.md),
+ [Turning a swarm strict](access.md#turning-a-swarm-strict)).
Everything else is the same for all the kinds. All endpoints need the node's basic
auth; examples leave it out.
@@ -115,11 +115,11 @@ Answers:
* `409` if another remake of this epoch is still open on this node's view, if an
expired one still holds votes (unless `?force=supersede`), or if this node can't
vote for a new one (it voted for another remake of this epoch, or may have before it
- restarted), or if this node's clock is off from most of its peers' ([`measurements.md`](measurements.md),
- Clocks): the coordinator stamps and judges the deadlines by it (unless
- `?force=clock`); or, as for every write a user asks for, if this node doesn't know
- the swarm's policy ([`access.md`](access.md)): the proposal is written as the user who
- asks.
+ restarted), or if this node's clock is off from most of its peers'
+ ([`measurements.md`](measurements.md), [Clocks](measurements.md#clocks)): the
+ coordinator stamps and judges the deadlines by it (unless `?force=clock`); or, as for
+ every write a user asks for, if this node doesn't know the swarm's policy
+ ([`access.md`](access.md)): the proposal is written as the user who asks.
* `400` for an invalid request; `503` if the node isn't ready.
Dropping the HTTP connection doesn't abort the remake.
@@ -254,9 +254,10 @@ aborts it itself, under three conditions that keep it from crossing a late commi
* if the node you ask sees the coordinator as an active peer, the coordinator is
stuck rather than gone (a different version, a bug: look at its log). Aborting then
needs `?force=coordinatorActive`;
-* the node you ask must have its clock in line with its peers' ([`measurements.md`](measurements.md),
- Clocks): whether the remake expired is judged by it, and a node ahead would abort a
- remake its coordinator may still commit. Otherwise `409`, unless `?force=clock`.
+* the node you ask must have its clock in line with its peers'
+ ([`measurements.md`](measurements.md), [Clocks](measurements.md#clocks)): whether the
+ remake expired is judged by it, and a node ahead would abort a remake its coordinator
+ may still commit. Otherwise `409`, unless `?force=clock`.
The abort is written as the user who asks, who may write remakes: with a policy
([`access.md`](access.md)), the other nodes take a decision from the coordinator or
@@ -350,8 +351,8 @@ The swarm stays writable throughout.
A rejoining node answers reads from its old document, marked with the
`x-continuum-stale` header, and writes go into it; they are carried over into the new
-epoch when the rejoin ends, like the node's writes from before ([`lifecycle.md`](lifecycle.md),
-Rejoining).
+epoch when the rejoin ends, like the node's writes from before
+([`lifecycle.md`](lifecycle.md), [Rejoining](lifecycle.md#rejoining)).
## Quarantine
@@ -396,7 +397,8 @@ remake report's `local.quarantine` on that node names the entry.
the other epoch of that generation rejoin it sideways once they see themselves
outnumbered (`More peers are on another epoch of this generation than on ours`,
warn), and what was written there goes to quarantine ([`lifecycle.md`](lifecycle.md),
- Rejoining). Look at those quarantines; report how it came about ([Limits](#limits)).
+ [Rejoining](lifecycle.md#rejoining)). Look at those quarantines; report how it came
+ about ([Limits](#limits)).
* **Repairing records by hand.** Remake records live in the document under
`_continuum/remakes/<id>`. Old ones need no cleaning up: an epoch's document holds
the remakes proposed in it and the record of the remake that made it, and earlier
@@ -409,10 +411,12 @@ remake report's `local.quarantine` on that node names the entry.
## Limits
-* **Clocks.** Voting periods, expiry and the replay window are judged by each node's
- own clock ([`trust.md`](trust.md), What depends on clocks). With clocks further apart than the
- grace period (four of the coordinator's keepalives), a remake aborted from another node after expiry
- could also have been committed by its coordinator: a contested remake.
+* **Clocks.** Voting periods, expiry and the replay window are judged by each node's own
+ clock ([`trust.md`](trust.md),
+ [What depends on clocks](trust.md#what-depends-on-clocks)). With clocks further apart
+ than the grace period (four of the coordinator's keepalives), a remake aborted from
+ another node after expiry could also have been committed by its coordinator: a contested
+ remake.
* **Document size.** Large transfers go in chunks (`--blob-chunk`, default 64KiB)
from up to four peers at once: the new document of a `replace`/`import` remake (it