@rivus/agent-kit-collab 0.0.0 → 0.3.0

package/dist/lease.js

@@ -0,0 +1,670 @@
+import { a as holderLiveness, i as isSqliteBusy, n as backoffMs, o as readText, r as tryProcessLock } from "./acquire-process-lock-A0oYDN9m.js";
+import { PlatformService } from "@rivus/agent-kit/platform/effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as z from "zod/mini";
+import * as Context from "effect/Context";
+import { AgentKitError, err, ok } from "@rivus/agent-kit/catalog";
+import * as Semaphore from "effect/Semaphore";
+import * as Schedule from "effect/Schedule";
+import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
+import * as Exit from "effect/Exit";
+import * as Ref from "effect/Ref";
+//#region src/lease/application/ports.ts
+const LeaseStoreBase = Context.Service()("@rivus/agent-kit-collab/lease/LeaseStore/v1");
+/** The lease store port; `sqliteLeaseStore`, `fileLeaseStore` and `memoryLeaseStore` provide it. */
+var LeaseStore = class extends LeaseStoreBase {};
+//#endregion
+//#region src/lease/application/store-failure.ts
+function storeFailure(key, reason, message, cause) {
+	return cause === void 0 ? {
+		_tag: "LeaseStoreFailure",
+		key,
+		reason,
+		message
+	} : {
+		_tag: "LeaseStoreFailure",
+		key,
+		reason,
+		message,
+		cause
+	};
+}
+//#endregion
+//#region src/lease/adapters/key-file-name.ts
+/** File names stay well under the usual 255-byte limit even with a suffix such as `.lease.json.stale`. */
+const MAX_LENGTH = 160;
+/**
+* The part of a file name that stands for `key`. Percent-encoding keeps `/`, `.` and other separators from forming a
+* path; a longer key keeps a readable prefix and a SHA-256 of the whole key.
+*/
+function keyFileName(key) {
+	const encoded = encodeURIComponent(key).replace(/[!'()*.~]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+	if (encoded.length <= MAX_LENGTH) return Effect.succeed(encoded);
+	return Effect.promise(() => crypto.subtle.digest("SHA-256", new TextEncoder().encode(key))).pipe(Effect.map((digest) => {
+		const hex = [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+		return `${encoded.slice(0, 64)}~${hex}`;
+	}));
+}
+//#endregion
+//#region src/lease/adapters/lease-record-codec.ts
+const holderSchema = z.object({
+	host: z.string(),
+	bootId: z.string(),
+	pid: z.number(),
+	startTime: z.number()
+});
+const snapshotSchema = z.object({
+	key: z.string(),
+	generation: z.number(),
+	revision: z.number(),
+	holder: z.nullable(holderSchema),
+	holderId: z.nullable(z.string()),
+	renewedAt: z.number()
+});
+/** Checks the shape of a stored record; the Lease aggregate checks its invariants when the manager restores it. */
+function decodeSnapshot(value) {
+	const parsed = snapshotSchema.safeParse(value);
+	return parsed.success ? parsed.data : void 0;
+}
+function decodeHolder(json) {
+	if (json === null) return null;
+	try {
+		const parsed = holderSchema.safeParse(JSON.parse(json));
+		return parsed.success ? parsed.data : void 0;
+	} catch {
+		return;
+	}
+}
+/** Only the identity fields, whatever else the platform's `ProcessIdentity` carries. */
+function encodeHolder(holder) {
+	if (holder === null) return null;
+	const { host, bootId, pid, startTime } = holder;
+	return JSON.stringify({
+		host,
+		bootId,
+		pid,
+		startTime
+	});
+}
+//#endregion
+//#region src/lease/domain/lease/policies/acquisition.ts
+/**
+* A lease can be taken when there is no record, the record is a tombstone, its holder is dead, or it has not been
+* renewed within the TTL as the observer saw it. A live or unknown holder that keeps renewing keeps the lease.
+*/
+function canAcquire(lease, view) {
+	return lease === void 0 || lease.holder === null || view.liveness === "dead" || !view.fresh;
+}
+//#endregion
+//#region src/lease/domain/lease/policies/fence-check.ts
+/** The token the next acquisition of `key` receives: one generation above the record, 1 for a new key. */
+function nextFencingToken(current, key) {
+	return {
+		key,
+		generation: (current?.generation ?? 0) + 1
+	};
+}
+/**
+* The check a protected resource runs inside its own atomic write: `lastSeen` is the highest token it has accepted
+* for the key. A smaller generation is refused; an equal one is the same holder writing again. On success, store the
+* returned token as the new `lastSeen`.
+*/
+function checkFence(lastSeen, token) {
+	if (lastSeen !== void 0 && lastSeen.key === token.key && token.generation < lastSeen.generation) return err({
+		_tag: "FenceRejected",
+		key: token.key,
+		generation: token.generation,
+		current: lastSeen.generation
+	});
+	return ok(token);
+}
+//#endregion
+//#region src/lease/domain/lease/aggregate/lease.ts
+/**
+* One key's lease. It has one holder at a time; its generation never decreases, release included, because release
+* keeps the record as a tombstone; every write increases its revision. Stores persist the snapshot and compare
+* revisions, so a transition only takes effect when no other writer got there first.
+*/
+var Lease = class Lease {
+	/** The first acquisition of a key that has no record. */
+	static create(claim) {
+		const { generation } = nextFencingToken(void 0, claim.key);
+		const state = new Lease({
+			key: claim.key,
+			generation,
+			revision: 1,
+			holder: claim.holder,
+			holderId: claim.holderId,
+			renewedAt: claim.now
+		});
+		return {
+			state,
+			events: [acquired(state.snapshot, null)]
+		};
+	}
+	static restore(snapshot) {
+		const problem = invalidity(snapshot);
+		if (problem !== void 0) return err({
+			_tag: "LeaseRecordInvalid",
+			key: snapshot.key,
+			message: problem
+		});
+		return ok(new Lease({ ...snapshot }));
+	}
+	snapshot;
+	constructor(snapshot) {
+		this.snapshot = snapshot;
+		Object.freeze(this);
+	}
+	/** Takes the lease when `canAcquire` allows it; the generation moves to the next fencing token. */
+	acquire(claim, view) {
+		const { holder, holderId, generation, key } = this.snapshot;
+		if (holder !== null && holderId !== null && !canAcquire(this.snapshot, view)) return err({
+			_tag: "LeaseHeld",
+			key,
+			generation,
+			holder,
+			holderId
+		});
+		const state = new Lease({
+			key,
+			generation: nextFencingToken(this.snapshot, key).generation,
+			revision: this.snapshot.revision + 1,
+			holder: claim.holder,
+			holderId: claim.holderId,
+			renewedAt: claim.now
+		});
+		return ok({
+			state,
+			events: [acquired(state.snapshot, holderId)]
+		});
+	}
+	/** A heartbeat: only the holding acquisition renews, and the generation stays. */
+	renew(holding, now) {
+		const lost = this.lostBy(holding);
+		if (lost !== void 0) return err(lost);
+		const state = new Lease({
+			...this.snapshot,
+			revision: this.snapshot.revision + 1,
+			renewedAt: now
+		});
+		const { key, generation, revision } = state.snapshot;
+		return ok({
+			state,
+			events: [{
+				_tag: "LeaseRenewed",
+				key,
+				generation,
+				revision
+			}]
+		});
+	}
+	/** Leaves a tombstone: no holder, the same generation, so the next acquisition still moves forward. */
+	release(holding, now) {
+		const lost = this.lostBy(holding);
+		if (lost !== void 0) return err(lost);
+		const state = new Lease({
+			...this.snapshot,
+			revision: this.snapshot.revision + 1,
+			holder: null,
+			holderId: null,
+			renewedAt: now
+		});
+		const { key, generation } = state.snapshot;
+		return ok({
+			state,
+			events: [{
+				_tag: "LeaseReleased",
+				key,
+				generation,
+				holderId: holding.holderId
+			}]
+		});
+	}
+	toSnapshot() {
+		return this.snapshot;
+	}
+	lostBy(holding) {
+		const { key, holderId, generation } = this.snapshot;
+		if (holderId === holding.holderId && generation === holding.generation) return;
+		const reason = holderId === null ? "released" : "taken-over";
+		return {
+			_tag: "LeaseLost",
+			key,
+			generation: holding.generation,
+			reason
+		};
+	}
+};
+function acquired(snapshot, previousHolderId) {
+	const { key, generation, holderId } = snapshot;
+	return {
+		_tag: "LeaseAcquired",
+		key,
+		generation,
+		holderId: holderId ?? "",
+		previousHolderId
+	};
+}
+function invalidity(snapshot) {
+	if (snapshot.key === "") return "the key is empty";
+	if (!Number.isSafeInteger(snapshot.generation) || snapshot.generation < 1) return `generation ${snapshot.generation} is not a positive integer`;
+	if (!Number.isSafeInteger(snapshot.revision) || snapshot.revision < snapshot.generation) return `revision ${snapshot.revision} is not an integer at least as large as the generation`;
+	if (snapshot.holder === null !== (snapshot.holderId === null)) return "a holder and a holder id come together";
+	return Number.isFinite(snapshot.renewedAt) ? void 0 : "renewedAt is not a number";
+}
+//#endregion
+//#region src/lease/domain/lease/policies/freshness.ts
+/** Restarts the observer's clock when the record has a revision it has not seen. */
+function observe(previous, lease, now) {
+	return previous?.revision === lease.revision ? previous : {
+		revision: lease.revision,
+		observedAt: now
+	};
+}
+/**
+* Whether a held lease is still valid for this observer: its record changed less than `ttlMs` ago by the observer's
+* monotonic clock. A record whose revision the observation has not seen has just changed, so it is fresh. A
+* tombstone is never fresh.
+*/
+function isFresh(lease, observation, now, ttlMs) {
+	return lease.holder !== null && (observation.revision !== lease.revision || now - observation.observedAt < ttlMs);
+}
+//#endregion
+//#region src/lease/adapters/process-fence.ts
+/** The first retry of a waiting fence or guard; later ones back off from it. */
+const RETRY_MS = 10;
+/**
+* Holds a process lock at `path` until the Scope closes: an exclusive SQLite lock when the platform has SQLite, a
+* lock file otherwise. Each attempt is uninterruptible and registers its release in the same step; waiting happens
+* between attempts, where interruption is safe, with a growing pause. A holder that exits frees the lock at once.
+*/
+function holdProcessLock(platform, key, path, options = {}) {
+	const attempt = (first) => Effect.acquireRelease(Effect.tryPromise({
+		try: () => tryProcessLock(platform, path, { first }),
+		catch: (cause) => storeFailure(key, "io", `cannot lock ${path}`, cause)
+	}).pipe(Effect.flatMap((result) => result.ok ? Effect.succeed(result.value) : Effect.fail(storeFailure(key, "busy", `${path} is locked`)))), (lock) => Effect.promise(() => lock.release()));
+	return Effect.gen(function* () {
+		const started = platform.clock.monotonic();
+		for (let turn = 0;; turn += 1) {
+			if (yield* attempt(turn === 0).pipe(Effect.as(true), Effect.catchIf((failure) => failure.reason === "busy", () => Effect.succeed(false)))) return;
+			if (options.timeoutMs !== void 0 && platform.clock.monotonic() - started >= options.timeoutMs) return yield* Effect.fail(storeFailure(key, "busy", `${path} is still locked after ${options.timeoutMs} ms`));
+			yield* Effect.sleep(backoffMs(RETRY_MS, turn));
+		}
+	});
+}
+//#endregion
+//#region src/lease/adapters/file-lease-store.ts
+const SCHEMA_VERSION$1 = 1;
+/**
+* A guard is held only for one read, compare and write, so waiting longer means a stalled holder: the write reports
+* `busy` instead of waiting, and callers such as a heartbeat retry it later.
+*/
+const GUARD_TIMEOUT_MS = 1e3;
+/**
+* The fallback store for platforms without SQLite: one JSON record per key, `<key>.lease.json`, replaced with
+* `writeAtomic`. Every `compareAndSet` holds the key's guard (`<key>.lease.guard`) while it reads, compares and
+* writes, and reports `busy` when the guard stays held longer than a second; `fence` holds `<key>.lease.fence`.
+* Both are process locks, so without SQLite they are lock files whose dead holders are reclaimed one reclaimer at a
+* time, with the gaps `acquireProcessLock` documents. A record with an unknown `schemaVersion` or shape is refused
+* and never overwritten.
+*/
+function fileLeaseStore(options) {
+	const { dir } = options;
+	return Layer.effect(LeaseStore, Effect.gen(function* () {
+		const platform = yield* PlatformService;
+		const pathOf = (key, suffix) => keyFileName(key).pipe(Effect.map((name) => `${dir}/${name}.lease${suffix}`));
+		const read = (key) => pathOf(key, ".json").pipe(Effect.flatMap((path) => readRecord(platform, key, path)));
+		return {
+			read,
+			compareAndSet: (key, expected, next) => Effect.scoped(Effect.gen(function* () {
+				yield* holdProcessLock(platform, key, yield* pathOf(key, ".guard"), { timeoutMs: GUARD_TIMEOUT_MS });
+				const path = yield* pathOf(key, ".json");
+				return yield* Effect.uninterruptible(Effect.gen(function* () {
+					if ((yield* readRecord(platform, key, path))?.revision !== expected) return false;
+					yield* Effect.tryPromise({
+						try: () => platform.fs.writeAtomic(path, JSON.stringify({
+							schemaVersion: SCHEMA_VERSION$1,
+							record: next
+						})),
+						catch: (cause) => storeFailure(key, "io", `cannot write ${path}`, cause)
+					});
+					return true;
+				}));
+			})),
+			fence: (key) => pathOf(key, ".fence").pipe(Effect.flatMap((path) => holdProcessLock(platform, key, path)))
+		};
+	}));
+}
+function readRecord(platform, key, path) {
+	return Effect.tryPromise({
+		try: () => readText(platform, path),
+		catch: (cause) => storeFailure(key, "io", `cannot read ${path}`, cause)
+	}).pipe(Effect.flatMap((text) => text === void 0 ? Effect.succeed(void 0) : decodeFile(key, path, text)));
+}
+function decodeFile(key, path, text) {
+	let json;
+	try {
+		json = JSON.parse(text);
+	} catch (cause) {
+		return Effect.fail(storeFailure(key, "invalid-record", `${path} is not JSON`, cause));
+	}
+	const { schemaVersion, record } = typeof json === "object" && json !== null ? json : {};
+	if (schemaVersion !== SCHEMA_VERSION$1) return Effect.fail(storeFailure(key, "unsupported-schema", `${path} has schemaVersion ${String(schemaVersion)}; expected 1`));
+	const snapshot = decodeSnapshot(record);
+	return snapshot === void 0 ? Effect.fail(storeFailure(key, "invalid-record", `${path} holds a record of an unexpected shape`)) : Effect.succeed(snapshot);
+}
+//#endregion
+//#region src/lease/adapters/memory-lease-store.ts
+/**
+* A store for one process, such as tests or a host whose leases never cross a process boundary. Each Layer build
+* starts empty.
+*/
+function memoryLeaseStore() {
+	return Layer.sync(LeaseStore, () => {
+		const records = /* @__PURE__ */ new Map();
+		const fences = /* @__PURE__ */ new Map();
+		const fenceOf = (key) => {
+			const fence = fences.get(key) ?? Semaphore.makeUnsafe(1);
+			fences.set(key, fence);
+			return fence;
+		};
+		return {
+			read: (key) => Effect.sync(() => records.get(key)),
+			compareAndSet: (key, expected, next) => Effect.sync(() => {
+				if (records.get(key)?.revision !== expected) return false;
+				records.set(key, next);
+				return true;
+			}),
+			fence: (key) => Effect.acquireRelease(fenceOf(key).take(1), () => fenceOf(key).release(1), { interruptible: true }).pipe(Effect.asVoid)
+		};
+	});
+}
+//#endregion
+//#region src/lease/adapters/sqlite-lease-store.ts
+const SCHEMA_VERSION = 1;
+/** Long enough for another writer's single-row transaction; longer waits block the event loop, so retry instead. */
+const BUSY_TIMEOUT_MS = 50;
+const BUSY_RETRIES = 100;
+const BUSY_RETRY_MS = 5;
+/**
+* The lease store for one machine: one row per key in a SQLite database. `compareAndSet` runs in a
+* `BEGIN IMMEDIATE` transaction, which takes SQLite's write lock (an fcntl lock) before reading the revision, so
+* processes sharing the file compare and write atomically. The lock is released when its process exits, so neither a
+* crashed writer nor a reused pid can leave the store stuck. Fails to build with `unavailable` when the platform has
+* no SQLite, and with `unsupported-schema` for a database written by a newer version.
+*/
+function sqliteLeaseStore(options) {
+	const { path } = options;
+	return Layer.effect(LeaseStore, Effect.gen(function* () {
+		const platform = yield* PlatformService;
+		const { sqlite } = platform;
+		if (sqlite === void 0) return yield* Effect.fail(storeFailure("", "unavailable", "the platform has no SQLite"));
+		const db = yield* Effect.acquireRelease(sqliteTry("", `cannot open ${path}`, () => sqlite.open(path)), (opened) => Effect.sync(() => opened.close()));
+		yield* retryBusy(sqliteTry("", `cannot prepare ${path}`, () => migrate(db)));
+		const statements = {
+			select: db.prepare("SELECT key, generation, revision, holder, holder_id, renewed_at FROM lease_record WHERE key = ?"),
+			selectRevision: db.prepare("SELECT revision FROM lease_record WHERE key = ?"),
+			upsert: db.prepare(`INSERT INTO lease_record (key, generation, revision, holder, holder_id, renewed_at) VALUES (?, ?, ?, ?, ?, ?)
+           ON CONFLICT (key) DO UPDATE SET generation = excluded.generation, revision = excluded.revision,
+             holder = excluded.holder, holder_id = excluded.holder_id, renewed_at = excluded.renewed_at`)
+		};
+		return {
+			read: (key) => retryBusy(sqliteTry(key, `cannot read ${path}`, () => statements.select.get(key))).pipe(Effect.flatMap((row) => decodeRow(key, row))),
+			compareAndSet: (key, expected, next) => retryBusy(sqliteTry(key, `cannot write ${path}`, () => compareAndSet(db, statements, expected, next))),
+			fence: (key) => keyFileName(key).pipe(Effect.flatMap((name) => holdProcessLock(platform, key, `${path}.${name}.fence`)))
+		};
+	}));
+}
+function migrate(db) {
+	db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+	db.exec("PRAGMA journal_mode = WAL");
+	transaction(db, () => {
+		const version = Number(db.prepare("PRAGMA user_version").get()?.user_version ?? 0);
+		if (version === 0) {
+			db.exec(`CREATE TABLE IF NOT EXISTS lease_record (
+        key TEXT PRIMARY KEY,
+        generation INTEGER NOT NULL,
+        revision INTEGER NOT NULL,
+        holder TEXT,
+        holder_id TEXT,
+        renewed_at INTEGER NOT NULL
+      ) STRICT`);
+			db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+		} else if (version !== SCHEMA_VERSION) throw new UnsupportedSchema(`the lease database has schema version ${version}; this version reads ${SCHEMA_VERSION}`);
+	});
+}
+function compareAndSet(db, statements, expected, next) {
+	return transaction(db, () => {
+		const stored = statements.selectRevision.get(next.key)?.revision;
+		if ((stored === void 0 ? void 0 : Number(stored)) !== expected) return false;
+		statements.upsert.run(next.key, next.generation, next.revision, encodeHolder(next.holder), next.holderId, next.renewedAt);
+		return true;
+	});
+}
+/** Runs `body` in a `BEGIN IMMEDIATE` transaction, committing when it returns and rolling back when it throws. */
+function transaction(db, body) {
+	db.exec("BEGIN IMMEDIATE");
+	try {
+		const result = body();
+		db.exec("COMMIT");
+		return result;
+	} catch (error) {
+		try {
+			db.exec("ROLLBACK");
+		} catch {}
+		throw error;
+	}
+}
+var UnsupportedSchema = class extends Error {};
+function sqliteTry(key, message, body) {
+	return Effect.try({
+		try: body,
+		catch: (cause) => {
+			if (cause instanceof UnsupportedSchema) return storeFailure(key, "unsupported-schema", cause.message);
+			return storeFailure(key, isSqliteBusy(cause) ? "busy" : "io", message, cause);
+		}
+	});
+}
+function retryBusy(effect) {
+	return effect.pipe(Effect.retry({
+		while: (failure) => failure.reason === "busy",
+		times: BUSY_RETRIES,
+		schedule: Schedule.spaced(BUSY_RETRY_MS)
+	}));
+}
+function decodeRow(key, row) {
+	if (row === void 0) return Effect.succeed(void 0);
+	const holder = typeof row.holder === "string" || row.holder === null ? decodeHolder(row.holder) : void 0;
+	const snapshot = holder === void 0 ? void 0 : decodeSnapshot({
+		key: row.key,
+		generation: row.generation,
+		revision: row.revision,
+		holder,
+		holderId: row.holder_id,
+		renewedAt: row.renewed_at
+	});
+	return snapshot === void 0 ? Effect.fail(storeFailure(key, "invalid-record", `the stored record for ${key} has an unexpected shape`)) : Effect.succeed(snapshot);
+}
+//#endregion
+//#region src/lease/application/from-result.ts
+/** Moves a plain `Result` into the typed error channel, where `catchTag` sees its error. */
+const fromResult = (result) => result.ok ? Effect.succeed(result.value) : Effect.fail(result.error);
+//#endregion
+//#region src/lease/application/lease-manager.ts
+/** CAS attempts within one acquisition before the store counts as busy; each lost race re-reads the record. */
+const MAX_CAS_TURNS = 8;
+/** Validates `config` and builds a manager over the `LeaseStore` and the platform in context. */
+function createLeaseManager(config) {
+	return Effect.gen(function* () {
+		const problem = configProblem(config);
+		if (problem !== void 0) return yield* Effect.fail({
+			_tag: "LeaseConfigInvalid",
+			message: problem
+		});
+		return makeManager(config, yield* LeaseStore, yield* PlatformService);
+	});
+}
+function configProblem({ ttlMs, heartbeatMs, retryMs }) {
+	for (const [name, value] of [
+		["ttlMs", ttlMs],
+		["heartbeatMs", heartbeatMs],
+		["retryMs", retryMs ?? heartbeatMs]
+	]) if (!Number.isFinite(value) || value <= 0) return `${name} must be a positive number of milliseconds, got ${value}`;
+	if (heartbeatMs * 2 > ttlMs) return `heartbeatMs × 2 must not exceed ttlMs (${heartbeatMs} × 2 > ${ttlMs})`;
+}
+function makeManager(config, store, platform) {
+	const observations = /* @__PURE__ */ new Map();
+	const now = () => platform.clock.monotonic();
+	const self = () => {
+		const { host, bootId, pid, startTime } = platform.process.self;
+		return {
+			host,
+			bootId,
+			pid,
+			startTime
+		};
+	};
+	/** A holder that cannot be looked up (the platform failed to identify the pid) is judged by its TTL alone. */
+	const judge = (holder, observer) => Effect.try({
+		try: () => holderLiveness(holder, observer, platform.process.identify(holder.pid)),
+		catch: (cause) => cause
+	}).pipe(Effect.orElseSucceed(() => "unknown"));
+	/** One acquisition attempt: reads the record, applies the Lease rules, and writes over exactly that revision. */
+	const take = (key, holderId) => Effect.gen(function* () {
+		for (let turn = 0; turn < MAX_CAS_TURNS; turn += 1) {
+			const record = yield* store.read(key);
+			const claim = {
+				key,
+				holder: self(),
+				holderId,
+				now: platform.clock.now()
+			};
+			let transition;
+			if (record === void 0) transition = Lease.create(claim);
+			else {
+				const lease = yield* fromResult(Lease.restore(record)).pipe(Effect.mapError((invalid) => storeFailure(key, "invalid-record", invalid.message)));
+				const at = now();
+				const observation = observe(observations.get(key), record, at);
+				observations.set(key, observation);
+				const fresh = isFresh(record, observation, at, config.ttlMs);
+				const { holder } = record;
+				const liveness = fresh && holder !== null ? yield* judge(holder, claim.holder) : "unknown";
+				transition = yield* fromResult(lease.acquire(claim, {
+					fresh,
+					liveness
+				}));
+			}
+			const next = transition.state.toSnapshot();
+			if (yield* store.compareAndSet(key, record?.revision, next)) {
+				observations.delete(key);
+				return next;
+			}
+		}
+		return yield* Effect.fail(storeFailure(key, "busy", "the lease record kept changing during acquisition"));
+	});
+	const lostBy = (key, holding) => Effect.gen(function* () {
+		const read = yield* Effect.exit(store.read(key));
+		const record = Exit.isSuccess(read) ? read.value : void 0;
+		const reason = !Exit.isSuccess(read) ? "taken-over" : record === void 0 ? "missing" : record.holder === null ? "released" : "taken-over";
+		return {
+			_tag: "LeaseLost",
+			key,
+			generation: holding.generation,
+			reason
+		};
+	});
+	/**
+	* Renews every `heartbeatMs`. A refused write means another writer moved the record, so the lease is lost; a store
+	* failure is retried until no renewal has been confirmed for a TTL, after which an observer may take it over. The
+	* write stays interruptible while it waits for the store; `release` re-reads the record, so a renewal interrupted
+	* between its write and `Ref.set` cannot keep the tombstone from being written.
+	*/
+	const heartbeat = (key, holding, ref) => Effect.gen(function* () {
+		let confirmedAt = now();
+		for (;;) {
+			yield* Effect.sleep(config.heartbeatMs);
+			const current = yield* Ref.get(ref);
+			const restored = Lease.restore(current);
+			const transition = restored.ok ? restored.value.renew(holding, platform.clock.now()) : void 0;
+			if (transition?.ok !== true) return yield* Effect.fail(yield* lostBy(key, holding));
+			const next = transition.value.state.toSnapshot();
+			const written = yield* Effect.exit(store.compareAndSet(key, current.revision, next).pipe(Effect.tap((done) => done ? Ref.set(ref, next) : Effect.void)));
+			if (Exit.isSuccess(written)) {
+				if (!written.value) return yield* Effect.fail(yield* lostBy(key, holding));
+				confirmedAt = now();
+			} else if (now() - confirmedAt >= config.ttlMs) return yield* Effect.fail({
+				_tag: "LeaseLost",
+				key,
+				generation: holding.generation,
+				reason: "expired"
+			});
+		}
+	});
+	/**
+	* Writes the tombstone over the record as read now, if it is still this acquisition's. A failure leaves the lease
+	* to expire after the TTL; a finalizer cannot fail.
+	*/
+	const release = (key, holding) => Effect.gen(function* () {
+		const current = yield* store.read(key);
+		const restored = current === void 0 ? void 0 : Lease.restore(current);
+		const transition = restored?.ok === true ? restored.value.release(holding, platform.clock.now()) : void 0;
+		if (current !== void 0 && transition?.ok === true) yield* store.compareAndSet(key, current.revision, transition.value.state.toSnapshot());
+	}).pipe(Effect.ignore);
+	const handle = (key, holding, lost) => {
+		const token = {
+			key,
+			generation: holding.generation
+		};
+		return {
+			key,
+			token,
+			lost: Deferred.await(lost),
+			runFenced: (work) => Effect.scoped(Effect.gen(function* () {
+				if (yield* Deferred.isDone(lost)) return yield* Deferred.await(lost);
+				yield* store.fence(key).pipe(Effect.raceFirst(Deferred.await(lost)));
+				const record = yield* store.read(key);
+				if (record?.holderId !== holding.holderId || record.generation !== holding.generation) {
+					const current = record?.generation;
+					return yield* Effect.fail({
+						_tag: "FenceRejected",
+						key,
+						generation: token.generation,
+						current
+					});
+				}
+				return yield* Effect.raceFirst(work(token), Deferred.await(lost));
+			}))
+		};
+	};
+	return {
+		acquire: (key, options = {}) => {
+			if (key === "") return Effect.die(new AgentKitError("invalid-lease-key", "A lease key must not be empty"));
+			const holderId = crypto.randomUUID();
+			const attempt = Effect.acquireRelease(take(key, holderId).pipe(Effect.flatMap((snapshot) => Ref.make(snapshot))), (ref) => Effect.flatMap(Ref.get(ref), ({ generation }) => release(key, {
+				holderId,
+				generation
+			})));
+			const acquired = options.wait === true ? attempt.pipe(Effect.retry({
+				while: (error) => error._tag === "LeaseHeld" || error.reason === "busy",
+				schedule: Schedule.spaced(config.retryMs ?? config.heartbeatMs)
+			})) : attempt;
+			return Effect.gen(function* () {
+				const ref = yield* acquired;
+				const { generation } = yield* Ref.get(ref);
+				const holding = {
+					holderId,
+					generation
+				};
+				const lost = yield* Deferred.make();
+				yield* Effect.forkScoped(heartbeat(key, holding, ref).pipe(Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause) ? Effect.failCause(cause) : Deferred.failCause(lost, cause))));
+				return handle(key, holding, lost);
+			});
+		},
+		read: (key) => store.read(key)
+	};
+}
+//#endregion
+export { LeaseStore, canAcquire, checkFence, createLeaseManager, fileLeaseStore, holderLiveness, isFresh, memoryLeaseStore, nextFencingToken, sqliteLeaseStore };