Refactor coordination session architecture and signal contracts

- Clean up file structure: delete dead files (session-stream, session-utils),
  merge node-runtime into node.ts, move try-acquire to errors.ts, move
  transport FSM into session-state.ts
- Fix signal ownership: session owns its own AbortController, lease owns its
  own AbortController (independent lifecycles, no cross-linking)
- Add typed error classes: SessionClosedError, SessionExpiredError,
  LeaseReleasedError, LeaderChangedError, ObservationEndedError
- Simplify Lease: delegates release to Semaphore, idempotent via AC check
- Simplify Mutex: Lock is now a type alias for Lease
- Simplify Election: accepts Semaphore directly, no transport dependency
- Move gRPC client to SessionTransport constructor
- Remove redundant emit_error effect and waitReady proxy
- Use Promise.withResolvers throughout
- Add integration tests for session lifecycle and lease signals
- Add e2e tests for race conditions, misuse, and typed error contracts
- Update docs and README with error classes documentation

Author: polRk

.changeset/refactor-coordination-signals.md

@@ -0,0 +1,18 @@
+---
+'@ydbjs/coordination': minor
+---
+
+Refactor coordination session architecture and signal contracts
+
+- Clean up file structure: delete dead files (session-stream, session-utils), merge node-runtime into node.ts, move try-acquire to errors.ts, move transport FSM into session-state.ts
+- Fix signal ownership: session owns its own AbortController (not delegated to transport), lease owns its own AbortController (not linked to session)
+- Add typed error classes: SessionClosedError, SessionExpiredError, LeaseReleasedError, LeaderChangedError, ObservationEndedError — all exported for instanceof checks
+- Simplify Lease: single #releasePromise pattern, delegates release to Semaphore.release()
+- Simplify Mutex: Lock is now a type alias for Lease (was empty subclass)
+- Simplify Election: accepts Semaphore directly (no longer knows about transport)
+- Move client to SessionTransport constructor (was passed on every connect)
+- Remove emit_error effect (redundant with mark_expired)
+- Remove waitReady proxy from SessionRuntime (use transport.waitReady directly)
+- Use Promise.withResolvers throughout (project convention)
+- Add integration tests for session lifecycle, lease signals, and user signal cancellation
+- Add e2e tests for race conditions, misuse scenarios, and typed error contracts

docs/advanced/errors.md

@@ -12,6 +12,15 @@ This guide outlines error classes and handling patterns used by the SDK.
 - `CommitError` — commit failed; exposes `retryable(idempotent)`.
 - `ClientError` — gRPC client-side error (e.g., `UNAVAILABLE`).
 
+### Coordination errors (`@ydbjs/coordination`)
+
+- `SessionClosedError` — session was closed gracefully or destroyed.
+- `SessionExpiredError` — recovery window expired, server dropped the session.
+- `LeaseReleasedError` — semaphore lease was released (found in `lease.signal.reason`).
+- `LeaderChangedError` — leader changed during `observe()` (found in `LeaderState.signal.reason`).
+- `ObservationEndedError` — the `observe()` iterator finished.
+- `TryAcquireMissError` — non-blocking acquire found no available tokens (internal).
+
 Use `instanceof` checks to branch logic.
 
 ```ts

docs/guide/coordination/index.md

@@ -105,8 +105,7 @@ await using _ = lock
 await doWork(lock.signal)
 ```
 
-`lock.signal` aborts when the lock is lost (e.g. session expired), so you can pass it to
-downstream operations to have them cancel automatically.
+`lock.signal` aborts when the lock is released. Use `session.signal` to detect session death.
 
 ## Semaphore
 

docs/ru/advanced/errors.md

@@ -12,6 +12,15 @@ title: Обработка ошибок
 - `CommitError` — неудачный коммит; содержит `retryable(idempotent)`.
 - `ClientError` — gRPC‑ошибка на стороне клиента (например, `UNAVAILABLE`).
 
+### Ошибки координации (`@ydbjs/coordination`)
+
+- `SessionClosedError` — сессия закрыта штатно или уничтожена.
+- `SessionExpiredError` — окно восстановления истекло, сервер удалил сессию.
+- `LeaseReleasedError` — аренда семафора освобождена (в `lease.signal.reason`).
+- `LeaderChangedError` — лидер сменился во время `observe()` (в `LeaderState.signal.reason`).
+- `ObservationEndedError` — итератор `observe()` завершился.
+- `TryAcquireMissError` — неблокирующий захват не нашёл свободных токенов (внутренняя).
+
 Используйте `instanceof` для ветвления логики.
 
 ```ts

docs/ru/guide/coordination/index.md

@@ -105,7 +105,7 @@ await using _ = lock
 await doWork(lock.signal)
 ```
 
-`lock.signal` прерывается при потере блокировки (например, при истечении сессии), поэтому
+`lock.signal` прерывается при освобождении блокировки. Используйте `session.signal` для обнаружения смерти сессии. Поэтому
 его можно передавать в нижележащие операции для их автоматической отмены.
 
 ## Семафор

e2e/coordination/election.test.ts

@@ -1,7 +1,12 @@
 import { beforeEach, expect, inject, onTestFinished, test } from 'vitest'
 
 import { Driver } from '@ydbjs/core'
