@rivus/agent-kit-collab 0.3.0 → 0.4.0

package/README.md

@@ -31,11 +31,11 @@ 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   |
+| Entry                                  | Main exports                                                                                                                                                                                        | Kind     |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| `@rivus/agent-kit-collab/process-lock` | `acquireProcessLock`, `ProcessLock`, `ProcessLockHeld`                                                                                                                                              | plain TS |
+| `@rivus/agent-kit-collab/lease`        | `createLeaseManager`, `LeaseRepository`, `sqliteLeaseRepository`, `fileLeaseRepository`, `memoryLeaseRepository`; rules `isFresh`, `canAcquire`, `nextFencingToken`, `checkFence`, `holderLiveness` | Effect   |
+| `@rivus/agent-kit-collab/lanes`        | `createLanes`                                                                                                                                                                                       | Effect   |
 
 ### Process lock
 
@@ -62,10 +62,12 @@ instead of getting `ProcessLockHeld` at once.
 
 ```ts
 import { NodePlatformLive } from "@rivus/agent-kit/node/effect";
-import { createLeaseManager, sqliteLeaseStore } from "@rivus/agent-kit-collab/lease";
+import { createLeaseManager, sqliteLeaseRepository } 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 LeaseLive = sqliteLeaseRepository({ path: "/var/lib/my-app/leases.db" }).pipe(
+  Layer.provideMerge(NodePlatformLive)
+);
 
 const program = Effect.scoped(
   Effect.gen(function* () {
@@ -89,19 +91,24 @@ await Effect.runPromiseExit(program.pipe(Effect.provide(LeaseLive)));
 - 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
+- `runFenced` holds the repository'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
+  the same repository 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.
+- `sqliteLeaseRepository` compares revisions inside `BEGIN IMMEDIATE` transactions. `fileLeaseRepository` is the
+  fallback without SQLite: one JSON file per key, written under a per-key lock file. `memoryLeaseRepository` serves
+  one process.
+- The repository port follows the kit's repository shape: `load(key)` is the stored `LeaseSnapshot` or `undefined`,
+  and `save(key, snapshot, expectedRevision)` writes only over that revision and fails with a `RevisionConflict`
+  when another writer moved the record first.
+
+Expected failures are typed values with a `_tag`: `LeaseHeld`, `LeaseLost`, `FenceRejected`, `LeaseConfigInvalid`,
+`LeaseRepositoryFailure` and the repository's `RevisionConflict`. The kit runs no Effect itself; run the program at
+your application's assembly root.
 
 ### Lanes
 

package/dist/{acquire-process-lock-A0oYDN9m.js → acquire-process-lock-BCvK1ehZ.js}

@@ -1,6 +1,6 @@
 import * as z from "zod/mini";
 import { err, ok } from "@rivus/agent-kit/catalog";
-//#region src/process-lock/application/holder.ts
+//#region src/process-lock/application/services/holder.ts
 const stampSchema = z.object({
 	host: z.string(),
 	bootId: z.string(),
@@ -78,7 +78,7 @@ function holderLiveness(holder, observer, current) {
 	return current.bootId === holder.bootId && current.startTime === holder.startTime ? "alive" : "dead";
 }
 //#endregion
-//#region src/process-lock/application/file-lock.ts
+//#region src/process-lock/application/services/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
@@ -165,7 +165,7 @@ 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
+//#region src/process-lock/application/services/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]);
 /**
@@ -200,7 +200,7 @@ function isSqliteBusy(error) {
 	return typeof errcode === "number" && BUSY_CODES.has(errcode & 255) || message === "database is locked";
 }
 //#endregion
-//#region src/process-lock/application/acquire-process-lock.ts
+//#region src/process-lock/application/use-cases/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
@@ -296,11 +296,12 @@ function once(release) {
 }
 function delay(ms, signal) {
 	return new Promise((resolve, reject) => {
+		let timer;
 		const onAbort = () => {
 			clearTimeout(timer);
 			reject(signal?.reason);
 		};
-		const timer = setTimeout(() => {
+		timer = setTimeout(() => {
 			signal?.removeEventListener("abort", onAbort);
 			resolve();
 		}, ms);

package/dist/lanes.d.ts

@@ -17,6 +17,13 @@ interface LanesConfigInvalid {
   readonly message: string;
 }
 //#endregion
+//#region src/lanes/domain/lane/policies/admission.d.ts
+/**
+ * `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";
+//#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
@@ -33,7 +40,7 @@ interface LaneSnapshot {
   readonly pending: boolean;
 }
 //#endregion
