@zukhruf/election 0.0.0-stage → 0.3.17

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ezzabuzaid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# @zukhruf/election
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Candidates campaign for one claim, and the candidate that wins it leads for one term. Each term has an epoch that is higher than the epoch of each earlier term, so a newer leader always outranks an older one. A term is a lease on leadership. It ends when the leader resigns or its process dies. With a backend that can take the claim away, a term can also be lost while the leader still runs, and the signal of the term tells its leader so.
+
+The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
+
+## Use it
+
+This project is an experiment.
+
+```sh
+npm install @zukhruf/election
+```
+
+## Elect a leader of one host
+
+`SqliteElection` elects one leader among the processes of one host that use the same directory. The claim is the `FileLock` of `@zukhruf/fs` on `claimFile`: an exclusive SQLite transaction. The operating system holds that lock until the leader's process dies, so a dead leader frees the claim at once, and a living leader never loses it.
+
+```ts
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { SqliteElection } from '@zukhruf/election';
+
+const directory = await mkdtemp(join(tmpdir(), 'jobs-'));
+const election = new SqliteElection({
+  directory,
+  claimFile: 'jobs.lock',
+  epochFile: 'jobs.epoch',
+});
+
+const first = await election.campaign();
+console.log('first term:', first?.epoch);
+console.log('a second candidate wins:', await election.campaign());
+
+await first?.resign();
+await using second = await election.campaign({ timeout: 1000 });
+console.log('next term:', second?.epoch);
+await rm(directory, { recursive: true, force: true });
+```
+
+Output:
+
+```
+first term: 1n
+a second candidate wins: undefined
+next term: 2n
+```
+
+- `campaign({ timeout, signal })` resolves with a `Term`, or with `undefined` when another candidate still leads after `timeout` milliseconds. Without a `timeout`, it tries once. When `signal` aborts, it rejects with `signal.reason`, and a claim that it won meanwhile is given up.
+- `claimFile` and `epochFile` are files in `directory`. Candidates with the same directory and the same file names are one group. Never delete `claimFile` while candidates run: a new file lets a second leader win.
+- The directory must be on a local file system. On a network file system, `campaign` rejects with `NetworkDirectoryError`.
+- `pollInterval` is the time between two tries, in milliseconds. It defaults to 10. A try never blocks the process.
+
+## The term
+
+A term is a lease on leadership. `Term` implements the `Lease` interface of [`@zukhruf/lease`](../lease/README.md), so a function that takes a `Lease` also takes a term. See the glossary of [leases](../lease/CONTEXT.md).
+
+- `term.epoch` is the number of the term. Each epoch is below 2^31.
+- `term.resign()` ends the term and gives the claim up. A second call waits for the first. `await using` resigns at the end of its scope.
+- `term.signal` aborts with `LeaseLostError` when the term is lost while its leader still runs. The `subject` of the error is `'leadership'`, and its `cause` is the reason of the backend. The signal does not abort when the leader resigns.
+
+A leader that acts for the group must stop when `term.signal` aborts, because another candidate can lead then. `SqliteElection` never loses a living term, so its signal never aborts. A backend that can take the claim away can lose one.
+
+A term has no fencing token. The signal warns the leader, but it does not protect a resource: a leader can write after another candidate won. To protect a resource, make fencing tokens from the epoch with `EpochTokenSource` of [`@zukhruf/fencing`](../fencing/README.md). Then a resource can refuse the writes of an older leader:
+
+```ts
+import { EpochTokenSource } from '@zukhruf/fencing';
+
+const tokens = new EpochTokenSource(term.epoch);
+const token = await tokens.next('orders');
+```
+
+[ADR 0002](./docs/adr/0002-a-term-is-a-lease-on-leadership-with-no-fencing.md) tells why.
+
+## Write a backend
+
+`LeaderElection` is an abstract class. It runs the campaign, and it owns the term. A backend is a subclass that implements five steps for its claim:
+
+| Step                      | What it does                                                                                                                                        |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open(signal)`            | Prepares one attempt, for example a connection. The campaign calls `tryClaim` on it again and again.                                                |
+| `tryClaim(claim, signal)` | Tries the claim once. Resolves with the epoch of the term it won, or `undefined` while another candidate holds the claim.                           |
+| `watch(claim, lose)`      | Watches a won claim for as long as its term lasts. Calls `lose` when the backend takes the claim away. Returns a `Disposable` that stops the watch. |
+| `release(claim)`          | Gives a won claim up when the leader resigns.                                                                                                       |
+| `close(claim)`            | Frees the resources of an attempt, at each end.                                                                                                     |
+
+A backend must keep four rules:
+
+1. `tryClaim` gives the epoch in the same step that wins the claim. Each epoch is higher than each earlier one, and below 2^31.
+2. `watch` calls `lose` before the backend can give the claim to another candidate. For a claim that the backend keeps only for a time, renew it well before that time ends, and count the time on a monotonic clock. Then an old leader stops before a new one starts.
+3. The campaign never calls `release` after a loss, because the claim can be another candidate's then.
+4. The campaign calls `close` after each end: a won term, a lost term, a failed attempt, or an attempt that never won.
+
+This backend elects among the candidates of one process. Its claim is an entry in a map:
+
+```ts
+import { LeaderElection } from '@zukhruf/election';
+
+const holders = new Map<string, bigint>();
+let lastEpoch = 0n;
+
+class MapElection extends LeaderElection<string> {
+  readonly #name: string;
+
+  constructor(name: string) {
+    super(10);
+    this.#name = name;
+  }
+
+  protected async open() {
+    return this.#name;
+  }
+
+  protected async tryClaim(name: string) {
+    if (holders.has(name)) return undefined;
+    lastEpoch += 1n;
+    holders.set(name, lastEpoch);
+    return lastEpoch;
+  }
+
+  // Nothing takes an entry of the map away, so there is nothing to watch.
+  protected watch() {
+    return { [Symbol.dispose]() {} };
+  }
+
+  protected async release(name: string) {
+    holders.delete(name);
+  }
+
+  protected async close() {}
+}
+
+const term = await new MapElection('jobs').campaign();
+console.log('leader:', term?.epoch);
+console.log('rival:', await new MapElection('jobs').campaign());
+await term?.resign();
+console.log(
+  'rival after the resign:',
+  (await new MapElection('jobs').campaign())?.epoch,
+);
+```
+
+Output:
+
+```
+leader: 1n
+rival: undefined
+rival after the resign: 2n
+```
+
+The socket lock store of `@zukhruf/mutex` uses `SqliteElection`, with the claim file `leader.lock` and the epoch file `leader.epoch`. Its leader serves the other candidates over a socket in the directory, so it works on one host only, also with another backend. Its server stops when `term.signal` aborts. `@zukhruf/single-flight` does not use this package yet, and keeps its own copy of the election ([copied code](./docs/copied-code.md)).
+
+## Errors
+
+| Error                   | When                                                                                                                                                                                                              |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NetworkDirectoryError` | The directory of a `SqliteElection` is on a network file system. It is the class of `@zukhruf/fs`.                                                                                                                |
+| `LeaseLostError`        | The reason of `term.signal` when the backend took the claim away. Its `subject` is `'leadership'`, and its `cause` is the backend's reason. It is the class of `@zukhruf/lease`, and this package exports it too. |
+| `signal.reason`         | A campaign rejects with it when its signal aborts.                                                                                                                                                                |
+
+## Documentation
+
+- [How SqliteElection elects a leader](./docs/concepts/leader-election.md)
+- [Recipe: Run a job in only one process](./docs/recipes/singleton-job-with-leader-election.md)
+- [ADR 0001: Leader election is a package, and each backend is a subclass of one campaign](./docs/adr/0001-leader-election-is-a-package-and-each-backend-is-a-subclass.md)
+- [ADR 0002: A term is a lease on leadership, with no fencing](./docs/adr/0002-a-term-is-a-lease-on-leadership-with-no-fencing.md)
+- [Code copied into this package](./docs/copied-code.md)
+
+## Development
+
+This package is part of the [zukhruf](../../README.md) workspace. Run the commands from the workspace root.
+
+```sh
+npm install
+npx nx run election:test        # builds, then runs the tests in src/
+npx nx run election:typecheck   # formats, lints, then type checks
+npx nx run election:build       # compiles src/ to dist/
+```
+
+```
+src/
+  leader-election.ts     LeaderElection: the campaign, and the steps of a backend
+  term.ts                Term: the epoch, the lease on leadership, and resign
+  sqlite/                SqliteElection: the backend of one host
+  testing/               the helpers that start candidate processes in the tests
+```

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { type CampaignOptions, LeaderElection } from './leader-election.ts';
+export { Term, type TermSteps } from './term.ts';
+export { SqliteElection, type SqliteElectionOptions, } from './sqlite/sqlite-election.ts';
+export { NetworkDirectoryError } from '@zukhruf/fs';
+export { LeaseLostError } from '@zukhruf/lease';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAE,IAAI,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { LeaderElection } from "./leader-election.js";
+export { Term } from "./term.js";
+export { SqliteElection, } from "./sqlite/sqlite-election.js";
+export { NetworkDirectoryError } from '@zukhruf/fs';
+export { LeaseLostError } from '@zukhruf/lease';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAE,IAAI,EAAkB,MAAM,WAAW,CAAC;AACjD,OAAO,EACL,cAAc,GAEf,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/leader-election.d.ts