-import { CoordinationClient, type CoordinationSession } from '@ydbjs/coordination'
+import {
+	CoordinationClient,
+	type CoordinationSession,
+	LeaderChangedError,
+	LeaseReleasedError,
+} from '@ydbjs/coordination'
 
 // #region setup
 declare module 'vitest' {
@@ -306,4 +311,59 @@ test('leader state signal aborts when the leader changes', async () => {
 
 	expect(capturedSignal).toBeDefined()
 	expect(capturedSignal!.aborted).toBe(true)
+	expect(capturedSignal!.reason).toBeInstanceOf(LeaderChangedError)
+})
+
+test('leadership.signal.reason is LeaseReleasedError after resign', async () => {
+	let election = sessionA.election(electionName)
+
+	let leadership = await election.campaign(Buffer.from('A'), AbortSignal.timeout(5000))
+	await leadership.resign(AbortSignal.timeout(5000))
+
+	expect(leadership.signal.reason).toBeInstanceOf(LeaseReleasedError)
+})
+
+test('double resign is idempotent', async () => {
+	let election = sessionA.election(electionName)
+
+	let leadership = await election.campaign(Buffer.from('A'), AbortSignal.timeout(5000))
+	await leadership.resign(AbortSignal.timeout(5000))
+	await expect(leadership.resign(AbortSignal.timeout(5000))).resolves.toBeUndefined()
+})
+
+test('N sessions race for leadership — exactly one wins', async () => {
+	let N = 4
+
+	let sessions: CoordinationSession[] = []
+	for (let i = 0; i < N; i++) {
+		// oxlint-disable-next-line no-await-in-loop
+		sessions.push(await client.createSession(testNodePath, {}, AbortSignal.timeout(5000)))
+	}
+
+	try {
+		// All sessions campaign simultaneously with short timeout
+		let results = await Promise.allSettled(
+			sessions.map((s) =>
+				s
+					.election(electionName)
+					.campaign(Buffer.from(`c${s.sessionId}`), AbortSignal.timeout(3000))
+			)
+		)
+
+		let winners = results.filter((r) => r.status === 'fulfilled')
+
+		// Exactly one should have won within the timeout
+		expect(winners.length).toBeGreaterThanOrEqual(1)
+
+		// Clean up — resign all winners
+		for (let r of winners) {
+			// oxlint-disable-next-line no-await-in-loop
+			await (r as PromiseFulfilledResult<any>).value.resign(AbortSignal.timeout(5000))
+		}
+	} finally {
+		for (let s of sessions) {
+			// oxlint-disable-next-line no-await-in-loop
+			await s.close(AbortSignal.timeout(5000)).catch(() => {})
+		}
+	}
 })

e2e/coordination/mutex.test.ts

@@ -1,7 +1,7 @@
 import { beforeEach, expect, inject, onTestFinished, test } from 'vitest'
 
 import { Driver } from '@ydbjs/core'
-import { CoordinationClient, Lock } from '@ydbjs/coordination'
+import { CoordinationClient, Lease } from '@ydbjs/coordination'
 import type { CoordinationSession } from '@ydbjs/coordination'
 
 // #region setup
@@ -45,7 +45,7 @@ test('lock acquires exclusive access', async () => {
 
 	let lock = await mutex.lock(AbortSignal.timeout(5000))
 
-	expect(lock).toBeInstanceOf(Lock)
+	expect(lock).toBeInstanceOf(Lease)
 	// Signal must be alive while the lock is held
 	expect(lock.signal.aborted).toBe(false)
 
@@ -66,7 +66,7 @@ test('async dispose releases the lock', async () => {
 	// verifies that dispose does not throw — that is the core contract.
 	// A second lock attempt proves the mutex is free again.
 	let lock2 = await mutex.lock(AbortSignal.timeout(5000))
-	expect(lock2).toBeInstanceOf(Lock)
+	expect(lock2).toBeInstanceOf(Lease)
 	await lock2.release(AbortSignal.timeout(5000))
 })
 
@@ -90,7 +90,7 @@ test('second lock blocks until first is released', async () => {
 
 	await using lockB = await acquireB
 
-	expect(lockB).toBeInstanceOf(Lock)
+	expect(lockB).toBeInstanceOf(Lease)
 	expect(lockB.signal.aborted).toBe(false)
 })
 
@@ -100,7 +100,7 @@ test('tryLock succeeds when mutex is free', async () => {
 	let lock = await mutex.tryLock(AbortSignal.timeout(5000))
 
 	expect(lock).not.toBeNull()
-	expect(lock).toBeInstanceOf(Lock)
+	expect(lock).toBeInstanceOf(Lease)
 
 	await lock!.release(AbortSignal.timeout(5000))
 })

e2e/coordination/node.test.ts

@@ -1,7 +1,7 @@
 import { beforeEach, expect, inject, onTestFinished, test } from 'vitest'
 
 import { Driver } from '@ydbjs/core'
-import { CoordinationClient } from '@ydbjs/coordination'
+import { CoordinationClient, SessionClosedError } from '@ydbjs/coordination'
 
 // #region setup
 declare module 'vitest' {
@@ -122,3 +122,26 @@ test('createSession rejects when signal is already aborted', async () => {
 
 	await expect(client.createSession(testNodePath, {}, aborted)).rejects.toThrow('pre-aborted')
 })
+
+test('session.signal.reason is SessionClosedError after close', async () => {
+	await client.createNode(testNodePath, {}, AbortSignal.timeout(5000))
+
+	let session = await client.createSession(testNodePath, {}, AbortSignal.timeout(5000))
+	await session.close(AbortSignal.timeout(5000))
+
+	expect(session.signal.aborted).toBe(true)
+	expect(session.signal.reason).toBeInstanceOf(SessionClosedError)
+})
+
+test('session.signal carries custom reason after destroy', async () => {
+	await client.createNode(testNodePath, {}, AbortSignal.timeout(5000))
+
+	let session = await client.createSession(testNodePath, {}, AbortSignal.timeout(5000))
+	let reason = new Error('custom destroy reason')
+	session.destroy(reason)
+
+	await new Promise((r) => setTimeout(r, 100))
+
+	expect(session.signal.aborted).toBe(true)
+	expect(session.signal.reason).toBe(reason)
+})