@zukhruf/fencing 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,141 @@
-# Temporary Holding Version
+# @zukhruf/fencing
 
-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.
+A holder can lose its lease and not know it. When it continues, it can write over the work of a newer holder. This package gives each grant a fencing token: an integer that grows with each grant. A fenced resource keeps the highest token that it accepted, and it refuses a write with a lower token. `@zukhruf/mutex` gives a fencing token on each lease.
+
+The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
+
+## The problem
+
+Process A holds a key and reads the stock. Then process A freezes, for example in a long garbage collection or after a `SIGSTOP`. The issuer decides that A stopped, and it grants the key to process B. B sells the last item. Then A continues, and A also sells the last item.
+
+```
+holder A:  [token 33] read stock=1 ......frozen...... write stock=0   ✗ stale write
+holder B:                          [token 34] read stock=1, write stock=0
+result:    two customers got the last item
+```
+
+A is a **stale holder**. The signal of A's lease can abort, but A can write before the issuer sees the loss. Thus the signal is a warning. Only the resource can refuse the write, because the write goes directly to the resource.
+
+## The resource checks the token
+
+With fencing tokens, B writes first with token 34. The resource keeps 34. Then A writes with token 33, and the resource refuses it:
+
+```
+B writes with token 34 → resource: highest = 34, write accepted
+A writes with token 33 → resource: 33 < 34, write refused ✓
+```
+
+The holder does not check its token. The resource does. A holder cannot know that a newer holder exists, but the resource saw the newer token.
+
+In SQL, add a `fence` column, and do the check and the write in one statement:
+
+```ts
+import { DatabaseSync } from 'node:sqlite';
+
+import type { FencingToken } from '@zukhruf/fencing';
+
+const database = new DatabaseSync('shop.db', { readBigInts: true });
+database.exec(`
+  CREATE TABLE IF NOT EXISTS stock (
+    product  TEXT PRIMARY KEY,
+    quantity INTEGER NOT NULL,
+    fence    INTEGER NOT NULL DEFAULT 0
+  )
+`);
+
+/** Reserves one item, unless a holder with a newer token wrote this product. */
+function reserve(product: string, token: FencingToken): boolean {
+  const { changes } = database
+    .prepare(
+      `UPDATE stock SET quantity = quantity - 1, fence = ?
+       WHERE product = ? AND fence <= ? AND quantity > 0`,
+    )
+    .run(token.value, product, token.value);
+  return Number(changes) > 0;
+}
+```
+
+Follow these rules:
+
+- **Refuse only lower tokens.** Use `fence <= :token`, not `fence < :token`. One holder can write two times with the same token.
+- **Do the check and the write in one statement.** If you read the fence first and write later, a stale write can occur between the two.
+- **Compare the tokens as integers.** Use a 64-bit integer column, for example `INTEGER` in SQLite or `BIGINT` in PostgreSQL. In `node:sqlite`, bind `token.value` (a `bigint`), and open the database with `readBigInts: true`.
+- **Do not make a token a JavaScript number.** A number above 2^53 loses its last digits, and the tokens of `EpochTokenSource` get there from epoch 2^21. `JSON.stringify` refuses a `bigint`. Send the decimal text of the token instead.
+
+Fencing tokens protect only a fenced resource. If a stale holder sends an email or calls an API that does not compare tokens, the token does not stop it.
+
+## A token as text
+
+`token.toString()` gives the decimal digits of the token, for example `"34"`. `FencingToken.parse(text)` reads that text back. It returns `null` for each other text, as `URL.parse` does:
+
+```ts
+import { FencingToken } from '@zukhruf/fencing';
+
+FencingToken.parse('34'); // FencingToken { value: 34n }
+FencingToken.parse('-1'); // null: a token is never negative
+FencingToken.parse(' 34'); // null
+FencingToken.parse('0x22'); // null
+```
+
+`BigInt` alone accepts more: `BigInt('')` is `0n`, `BigInt(' 34')` is `34n`, and `BigInt('0x22')` is `34n`. Thus use `parse` for each token that you read from a message or a header.
+
+## One key, one token source
+
+A token has no name of its key and no name of its token source. Two tokens of different keys, or of different token sources, cannot be compared. A counter in memory and a counter in a file can both give token 7 to two different holders.
+
+Thus a fenced resource compares the tokens of one key, from one token source. Give each protected row, file, or object its own key. Give all issuers of that key the same token source.
+
+## Token sources
+
+A **token source** makes the tokens of an issuer. The issuer asks it for the next token of a key, one time for each grant. The issuer never asks for two tokens of one key at the same time: a mutex holds the key while it asks.
+
+| Token source                | Tokens                                                                                                  | Durable                                    |
+| --------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `CounterTokenSource`        | 1, 2, 3, … in memory, one counter for all keys.                                                         | No. It starts again at 1 with the process. |
+| `MonotonicClockTokenSource` | The monotonic clock of the process (`process.hrtime.bigint()`). Each token is higher than the last one. | No. Its order holds only in one process.   |
+| `FileTokenSource`           | 1, 2, 3, … for each key, in a file `<key>.fence` in the directory that you give.                        | Yes.                                       |
+| `EpochTokenSource`          | `epoch << 32 \| counter`. The counter starts at 1 and is one counter for all keys.                      | Yes, when each start uses a higher epoch.  |
+
+Select a token source:
+
+- **The resource does not live longer than the process**, for example a cache in memory: use `CounterTokenSource`.
+- **Worker threads of one process share a resource**: use `MonotonicClockTokenSource`. All threads of a process read the same monotonic clock, so a thread gets a higher token than the thread that held the key before it, with no shared memory.
+- **The resource is durable**, for example a database or a file: use `FileTokenSource`. The resource keeps the highest token after your process stops. A source in memory starts again at 1, and then the resource refuses each new write.
+- **A leader issues the grants, and a new leader can take over**: use `EpochTokenSource` with the epoch of the leader's term, for example `term.epoch` of `@zukhruf/election`.
+
+```ts
+import { FileTokenSource } from '@zukhruf/fencing';
+
+const tokens = new FileTokenSource('/var/lib/my-app/fences');
+const token = await tokens.next('product:42');
+```
+
+`FileTokenSource` makes the directory if it is absent. It keeps the counter of each key as decimal text, and it replaces the file in one step and syncs it to the disk before it gives the token. On Linux and macOS, a power loss cannot make it give one token two times. The name of the file comes from the key with `safeFileName` of `@zukhruf/fs`. Processes that use earlier versions of `@zukhruf/mutex` find the same files.
+
+`EpochTokenSource` puts the epoch in the high 32 bits and the counter in the low 32 bits, as ZooKeeper does in its `zxid`. Each token of a newer epoch is higher than each token of an older epoch. A new leader thus outranks all grants of the leader before it. The epoch must be from 0 to 2^31 − 1, so that each token fits a signed 64-bit integer. One epoch gives at most 2^32 − 1 tokens. After that, `next` throws a `RangeError`.
+
+## A fenced lease
+
+An issuer of fenced access gives the holder a `FencedLease`: a `Lease` of `@zukhruf/lease` that also has a `token`. The signal warns the holder. The token protects the resource.
+
+```ts
+import type { FencedLease } from '@zukhruf/fencing';
+
+async function sell(lease: FencedLease, product: string) {
+  lease.signal.throwIfAborted();
+  if (!reserve(product, lease.token)) throw new Error('A newer holder wrote.');
+}
+```
+
+## Why not a random value, a UUID, or a time
+
+A resource can refuse a stale holder only when the tokens of one key are strictly in the order of the grants. A random value or a UUID has no order. A UUIDv7 has an order by time only to the millisecond, and it is random in that millisecond. In a test in Node 26, 50,160 of 100,000 UUIDv7 values from one thread were lower than the value before them. A clock of the wall can go back. See [ADR 0001](./docs/adr/0001-a-fencing-token-is-a-number-the-resource-checks.md).
+
+## The same concepts in other systems
+
+| This package                  | Other systems                                                                                                    |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Fencing token                 | Kleppmann, "How to do distributed locking" (2016); Chubby sequencer; Hazelcast `FencedLock` fence; etcd revision |
+| The resource checks the token | Chubby `CheckSequencer()`; an SQL `UPDATE … WHERE fence <= ?`                                                    |
+| `EpochTokenSource`            | ZooKeeper `zxid`: epoch in the high 32 bits, counter in the low 32 bits; Raft term; Kafka leader epoch           |
+| `FencedLease`                 | Hazelcast `FencedLock`; etcd `concurrency.Mutex` with its session and the revision of its key                    |