@@ -0,0 +1,39 @@
+import { Term } from './term.ts';
+export interface CampaignOptions {
+    /** Milliseconds to keep trying before conceding to the current leader. Defaults to one attempt. */
+    timeout?: number | undefined;
+    /** Stops the campaign, which then rejects with `signal.reason`. A term won after it aborted is given up. */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Elects one leader among candidates. The campaign is the same for each
+ * backend: open an attempt, try the claim until it is won or the time is
+ * up, watch the won claim, and hand it to a term. Each backend is a
+ * subclass that implements the steps for its claim.
+ *
+ * A backend keeps four rules:
+ * - `tryClaim` returns the epoch of the term it won, in the same step, and
+ *   each epoch is higher than every earlier one and below 2^31.
+ * - `watch` calls `lose` before the backend can grant the claim to another
+ *   candidate, so an old leader stops before a new one starts.
+ * - `release` is never called after a loss: the claim may be another
+ *   candidate's by then.
+ * - `close` frees the attempt's resources, after each end.
+ */
+export declare abstract class LeaderElection<Claim> {
+    #private;
+    protected constructor(pollInterval: number);
+    /** Resolves with the new term, or `undefined` when another candidate still leads after `timeout`. */
+    campaign({ timeout, signal }?: CampaignOptions): Promise<Term | undefined>;
+    /** Prepares one attempt: the resources that `tryClaim` uses again and again. */
+    protected abstract open(signal: AbortSignal | undefined): Promise<Claim>;
+    /** Tries the claim once. Resolves with the epoch of the term it won, or `undefined` while another candidate holds it. */
+    protected abstract tryClaim(claim: Claim, signal: AbortSignal | undefined): Promise<bigint | undefined>;
+    /** Watches a won claim for as long as its term lasts, and calls `lose` when the backend takes it away. */
+    protected abstract watch(claim: Claim, lose: (reason: Error) => void): Disposable;
+    /** Gives a won claim up. Never called after a loss. */
+    protected abstract release(claim: Claim): Promise<void>;
+    /** Frees the resources of an attempt, whether it won, lost or failed. */
+    protected abstract close(claim: Claim): Promise<void>;
+}
+//# sourceMappingURL=leader-election.d.ts.map

package/dist/leader-election.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leader-election.d.ts","sourceRoot":"","sources":["../src/leader-election.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,WAAW,eAAe;IAC9B,mGAAmG;IACnG,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,4GAA4G;IAC5G,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;;;;;;;;GAcG;AACH,8BAAsB,cAAc,CAAC,KAAK;;IAGxC,SAAS,aAAa,YAAY,EAAE,MAAM;IAI1C,qGAAqG;IAC/F,QAAQ,CAAC,EAAE,OAAW,EAAE,MAAM,EAAE,GAAE,eAAoB,GAAG,OAAO,CACpE,IAAI,GAAG,SAAS,CACjB;IAUD,gFAAgF;IAChF,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC;IAExE,yHAAyH;IACzH,SAAS,CAAC,QAAQ,CAAC,QAAQ,CACzB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAE9B,0GAA0G;IAC1G,SAAS,CAAC,QAAQ,CAAC,KAAK,CACtB,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,CAAC,MAAM,EAAE,KAAK,KAAK,IAAI,GAC5B,UAAU;IAEb,uDAAuD;IACvD,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAEvD,yEAAyE;IACzE,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;CAkDtD"}

package/dist/leader-election.js

@@ -0,0 +1,77 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { untilAborted } from '@zukhruf/async';
+import { Term } from "./term.js";
+/**
+ * Elects one leader among candidates. The campaign is the same for each
+ * backend: open an attempt, try the claim until it is won or the time is
+ * up, watch the won claim, and hand it to a term. Each backend is a
+ * subclass that implements the steps for its claim.
+ *
+ * A backend keeps four rules:
+ * - `tryClaim` returns the epoch of the term it won, in the same step, and
+ *   each epoch is higher than every earlier one and below 2^31.
+ * - `watch` calls `lose` before the backend can grant the claim to another
+ *   candidate, so an old leader stops before a new one starts.
+ * - `release` is never called after a loss: the claim may be another
+ *   candidate's by then.
+ * - `close` frees the attempt's resources, after each end.
+ */
+export class LeaderElection {
+    #pollInterval;
+    constructor(pollInterval) {
+        this.#pollInterval = pollInterval;
+    }
+    /** Resolves with the new term, or `undefined` when another candidate still leads after `timeout`. */
+    async campaign({ timeout = 0, signal } = {}) {
+        signal?.throwIfAborted();
+        const deadline = performance.now() + timeout;
+        for (;;) {
+            const outcome = await this.#attempt(deadline, signal);
+            // A claim lost before its term began is no term: try again with a new attempt.
+            if (outcome !== 'lost')
+                return outcome;
+        }
+    }
+    async #attempt(deadline, signal) {
+        const claim = await this.open(signal);
+        let epoch;
+        try {
+            for (;;) {
+                epoch = await this.tryClaim(claim, signal);
+                if (epoch !== undefined)
+                    break;
+                if (performance.now() >= deadline)
+                    break;
+                await untilAborted(delay(this.#pollInterval, undefined, { signal }), signal);
+            }
+        }
+        catch (error) {
+            await this.close(claim).catch(() => { });
+            throw error;
+        }
+        if (epoch === undefined) {
+            await this.close(claim);
+            return undefined;
+        }
+        return this.#begin(claim, epoch, signal);
+    }
+    /** Hands a won claim to its term, or gives it up when the caller left meanwhile. */
+    async #begin(claim, epoch, signal) {
+        let term;
+        try {
+            signal?.throwIfAborted();
+            term = new Term(epoch, {
+                watch: (lose) => this.watch(claim, lose),
+                release: () => this.release(claim),
+                close: () => this.close(claim),
+            });
+        }
+        catch (error) {
+            await this.release(claim).catch(() => { });
+            await this.close(claim).catch(() => { });
+            throw error;
+        }
+        return term.signal.aborted ? 'lost' : term;
+    }
+}
+//# sourceMappingURL=leader-election.js.map

package/dist/leader-election.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"leader-election.js","sourceRoot":"","sources":["../src/leader-election.ts"],"names":[],"mappings":"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"}