-//#region src/lanes/application/create-lanes.d.ts
+//#region src/lanes/application/use-cases/create-lanes.d.ts
 interface LanesConfig<E, R> {
   /** Activations that may run at once across all keys; a positive integer. */
   readonly maxConcurrent: number;
@@ -74,11 +81,6 @@ type ActivationExit<E> = {
   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";

package/dist/lanes.js

@@ -12,8 +12,21 @@ function admit(load, limits) {
 	if (load.running < limits.maxConcurrent && load.queued === 0) return "start";
 	return load.queued < limits.maxQueued ? "queue" : "full";
 }
+/**
+* Which queued lane may start now, or `undefined` when none may: the lanes are closed, the queue is empty, or every
+* slot is running. The queue is FIFO: a free slot goes to the lane that has waited longest, and the slot a finishing
+* activation frees goes to the head of the queue first.
+*/
+function nextToStart(queue, load, limits, closed) {
+	if (closed || load.running >= limits.maxConcurrent) return;
+	return queue[0];
+}
+/** Reads how a wake ended from the events its transition produced. */
+function wakeResult(events) {
+	return events.some(({ _tag }) => _tag === "ActivationStarted") ? "started" : events.some(({ _tag }) => _tag === "LaneQueued") ? "queued" : "coalesced";
+}
 //#endregion
-//#region src/lanes/domain/lane/aggregate/lane.ts
+//#region src/lanes/domain/lane/aggregates/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
@@ -168,11 +181,11 @@ function laneLimits(input) {
 	});
 }
 //#endregion
