HarperFast / HarperFast/harper-pro

Record locks Phase 1: durable membership epoch protocol (single-decree agreement per database)

Open
#825 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.