package/dist/sqlite/sqlite-election.d.ts

@@ -0,0 +1,33 @@
+import { FileLock } from '@zukhruf/fs';
+import { LeaderElection } from '../leader-election.ts';
+export interface SqliteElectionOptions {
+    /** The local folder where the candidates meet. */
+    directory: string;
+    /**
+     * The file in `directory` whose file lock is the claim.
+     * Never delete it while candidates run: a new file would let a second
+     * leader win.
+     */
+    claimFile: string;
+    /** The file in `directory` that records the epoch of the last term, as decimal text. */
+    epochFile: string;
+    /** Milliseconds between two tries while another process leads. Defaults to 10. */
+    pollInterval?: number | undefined;
+}
+/**
+ * Elects one leader among the processes of one host that share `directory`.
+ * The claim is the file lock of `claimFile`, held for the whole term. The
+ * kernel keeps that lock until the leader's process dies, so a living leader
+ * never loses its term, and a dead one frees it at once.
+ */
+export declare class SqliteElection extends LeaderElection<FileLock> {
+    #private;
+    constructor({ directory, claimFile, epochFile, pollInterval, }: SqliteElectionOptions);
+    protected open(): Promise<FileLock>;
+    protected tryClaim(claim: FileLock): Promise<bigint | undefined>;
+    /** The kernel holds the claim for as long as the process lives, so there is nothing to watch. */
+    protected watch(): Disposable;
+    protected release(claim: FileLock): Promise<void>;
+    protected close(claim: FileLock): Promise<void>;
+}
+//# sourceMappingURL=sqlite-election.d.ts.map