-//#region src/lanes/application/from-result.ts
+//#region src/lanes/application/services/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
+//#region src/lanes/application/use-cases/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);
 /**
@@ -220,10 +233,14 @@ function createLanes(config) {
 			}
 			return started;
 		};
-		/** Gives the free slots to the lanes that have waited longest. */
+		/** Hands the free slots to the lanes that `nextToStart` picks: the ones 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()));
+			const load = () => ({
+				running: activations.size,
+				queued: queue.length
+			});
+			for (let key = nextToStart(queue, load(), limits, closed); key !== void 0; key = nextToStart(queue, load(), limits, closed)) started.push(...apply(laneOf(key).start()));
 			return started;
 		};
 		const interrupted = (key, reason) => ({
@@ -276,8 +293,9 @@ function createLanes(config) {
 				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";
+		function fork(started) {
+			return Effect.forEach(started, (activation) => Effect.forkDetach(run(activation), { uninterruptible: true }), { discard: true });
+		}
 		const close = Effect.suspend(() => {
 			if (!closed) {
 				closed = true;

package/dist/lease.d.ts

@@ -80,6 +80,13 @@ interface FenceRejected {
   readonly current: number | undefined;
 }
 //#endregion
+//#region src/lease/domain/lease/errors/lease-config-invalid.d.ts
+/** A lease duration is out of range, or the heartbeat does not fit twice into the TTL. */
+interface LeaseConfigInvalid {
+  readonly _tag: "LeaseConfigInvalid";
+  readonly message: string;
+}
+//#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
@@ -131,14 +138,26 @@ export declare function isFresh(lease: LeaseSnapshot, observation: LeaseObservat
 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";
+/**
+ * Another writer wrote over the revision a `save` was conditioned on, so it wrote nothing. Declared here, next to
+ * the port; other contexts declare their own.
+ */
+interface RevisionConflict {
+  readonly _tag: "RevisionConflict";
+  readonly key: string;
+  /** The revision the save was conditioned on; `undefined` when it required the record not to exist. */
+  readonly expectedRevision: number | undefined;
+  /** The revision the stored record had when the save compared it; `undefined` when there was none. */
+  readonly storedRevision: number | undefined;
+}
+/** The repository could not read or write a record; the lease's state is unknown, not changed. */
+interface LeaseRepositoryFailure {
+  readonly _tag: "LeaseRepositoryFailure";
   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.
+   * `busy`: other writers kept the repository locked; `invalid-record`: a stored record is unreadable or breaks the
+   * invariants and is left as it is; `unsupported-schema`: the repository was written by a newer version;
+   * `unavailable`: the platform lacks what the repository needs; `io`: any other failure.
    */
   readonly reason: "busy" | "io" | "invalid-record" | "unsupported-schema" | "unavailable";
   readonly message: string;
@@ -147,8 +166,10 @@ interface LeaseStoreFailure {
 /**
  * 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.
+ * - `load(key)` is the stored record, or `undefined` when there is none.
+ * - `save(key, snapshot, expectedRevision)` writes atomically across every process that uses the same repository
+ *   location: it writes only when the stored record's revision equals `expectedRevision` (`undefined`: no record),
+ *   and fails with a `RevisionConflict` instead of writing when another writer moved the record first.
  * - 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.
@@ -156,58 +177,59 @@ interface LeaseStoreFailure {
  *
  * 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`.
+ * repository 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>;
+interface LeaseRepositoryShape {
+  load(key: string): Effect.Effect<LeaseSnapshot | undefined, LeaseRepositoryFailure>;
+  save(key: string, snapshot: LeaseSnapshot, expectedRevision: number | undefined): Effect.Effect<void, LeaseRepositoryFailure | RevisionConflict>;
+  fence(key: string): Effect.Effect<void, LeaseRepositoryFailure, 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 {}
+declare const KEY = "@rivus/agent-kit-collab/lease/LeaseRepository/v1";
+declare const LeaseRepositoryBase: Context.ServiceClass<LeaseRepository, typeof KEY, LeaseRepositoryShape>;
+/** The lease repository port; `sqliteLeaseRepository`, `fileLeaseRepository` and `memoryLeaseRepository` provide it. */
+export declare class LeaseRepository extends LeaseRepositoryBase {}
 //#endregion
-//#region src/lease/adapters/file-lease-store.d.ts
-interface FileLeaseStoreOptions {
+//#region src/lease/infra/repository/file-lease-repository.d.ts
+interface FileLeaseRepositoryOptions {
   /** 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.
+ * The fallback repository for platforms without SQLite: one JSON record per key, `<key>.lease.json`, replaced with
+ * `writeAtomic`. Every `save` 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>;
+export declare function fileLeaseRepository(options: FileLeaseRepositoryOptions): Layer.Layer<LeaseRepository, never, PlatformService>;
 //#endregion
-//#region src/lease/adapters/memory-lease-store.d.ts
+//#region src/lease/infra/repository/memory-lease-repository.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.
+ * A repository 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>;
+export declare function memoryLeaseRepository(): Layer.Layer<LeaseRepository>;
 //#endregion
-//#region src/lease/adapters/sqlite-lease-store.d.ts
-interface SqliteLeaseStoreOptions {
+//#region src/lease/infra/repository/sqlite-lease-repository.d.ts
+interface SqliteLeaseRepositoryOptions {
   /**
    * 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.
+   * `<path>.<key>.fence` (plus a `.holder` file each), so give the repository 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.
+ * The lease repository for one machine: one row per key in a SQLite database. `save` 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 repository 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>;
+export declare function sqliteLeaseRepository(options: SqliteLeaseRepositoryOptions): Layer.Layer<LeaseRepository, LeaseRepositoryFailure, PlatformService>;
 //#endregion
-//#region src/lease/application/lease-manager.d.ts
+//#region src/lease/application/use-cases/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;
@@ -216,15 +238,11 @@ interface LeaseConfig {
   /** 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.
+   * Keep trying every `retryMs` while the lease is held or the repository is busy (a guard that stays locked),
+   * instead of failing with `LeaseHeld` or a `busy` `LeaseRepositoryFailure`. The wait ends when the lease is taken,
+   * on another repository failure, or when the fiber is interrupted.
    */
   readonly wait?: boolean;
 }
@@ -238,7 +256,7 @@ interface LeaseHandle {
    */
   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
+   * Runs `work` under the repository'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`.
    *
@@ -248,7 +266,7 @@ interface LeaseHandle {
    * 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>>;
+  runFenced<A, E, R>(work: (token: FencingToken) => Effect.Effect<A, E, R>): Effect.Effect<A, E | LeaseLost | FenceRejected | LeaseRepositoryFailure, Exclude<R, Scope.Scope>>;
 }
 interface LeaseManager {
   /**
@@ -256,10 +274,10 @@ interface LeaseManager {
    * 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>;
+  acquire(key: string, options?: AcquireOptions): Effect.Effect<LeaseHandle, LeaseHeld | LeaseRepositoryFailure, Scope.Scope>;
+  read(key: string): Effect.Effect<LeaseSnapshot | undefined, LeaseRepositoryFailure>;
 }
-/** 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>;
+/** Validates `config` and builds a manager over the `LeaseRepository` and the platform in context. */
+export declare function createLeaseManager(config: LeaseConfig): Effect.Effect<LeaseManager, LeaseConfigInvalid, LeaseRepository | PlatformService>;
 //#endregion
-export type { AcquireOptions, AcquisitionView, FenceRejected, FencingToken, FileLeaseStoreOptions, Holder, HolderLiveness, LeaseConfig, LeaseConfigInvalid, LeaseHandle, LeaseHeld, LeaseLost, LeaseManager, LeaseObservation, LeaseSnapshot, LeaseStoreFailure, LeaseStoreShape, SqliteLeaseStoreOptions };
+export type { AcquireOptions, AcquisitionView, FenceRejected, FencingToken, FileLeaseRepositoryOptions, Holder, HolderLiveness, LeaseConfig, LeaseConfigInvalid, LeaseHandle, LeaseHeld, LeaseLost, LeaseManager, LeaseObservation, LeaseRepositoryFailure, LeaseRepositoryShape, LeaseSnapshot, RevisionConflict, SqliteLeaseRepositoryOptions };

package/dist/lease.js

@@ -1,4 +1,4 @@
-import { a as holderLiveness, i as isSqliteBusy, n as backoffMs, o as readText, r as tryProcessLock } from "./acquire-process-lock-A0oYDN9m.js";
+import { a as holderLiveness, i as isSqliteBusy, n as backoffMs, o as readText, r as tryProcessLock } from "./acquire-process-lock-BCvK1ehZ.js";
 import { PlatformService } from "@rivus/agent-kit/platform/effect";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
@@ -12,27 +12,35 @@ 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 {};
+const LeaseRepositoryBase = Context.Service()("@rivus/agent-kit-collab/lease/LeaseRepository/v1");
+/** The lease repository port; `sqliteLeaseRepository`, `fileLeaseRepository` and `memoryLeaseRepository` provide it. */
+var LeaseRepository = class extends LeaseRepositoryBase {};
 //#endregion
-//#region src/lease/application/store-failure.ts
-function storeFailure(key, reason, message, cause) {
+//#region src/lease/application/services/repository-failure.ts
+function repositoryFailure(key, reason, message, cause) {
 	return cause === void 0 ? {
-		_tag: "LeaseStoreFailure",
+		_tag: "LeaseRepositoryFailure",
 		key,
 		reason,
 		message
 	} : {
-		_tag: "LeaseStoreFailure",
+		_tag: "LeaseRepositoryFailure",
 		key,
 		reason,
 		message,
 		cause
 	};
 }
+function revisionConflict(key, expectedRevision, storedRevision) {
+	return {
+		_tag: "RevisionConflict",
+		key,
+		expectedRevision,
+		storedRevision
+	};
+}
 //#endregion
-//#region src/lease/adapters/key-file-name.ts
+//#region src/lease/infra/models/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;
 /**
@@ -48,7 +56,7 @@ function keyFileName(key) {
 	}));
 }
 //#endregion
-//#region src/lease/adapters/lease-record-codec.ts
+//#region src/lease/infra/models/lease-record-codec.ts
 const holderSchema = z.object({
 	host: z.string(),
 	bootId: z.string(),
@@ -121,7 +129,19 @@ function checkFence(lastSeen, token) {
 	return ok(token);
 }
 //#endregion
-//#region src/lease/domain/lease/aggregate/lease.ts
+//#region src/lease/domain/lease/policies/loss.ts
+/**
+* Why an acquisition that could not renew or write no longer holds, judged from the record it sees: the record is
+* gone (`missing`), a tombstone says it was released, or another holder wrote it (`taken-over`). A tombstone is a
+* record with no holder, so the holder field decides, whatever `holderId` says. How a read that failed counts is
+* the caller's error mapping, not a property of a record.
+*/
+function lossReason(record) {
+	if (record === void 0) return "missing";
+	return record.holder === null ? "released" : "taken-over";
+}
+//#endregion
+//#region src/lease/domain/lease/aggregates/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
@@ -183,7 +203,7 @@ var Lease = class Lease {
 	}
 	/** A heartbeat: only the holding acquisition renews, and the generation stays. */
 	renew(holding, now) {
-		const lost = this.lostBy(holding);
+		const lost = this.lossOf(holding);
 		if (lost !== void 0) return err(lost);
 		const state = new Lease({
 			...this.snapshot,
@@ -203,7 +223,7 @@ var Lease = class Lease {
 	}
 	/** Leaves a tombstone: no holder, the same generation, so the next acquisition still moves forward. */
 	release(holding, now) {
-		const lost = this.lostBy(holding);
+		const lost = this.lossOf(holding);
 		if (lost !== void 0) return err(lost);
 		const state = new Lease({
 			...this.snapshot,
@@ -226,15 +246,19 @@ var Lease = class Lease {
 	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";
+	/** Whether this record is still the given acquisition's: the same holder id and generation. */
+	holds(holding) {
+		const { holderId, generation } = this.snapshot;
+		return holderId === holding.holderId && generation === holding.generation;
+	}
+	/** Why this acquisition no longer holds, or `undefined` when it still does. */
+	lossOf(holding) {
+		if (this.holds(holding)) return;
 		return {
 			_tag: "LeaseLost",
-			key,
+			key: this.snapshot.key,
 			generation: holding.generation,
-			reason
+			reason: lossReason(this.snapshot)
 		};
 	}
 };
@@ -272,8 +296,38 @@ function observe(previous, lease, now) {
 function isFresh(lease, observation, now, ttlMs) {
 	return lease.holder !== null && (observation.revision !== lease.revision || now - observation.observedAt < ttlMs);
 }
+/**
+* Whether the holder itself must give up: it has not confirmed a renewal for a full TTL, so an observer's clock may
+* already have expired the lease and a takeover can have happened. Both times come from the holder's own monotonic
+* clock; `confirmedAt` is when its last renewal write was accepted.
+*/
+function holderExpired(confirmedAt, now, ttlMs) {
+	return now - confirmedAt >= ttlMs;
+}
+//#endregion
+//#region src/lease/domain/lease/value-objects/lease-timing.ts
+/** Accepts a timing where every duration is positive and one late heartbeat cannot lose the lease. */
+function leaseTiming(input) {
+	const { ttlMs, heartbeatMs } = input;
+	const retryMs = input.retryMs ?? heartbeatMs;
+	const invalid = (message) => err({
+		_tag: "LeaseConfigInvalid",
+		message
+	});
+	for (const [name, value] of [
+		["ttlMs", ttlMs],
+		["heartbeatMs", heartbeatMs],
+		["retryMs", retryMs]
+	]) if (!Number.isFinite(value) || value <= 0) return invalid(`${name} must be a positive number of milliseconds, got ${value}`);
+	if (heartbeatMs * 2 > ttlMs) return invalid(`heartbeatMs × 2 must not exceed ttlMs (${heartbeatMs} × 2 > ${ttlMs})`);
+	return ok({
+		ttlMs,
+		heartbeatMs,
+		retryMs
+	});
+}
 //#endregion
-//#region src/lease/adapters/process-fence.ts
+//#region src/lease/infra/adapters/process-fence.ts
 /** The first retry of a waiting fence or guard; later ones back off from it. */
 const RETRY_MS = 10;
 /**
@@ -284,19 +338,19 @@ const RETRY_MS = 10;
 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()));
+		catch: (cause) => repositoryFailure(key, "io", `cannot lock ${path}`, cause)
+	}).pipe(Effect.flatMap((result) => result.ok ? Effect.succeed(result.value) : Effect.fail(repositoryFailure(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`));
+			if (options.timeoutMs !== void 0 && platform.clock.monotonic() - started >= options.timeoutMs) return yield* Effect.fail(repositoryFailure(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
+//#region src/lease/infra/repository/file-lease-repository.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
@@ -304,34 +358,34 @@ const SCHEMA_VERSION$1 = 1;
 */
 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.
+* The fallback repository for platforms without SQLite: one JSON record per key, `<key>.lease.json`, replaced with
+* `writeAtomic`. Every `save` 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) {
+function fileLeaseRepository(options) {
 	const { dir } = options;
-	return Layer.effect(LeaseStore, Effect.gen(function* () {
+	return Layer.effect(LeaseRepository, 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)));
+		const load = (key) => pathOf(key, ".json").pipe(Effect.flatMap((path) => readRecord(platform, key, path)));
 		return {
-			read,
-			compareAndSet: (key, expected, next) => Effect.scoped(Effect.gen(function* () {
+			load,
+			save: (key, next, expectedRevision) => 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;
+					const current = yield* readRecord(platform, key, path);
+					if (current?.revision !== expectedRevision) return yield* Effect.fail(revisionConflict(key, expectedRevision, current?.revision));
 					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)
+						catch: (cause) => repositoryFailure(key, "io", `cannot write ${path}`, cause)
 					});
-					return true;
 				}));
 			})),
 			fence: (key) => pathOf(key, ".fence").pipe(Effect.flatMap((path) => holdProcessLock(platform, key, path)))
@@ -341,7 +395,7 @@ function fileLeaseStore(options) {
 function readRecord(platform, key, path) {
 	return Effect.tryPromise({
 		try: () => readText(platform, path),
-		catch: (cause) => storeFailure(key, "io", `cannot read ${path}`, cause)
+		catch: (cause) => repositoryFailure(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) {
@@ -349,21 +403,21 @@ function decodeFile(key, path, text) {
 	try {
 		json = JSON.parse(text);
 	} catch (cause) {
-		return Effect.fail(storeFailure(key, "invalid-record", `${path} is not JSON`, cause));
+		return Effect.fail(repositoryFailure(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`));
+	if (schemaVersion !== SCHEMA_VERSION$1) return Effect.fail(repositoryFailure(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);
+	return snapshot === void 0 ? Effect.fail(repositoryFailure(key, "invalid-record", `${path} holds a record of an unexpected shape`)) : Effect.succeed(snapshot);
 }
 //#endregion
-//#region src/lease/adapters/memory-lease-store.ts
+//#region src/lease/infra/repository/memory-lease-repository.ts
 /**
-* A store for one process, such as tests or a host whose leases never cross a process boundary. Each Layer build
-* starts empty.
+* A repository 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, () => {
+function memoryLeaseRepository() {
+	return Layer.sync(LeaseRepository, () => {
 		const records = /* @__PURE__ */ new Map();
 		const fences = /* @__PURE__ */ new Map();
 		const fenceOf = (key) => {
@@ -372,36 +426,37 @@ function memoryLeaseStore() {
 			return fence;
 		};
 		return {
-			read: (key) => Effect.sync(() => records.get(key)),
-			compareAndSet: (key, expected, next) => Effect.sync(() => {
-				if (records.get(key)?.revision !== expected) return false;
+			load: (key) => Effect.sync(() => records.get(key)),
+			save: (key, next, expectedRevision) => Effect.suspend(() => {
+				const stored = records.get(key);
+				if (stored?.revision !== expectedRevision) return Effect.fail(revisionConflict(key, expectedRevision, stored?.revision));
 				records.set(key, next);
-				return true;
+				return Effect.void;
 			}),
 			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
+//#region src/lease/infra/repository/sqlite-lease-repository.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.
+* The lease repository for one machine: one row per key in a SQLite database. `save` 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 repository 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) {
+function sqliteLeaseRepository(options) {
 	const { path } = options;
-	return Layer.effect(LeaseStore, Effect.gen(function* () {
+	return Layer.effect(LeaseRepository, 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"));
+		if (sqlite === void 0) return yield* Effect.fail(repositoryFailure("", "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 = {
@@ -412,12 +467,13 @@ function sqliteLeaseStore(options) {
              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))),
+			load: (key) => retryBusy(sqliteTry(key, `cannot read ${path}`, () => statements.select.get(key))).pipe(Effect.flatMap((row) => decodeRow(key, row))),
+			save: (key, next, expectedRevision) => retryBusy(sqliteTry(key, `cannot write ${path}`, () => saveInTransaction(db, statements, key, next, expectedRevision))).pipe(Effect.flatMap((outcome) => outcome === void 0 ? Effect.void : Effect.fail(outcome))),
 			fence: (key) => keyFileName(key).pipe(Effect.flatMap((name) => holdProcessLock(platform, key, `${path}.${name}.fence`)))
 		};
 	}));
 }
+var UnsupportedSchema = class extends Error {};
 function migrate(db) {
 	db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
 	db.exec("PRAGMA journal_mode = WAL");
@@ -436,12 +492,12 @@ function migrate(db) {
 		} 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) {
+function saveInTransaction(db, statements, key, next, expectedRevision) {
 	return transaction(db, () => {
-		const stored = statements.selectRevision.get(next.key)?.revision;
-		if ((stored === void 0 ? void 0 : Number(stored)) !== expected) return false;
+		const storedRow = statements.selectRevision.get(next.key);
+		const stored = storedRow === void 0 ? void 0 : Number(storedRow.revision);
+		if (stored !== expectedRevision) return revisionConflict(key, expectedRevision, stored);
 		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. */
@@ -458,13 +514,12 @@ function transaction(db, body) {
 		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);
+			if (cause instanceof UnsupportedSchema) return repositoryFailure(key, "unsupported-schema", cause.message);
+			return repositoryFailure(key, isSqliteBusy(cause) ? "busy" : "io", message, cause);
 		}
 	});
 }
@@ -486,36 +541,23 @@ function decodeRow(key, row) {
 		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);
+	return snapshot === void 0 ? Effect.fail(repositoryFailure(key, "invalid-record", `the stored record for ${key} has an unexpected shape`)) : Effect.succeed(snapshot);
 }
 //#endregion
-//#region src/lease/application/from-result.ts
+//#region src/lease/application/services/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. */
+//#region src/lease/application/use-cases/lease-manager.ts
+/** CAS attempts within one acquisition before the repository 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. */
+/** Validates `config` and builds a manager over the `LeaseRepository` 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);
+		return makeManager(yield* fromResult(leaseTiming(config)), yield* LeaseRepository, 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) {
+function makeManager(timing, store, platform) {
 	const observations = /* @__PURE__ */ new Map();
 	const now = () => platform.clock.monotonic();
 	const self = () => {
@@ -535,7 +577,7 @@ function makeManager(config, store, platform) {
 	/** 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 record = yield* store.load(key);
 			const claim = {
 				key,
 				holder: self(),
@@ -545,11 +587,11 @@ function makeManager(config, store, platform) {
 			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 lease = yield* fromResult(Lease.restore(record)).pipe(Effect.mapError((invalid) => repositoryFailure(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 fresh = isFresh(record, observation, at, timing.ttlMs);
 				const { holder } = record;
 				const liveness = fresh && holder !== null ? yield* judge(holder, claim.holder) : "unknown";
 				transition = yield* fromResult(lease.acquire(claim, {
@@ -558,17 +600,16 @@ function makeManager(config, store, platform) {
 				}));
 			}
 			const next = transition.state.toSnapshot();
-			if (yield* store.compareAndSet(key, record?.revision, next)) {
+			if (yield* store.save(key, next, record?.revision).pipe(Effect.as(true), Effect.catchTag("RevisionConflict", () => Effect.succeed(false)))) {
 				observations.delete(key);
 				return next;
 			}
 		}
-		return yield* Effect.fail(storeFailure(key, "busy", "the lease record kept changing during acquisition"));
+		return yield* Effect.fail(repositoryFailure(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";
+		const read = yield* Effect.exit(store.load(key));
+		const reason = Exit.isSuccess(read) ? lossReason(read.value) : "taken-over";
 		return {
 			_tag: "LeaseLost",
 			key,
@@ -577,25 +618,25 @@ function makeManager(config, store, platform) {
 		};
 	});
 	/**
-	* 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.
+	* Renews every `heartbeatMs`. A refused write means another writer moved the record, so the lease is lost; a
+	* repository 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 repository; `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);
+			yield* Effect.sleep(timing.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)));
+			const written = yield* Effect.exit(store.save(key, next, current.revision).pipe(Effect.tap(() => Ref.set(ref, next)), Effect.as(true), Effect.catchTag("RevisionConflict", () => Effect.succeed(false))));
 			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({
+			} else if (holderExpired(confirmedAt, now(), timing.ttlMs)) return yield* Effect.fail({
 				_tag: "LeaseLost",
 				key,
 				generation: holding.generation,
@@ -608,10 +649,10 @@ function makeManager(config, store, platform) {
 	* to expire after the TTL; a finalizer cannot fail.
 	*/
 	const release = (key, holding) => Effect.gen(function* () {
-		const current = yield* store.read(key);
+		const current = yield* store.load(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());
+		if (current !== void 0 && transition?.ok === true) yield* store.save(key, transition.value.state.toSnapshot(), current.revision);
 	}).pipe(Effect.ignore);
 	const handle = (key, holding, lost) => {
 		const token = {
@@ -625,8 +666,8 @@ function makeManager(config, store, platform) {
 			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 record = yield* store.load(key);
+				if ((record === void 0 ? void 0 : yield* fromResult(Lease.restore(record)).pipe(Effect.mapError((invalid) => repositoryFailure(key, "invalid-record", invalid.message))))?.holds(holding) !== true) {
 					const current = record?.generation;
 					return yield* Effect.fail({
 						_tag: "FenceRejected",
@@ -649,7 +690,7 @@ function makeManager(config, store, platform) {
 			})));
 			const acquired = options.wait === true ? attempt.pipe(Effect.retry({
 				while: (error) => error._tag === "LeaseHeld" || error.reason === "busy",
-				schedule: Schedule.spaced(config.retryMs ?? config.heartbeatMs)
+				schedule: Schedule.spaced(timing.retryMs)
 			})) : attempt;
 			return Effect.gen(function* () {
 				const ref = yield* acquired;
@@ -663,8 +704,8 @@ function makeManager(config, store, platform) {
 				return handle(key, holding, lost);
 			});
 		},
-		read: (key) => store.read(key)
+		read: (key) => store.load(key)
 	};
 }
 //#endregion
-export { LeaseStore, canAcquire, checkFence, createLeaseManager, fileLeaseStore, holderLiveness, isFresh, memoryLeaseStore, nextFencingToken, sqliteLeaseStore };
+export { LeaseRepository, canAcquire, checkFence, createLeaseManager, fileLeaseRepository, holderLiveness, isFresh, memoryLeaseRepository, nextFencingToken, sqliteLeaseRepository };

package/dist/process-lock.d.ts

@@ -8,7 +8,7 @@ import { Platform } from "@rivus/agent-kit/platform";
  */
 type ProcessLockPlatform = Pick<Platform, "fs" | "process" | "clock" | "sqlite">;
 //#endregion
-//#region src/process-lock/application/holder.d.ts
+//#region src/process-lock/application/services/holder.d.ts
 /** Who holds or held a process lock, as recorded when it was acquired; it may be stale. */
 interface ProcessLockHolder {
   readonly host: string;
@@ -19,7 +19,7 @@ interface ProcessLockHolder {
   readonly acquiredAt: number;
 }
 //#endregion
-//#region src/process-lock/application/acquire-process-lock.d.ts
+//#region src/process-lock/application/use-cases/acquire-process-lock.d.ts
 interface ProcessLockOptions {
   /** Keep trying while another process holds the lock, instead of returning `ProcessLockHeld` at once. */
   readonly wait?: boolean;

package/dist/process-lock.js

@@ -1,2 +1,2 @@
-import { t as acquireProcessLock } from "./acquire-process-lock-A0oYDN9m.js";
+import { t as acquireProcessLock } from "./acquire-process-lock-BCvK1ehZ.js";
 export { acquireProcessLock };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivus/agent-kit-collab",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Collaboration primitives between coding agents: fenced leases, single-instance process locks and keyed scheduling lanes.",
   "license": "MIT",
   "repository": {
@@ -40,8 +40,8 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
     "@effect/vitest": "4.0.1",
-    "@perfectpan/lint-config": "github:PerfectPan/lint-config#v0.3.2",
-    "@rivus/agent-kit": "0.3.0",
+    "@perfectpan/lint-config": "github:PerfectPan/lint-config#v0.4.0",
+    "@rivus/agent-kit": "0.4.0",
     "@size-limit/preset-small-lib": "14.1.0",
     "@types/node": "24.19.1",
     "effect": "4.0.1",
@@ -56,7 +56,7 @@
     "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@rivus/agent-kit": "^0.3.0",
+    "@rivus/agent-kit": "^0.4.0",
     "effect": "4.0.1"
   },
   "peerDependenciesMeta": {