@rivus/agent-kit-collab 0.0.0 → 0.3.0

package/dist/lanes.js

@@ -0,0 +1,323 @@
+import * as Effect from "effect/Effect";
+import { err, ok } from "@rivus/agent-kit/catalog";
+import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
+import * as Exit from "effect/Exit";
+//#region src/lanes/domain/lane/policies/admission.ts
+/**
+* Where a wake of an idle lane goes: it starts while a slot is free and nobody waits for one, waits at the end of the
+* queue while the queue has room, and is refused otherwise. A newcomer never passes a lane that is already waiting.
+*/
+function admit(load, limits) {
+	if (load.running < limits.maxConcurrent && load.queued === 0) return "start";
+	return load.queued < limits.maxQueued ? "queue" : "full";
+}
+//#endregion
+//#region src/lanes/domain/lane/aggregate/lane.ts
+/**
+* One key's lane, held in memory only. At most one activation runs at a time, and every wake that arrives before an
+* activation starts is served by that activation: wakes coalesce instead of queueing one run each. Only an idle lane
+* asks for a slot, so a lane occupies at most one place in the queue.
+*/
+var Lane = class Lane {
+	static create(key) {
+		return new Lane({
+			key,
+			state: "idle",
+			pending: false
+		});
+	}
+	snapshot;
+	constructor(snapshot) {
+		this.snapshot = snapshot;
+		Object.freeze(this);
+	}
+	/**
+	* An idle lane starts or joins the queue as `admit` decides, and is refused with `LaneQueueFull` when the queue has
+	* no room. A queued or running lane takes the wake as pending: it never asks for another slot.
+	*/
+	wake(load, limits) {
+		const { key, state } = this.snapshot;
+		if (state !== "idle") return ok(this.to({
+			key,
+			state,
+			pending: true
+		}, {
+			_tag: "WakeCoalesced",
+			key
+		}));
+		switch (admit(load, limits)) {
+			case "start": return ok(this.to({
+				key,
+				state: "running",
+				pending: false
+			}, {
+				_tag: "ActivationStarted",
+				key
+			}));
+			case "queue": return ok(this.to({
+				key,
+				state: "queued",
+				pending: true
+			}, {
+				_tag: "LaneQueued",
+				key
+			}));
+			case "full": return err({
+				_tag: "LaneQueueFull",
+				key,
+				maxQueued: limits.maxQueued
+			});
+		}
+	}
+	/** A queued lane got a slot: its activation starts and serves every wake so far. */
+	start() {
+		const { key } = this.expect("queued");
+		return this.to({
+			key,
+			state: "running",
+			pending: false
+		}, {
+			_tag: "LaneDequeued",
+			key
+		}, {
+			_tag: "ActivationStarted",
+			key
+		});
+	}
+	/**
+	* The running activation ended. A wake it did not serve sends the lane to the end of the queue, behind the lanes
+	* that waited while it ran; the slot it frees goes to the head of the queue first.
+	*/
+	finish() {
+		const { key, pending } = this.expect("running");
+		const ended = {
+			_tag: "ActivationEnded",
+			key
+		};
+		return pending ? this.to({
+			key,
+			state: "queued",
+			pending: true
+		}, ended, {
+			_tag: "LaneQueued",
+			key
+		}) : this.to({
+			key,
+			state: "idle",
+			pending: false
+		}, ended);
+	}
+	/**
+	* Drops the wakes the lane owes: a queued lane leaves the queue, a running one keeps running without a follow-up.
+	* Ending the running activation is the caller's part; wakes after the cancel are owed again.
+	*/
+	cancel() {
+		const { key, state, pending } = this.snapshot;
+		if (state === "queued") return this.to({
+			key,
+			state: "idle",
+			pending: false
+		}, {
+			_tag: "LaneDequeued",
+			key
+		});
+		if (state === "running" && pending) return this.to({
+			key,
+			state,
+			pending: false
+		}, {
+			_tag: "PendingDropped",
+			key
+		});
+		return {
+			state: this,
+			events: []
+		};
+	}
+	toSnapshot() {
+		return this.snapshot;
+	}
+	to(snapshot, ...events) {
+		return {
+			state: new Lane(snapshot),
+			events
+		};
+	}
+	/** Starting a lane that is not queued, or finishing one that is not running, is a scheduler bug, not an outcome. */
+	expect(state) {
+		if (this.snapshot.state !== state) throw new Error(`lane ${this.snapshot.key} is ${this.snapshot.state}, not ${state}`);
+		return this.snapshot;
+	}
+};
+//#endregion
+//#region src/lanes/domain/lane/value-objects/lane-limits.ts
+function laneLimits(input) {
+	const { maxConcurrent, maxQueued = Number.POSITIVE_INFINITY, turnTimeoutMs } = input;
+	const invalid = (message) => err({
+		_tag: "LanesConfigInvalid",
+		message
+	});
+	if (!Number.isSafeInteger(maxConcurrent) || maxConcurrent < 1) return invalid(`maxConcurrent must be a positive integer, got ${maxConcurrent}`);
+	if (maxQueued !== Number.POSITIVE_INFINITY && (!Number.isSafeInteger(maxQueued) || maxQueued < 0)) return invalid(`maxQueued must be a non-negative integer, got ${maxQueued}`);
+	if (turnTimeoutMs !== void 0 && (!Number.isFinite(turnTimeoutMs) || turnTimeoutMs <= 0)) return invalid(`turnTimeoutMs must be a positive number of milliseconds, got ${turnTimeoutMs}`);
+	return ok({
+		maxConcurrent,
+		maxQueued,
+		turnTimeoutMs
+	});
+}
+//#endregion
+//#region src/lanes/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/lanes/application/create-lanes.ts
+/** An end the activation did not reach by itself: an interruption, by the lanes or its own. */
+const cutShort = (exit) => Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause);
+/**
+* Creates lanes in the caller's Scope. The lanes capture the context they are created in and give it to every
+* activation; fails with `LanesConfigInvalid` for a limit out of range.
+*/
+function createLanes(config) {
+	return Effect.gen(function* () {
+		const limits = yield* fromResult(laneLimits(config));
+		const context = yield* Effect.context();
+		const { activate, onExit } = config;
+		const lanes = /* @__PURE__ */ new Map();
+		const activations = /* @__PURE__ */ new Map();
+		const queue = [];
+		let closed = false;
+		const laneOf = (key) => {
+			const lane = lanes.get(key);
+			if (lane === void 0) throw new Error(`no lane for ${key}`);
+			return lane;
+		};
+		/** Records a transition and returns the activations it started; the caller forks them. */
+		const apply = ({ state, events }) => {
+			const { key, state: laneState } = state.toSnapshot();
+			if (laneState === "idle") lanes.delete(key);
+			else lanes.set(key, state);
+			const started = [];
+			for (const event of events) switch (event._tag) {
+				case "LaneQueued":
+					queue.push(key);
+					break;
+				case "LaneDequeued":
+					queue.splice(queue.indexOf(key), 1);
+					break;
+				case "ActivationStarted": {
+					const activation = {
+						key,
+						stop: Deferred.makeUnsafe(),
+						ended: Deferred.makeUnsafe()
+					};
+					activations.set(key, activation);
+					started.push(activation);
+					break;
+				}
+				case "ActivationEnded": activations.delete(key);
+			}
+			return started;
+		};
+		/** Gives the free slots to the lanes that have waited longest. */
+		const pump = () => {
+			const started = [];
+			for (let key = queue[0]; !closed && key !== void 0 && activations.size < limits.maxConcurrent; key = queue[0]) started.push(...apply(laneOf(key).start()));
+			return started;
+		};
+		const interrupted = (key, reason) => ({
+			_tag: "ActivationInterrupted",
+			key,
+			reason
+		});
+		const exitOf = (key, exit) => Exit.isSuccess(exit) ? {
+			_tag: "ActivationSucceeded",
+			key
+		} : {
+			_tag: "ActivationFailed",
+			key,
+			cause: exit.cause
+		};
+		/**
+		* Runs the work, raced against `stop`; the loser is interrupted and awaited, which for the work includes closing
+		* its Scope. `stop` comes first in the race, so an activation stopped before its fiber started never calls
+		* `activate`: the race forks its contenders in order and stops at the first that has ended. The turn timer only
+		* completes `stop`, so a cancel or close that came first keeps its reason while the cleanup outlasts the deadline.
+		*/
+		const settle = ({ key, stop }) => Effect.suspend(() => {
+			let body;
+			let work;
+			const record = Effect.scoped(Effect.suspend(() => activate(key)).pipe(Effect.onExit((exit) => Effect.sync(() => {
+				body = exit;
+			})))).pipe(Effect.onExit((exit) => Effect.sync(() => {
+				work = exit;
+			})), Effect.exit);
+			const raced = Effect.raceFirst(Deferred.await(stop), record);
+			const { turnTimeoutMs } = limits;
+			const timed = turnTimeoutMs === void 0 ? raced : Effect.raceFirst(raced, Effect.sleep(turnTimeoutMs).pipe(Effect.andThen(Deferred.succeed(stop, "timeout")), Effect.andThen(Effect.never)));
+			return Effect.map(timed, (result) => {
+				if (typeof result !== "string") return exitOf(key, result);
+				if (body === void 0 || cutShort(body)) return interrupted(key, result);
+				const own = (work === void 0 || Exit.isSuccess(work) ? [] : work.cause.reasons).filter((reason) => !Cause.isInterruptReason(reason));
+				return exitOf(key, own.length === 0 ? body : Exit.failCause(Cause.fromReasons(own)));
+			});
+		});
+		/**
+		* One activation's fiber. It is forked uninterruptible and nothing else holds it, so it always reaches the end of
+		* the activation, which frees the slot; only the raced work inside can be interrupted.
+		*/
+		const run = (activation) => Effect.gen(function* () {
+			const exit = yield* settle(activation);
+			if (onExit !== void 0) yield* Effect.scoped(Effect.suspend(() => onExit(exit))).pipe(Effect.catchCause((cause) => Effect.logWarning(`lanes: onExit failed for ${exit.key}`, cause)));
+			yield* Effect.suspend(() => {
+				const started = [...apply(laneOf(activation.key).finish()), ...pump()];
+				Deferred.doneUnsafe(activation.ended, Exit.void);
+				return fork(started);
+			});
+		}).pipe(Effect.provideContext(context));
+		const fork = (started) => Effect.forEach(started, (activation) => Effect.forkDetach(run(activation), { uninterruptible: true }), { discard: true });
+		const wakeResult = (events) => events.some(({ _tag }) => _tag === "ActivationStarted") ? "started" : events.some(({ _tag }) => _tag === "LaneQueued") ? "queued" : "coalesced";
+		const close = Effect.suspend(() => {
+			if (!closed) {
+				closed = true;
+				for (const lane of lanes.values()) apply(lane.cancel());
+			}
+			const running = [...activations.values()];
+			for (const { stop } of running) Deferred.doneUnsafe(stop, Exit.succeed("close"));
+			return Effect.forEach(running, ({ ended }) => Deferred.await(ended), { discard: true });
+		});
+		yield* Effect.addFinalizer(() => close);
+		return {
+			wake: (key) => Effect.uninterruptible(Effect.suspend(() => {
+				if (closed) return Effect.fail({
+					_tag: "LanesClosed",
+					key
+				});
+				const woken = (lanes.get(key) ?? Lane.create(key)).wake({
+					running: activations.size,
+					queued: queue.length
+				}, limits);
+				if (!woken.ok) return Effect.fail(woken.error);
+				return Effect.as(fork(apply(woken.value)), wakeResult(woken.value.events));
+			})),
+			cancel: (key) => Effect.suspend(() => {
+				const lane = lanes.get(key);
+				if (lane !== void 0) apply(lane.cancel());
+				const activation = activations.get(key);
+				if (activation === void 0) return Effect.void;
+				Deferred.doneUnsafe(activation.stop, Exit.succeed("cancel"));
+				return Deferred.await(activation.ended);
+			}),
+			status: Effect.sync(() => ({
+				running: activations.size,
+				queued: queue.length,
+				closed,
+				lanes: [...activations.keys(), ...queue].map((key) => laneOf(key).toSnapshot())
+			})),
+			close
+		};
+	});
+}
+//#endregion
+export { createLanes };