package/dist/sqlite/sqlite-election.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-election.d.ts","sourceRoot":"","sources":["../../src/sqlite/sqlite-election.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,QAAQ,EAIT,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,cAAc,CAAC,QAAQ,CAAC;;gBAK9C,EACV,SAAS,EACT,SAAS,EACT,SAAS,EACT,YAAiB,GAClB,EAAE,qBAAqB;cAOR,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC;cAMzB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAQtE,iGAAiG;IACjG,SAAS,CAAC,KAAK,IAAI,UAAU;cAIb,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;cAIvC,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAGtD"}

package/dist/sqlite/sqlite-election.js

@@ -0,0 +1,55 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FileLock, assertLocalDirectory, durableWrite, isErrno, } from '@zukhruf/fs';
+import { LeaderElection } from "../leader-election.js";
+/**
+ * Elects one leader among the processes of one host that share `directory`.
+ * The claim is the file lock of `claimFile`, held for the whole term. The
+ * kernel keeps that lock until the leader's process dies, so a living leader
+ * never loses its term, and a dead one frees it at once.
+ */
+export class SqliteElection extends LeaderElection {
+    #directory;
+    #claimPath;
+    #epochPath;
+    constructor({ directory, claimFile, epochFile, pollInterval = 10, }) {
+        super(pollInterval);
+        this.#directory = directory;
+        this.#claimPath = join(directory, claimFile);
+        this.#epochPath = join(directory, epochFile);
+    }
+    async open() {
+        await assertLocalDirectory(this.#directory);
+        await mkdir(this.#directory, { recursive: true });
+        return FileLock.open(this.#claimPath);
+    }
+    async tryClaim(claim) {
+        if (!claim.tryLock())
+            return undefined;
+        // Safe without further locking: only the holder of the claim gets here.
+        const epoch = (await readEpoch(this.#epochPath)) + 1n;
+        await durableWrite(this.#epochPath, epoch.toString());
+        return epoch;
+    }
+    /** The kernel holds the claim for as long as the process lives, so there is nothing to watch. */
+    watch() {
+        return { [Symbol.dispose]() { } };
+    }
+    async release(claim) {
+        claim.unlock();
+    }
+    async close(claim) {
+        claim[Symbol.dispose]();
+    }
+}
+async function readEpoch(path) {
+    try {
+        return BigInt(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return 0n;
+        throw error;
+    }
+}
+//# sourceMappingURL=sqlite-election.js.map

package/dist/sqlite/sqlite-election.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-election.js","sourceRoot":"","sources":["../../src/sqlite/sqlite-election.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,YAAY,EACZ,OAAO,GACR,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAiBvD;;;;;GAKG;AACH,MAAM,OAAO,cAAe,SAAQ,cAAwB;IACjD,UAAU,CAAS;IACnB,UAAU,CAAS;IACnB,UAAU,CAAS;IAE5B,YAAY,EACV,SAAS,EACT,SAAS,EACT,SAAS,EACT,YAAY,GAAG,EAAE,GACK;QACtB,KAAK,CAAC,YAAY,CAAC,CAAC;QACpB,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAC7C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC/C,CAAC;IAES,KAAK,CAAC,IAAI;QAClB,MAAM,oBAAoB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5C,MAAM,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;IAES,KAAK,CAAC,QAAQ,CAAC,KAAe;QACtC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE;YAAE,OAAO,SAAS,CAAC;QACvC,wEAAwE;QACxE,MAAM,KAAK,GAAG,CAAC,MAAM,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,EAAE,CAAC;QACtD,MAAM,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QACtD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,iGAAiG;IACvF,KAAK;QACb,OAAO,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAI,CAAC,EAAE,CAAC;IACnC,CAAC;IAES,KAAK,CAAC,OAAO,CAAC,KAAe;QACrC,KAAK,CAAC,MAAM,EAAE,CAAC;IACjB,CAAC;IAES,KAAK,CAAC,KAAK,CAAC,KAAe;QACnC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;IAC1B,CAAC;CACF;AAED,KAAK,UAAU,SAAS,CAAC,IAAY;IACnC,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC;YAAE,OAAO,EAAE,CAAC;QACxC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/term.d.ts

@@ -0,0 +1,32 @@
+import { type Lease } from '@zukhruf/lease';
+/** What a term needs from its election to end: the backend's steps for the claim it won. */
+export interface TermSteps {
+    /** Starts watching the claim; `lose` reports that the backend took it away. */
+    watch(lose: (reason: Error) => void): Disposable;
+    /** Gives the claim up. Called only for a term that was not lost. */
+    release(): Promise<void>;
+    /** Frees the claim's resources. Called at each end. */
+    close(): Promise<void>;
+}
+/**
+ * One term of the elected leader: a lease on leadership. It ends when the
+ * leader resigns, when its process dies, or when the backend takes the claim
+ * away. Only the last one can happen while the leader still runs, and then
+ * `signal` aborts with `LeaseLostError`.
+ */
+export declare class Term implements Lease, AsyncDisposable {
+    #private;
+    /** Higher than the epoch of each earlier term, so a newer leader can always outrank an older one. */
+    readonly epoch: bigint;
+    constructor(epoch: bigint, steps: TermSteps);
+    /** Aborts with `LeaseLostError` when the term ends while its leader still runs. */
+    get signal(): AbortSignal;
+    /**
+     * Ends the term and gives the claim up. A second call waits for the first.
+     * After a loss, it only waits until the claim's resources are free, and it
+     * never rejects.
+     */
+    resign(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=term.d.ts.map

package/dist/term.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"term.d.ts","sourceRoot":"","sources":["../src/term.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAmB,MAAM,gBAAgB,CAAC;AAE7D,4FAA4F;AAC5F,MAAM,WAAW,SAAS;IACxB,+EAA+E;IAC/E,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,KAAK,KAAK,IAAI,GAAG,UAAU,CAAC;IACjD,oEAAoE;IACpE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,uDAAuD;IACvD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAKD;;;;;GAKG;AACH,qBAAa,IAAK,YAAW,KAAK,EAAE,eAAe;;IACjD,qGAAqG;IACrG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAQX,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS;IAM3C,mFAAmF;IACnF,IAAI,MAAM,IAAI,WAAW,CAExB;IAED;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAU7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CA+CvC"}

package/dist/term.js

@@ -0,0 +1,91 @@
+import { Latch } from '@zukhruf/async';
+import { LeaseController } from '@zukhruf/lease';
+/**
+ * One term of the elected leader: a lease on leadership. It ends when the
+ * leader resigns, when its process dies, or when the backend takes the claim
+ * away. Only the last one can happen while the leader still runs, and then
+ * `signal` aborts with `LeaseLostError`.
+ */
+export class Term {
+    /** Higher than the epoch of each earlier term, so a newer leader can always outrank an older one. */
+    epoch;
+    #steps;
+    #lease = new LeaseController('leadership');
+    /** Aborts once the term starts to end, by resign or by loss. */
+    #ending = new AbortController();
+    #ended = new Latch();
+    #watching = new DisposableStack();
+    constructor(epoch, steps) {
+        this.epoch = epoch;
+        this.#steps = steps;
+        this.#watching.use(steps.watch((reason) => this.#lose(reason)));
+    }
+    /** Aborts with `LeaseLostError` when the term ends while its leader still runs. */
+    get signal() {
+        return this.#lease.signal;
+    }
+    /**
+     * Ends the term and gives the claim up. A second call waits for the first.
+     * After a loss, it only waits until the claim's resources are free, and it
+     * never rejects.
+     */
+    async resign() {
+        if (!this.#ending.signal.aborted) {
+            this.#ending.abort();
+            this.#lease.end();
+            this.#ended.open(await this.#giveUp());
+        }
+        const ending = await this.#ended.wait();
+        if (ending.failed)
+            throw ending.error;
+    }
+    [Symbol.asyncDispose]() {
+        return this.resign();
+    }
+    #lose(reason) {
+        // After a resign began, the lease ignores the loss: the leader gave the
+        // claim up on purpose, so it is not told.
+        this.#lease.lose(reason);
+        // The claim is freed once, by the resign or by the first loss.
+        if (this.#ending.signal.aborted)
+            return;
+        this.#ending.abort();
+        // Freed one step later: a watch that reports a loss before it returns is
+        // held by then, so it stops before its claim is freed.
+        void Promise.resolve()
+            .then(() => this.#freeLost())
+            .then((ending) => this.#ended.open(ending));
+    }
+    async #giveUp() {
+        try {
+            this.#watching.dispose();
+            await this.#steps.release();
+        }
+        catch (error) {
+            await this.#steps.close().catch(() => { });
+            return { failed: true, error };
+        }
+        try {
+            await this.#steps.close();
+            return { failed: false };
+        }
+        catch (error) {
+            return { failed: true, error };
+        }
+    }
+    /**
+     * A lost claim is no longer this term's to give up: a release could undo
+     * the next leader's claim. Only its resources are freed, and a loss has no
+     * caller to report a failure to.
+     */
+    async #freeLost() {
+        try {
+            this.#watching.dispose();
+        }
+        finally {
+            await this.#steps.close().catch(() => { });
+        }
+        return { failed: false };
+    }
+}
+//# sourceMappingURL=term.js.map

package/dist/term.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"term.js","sourceRoot":"","sources":["../src/term.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@zukhruf/election",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.17",
+  "description": "Elect one leader among the processes that share a directory, with a term that ends when the leader dies and an epoch that grows with each term. Backends are subclasses of one campaign.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JanuaryLabs/zukhruf",
+    "directory": "packages/election"
+  },
+  "bugs": {
+    "url": "https://github.com/JanuaryLabs/zukhruf/issues"
+  },
+  "homepage": "https://github.com/JanuaryLabs/zukhruf/tree/main/packages/election#readme",
+  "keywords": [
+    "leader-election",
+    "election",
+    "leader",
+    "epoch",
+    "inter-process",
+    "sqlite"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@zukhruf/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/spec/**",
+    "!**/*.tsbuildinfo",
+    "!**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@zukhruf/async": "^0.3.13",
+    "@zukhruf/fs": "^0.3.16",
+    "@zukhruf/lease": "^0.3.16"
+  }
+}