docs(adr): ADR 009 names the client's position a watermark (improvise-felo.4)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
This commit is contained in:
Claude (adr9-steward)
2026-10-09 21:29:21 -07:00
committed by Edward Langley
parent 2bea189c67
commit 7ea88606e2
+11 -8
View File
@@ -225,21 +225,24 @@ an **edge adapter**. So every edge has the same semantics:
alive while its next message or request succeeds. Each hop keeps alive in both
directions. A side that hears nothing within the timeout, or whose request fails,
treats the hop as dropped. The downstream side then asks for a correction from its
last stamp.
watermark.
- **Correction is Z-set arithmetic.** A correction is `target − held`, where `target`
is the current state for the client's window and `held` is what the client holds.
Applying it with ordinary Z-set addition gives `held + (target − held) = target`, so
the group structure of `ZSet` provides it, with no separate machinery. The client
sends its last stamp:
- where the shared log covers that stamp, the host sends the sum of the logged deltas
since then;
the group structure of `ZSet` provides it, with no separate machinery. The client's
position is a **watermark**: the publication number up to which it has applied the
stream, so everything at or before it is applied. There is one publication sequence,
so a watermark is one number, held per shape key the client reads. The host and any
gateway keep no watermarks: a client sends its own with each request.
- where the shared log covers the watermark, the host sends the sum of the logged
deltas after it;
- otherwise the host sends `target`, and the client, which knows `held`, applies
`target − held`;
- a full refetch is `target − ∅`.
A correction is labelled with the publication range it covers, so it is applied only
at the stamp it starts from, which makes it idempotent and resumable. It uses the same
at the watermark it starts from, which makes it idempotent and resumable. It uses the same
lossless delta form as a notice, so a client, a gateway or a worker applies it with the
same code.
@@ -295,8 +298,8 @@ fetched.
**Edge adapters at the client.** Toward the circuit, a client's adapter is a sink for
results and notices and a source of requests. Toward the client it is the mirror image.
Each hop has an adapter at each end, and each end keeps only that hop's state: the last
stamp it applied and its liveness timer. A gateway hop (browser ⇄ gateway ⇄ host) may
Each hop has an adapter at each end, and each end keeps only that hop's state: its
liveness timer, and at the client end the watermark. A gateway hop (browser ⇄ gateway ⇄ host) may
serve many clients behind one upstream connection, so the host sends one notice per
gateway rather than one per client. In process, an edge is a function call.