HarperFast / HarperFast/harper-pro
Record locks Phase 1: durable membership epoch protocol (single-decree agreement per database)
- Dominant language
- JavaScript
- Stars
- 3
- Forks
- 0
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 80
Description
Part of the Phase 1 record-lock redesign — the replacement for the Ricart–Agrawala arbitration rule
currently on [harper#2498](https://github.com/HarperFast/harper/pull/2498). Design note:
[`docs/record-lock-ownership.md`](https://github.com/HarperFast/harper/blob/feat/record-lock-phase1/docs/record-lock-ownership.md)
§4. This is the harper-pro half, because harper-pro owns topology.
The redesign has three levels at three very different rates: a **membership epoch** (rare, durable,
agreed), a **home node** per key derived from it (free), and **volatile per-record delegations**
(the amortization). This issue is the first level, and it is the only place consensus appears in the
whole design.
## What it is
Per database, an epoch `(number, members[], ringVersion)` with a lease. Advancing it is
single-decree agreement over a majority of the *current* members, with acceptor promises and
accepted values **persisted before they are acknowledged**. It runs once per membership change plus
one renewal per node per lease period — never per key and never per lock. A node that cannot renew
with a majority stops acting, so the minority side of a partition stops issuing locks while the
majority side continues.
`hdb_nodes` cannot back this directly: that table is LWW-replicated and therefore not agreed.
## Why the durable state is not optional
§4.0 of the note carries the counterexample, and it is worth reading before anyone proposes the
cheaper variant again: a restarted acceptor that forgets its acceptance forks the configuration into
two live epochs renewing on disjoint majorities. No timing argument substitutes for durable acceptor
state. A planning-review round returned `better-alternative-exists` against the stateless version and
it was adopted.
## Scope
- The durable per-database epoch record and the acceptor state machine (§4.1).
- Bootstrap and rejoin, including reservation reconstruction after a restart (§4.2).
- Retiring a healthy epoch, and the retirement interval anchored on acceptor reservations (§4.4) —
the interval is what bounds how long a key is unavailable after its home fails.
- Routing: exactly one algorithm for deriving a key's home from `members[]` (§4.5), rendezvous hash
over replication-group membership so it needs no operator sharding configuration.
- `transport.epoch(database)` exposing the current epoch to core.
- Configuration certificates authenticated by **verifying each accepting identity is a distinct
member of the preceding configuration** — an authenticated sender presenting a claimed list of
votes is not quorum evidence (§8).
## Also unblocks
This is what finally lets harper-pro assert `agreedDown`, the gap
[#822](https://github.com/HarperFast/harper-pro/pull/822) records as a core follow-up: a locally
observed DOWN view is not agreement, and today nothing is ever excluded from a grant set.
## Blocked on
The measurement gate — no number in the design note is a benchmark.
Refs #438, HarperFast/harper#483
🤖 Filed by Claude Opus 5 on behalf of Kris.
Contributor guide
Research direction
Read docs/record-lock-ownership.md, especially §4.0–§4.5 and §8, before examining the transport.epoch(database) entry point. Confirm the measurement gate first; done means the durable epoch and acceptor state, bootstrap/rejoin, retirement, routing, transport exposure, and certificate checks are covered as scoped.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, nodejs
- Domain
- backend, databases, distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100