Let P satisfy P.InitCompatible and P.strategy = ElectionStrategy.DEFAULT_INSTANCE, and let W satisfy Inv P W. For every node n, join j with W.sent (.join j) and j.targetNode.id = n, state cs' and flag b with (W.node n).handleJoin P.strategy j = .ok (cs', b): Inv P (W.set n cs').
The hard case is a join that wins the election: then no publication of the node's current term exists, its accepted state is of an older term, and no other node has won the term, because two election records of one term have the same candidate (inv_election_unique). With the default strategy an election, once won, stays won when votes are added.
Preamble
import Definitions.Def_OpenSearchSafety
open OpenSearchCoordination OpenSearchSafety
OpenSearch b2a54ba5c0defba3d1d20423e911d4bf920bab19: CoordinationState (the per-node handlers as transcribed by the OpenSearchCoordination mission; handleCommit lines 523-573, isPublishQuorum 156-158, invariant 601-611): https://github.com/opensearch-project/OpenSearch/blob/b2a54ba5c0defba3d1d20423e911d4bf920bab19/server/src/main/java/org/opensearch/cluster/coordination/CoordinationState.java; Coordinator (the calls into CoordinationState: handleApplyCommit lines 419-452, handlePublishRequest 454-526, startElection 583-602, abdicateTo 604-620, ensureTermAtLeast 635-641, joinLeaderInTerm 643-657, setInitialConfiguration 1101-1161, handleJoin 1267-1299, publish 1350 with the handleClientValue call at 1404, CoordinatorPublication.handlePublishResponse 1871-1876): https://github.com/opensearch-project/OpenSearch/blob/b2a54ba5c0defba3d1d20423e911d4bf920bab19/server/src/main/java/org/opensearch/cluster/coordination/Coordinator.java; ClusterBootstrapService (requirements 146-157, onFoundPeersUpdated 176-215, startBootstrap 259-273, checkRequirements 306-335): https://github.com/opensearch-project/OpenSearch/blob/b2a54ba5c0defba3d1d20423e911d4bf920bab19/server/src/main/java/org/opensearch/cluster/coordination/ClusterBootstrapService.java#L146-L335; GatewayMetaState.start (persisted state loaded and rebuilt 141-231, remote restore 169-188, synchronous and asynchronous persistence 199-207, nodes without the cluster-manager and data roles 232-255): https://github.com/opensearch-project/OpenSearch/blob/b2a54ba5c0defba3d1d20423e911d4bf920bab19/server/src/main/java/org/opensearch/gateway/GatewayMetaState.java#L126-L257; PersistedStateRegistry.addPersistedState (lines 38-41): https://github.com/opensearch-project/OpenSearch/blob/b2a54ba5c0defba3d1d20423e911d4bf920bab19/server/src/main/java/org/opensearch/cluster/coordination/PersistedStateRegistry.java#L38-L41; ElectionStrategy (DEFAULT_INSTANCE lines 46-59): https://github.com/opensearch-project/OpenSearch/blob/b2a54ba5c0defba3d1d20423e911d4bf920bab19/server/src/main/java/org/opensearch/cluster/coordination/ElectionStrategy.java#L44-L110; the randomized safety test CoordinationStateTestCluster (reboot 156-193, runRandomly 279-329, invariant 331-370): https://github.com/opensearch-project/OpenSearch/blob/b2a54ba5c0defba3d1d20423e911d4bf920bab19/test/framework/src/main/java/org/opensearch/cluster/coordination/CoordinationStateTestCluster.java and CoordinationStateTests.testSafety (lines 917-924): https://github.com/opensearch-project/OpenSearch/blob/b2a54ba5c0defba3d1d20423e911d4bf920bab19/server/src/test/java/org/opensearch/cluster/coordination/CoordinationStateTests.java#L917-L924; for comparison, Elastic's TLA+ model ZenWithTerms (HandleCommit 241-250, CommittedValuesDescendantsFromInitialValue 338-347, CommitHasQuorumVsPreviousCommittedConfiguration 349-358): https://github.com/elastic/elasticsearch-formal-models/blob/ca30663506a7e18de9d23fabbc70a369903d7c98/ZenWithTerms/tla/ZenWithTerms.tla
Read-back
What the Lean code literally says, in plain math · claude-opus-5-5 (independent sub-agent, blind: Lean code + auditor instructions only)
Read-back: OpenSearchSafety.inv_join
Notions used
Sources and conventions. Rendered from Definitions/Def_OpenSearchCoordination.lean, Definitions/Def_OpenSearchSafety.lean and the stub Theorems/Thm_OpenSearchSafety_inv_join.lean; Java line numbers refer to OpenSearch b2a54ba5c0defba3d1d20423e911d4bf920bab19 (CS = CoordinationState.java, CM = CoordinationMetadata.java, ES = ElectionStrategy.java, CO = Coordinator.java, CBS = ClusterBootstrapService.java), checked against the local checkout. Throughout, V is an arbitrary payload type, P a parameter record and W a cluster; csn abbreviates W.node(n), the coordination state of node n in W, and "m∈sent" means W.sent(m). Booleans are read as truth values: "won(cs)" means electionWon = true, "¬won(cs)" means electionWon = false.
Nodes, configurations, quorums. Node ids are natural numbers. A discovery noded is a pair (d.id,d.cm) of an id and a Boolean (isClusterManagerNode). A voting configurationc is a strictly increasing list of node ids, hence duplicate-free; two configurations are equal exactly when they have the same members. ∅ denotes the empty configuration EMPTY_CONFIG; "c is empty" means its list is empty. For a configuration c and any list q of ids,
hasQuorum(c,q)⟺2⋅{x∈c:x∈q}>∣c∣,
so the empty configuration has no quorum, and ids of q outside c as well as repetitions in q are irrelevant. Transcription check: matches VotingConfiguration.hasQuorum (CM:405-409).
A vote collection is a list of node ids; the empty collection is []; isQuorum(v,c):=hasQuorum(c,v); addVote(v,d) is (d.id::v,added) if d.cm is true and d.id∈/v, and (v,not added) otherwise. Transcription check:VoteCollection (CS:750-814) keys a map by node id; addVote (CS:755-757) changes the key set exactly in the same cases.
Cluster states. A cluster state s has a term s.term∈N, a version s.version∈Z, a metadata version s.mv∈Z, a last committed and a last accepted configuration s.lcc and s.lac, an optional natural number s.cmNode (the cluster-manager node), two Booleans s.uuidKnown and s.uuidCommitted, and a payload s.value∈V. Two cluster states are equal when all nine fields are. vomv(s) (versionOrMetadataVersion) is s.mv if s.term=0 and s.version otherwise. markCommitted(s) is s with lcc replaced by s.lac and with uuidCommitted set to true when s.uuidKnown is true; nothing else changes (transcribes CS:703-740; the Java assertion at CS:708-710 is not checked).
Message contents. A joinj has a source and a target discovery node j.src, j.tgt, a term j.term∈N, a last accepted term j.lat∈N and a last accepted version j.lav∈Z; two joins are equal when all five fields are. A publish response is a pair ⟨t,v⟩∈N×Z. An apply-commit request is a triple ⟨d,t,v⟩ of a discovery node, a term and a version. A start-join request is a pair of a discovery node and a term; it is not a cluster message (see the steps).
Coordination states. A coordination state cs has a local node cs.localNode (a discovery node), a current term ct(cs)∈N, a last accepted state cs.las (a cluster state), two vote collections joinVotes(cs) and pubVotes(cs), Booleans started(cs) (startedJoinSinceLastReboot) and won(cs) (electionWon), a last published version lpv(cs)∈Z and a last published configuration lpc(cs). lat(cs), lav(cs), lcc(cs), lac(cs) are the term, version, last committed and last accepted configuration of cs.las. init(d,t,s) is the coordination state with local node d, current term t, last accepted state s, both vote collections empty, started and won false, lpv=0 and lpc=s.lac (the constructor, CS:84-106).
Election strategies. An election strategy is a Boolean function σ(d,t,at,av,c1,c2,v) of a discovery node, two naturals, an integer, two configurations and a vote collection; DEFAULT_INSTANCE is the constant-true function. isElectionQuorumσ(cs,v):=isQuorum(v,lcc(cs))∧isQuorum(v,lac(cs))∧σ(cs.localNode,ct(cs),lat(cs),lav(cs),lcc(cs),lac(cs),v); for the default strategy the third conjunct is true. isPublishQuorum(cs,v):=isQuorum(v,lcc(cs))∧isQuorum(v,lpc(cs)). Transcription check: ES:68-88 with CS:144-154, and CS:156-158.
Parameters. A parameter record P consists of elig:N→Bool (eligible: whether a node is cluster-manager-eligible), a predicate initConfs on configurations (an arbitrary set of "bootstrap configurations": possibly empty, possibly containing ∅, possibly infinite), and an election strategy σP (strategy). dn(n):=(n,elig(n)); "x is eligible" means elig(x)= true. InitCompatible(P) holds when for all configurations X,Y with initConfs(X) and initConfs(Y) and all lists q1,q2 of eligible ids,
hasQuorum(X,q1)∧hasQuorum(Y,q2)⟹∃x,x∈q1∧x∈q2
(for X=Y this is automatic: two majorities of one configuration meet).
Messages and clusters. A cluster message is one of: join(j); pubReq(a,s,pt,pv), a publish request from node a carrying a cluster state s and a ghost parent(pt,pv)∈N×Z; pubResp(a,d,r), a publish response r from node a to node d; commit(c), an apply-commit request c. A cluster W is a function W.node from node ids to coordination states together with a predicate W.sent on messages (the messages sent so far). W.set(n,cs) replaces node n's state by cs and changes nothing else; W.send(m) adds m to the sent set and changes nothing else. A key is a pair (t,v)∈N×Z; the key of a publication pubReq(a,s,pt,pv) is (s.term,s.version).
The handler. Each handler returns either an error (the corresponding step is then impossible) or a result. Guards are tested in the order listed; the first that applies gives the error.
handleJoinσ(cs,j): errors, in order, if j.term=ct(cs); if ¬started(cs); if j.lat>lat(cs); if j.lat=lat(cs) and j.lav>vomv(cs.las); if lac(cs) is empty. Otherwise, with (v′,b)=addVote(joinVotes(cs),j.src) and w=isElectionQuorumσ(cs,v′), the result is cs with joinVotes:=v′ and won:=w, and moreover lpv:=lav(cs) if w holds and won(cs) did not; together with the Boolean b ("vote added"). The target j.tgt is not examined. Transcription check: CS:264-339; the Java assertions CS:265 (target is the local node) and CS:323-324 (a won election is not lost) are not checked by the handler.
Commits.Committed(W,t,v) holds when commit(⟨d,t,v⟩)∈sent for some discovery node d (the source is irrelevant).
Descent.Parent(W,(t,v),(t′,v′)) holds when some pubReq(a,s,t,v)∈sent has s.term=t′ and s.version=v′: a publication of key (t′,v′) was sent with ghost parent (t,v). Descends(W,k,k′), for keys k,k′, is the least relation that holds when k′=k — for every key, whether or not anything was published under it — and that holds of (k,k′′) whenever it holds of (k,k′) and Parent(W,k′,k′′). Thus Descends(W,k,k′) means: k=k′, or there is a chain k=k0,k1,…,km=k′ with m≥1 and Parent(W,ki−1,ki) for each i. Descent relates keys through ghost parents only; it says nothing about the payloads of the states.
Auxiliary notions of the invariant.
KeyLE((t,v),(t′,v′)): t<t′, or t=t′ and v≤v′.
Below((lt,lv),(bt,bv)): lt<bt, or lt=bt and (bt=0 or lv≤bv) — at term 0 versions are not compared.
Realizes(P,W,(t,v),x,y): either t=0, x=y and initConfs(x) (with v unconstrained); or some pubReq(a,s,pt,pv)∈sent has s.term=t, s.version=v, y=s.lac, and either x=s.lcc, or x=s.lac and Committed(W,t,v).
JoinVoters(P,W,L,t,J): every x∈J is eligible and some join(j)∈sent has j.src.id=x, j.tgt.id=L and j.term=t.
BaseVoters(P,W,L,t,(bt,bv),J): the same, the witnessing join satisfying in addition Below((j.lat,j.lav),(bt,bv)).
RespVoters(P,W,(t,v),A): every x∈A is eligible and pubResp(x,d,⟨t,v⟩)∈sent for some d.
ElectionRecord(P,W,L,t,(bt,bv),x,y,J): bt<t, Realizes(P,W,(bt,bv),x,y), BaseVoters(P,W,L,t,(bt,bv),J), hasQuorum(x,J) and hasQuorum(y,J).
Won(P,W,b,t): b is eligible, and either (won(csb) and ct(csb)=t) or some pubReq(b,s,pt,pv)∈sent has s.term=t.
The invariant.Inv(P,W) is the conjunction of the following 30 statements (Lean field names in parentheses); nodes n,m,a,b,d range over all node ids, j,j′ over all joins, r over all publish responses.
(joinVotes_sent) every m∈joinVotes(csn) is eligible, and some join(j)∈sent has j.src.id=m, j.tgt.id=n, j.term=ct(csn) and Below((j.lat,j.lav),(lat(csn),lav(csn))).
(publishVotes_sent) every m∈pubVotes(csn) is eligible and pubResp(m,n,⟨ct(csn),lpv(csn)⟩)∈sent.
(join_wf) if join(j)∈sent then j.src=dn(j.src.id) and j.tgt.id is eligible.
(join_term_le) if join(j)∈sent and j.src.id is eligible then j.term≤ct(csj.src.id).
(join_unique) if join(j),join(j′)∈sent, j.src.id is eligible, j.src.id=j′.src.id and j.term=j′.term, then j=j′ (all five fields, in particular the same target).
(join_after_response) if join(j)∈sent, pubResp(a,d,r)∈sent, j.src.id=a, a is eligible and r.term<j.term, then KeyLE((r.term,r.version),(j.lat,j.lav)).
(response_le) if pubResp(a,d,r)∈sent and a is eligible, then r.term≤ct(csa) and KeyLE((r.term,r.version),(lat(csa),lav(csa))).
(response_published) if pubResp(a,d,r)∈sent then some pubReq(d,s,pt,pv)∈sent — sent by the addressee d — has s.term=r.term and s.version=r.version.
Publications: for every pubReq(a,s,pt,pv)∈sent:
(pub_wf) a is eligible, s.term≥1, pt≤s.term, pv<s.version, and pt=0⇒initConfs(s.lcc).
(pub_parent) if pt≥1, some pubReq(a′,s′,pt′,pv′)∈sent has s′.term=pt, s′.version=pv, [s.lcc=s′.lcc, or s.lcc=s′.lac and Committed(W,pt,pv)], and [s.lac=s′.lac⇒s.lcc=s′.lac].
(pub_unique) every pubReq(a′,s′,pt′,pv′)∈sent with s′.term=s.term and s′.version=s.version has a′=a, s′=s, pt′=pt and pv′=pv.
(pub_rooted) Descends(W,(0,v0),(s.term,s.version)) for some v0∈Z.
(pub_same_term) every pubReq(a′,s′,pt′,pv′)∈sent with s′.term=s.term has Descends(W,(s.term,s.version),(s′.term,s′.version)) or the converse.
(pub_voters) some list J has JoinVoters(P,W,a,s.term,J), hasQuorum(s.lcc,J) and hasQuorum(s.lac,J).
(pub_election) if pt<s.term, some y and J have ElectionRecord(P,W,a,s.term,(pt,pv),s.lcc,y,J).
Commits:
(commit_quorum) for every commit(⟨d,t,v⟩)∈sent, some pubReq(a,s,pt,pv)∈sent has s.term=t and s.version=v, and some list A has RespVoters(P,W,(t,v),A), hasQuorum(s.lac,A), and either hasQuorum(s.lcc,A), or [Committed(W,pt,pv) and some pubReq(a′,s′,pt′,pv′)∈sent has s′.term=pt, s′.version=pv, s′.lac=s.lac].
Leaders:
(won_unique) Won(P,W,a,t)∧Won(P,W,b,t)⇒a=b.
(pub_source_term) for every pubReq(a,s,pt,pv)∈sent: s.term<ct(csa), or s.term=ct(csa) and (won(csa) or ¬started(csa)).
(leader_pubs) if won(csn), every pubReq(a,s,pt,pv)∈sent with s.term=ct(csn), whoever its sender a, has s.version≤lpv(csn), Descends(W,(s.term,s.version),(ct(csn),lpv(csn))), isQuorum(joinVotes(csn),s.lcc) and isQuorum(joinVotes(csn),s.lac).
(leader_inflight) if won(csn) and lpv(csn)=lav(csn), some s has pubReq(n,s,lat(csn),lav(csn))∈sent, s.term=ct(csn), s.version=lpv(csn), lpc(csn)=s.lac, and either lcc(csn)=s.lcc, or [lcc(csn)=s.lac, Committed(W,lat(csn),lav(csn)) and lac(csn)=s.lac].
(leader_settled) if won(csn) and lpv(csn)=lav(csn): either lat(csn)=ct(csn) and lpc(csn)=lac(csn), or lat(csn)<ct(csn) and no pubReq(a,s,pt,pv)∈sent has s.term=ct(csn).
Docstring remarks. The docstring of idle_of_not_won says that a node that has not won "has published nothing in its term"; the term only says lpv=0 and no publish votes, which a node that published in its current term and then restarted also satisfies. The docstring of leader_pubs speaks of "an elected node's publications of its term"; the term covers every publication of that term, whoever sent it (a stronger statement).
1. Declaration
Binders and hypotheses, in order:
an implicit payload type V and a parameter record P;
hP : InitCompatible(P);
hes : σP=DEFAULT_INSTANCE, so that isElectionQuorumσP(cs,v) is just isQuorum(v,lcc(cs))∧isQuorum(v,lac(cs));
a cluster W and hinv : Inv(P,W) — any cluster satisfying the invariant, reachable or not;
a node n, a join j, a coordination state cs′ and a Boolean b;
hsent : join(j)∈sent;
hdest : j.tgt.id=n;
h : handleJoinσP(csn,j)=ok(cs′,b). Using hes, this holds exactly when j.term=ct(csn), started(csn), j.lat≤lat(csn), not [j.lat=lat(csn) and j.lav>vomv(csn.las)], and lac(csn) is non-empty; and then, with (v′,b)=addVote(joinVotes(csn),j.src) and w=isQuorum(v′,lcc(csn))∧isQuorum(v′,lac(csn)), cs′ is csn with joinVotes:=v′, won:=w, and lpv:=lav(csn) when w holds and won(csn) did not.
Items 5–8 are exactly the data and premises of the join step.
Conclusion.Inv(P,W.set(n,cs′)): the invariant holds after node n records the vote of j's source (if new and cluster-manager-eligible by the join's own flag), recomputes won and, on a fresh win, sets lpv to its accepted version. No message is sent.
2. What is not constrained
hP and hes are genuine hypotheses (here named without the underscore that the other step lemmas use; only the naming differs). The lemma is stated only for parameters whose bootstrap configurations are compatible and whose election strategy is the default one.
W is not required to be reachable: the lemma asserts that this step preserves Inv from every cluster satisfying Inv (the inductive-step form). It is exactly as strong as the claim that Inv is inductive for this step.
Apart from hP, elig and initConfs are arbitrary, and so is the payload type V.
The same sent join may be handled any number of times. If j.src.cm is false or the source already voted, no vote is added and w is recomputed on unchanged votes. b is determined by h (whether the vote was added) and plays no role in the conclusion.
The Java assertions of handleJoin (target is the local node, CS:265; a won election is not lost, CS:323-324) are not hypotheses; hdest supplies the first.
The version comparison of the handler uses vomv (the metadata version at accepted term 0), while the invariant's Below compares versions only at accepted terms ≥1; the two agree in that at term 0 the invariant constrains no version.
Not vacuous. Take elig(n)⟺n=0, initConfs={{0}} and the default strategy (then InitCompatible(P) holds), and the initial cluster in which every node is init(dn(n),0,s0) with s0 of term 0, version 0 and empty configurations. Node 0 can then, in order: (0) bootstrap with sb (term 0, version 0, both configurations {0}); (1) handle the start-join (dn(0),1), sending j=⟨dn(0),dn(0),1,0,sb.mv⟩; (2) handle j and win with votes [0]; (3) publish s1 (term 1, version 1, both configurations {0}) with ghost parent (0,0); (4) accept s1 and send the response ⟨1,1⟩ to itself; (5) count that response, which is a publish quorum, and send commit(⟨dn(0),1,1⟩); (6) apply that commit. By direct inspection, each cluster before one of these steps satisfies Inv (most conjuncts are vacuous; the others are witnessed by the single join, publication, response and commit). The hypotheses of this lemma hold for step (2).
3. Plain-language summary
Handling, at its addressee, a sent join vote for the addressee's current term — adding the vote and possibly winning the election — preserves the invariant (for compatible bootstrap configurations and the default strategy).
Confirmed by the moderator at approval.