@rivus/agent-kit-collab 0.0.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PerfectPan
+
+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

@@ -0,0 +1,149 @@
+# @rivus/agent-kit-collab
+
+Collaboration primitives for processes that run coding agents side by side: a lease with fencing tokens, so that
+one process at a time owns a task and a stale owner's writes are refused, a single-instance process lock, and lanes
+that run work per key, one activation at a time, under a global concurrency cap. The package knows no particular
+agent; it reaches files, processes, clocks and SQLite through the `Platform` of
+[`@rivus/agent-kit`](https://www.npmjs.com/package/@rivus/agent-kit).
+
+Status: 0.x, with one lockstep release policy for this package and `@rivus/agent-kit` (same version). A minor release may contain breaking
+changes.
+
+## Install
+
+```bash
+npm install @rivus/agent-kit @rivus/agent-kit-collab
+# for /lease and /lanes, which are Effect entries:
+npm install effect@4.0.1
+```
+
+Select a verified non-placeholder release that exports the entries you need, with both packages at the same
+version. See [Adopting agent-kit](https://github.com/PerfectPan/agent-kit/blob/main/docs/development/adoption.md) for migration checks and rollback.
+
+`@rivus/agent-kit` is a peer dependency, so the process holds one copy of the platform types. `effect` 4.0.1 is an
+optional peer that only `/lease` and `/lanes` need. ESM only, no side effects, Node.js 22.13 or later on darwin or
+linux (the locks identify processes by boot id, pid and start time, which the platform does not support on win32).
+Every lock supports local directories only; neither SQLite's locks nor lock files are reliable on NFS. Holders are
+judged by host name, boot id, pid and start time, so all processes that share a lock must see one process table:
+containers that share the host's name and kernel but not its PID namespace are not supported, and a host renamed
+while it holds locks makes its holders look remote (judged by the TTL alone; a lock file of a dead holder then stays
+until removed).
+
+## Entries
+
+| Entry                                  | Main exports                                                                                                                                                                    | Kind     |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| `@rivus/agent-kit-collab/process-lock` | `acquireProcessLock`, `ProcessLock`, `ProcessLockHeld`                                                                                                                          | plain TS |
+| `@rivus/agent-kit-collab/lease`        | `createLeaseManager`, `LeaseStore`, `sqliteLeaseStore`, `fileLeaseStore`, `memoryLeaseStore`; rules `isFresh`, `canAcquire`, `nextFencingToken`, `checkFence`, `holderLiveness` | Effect   |
+| `@rivus/agent-kit-collab/lanes`        | `createLanes`                                                                                                                                                                   | Effect   |
+
+### Process lock
+
+```ts
+import { createNodePlatform } from "@rivus/agent-kit/node";
+import { acquireProcessLock } from "@rivus/agent-kit-collab/process-lock";
+
+const lock = await acquireProcessLock(createNodePlatform(), "/var/run/my-daemon/daemon.lock");
+if (!lock.ok) {
+  console.error(`already running (pid ${lock.error.holder?.pid ?? "unknown"})`);
+  process.exit(1);
+}
+// ... run; the kernel releases the lock if the process dies, or call:
+await lock.value.release();
+```
+
+With `platform.sqlite` the lock is a SQLite database held with `locking_mode=EXCLUSIVE`; the kernel drops it the
+moment the holder exits or crashes, and nothing is reclaimed. The holder's identity goes into `<path>.holder` for
+diagnostics only. Without SQLite the lock is a file that holds the identity; a lock file whose holder died on this
+host is reclaimed on the next attempt, one reclaimer at a time. Pass `{ wait: true, signal }` to wait for the holder
+instead of getting `ProcessLockHeld` at once.
+
+### Lease
+
+```ts
+import { NodePlatformLive } from "@rivus/agent-kit/node/effect";
+import { createLeaseManager, sqliteLeaseStore } from "@rivus/agent-kit-collab/lease";
+import { Effect, Layer } from "effect";
+
+const LeaseLive = sqliteLeaseStore({ path: "/var/lib/my-app/leases.db" }).pipe(Layer.provideMerge(NodePlatformLive));
+
+const program = Effect.scoped(
+  Effect.gen(function* () {
+    const leases = yield* createLeaseManager({ ttlMs: 60_000, heartbeatMs: 15_000 });
+    const lease = yield* leases.acquire("task:42"); // fails with LeaseHeld while another live holder renews it
+    // Writes carry the fencing token; when the lease is lost, the fenced work is interrupted.
+    yield* lease.runFenced((token) => saveResult(token));
+    // Stop other work on loss by racing it against lease.lost.
+    yield* longRunningWork.pipe(Effect.raceFirst(lease.lost));
+  })
+);
+
+await Effect.runPromiseExit(program.pipe(Effect.provide(LeaseLive)));
+```
+
+- A lease has one holder. Its generation, the fencing token, grows on every acquisition and never goes back: a
+  release keeps the record as a tombstone. Losing the lease and getting it again gives a new generation, so the old
+  handle's token is refused.
+- The holder renews every `heartbeatMs` in the Scope that acquired it; `heartbeatMs × 2` must not exceed `ttlMs`.
+  Closing the Scope stops the heartbeat and releases the lease.
+- A holder on the same host whose process is gone (or whose pid now belongs to another process) is taken over at
+  once. A holder that is alive but stopped renewing is taken over after the TTL, measured by the observer's own
+  monotonic clock from the moment it first saw the current record.
+- `runFenced` holds the store's per-key fence and re-reads the record before the work starts; waiting for the fence
+  stops when the lease is lost. The fence is released when the work's fiber ends, so a successor's fenced work starts
+  after that. An interrupted fiber ends at once, but a Promise it started keeps running: put a write that cannot be
+  cancelled in `Effect.uninterruptible` (the fence then waits for it to settle), or pass it the AbortSignal that
+  `Effect.tryPromise` provides and let it settle only once the write has stopped.
+- Guard plus re-read is as strong as a check by the protected resource itself only when every writer goes through
+  the same store on the same machine; a resource that can compare atomically should keep the highest token it has
+  seen and call `checkFence`.
+- `sqliteLeaseStore` compares revisions inside `BEGIN IMMEDIATE` transactions. `fileLeaseStore` is the fallback
+  without SQLite: one JSON file per key, written under a per-key lock file. `memoryLeaseStore` serves one process.
+
+Expected failures are typed values with a `_tag`: `LeaseHeld`, `LeaseLost`, `FenceRejected`, `LeaseConfigInvalid`
+and `LeaseStoreFailure`. The kit runs no Effect itself; run the program at your application's assembly root.
+
+### Lanes
+
+```ts
+import { createLanes } from "@rivus/agent-kit-collab/lanes";
+import { Effect } from "effect";
+
+const program = Effect.scoped(
+  Effect.gen(function* () {
+    const lanes = yield* createLanes({
+      maxConcurrent: 4, // activations running at once across all keys
+      maxQueued: 32, // keys waiting for a free slot
+      turnTimeoutMs: 600_000, // an activation running longer is interrupted
+      activate: (key) => runTurn(key), // the work for one key, in a Scope of its own
+      onExit: (exit) => report(exit) // ActivationSucceeded | ActivationFailed | ActivationInterrupted
+    });
+    yield* lanes.wake("room:1"); // "started", "queued" or "coalesced"; never waits for the activation
+    // ... closing the Scope interrupts the running activations and waits for them.
+  })
+);
+```
+
+- A lane runs at most one activation at a time. Every wake that arrives before an activation starts is served by
+  it: waking a running lane any number of times leaves one activation to follow the running one, and waking a
+  queued lane changes nothing.
+- An idle lane starts while a slot is free and nobody waits; otherwise it waits at the end of the queue, and when
+  `maxQueued` lanes already wait, `wake` fails with `LaneQueueFull`. A freed slot goes to the lane that has waited
+  longest, so a lane woken again while it ran waits behind the lanes queued meanwhile. Without `maxQueued`, the queue
+  holds at most one entry per key.
+- `cancel(key)` drops the wakes the key owes and interrupts its running activation, and returns once the activation
+  has ended (its finalizers and `onExit` included). `close` refuses later wakes with `LanesClosed`, drops the queue,
+  interrupts every running activation and waits for them; closing the Scope that created the lanes runs it.
+- An activation runs with the context `createLanes` ran in. Its Scope closes when it ends, and the lane moves on only
+  after that: an interrupted activation's finalizers have run before the next activation of any key takes its slot.
+- `onExit` hears how each activation ended. One that succeeded or failed by itself is reported so even when a cancel,
+  close or timeout arrives while its Scope closes; `ActivationInterrupted` means the lanes cut it short, or stopped it
+  before it started, in which case `activate` was never called. `onExit` runs uninterruptibly, so `cancel` and `close`
+  wait for it; it must not wait for them in turn, and a defect it raises is logged as a warning.
+
+Nothing is persisted: lanes live in one process. Expected failures are typed values with a `_tag`:
+`LaneQueueFull`, `LanesClosed` and `LanesConfigInvalid`.
+
+## License
+
+MIT

package/dist/acquire-process-lock-A0oYDN9m.js

@@ -0,0 +1,311 @@
+import * as z from "zod/mini";
+import { err, ok } from "@rivus/agent-kit/catalog";
+//#region src/process-lock/application/holder.ts
+const stampSchema = z.object({
+	host: z.string(),
+	bootId: z.string(),
+	pid: z.number(),
+	startTime: z.number(),
+	acquiredAt: z.number(),
+	nonce: z.string()
+});
+function newStamp(platform) {
+	const { host, bootId, pid, startTime } = platform.process.self;
+	return {
+		host,
+		bootId,
+		pid,
+		startTime,
+		acquiredAt: platform.clock.now(),
+		nonce: crypto.randomUUID()
+	};
+}
+function holderOf(stamp) {
+	const { host, bootId, pid, startTime, acquiredAt } = stamp;
+	return {
+		host,
+		bootId,
+		pid,
+		startTime,
+		acquiredAt
+	};
+}
+async function readStamp(platform, path) {
+	const text = await readText(platform, path);
+	if (text === void 0) return;
+	let json;
+	try {
+		json = JSON.parse(text);
+	} catch {
+		return {
+			text,
+			stamp: void 0
+		};
+	}
+	const parsed = stampSchema.safeParse(json);
+	return {
+		text,
+		stamp: parsed.success ? parsed.data : void 0
+	};
+}
+/** The text of a small file, `undefined` when it does not exist. */
+async function readText(platform, path) {
+	const decoder = new TextDecoder();
+	let text = "";
+	try {
+		for await (const chunk of platform.fs.read(path)) text += decoder.decode(chunk, { stream: true });
+	} catch (error) {
+		if (typeof error === "object" && error !== null && error.code === "ENOENT") return;
+		throw error;
+	}
+	return text + decoder.decode();
+}
+//#endregion
+//#region src/lease/domain/lease/policies/holder-liveness.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.
+*/
+function holderLiveness(holder, observer, current) {
+	if (holder.host !== observer.host) return "unknown";
+	if (holder.bootId !== observer.bootId || current === void 0) return "dead";
+	return current.bootId === holder.bootId && current.startTime === holder.startTime ? "alive" : "dead";
+}
+//#endregion
+//#region src/process-lock/application/file-lock.ts
+/**
+* How long a lock file may stay empty or unreadable before it counts as abandoned. A holder writes its stamp right
+* after creating the file, so only a process that died in between leaves it empty. A holder stalled for longer than
+* this between the two steps loses its file to a reclaimer and may then overwrite the reclaimer's stamp with its own;
+* the read-back below catches the overwrite only when it lands before the reclaimer reads back.
+*/
+const UNSTAMPED_GRACE_MS = 3e4;
+/** `.stale`, `.stale.stale`, …: each level serializes the reclaim of the level below. */
+const MAX_RECLAIM_DEPTH = 3;
+/**
+* Tries once to take the lock file at `path`; it never waits for a live holder. The file holds the holder's stamp. A
+* file whose holder is dead (same host, and an earlier boot, no such pid or a reused pid) is reclaimed, as
+* npm/lockfile does with its `.STALE` lock: only the reclaimer that takes `<path>.stale` may remove it, and only after
+* reading the same dead stamp again, so two reclaimers cannot each remove the other's fresh lock.
+*
+* Weaker than the SQLite lock: a holder on another host is never judged dead, and neither is a dead holder's stamp
+* written before this host's name changed, so such a file stays until it is removed by hand; a stamp is written after
+* the file is created, a crash between the two leaves an empty file for `UNSTAMPED_GRACE_MS`, and a holder stalled
+* longer than that between the two can end up holding the lock together with its reclaimer.
+*/
+async function tryFileLock(platform, path, stamp, depth = 0) {
+	let reclaimed = false;
+	for (let turn = 0; turn < 8; turn += 1) {
+		if (await platform.fs.createExclusive(path)) {
+			try {
+				await platform.fs.writeAtomic(path, JSON.stringify(stamp));
+			} catch (error) {
+				await platform.fs.remove(path);
+				throw error;
+			}
+			const written = await readStamp(platform, path);
+			if (written?.stamp?.nonce !== stamp.nonce) return {
+				acquired: false,
+				stamp: written?.stamp
+			};
+			return {
+				acquired: true,
+				stamp,
+				release: () => releaseFileLock(platform, path, stamp.nonce)
+			};
+		}
+		const observed = await readStamp(platform, path);
+		if (observed === void 0) continue;
+		if (reclaimed || depth >= MAX_RECLAIM_DEPTH || !await abandoned(platform, path, observed)) return {
+			acquired: false,
+			stamp: observed.stamp
+		};
+		reclaimed = await reclaim(platform, path, observed, stamp, depth);
+		if (!reclaimed) return {
+			acquired: false,
+			stamp: observed.stamp
+		};
+	}
+	return {
+		acquired: false,
+		stamp: (await readStamp(platform, path))?.stamp
+	};
+}
+async function abandoned(platform, path, observed) {
+	const { stamp } = observed;
+	if (stamp === void 0) {
+		const stat = await platform.fs.stat(path);
+		return stat !== void 0 && platform.clock.now() - stat.mtimeMs > UNSTAMPED_GRACE_MS;
+	}
+	const { self } = platform.process;
+	return holderLiveness(stamp, self, platform.process.identify(stamp.pid)) === "dead";
+}
+/** Removes the abandoned lock file while holding `<path>.stale`; `false` when another reclaimer holds that. */
+async function reclaim(platform, path, observed, stamp, depth) {
+	const guard = await tryFileLock(platform, `${path}.stale`, {
+		...stamp,
+		nonce: crypto.randomUUID()
+	}, depth + 1);
+	if (!guard.acquired) return false;
+	try {
+		const current = await readStamp(platform, path);
+		if (current !== void 0 && current.text === observed.text && await abandoned(platform, path, current)) await platform.fs.remove(path);
+		return true;
+	} finally {
+		await guard.release();
+	}
+}
+async function releaseFileLock(platform, path, nonce) {
+	if ((await readStamp(platform, path))?.stamp?.nonce === nonce) await platform.fs.remove(path);
+}
+//#endregion
+//#region src/process-lock/application/sqlite-lock.ts
+/** SQLITE_BUSY and SQLITE_LOCKED, the primary codes of their extended codes: another connection holds the lock. */
+const BUSY_CODES = /* @__PURE__ */ new Set([5, 6]);
+/**
+* Takes an exclusive lock on the SQLite database at `path`, creating the file, or returns `undefined` when another
+* connection holds it. The lock is an fcntl lock on the file: it lasts until `ROLLBACK` and `close`, and the kernel
+* drops it when the process exits or crashes, so no holder can be left behind and nothing is ever reclaimed.
+*/
+function trySqliteLock(sqlite, path, busyTimeoutMs) {
+	const db = sqlite.open(path);
+	try {
+		db.exec(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
+		db.exec("PRAGMA journal_mode = MEMORY");
+		db.exec("PRAGMA locking_mode = EXCLUSIVE");
+		db.exec("BEGIN EXCLUSIVE");
+		return db;
+	} catch (error) {
+		db.close();
+		if (isSqliteBusy(error)) return;
+		throw error;
+	}
+}
+function unlockSqlite(db) {
+	try {
+		db.exec("ROLLBACK");
+	} finally {
+		db.close();
+	}
+}
+function isSqliteBusy(error) {
+	if (typeof error !== "object" || error === null) return false;
+	const { errcode, message } = error;
+	return typeof errcode === "number" && BUSY_CODES.has(errcode & 255) || message === "database is locked";
+}
+//#endregion
+//#region src/process-lock/application/acquire-process-lock.ts
+/**
+* A single-instance lock on `path`, which must be in an existing local directory (not NFS). With `platform.sqlite`,
+* `path` is a SQLite database held with `locking_mode=EXCLUSIVE`: the kernel releases it when the process exits or
+* crashes, at once, and nothing is ever reclaimed. The holder's identity goes into `<path>.holder` for diagnostics
+* only. Without SQLite, `path` is a lock file that holds the identity itself; a lock file whose holder died is
+* reclaimed on the next attempt, which needs the holder on this host (see `tryFileLock` for the remaining gaps).
+*
+* Supports darwin and linux, where the platform can identify processes.
+*/
+async function acquireProcessLock(platform, path, options = {}) {
+	const { signal, wait = false, retryMs = 50 } = options;
+	for (let attempt = 0;; attempt += 1) {
+		signal?.throwIfAborted();
+		const result = await tryProcessLock(platform, path, { first: attempt === 0 });
+		if (result.ok) {
+			if (signal?.aborted === true) {
+				await result.value.release();
+				signal.throwIfAborted();
+			}
+			return result;
+		}
+		if (!wait) return result;
+		await delay(backoffMs(retryMs, attempt), signal);
+	}
+}
+/** Retries of a waiting caller double from `retryMs` up to 16 times it, with jitter so that waiters drift apart. */
+function backoffMs(retryMs, attempt) {
+	return Math.min(retryMs * 2 ** attempt, retryMs * 16) * (.75 + Math.random() * .5);
+}
+const SETTLE_RETRIES = 4;
+/**
+* One attempt without waiting for a holder. The `first` attempt of an acquisition settles a race between processes
+* that start together (see `SETTLE_MS`); later attempts of a waiting caller do not block the thread at all.
+*/
+async function tryProcessLock(platform, path, options) {
+	const stamp = newStamp(platform);
+	const { sqlite } = platform;
+	if (sqlite === void 0) {
+		const attempt = await tryFileLock(platform, path, stamp);
+		if (!attempt.acquired) return err({
+			_tag: "ProcessLockHeld",
+			path,
+			holder: attempt.stamp && holderOf(attempt.stamp)
+		});
+		return ok({
+			path,
+			mechanism: "file",
+			holder: holderOf(attempt.stamp),
+			release: once(attempt.release)
+		});
+	}
+	const holderFile = `${path}.holder`;
+	const busyTimeoutMs = options.first ? 10 : 0;
+	let db = trySqliteLock(sqlite, path, busyTimeoutMs);
+	for (let retry = 0; db === void 0 && options.first && retry < SETTLE_RETRIES; retry += 1) {
+		await delay(5 + Math.random() * 20, void 0);
+		db = trySqliteLock(sqlite, path, busyTimeoutMs);
+	}
+	if (db === void 0) {
+		const recorded = await readStamp(platform, holderFile);
+		return err({
+			_tag: "ProcessLockHeld",
+			path,
+			holder: recorded?.stamp && holderOf(recorded.stamp)
+		});
+	}
+	try {
+		await platform.fs.writeAtomic(holderFile, JSON.stringify(stamp));
+	} catch (error) {
+		unlockSqlite(db);
+		throw error;
+	}
+	const release = async () => {
+		try {
+			await platform.fs.remove(holderFile);
+		} finally {
+			unlockSqlite(db);
+		}
+	};
+	return ok({
+		path,
+		mechanism: "sqlite",
+		holder: holderOf(stamp),
+		release: once(release)
+	});
+}
+function once(release) {
+	let released;
+	return () => {
+		released ??= release();
+		return released;
+	};
+}
+function delay(ms, signal) {
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+//#endregion
+export { holderLiveness as a, isSqliteBusy as i, backoffMs as n, readText as o, tryProcessLock as r, acquireProcessLock as t };

package/dist/lanes.d.ts

@@ -0,0 +1,120 @@
+import * as Effect from "effect/Effect";
+import { Result } from "@rivus/agent-kit/catalog";
+import * as Cause from "effect/Cause";
+import * as Scope from "effect/Scope";
+//#region src/lanes/domain/lane/errors/lane-queue-full.d.ts
+/** An idle lane was woken while every slot was taken and `maxQueued` lanes were already waiting. */
+interface LaneQueueFull {
+  readonly _tag: "LaneQueueFull";
+  readonly key: string;
+  readonly maxQueued: number;
+}
+//#endregion
+//#region src/lanes/domain/lane/errors/lanes-config-invalid.d.ts
+/** `maxConcurrent`, `maxQueued` or `turnTimeoutMs` is out of range. */
+interface LanesConfigInvalid {
+  readonly _tag: "LanesConfigInvalid";
+  readonly message: string;
+}
+//#endregion
+//#region src/lanes/domain/lane/value-objects/lane-snapshot.d.ts
+/**
+ * `idle`: nothing runs and nothing is owed. `queued`: woken while every slot was taken, waiting for one. `running`: one
+ * activation runs.
+ */
+type LaneState = "idle" | "queued" | "running";
+interface LaneSnapshot {
+  readonly key: string;
+  readonly state: LaneState;
+  /**
+   * A wake that no started activation has served yet: always set while `queued`, and set while `running` when a wake
+   * arrived after the activation started, so one more activation follows it.
+   */
+  readonly pending: boolean;
+}
+//#endregion
+//#region src/lanes/application/create-lanes.d.ts
+interface LanesConfig<E, R> {
+  /** Activations that may run at once across all keys; a positive integer. */
+  readonly maxConcurrent: number;
+  /**
+   * Lanes that may wait for a free slot; a non-negative integer. A lane waits at most once however often it is woken,
+   * so without a bound the queue holds at most one entry per key.
+   */
+  readonly maxQueued?: number;
+  /** The longest one activation may run, in milliseconds, before it is interrupted; no limit when absent. */
+  readonly turnTimeoutMs?: number;
+  /**
+   * The work for one key. It runs in a Scope of its own, closed when it ends, with the context `createLanes` ran in.
+   * `cancel`, `close` and the turn timeout interrupt it, and the lane moves on only after its finalizers have run.
+   */
+  readonly activate: (key: string) => Effect.Effect<unknown, E, R>;
+  /**
+   * Hears how each activation ended, before the lane can start its next activation. It runs uninterruptibly, and
+   * `cancel` and `close` wait for it, so keep it short and do not wait for either of them in it. A defect it raises is
+   * logged as a warning.
+   */
+  readonly onExit?: (exit: ActivationExit<E>) => Effect.Effect<void, never, R>;
+}
+/** Why the lanes interrupted an activation. */
+type ActivationInterruptReason = "cancel" | "close" | "timeout";
+/**
+ * How an activation ended. An activation that succeeded or failed by itself is reported so even when a cancel, close
+ * or timeout comes while its Scope closes; `ActivationInterrupted` means the lanes cut it short or it never started.
+ */
+type ActivationExit<E> = {
+  readonly _tag: "ActivationSucceeded";
+  readonly key: string;
+} | {
+  readonly _tag: "ActivationFailed";
+  readonly key: string;
+  readonly cause: Cause.Cause<E>;
+} | {
+  readonly _tag: "ActivationInterrupted";
+  readonly key: string;
+  readonly reason: ActivationInterruptReason;
+};
+/**
+ * `started`: an activation started; `queued`: the lane waits for a free slot; `coalesced`: an activation that has not
+ * started yet serves this wake (the queued one, or the one that follows the running one).
+ */
+type WakeResult = "started" | "queued" | "coalesced";
+/** `close` ran, or the Scope that created the lanes closed. */
+interface LanesClosed {
+  readonly _tag: "LanesClosed";
+  readonly key: string;
+}
+interface LanesStatus {
+  readonly running: number;
+  readonly queued: number;
+  readonly closed: boolean;
+  /** Every lane that is not idle: the running ones, then the queued ones in queue order. */
+  readonly lanes: readonly LaneSnapshot[];
+}
+/** Lanes created in a caller's Scope; closing that Scope runs `close`. */
+interface Lanes {
+  /**
+   * Asks for an activation of `key` without waiting for it. An idle lane starts when a slot is free and nobody waits
+   * for one, otherwise it joins the end of the queue, or fails with `LaneQueueFull` when `maxQueued` lanes already
+   * wait. A queued or running lane coalesces the wake: at most one more activation follows the running one.
+   */
+  wake(key: string): Effect.Effect<WakeResult, LaneQueueFull | LanesClosed>;
+  /**
+   * Drops the wakes `key` owes and interrupts its running activation, then waits until that activation, `onExit`
+   * included, has ended. Wakes that arrive after the cancel are served as usual.
+   */
+  cancel(key: string): Effect.Effect<void>;
+  readonly status: Effect.Effect<LanesStatus>;
+  /**
+   * Refuses later wakes with `LanesClosed`, drops the queue and every pending wake, interrupts the running
+   * activations and waits until they have ended. Idempotent.
+   */
+  readonly close: Effect.Effect<void>;
+}
+/**
+ * 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.
+ */
+export declare function createLanes<E = never, R = never>(config: LanesConfig<E, R>): Effect.Effect<Lanes, LanesConfigInvalid, R | Scope.Scope>;
+//#endregion
+export type { ActivationExit, ActivationInterruptReason, LaneQueueFull, LaneSnapshot, LaneState, Lanes, LanesClosed, LanesConfig, LanesConfigInvalid, LanesStatus, WakeResult };