package/dist/lease.d.ts

@@ -0,0 +1,265 @@
+import { PlatformService } from "@rivus/agent-kit/platform/effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Context from "effect/Context";
+import { Result } from "@rivus/agent-kit/catalog";
+import * as Scope from "effect/Scope";
+//#region src/lease/domain/lease/value-objects/holder.d.ts
+/**
+ * The process that holds a lease, with the same shape as the Platform's `ProcessIdentity`. The start time tells a
+ * reused pid apart from the holder; the boot id tells a process of an earlier boot apart.
+ */
+interface Holder {
+  readonly host: string;
+  readonly bootId: string;
+  readonly pid: number;
+  readonly startTime: number;
+}
+/** `unknown` when the holder runs on another host, where the observer cannot look it up. */
+type HolderLiveness = "alive" | "dead" | "unknown";
+//#endregion
+//#region src/lease/domain/lease/errors/lease-held.d.ts
+/** Another acquisition holds the lease and is alive and renewing, as far as the observer can tell. */
+interface LeaseHeld {
+  readonly _tag: "LeaseHeld";
+  readonly key: string;
+  readonly generation: number;
+  readonly holder: Holder;
+  readonly holderId: string;
+}
+//#endregion
+//#region src/lease/domain/lease/errors/lease-lost.d.ts
+/**
+ * This acquisition no longer holds the lease: another one took it over or released it, the record vanished, or no
+ * renewal could be confirmed within the TTL.
+ */
+interface LeaseLost {
+  readonly _tag: "LeaseLost";
+  readonly key: string;
+  readonly generation: number;
+  readonly reason: "taken-over" | "released" | "missing" | "expired";
+}
+//#endregion
+//#region src/lease/domain/lease/value-objects/lease-snapshot.d.ts
+/** A lease record as stores keep it. A released lease stays as a tombstone with no holder. */
+interface LeaseSnapshot {
+  readonly key: string;
+  /** The fencing token: +1 on every acquisition, unchanged by renewals and release. */
+  readonly generation: number;
+  /** +1 on every write; stores compare it to write only over the record a caller read. */
+  readonly revision: number;
+  readonly holder: Holder | null;
+  /** Names one acquisition, so that two acquisitions by the same process are told apart. */
+  readonly holderId: string | null;
+  /** Wall-clock time of the last write, for diagnostics; expiry is judged with the observer's monotonic clock. */
+  readonly renewedAt: number;
+}
+//#endregion
+//#region src/lease/domain/lease/policies/acquisition.d.ts
+/** What the observer found out about the current holder before trying to acquire. */
+interface AcquisitionView {
+  /** `isFresh` for the record as read. */
+  readonly fresh: boolean;
+  /** `holderLiveness` for its holder; irrelevant for a tombstone. */
+  readonly liveness: HolderLiveness;
+}
+/**
+ * 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.
+ */
+export declare function canAcquire(lease: LeaseSnapshot | undefined, view: AcquisitionView): boolean;
+//#endregion
+//#region src/lease/domain/lease/errors/fence-rejected.d.ts
+/** A fenced write carried an older generation than the lease record or the protected resource has seen. */
+interface FenceRejected {
+  readonly _tag: "FenceRejected";
+  readonly key: string;
+  /** The generation of the rejected token. */
+  readonly generation: number;
+  /** The generation that wins, or `undefined` when the record is missing. */
+  readonly current: number | undefined;
+}
+//#endregion
+//#region src/lease/domain/lease/value-objects/fencing-token.d.ts
+/**
+ * Proof of holding a lease, passed with every fenced write. A resource that can compare atomically keeps the highest
+ * generation it has seen for the key and refuses a smaller one (`checkFence`).
+ */
+interface FencingToken {
+  readonly key: string;
+  readonly generation: number;
+}
+//#endregion
+//#region src/lease/domain/lease/policies/fence-check.d.ts
+/** The token the next acquisition of `key` receives: one generation above the record, 1 for a new key. */
+export declare function nextFencingToken(current: LeaseSnapshot | undefined, key: string): FencingToken;
+/**
+ * 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`.
+ */
+export declare function checkFence(lastSeen: FencingToken | undefined, token: FencingToken): Result<FencingToken, FenceRejected>;
+//#endregion
+//#region src/lease/domain/lease/policies/freshness.d.ts
+/**
+ * When an observer last saw a lease record change. Monotonic clocks of two processes cannot be compared, so each
+ * observer times a revision from the moment it first read it, as client-go's leader election does.
+ */
+interface LeaseObservation {
+  readonly revision: number;
+  /** The observer's monotonic time when it first read `revision`. */
+  readonly observedAt: number;
+}
+/**
+ * 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.
+ */
+export declare function isFresh(lease: LeaseSnapshot, observation: LeaseObservation, now: number, ttlMs: number): boolean;
+//#endregion
+//#region src/lease/domain/lease/policies/holder-liveness.d.ts
+/**
+ * Judges a recorded holder from the observer's machine. `current` is what the observer's platform reports for the
+ * holder's pid now (`identify(holder.pid)`), `undefined` when no such process exists. A process of an earlier boot is
+ * dead; a pid now owned by a process with another start time is a reused pid, so the holder is dead too.
+ *
+ * Holder and observer must see the same processes: same host name and boot id are taken to mean one process table.
+ * Containers that share the host's name and kernel but have their own PID namespaces break that, and a live holder
+ * in another namespace looks dead. A host whose name changed makes its earlier holders look remote (`unknown`), so
+ * they are judged by the TTL alone.
+ */
+export declare function holderLiveness(holder: Holder, observer: Holder, current: Holder | undefined): HolderLiveness;
+//#endregion
+//#region src/lease/application/ports.d.ts
+/** The store could not read or write a record; the lease's state is unknown, not changed. */
+interface LeaseStoreFailure {
+  readonly _tag: "LeaseStoreFailure";
+  readonly key: string;
+  /**
+   * `busy`: other writers kept the store locked; `invalid-record`: a stored record is unreadable or breaks the
+   * invariants and is left as it is; `unsupported-schema`: the store was written by a newer version; `unavailable`:
+   * the platform lacks what the store needs; `io`: any other failure.
+   */
+  readonly reason: "busy" | "io" | "invalid-record" | "unsupported-schema" | "unavailable";
+  readonly message: string;
+  readonly cause?: unknown;
+}
+/**
+ * Where lease records live. Calling convention for every implementation:
+ *
+ * - `compareAndSet` is atomic across every process that uses the same store location: it writes `next` only when the
+ *   stored record's revision equals `expected` (`undefined`: no record), and reports whether it wrote.
+ * - Records are never deleted. A release writes a tombstone, so a key's generation never goes back.
+ * - `fence(key)` holds one guard per key across those processes until its Scope closes; waiting for it can be
+ *   interrupted, and a guard whose holder process exited is freed without waiting for a TTL.
+ * - Only local directories are supported; neither SQLite's locks nor lock files are reliable on NFS.
+ *
+ * The lease's `runFenced` takes the guard and re-reads the holder before the work starts. That is equivalent to the
+ * protected resource checking the fencing token itself only when every writer of the resource goes through the same
+ * store on the same machine; a resource that can compare atomically should also run `checkFence`.
+ */
+interface LeaseStoreShape {
+  read(key: string): Effect.Effect<LeaseSnapshot | undefined, LeaseStoreFailure>;
+  compareAndSet(key: string, expected: number | undefined, next: LeaseSnapshot): Effect.Effect<boolean, LeaseStoreFailure>;
+  fence(key: string): Effect.Effect<void, LeaseStoreFailure, Scope.Scope>;
+}
+declare const KEY = "@rivus/agent-kit-collab/lease/LeaseStore/v1";
+declare const LeaseStoreBase: Context.ServiceClass<LeaseStore, typeof KEY, LeaseStoreShape>;
+/** The lease store port; `sqliteLeaseStore`, `fileLeaseStore` and `memoryLeaseStore` provide it. */
+export declare class LeaseStore extends LeaseStoreBase {}
+//#endregion
+//#region src/lease/adapters/file-lease-store.d.ts
+interface FileLeaseStoreOptions {
+  /** An existing local directory that holds one record file and its lock files per key. */
+  readonly dir: string;
+}
+/**
+ * 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.
+ */
+export declare function fileLeaseStore(options: FileLeaseStoreOptions): Layer.Layer<LeaseStore, never, PlatformService>;
+//#endregion
+//#region src/lease/adapters/memory-lease-store.d.ts
+/**
+ * A store for one process, such as tests or a host whose leases never cross a process boundary. Each Layer build
+ * starts empty.
+ */
+export declare function memoryLeaseStore(): Layer.Layer<LeaseStore>;
+//#endregion
+//#region src/lease/adapters/sqlite-lease-store.d.ts
+interface SqliteLeaseStoreOptions {
+  /**
+   * The database file, in an existing local directory. The per-key fence locks of `runFenced` live next to it as
+   * `<path>.<key>.fence` (plus a `.holder` file each), so give the store a directory of its own or a distinct name.
+   */
+  readonly path: string;
+}
+/**
+ * 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.
+ */
+export declare function sqliteLeaseStore(options: SqliteLeaseStoreOptions): Layer.Layer<LeaseStore, LeaseStoreFailure, PlatformService>;
+//#endregion
+//#region src/lease/application/lease-manager.d.ts
+interface LeaseConfig {
+  /** How long a lease stays valid without a renewal, as each observer's monotonic clock measures it. */
+  readonly ttlMs: number;
+  /** How often the holder renews. Two heartbeats must fit in the TTL, so one late heartbeat does not lose it. */
+  readonly heartbeatMs: number;
+  /** How often `acquire({ wait: true })` tries again; `heartbeatMs` by default. */
+  readonly retryMs?: number;
+}
+interface LeaseConfigInvalid {
+  readonly _tag: "LeaseConfigInvalid";
+  readonly message: string;
+}
+interface AcquireOptions {
+  /**
+   * Keep trying every `retryMs` while the lease is held or the store is busy (a guard that stays locked), instead of
+   * failing with `LeaseHeld` or a `busy` `LeaseStoreFailure`. The wait ends when the lease is taken, on another store
+   * failure, or when the fiber is interrupted.
+   */
+  readonly wait?: boolean;
+}
+/** A held lease. It belongs to the Scope `acquire` ran in: closing the Scope stops the heartbeat and releases it. */
+interface LeaseHandle {
+  readonly key: string;
+  readonly token: FencingToken;
+  /**
+   * Fails with `LeaseLost` once the heartbeat finds the lease taken over, released or missing, or cannot confirm a
+   * renewal within the TTL; it never succeeds. Race other work against it to stop that work on loss.
+   */
+  readonly lost: Effect.Effect<never, LeaseLost>;
+  /**
+   * Runs `work` under the store's per-key fence, after re-reading that this acquisition still holds the lease, and
+   * passes it the fencing token for the writes it makes. Waiting for the fence stops when the lease is lost. When the
+   * lease is lost while `work` runs, `work` is interrupted and the result fails with `LeaseLost`.
+   *
+   * The fence is released when `work`'s fiber has ended, so a successor's fenced work starts only after that. An
+   * interrupted fiber ends at once, though, while a Promise it started (`Effect.tryPromise`) keeps running: put a
+   * write that cannot be cancelled in `Effect.uninterruptible`, which keeps the fence until the write settles, or pass
+   * it the AbortSignal `tryPromise` provides and settle only after the write has stopped. A resource that can compare
+   * atomically should also keep the highest token it has seen and refuse older ones with `checkFence`.
+   */
+  runFenced<A, E, R>(work: (token: FencingToken) => Effect.Effect<A, E, R>): Effect.Effect<A, E | LeaseLost | FenceRejected | LeaseStoreFailure, Exclude<R, Scope.Scope>>;
+}
+interface LeaseManager {
+  /**
+   * Takes the lease for `key` in the caller's Scope and keeps renewing it there. Fails with `LeaseHeld` while a live
+   * holder keeps it fresh; a dead holder (same host) is taken over at once, a silent one after the TTL. Throws an
+   * `AgentKitError` (as a defect) for an empty key.
+   */
+  acquire(key: string, options?: AcquireOptions): Effect.Effect<LeaseHandle, LeaseHeld | LeaseStoreFailure, Scope.Scope>;
+  read(key: string): Effect.Effect<LeaseSnapshot | undefined, LeaseStoreFailure>;
+}
+/** Validates `config` and builds a manager over the `LeaseStore` and the platform in context. */
+export declare function createLeaseManager(config: LeaseConfig): Effect.Effect<LeaseManager, LeaseConfigInvalid, LeaseStore | PlatformService>;
+//#endregion
+export type { AcquireOptions, AcquisitionView, FenceRejected, FencingToken, FileLeaseStoreOptions, Holder, HolderLiveness, LeaseConfig, LeaseConfigInvalid, LeaseHandle, LeaseHeld, LeaseLost, LeaseManager, LeaseObservation, LeaseSnapshot, LeaseStoreFailure, LeaseStoreShape, SqliteLeaseStoreOptions };