package/dist/counter-token-source.d.ts

@@ -0,0 +1,11 @@
+import { FencingToken } from './fencing-token.ts';
+import type { TokenSource } from './token-source.ts';
+/**
+ * Counts in memory, so tokens restart when the process does. Only fence
+ * resources that do not outlive the process with it.
+ */
+export declare class CounterTokenSource implements TokenSource {
+    #private;
+    next(_key: string): Promise<FencingToken>;
+}
+//# sourceMappingURL=counter-token-source.d.ts.map

package/dist/counter-token-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"counter-token-source.d.ts","sourceRoot":"","sources":["../src/counter-token-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,WAAW;;IAG9C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAIhD"}

package/dist/counter-token-source.js

@@ -0,0 +1,13 @@
+import { FencingToken } from "./fencing-token.js";
+/**
+ * Counts in memory, so tokens restart when the process does. Only fence
+ * resources that do not outlive the process with it.
+ */
+export class CounterTokenSource {
+    #last = 0n;
+    async next(_key) {
+        this.#last++;
+        return new FencingToken(this.#last);
+    }
+}
+//# sourceMappingURL=counter-token-source.js.map

package/dist/counter-token-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"counter-token-source.js","sourceRoot":"","sources":["../src/counter-token-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IAC7B,KAAK,GAAG,EAAE,CAAC;IAEX,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/epoch-token-source.d.ts

@@ -0,0 +1,13 @@
+import { FencingToken } from './fencing-token.ts';
+import type { TokenSource } from './token-source.ts';
+/**
+ * Packs `epoch << 32 | sequence`, so every token minted in a newer epoch beats
+ * every token from an older one: a new leader outranks all of its
+ * predecessor's grants. The result fits a signed 64-bit integer.
+ */
+export declare class EpochTokenSource implements TokenSource {
+    #private;
+    constructor(epoch: bigint);
+    next(_key: string): Promise<FencingToken>;
+}
+//# sourceMappingURL=epoch-token-source.d.ts.map

package/dist/epoch-token-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epoch-token-source.d.ts","sourceRoot":"","sources":["../src/epoch-token-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMrD;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,WAAW;;gBAItC,KAAK,EAAE,MAAM;IAOnB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAOhD"}

package/dist/epoch-token-source.js

@@ -0,0 +1,27 @@
+import { FencingToken } from "./fencing-token.js";
+const SEQUENCE_BITS = 32n;
+const EPOCH_LIMIT = 1n << 31n;
+const SEQUENCE_LIMIT = 1n << SEQUENCE_BITS;
+/**
+ * Packs `epoch << 32 | sequence`, so every token minted in a newer epoch beats
+ * every token from an older one: a new leader outranks all of its
+ * predecessor's grants. The result fits a signed 64-bit integer.
+ */
+export class EpochTokenSource {
+    #epoch;
+    #sequence = 0n;
+    constructor(epoch) {
+        if (epoch < 0n || epoch >= EPOCH_LIMIT) {
+            throw new RangeError(`Epoch ${epoch} is outside [0, ${EPOCH_LIMIT}).`);
+        }
+        this.#epoch = epoch;
+    }
+    async next(_key) {
+        this.#sequence++;
+        if (this.#sequence >= SEQUENCE_LIMIT) {
+            throw new RangeError(`Epoch ${this.#epoch} has no tokens left.`);
+        }
+        return new FencingToken((this.#epoch << SEQUENCE_BITS) | this.#sequence);
+    }
+}
+//# sourceMappingURL=epoch-token-source.js.map

package/dist/epoch-token-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"epoch-token-source.js","sourceRoot":"","sources":["../src/epoch-token-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,MAAM,aAAa,GAAG,GAAG,CAAC;AAC1B,MAAM,WAAW,GAAG,EAAE,IAAI,GAAG,CAAC;AAC9B,MAAM,cAAc,GAAG,EAAE,IAAI,aAAa,CAAC;AAE3C;;;;GAIG;AACH,MAAM,OAAO,gBAAgB;IAClB,MAAM,CAAS;IACxB,SAAS,GAAG,EAAE,CAAC;IAEf,YAAY,KAAa;QACvB,IAAI,KAAK,GAAG,EAAE,IAAI,KAAK,IAAI,WAAW,EAAE,CAAC;YACvC,MAAM,IAAI,UAAU,CAAC,SAAS,KAAK,mBAAmB,WAAW,IAAI,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,IAAI,IAAI,CAAC,SAAS,IAAI,cAAc,EAAE,CAAC;YACrC,MAAM,IAAI,UAAU,CAAC,SAAS,IAAI,CAAC,MAAM,sBAAsB,CAAC,CAAC;QACnE,CAAC;QACD,OAAO,IAAI,YAAY,CAAC,CAAC,IAAI,CAAC,MAAM,IAAI,aAAa,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3E,CAAC;CACF"}

package/dist/fenced-lease.d.ts

@@ -0,0 +1,11 @@
+import type { Lease } from '@zukhruf/lease';
+import type { FencingToken } from './fencing-token.ts';
+/**
+ * What an issuer of fenced access, such as a mutex or a single flight, gives
+ * its holder: the lease warns the holder, and the token lets a fenced resource
+ * refuse the holder's writes once a newer holder has written.
+ */
+export interface FencedLease extends Lease {
+    readonly token: FencingToken;
+}
+//# sourceMappingURL=fenced-lease.d.ts.map

package/dist/fenced-lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fenced-lease.d.ts","sourceRoot":"","sources":["../src/fenced-lease.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,WAAY,SAAQ,KAAK;IACxC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;CAC9B"}

package/dist/fenced-lease.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fenced-lease.js.map

package/dist/fenced-lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fenced-lease.js","sourceRoot":"","sources":["../src/fenced-lease.ts"],"names":[],"mappings":""}

package/dist/fencing-token.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Grows with every grant. A resource that rejects writes carrying a token
+ * older than the newest it has seen ignores holders that were superseded
+ * without knowing it (frozen, partitioned, or outlived by a failover).
+ */
+export declare class FencingToken {
+    readonly value: bigint;
+    constructor(value: bigint);
+    /**
+     * Reads decimal digits, the text that `toString` writes, or returns null for
+     * any other text. `BigInt` alone would also accept `''`, `' 1'` and `'0x10'`,
+     * and a token is never negative.
+     */
+    static parse(text: string): FencingToken | null;
+    isNewerThan(other: FencingToken): boolean;
+    toString(): string;
+}
+//# sourceMappingURL=fencing-token.d.ts.map

package/dist/fencing-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fencing-token.d.ts","sourceRoot":"","sources":["../src/fencing-token.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,YAAY;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,KAAK,EAAE,MAAM;IAIzB;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAI/C,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;IAIzC,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/fencing-token.js

@@ -0,0 +1,26 @@
+/**
+ * Grows with every grant. A resource that rejects writes carrying a token
+ * older than the newest it has seen ignores holders that were superseded
+ * without knowing it (frozen, partitioned, or outlived by a failover).
+ */
+export class FencingToken {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    /**
+     * Reads decimal digits, the text that `toString` writes, or returns null for
+     * any other text. `BigInt` alone would also accept `''`, `' 1'` and `'0x10'`,
+     * and a token is never negative.
+     */
+    static parse(text) {
+        return /^\d+$/.test(text) ? new FencingToken(BigInt(text)) : null;
+    }
+    isNewerThan(other) {
+        return this.value > other.value;
+    }
+    toString() {
+        return this.value.toString();
+    }
+}
+//# sourceMappingURL=fencing-token.js.map

package/dist/fencing-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fencing-token.js","sourceRoot":"","sources":["../src/fencing-token.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,YAAY;IACd,KAAK,CAAS;IAEvB,YAAY,KAAa;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,IAAY;QACvB,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACpE,CAAC;IAED,WAAW,CAAC,KAAmB;QAC7B,OAAO,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAClC,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC/B,CAAC;CACF"}

package/dist/file-token-source.d.ts

@@ -0,0 +1,13 @@
+import { FencingToken } from './fencing-token.ts';
+import type { TokenSource } from './token-source.ts';
+/**
+ * Keeps one counter file per key in `directory`, so tokens keep growing across
+ * process restarts and can fence durable resources. Relies on the caller holding
+ * the key's lock: read, increment and replace are not atomic on their own.
+ */
+export declare class FileTokenSource implements TokenSource {
+    #private;
+    constructor(directory: string);
+    next(key: string): Promise<FencingToken>;
+}
+//# sourceMappingURL=file-token-source.d.ts.map

package/dist/file-token-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-token-source.d.ts","sourceRoot":"","sources":["../src/file-token-source.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;GAIG;AACH,qBAAa,eAAgB,YAAW,WAAW;;gBAGrC,SAAS,EAAE,MAAM;IAIvB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAQ/C"}

package/dist/file-token-source.js

@@ -0,0 +1,34 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { draftSuffixLength, durableWrite, isErrno, safeFileName, } from '@zukhruf/fs';
+import { FencingToken } from "./fencing-token.js";
+/**
+ * Keeps one counter file per key in `directory`, so tokens keep growing across
+ * process restarts and can fence durable resources. Relies on the caller holding
+ * the key's lock: read, increment and replace are not atomic on their own.
+ */
+export class FileTokenSource {
+    #directory;
+    constructor(directory) {
+        this.#directory = directory;
+    }
+    async next(key) {
+        await mkdir(this.#directory, { recursive: true });
+        const name = safeFileName(key, '.fence'.length + draftSuffixLength);
+        const path = join(this.#directory, `${name}.fence`);
+        const token = (await readCounter(path)) + 1n;
+        await durableWrite(path, token.toString());
+        return new FencingToken(token);
+    }
+}
+async function readCounter(path) {
+    try {
+        return BigInt(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return 0n;
+        throw error;
+    }
+}
+//# sourceMappingURL=file-token-source.js.map

package/dist/file-token-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-token-source.js","sourceRoot":"","sources":["../src/file-token-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,OAAO,EACP,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD;;;;GAIG;AACH,MAAM,OAAO,eAAe;IACjB,UAAU,CAAS;IAE5B,YAAY,SAAiB;QAC3B,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,MAAM,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,GAAG,iBAAiB,CAAC,CAAC;QACpE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,IAAI,QAAQ,CAAC,CAAC;QACpD,MAAM,KAAK,GAAG,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;QAC7C,MAAM,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC3C,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;CACF;AAED,KAAK,UAAU,WAAW,CAAC,IAAY;IACrC,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/index.d.ts

@@ -0,0 +1,8 @@
+export { CounterTokenSource } from './counter-token-source.ts';
+export { EpochTokenSource } from './epoch-token-source.ts';
+export type { FencedLease } from './fenced-lease.ts';
+export { FencingToken } from './fencing-token.ts';
+export { FileTokenSource } from './file-token-source.ts';
+export { MonotonicClockTokenSource } from './monotonic-clock-token-source.ts';
+export type { TokenSource } from './token-source.ts';
+//# 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,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { CounterTokenSource } from "./counter-token-source.js";
+export { EpochTokenSource } from "./epoch-token-source.js";
+export { FencingToken } from "./fencing-token.js";
+export { FileTokenSource } from "./file-token-source.js";
+export { MonotonicClockTokenSource } from "./monotonic-clock-token-source.js";
+//# 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,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/monotonic-clock-token-source.d.ts

@@ -0,0 +1,12 @@
+import { FencingToken } from './fencing-token.ts';
+import type { TokenSource } from './token-source.ts';
+/**
+ * Reads the process-wide monotonic clock, which every worker thread shares, so
+ * grants serialized by a lock read strictly later times without shared memory.
+ * Tokens restart when the process does.
+ */
+export declare class MonotonicClockTokenSource implements TokenSource {
+    #private;
+    next(_key: string): Promise<FencingToken>;
+}
+//# sourceMappingURL=monotonic-clock-token-source.d.ts.map

package/dist/monotonic-clock-token-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monotonic-clock-token-source.d.ts","sourceRoot":"","sources":["../src/monotonic-clock-token-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;GAIG;AACH,qBAAa,yBAA0B,YAAW,WAAW;;IAGrD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAKhD"}

package/dist/monotonic-clock-token-source.js

@@ -0,0 +1,15 @@
+import { FencingToken } from "./fencing-token.js";
+/**
+ * Reads the process-wide monotonic clock, which every worker thread shares, so
+ * grants serialized by a lock read strictly later times without shared memory.
+ * Tokens restart when the process does.
+ */
+export class MonotonicClockTokenSource {
+    #last = 0n;
+    async next(_key) {
+        const now = process.hrtime.bigint();
+        this.#last = now > this.#last ? now : this.#last + 1n;
+        return new FencingToken(this.#last);
+    }
+}
+//# sourceMappingURL=monotonic-clock-token-source.js.map

package/dist/monotonic-clock-token-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"monotonic-clock-token-source.js","sourceRoot":"","sources":["../src/monotonic-clock-token-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD;;;;GAIG;AACH,MAAM,OAAO,yBAAyB;IACpC,KAAK,GAAG,EAAE,CAAC;IAEX,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QACtD,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/token-source.d.ts

@@ -0,0 +1,9 @@
+import type { FencingToken } from './fencing-token.ts';
+/**
+ * Mints fencing tokens. Callers mint for one key one at a time (a mutex holds
+ * the key's lock while it calls `next`), so each token is newer than the last.
+ */
+export interface TokenSource {
+    next(key: string): Promise<FencingToken>;
+}
+//# sourceMappingURL=token-source.d.ts.map

package/dist/token-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-source.d.ts","sourceRoot":"","sources":["../src/token-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1C"}

package/dist/token-source.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=token-source.js.map

package/dist/token-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-source.js","sourceRoot":"","sources":["../src/token-source.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@zukhruf/fencing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.17",
+  "description": "Fencing tokens: a number that grows with each grant, so a protected resource refuses the writes of a stale holder. Token sources that count in memory, in files, or by epoch, and the fenced lease that carries a token.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JanuaryLabs/zukhruf",
+    "directory": "packages/fencing"
+  },
+  "bugs": {
+    "url": "https://github.com/JanuaryLabs/zukhruf/issues"
+  },
+  "homepage": "https://github.com/JanuaryLabs/zukhruf/tree/main/packages/fencing#readme",
+  "keywords": [
+    "fencing",
+    "fencing-token",
+    "lock",
+    "lease",
+    "stale",
+    "distributed"
+  ],
+  "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/fs": "^0.3.16",
+    "@zukhruf/lease": "^0.3.16"
+  }
+}