@planet-matrix/mobius-model 0.5.0 → 0.9.0

package/tests/unit/openai/openai.spec.ts

@@ -0,0 +1,64 @@
+import { expect, test } from "vitest"
+
+import { streamConsumeInMacroTask } from "#Source/basic/index.ts"
+import { eitherToTuple } from "#Source/result/index.ts"
+import { tubeToReadableStream } from "#Source/tube/index.ts"
+import { Openai } from "#Source/openai/index.ts"
+
+const testApiKey = "sk-DLj8aHvKjvHfZ7IHA2F07c968c3d4aE491C1525e40E24932"
+const testBaseUrl = "https://cn.api.openai-next.com/v1/"
+const openai = new Openai({
+  apiKey: testApiKey,
+  baseUrl: testBaseUrl,
+})
+
+test("customEmbedding ", { timeout: 60_000 }, async () => {
+  const embedding = await openai.customEmbedding({
+    input: "床前明月光，疑是地上霜。举头望明月，低头思故乡。",
+  })
+  const [left, right] = eitherToTuple(embedding)
+  if (left !== undefined) {
+    throw new Error(`请求失败: ${JSON.stringify(left)}`)
+  }
+  const resultLength = right.embedding.length
+  expect(resultLength).toBe(1_536)
+})
+
+test("customChatCompletion ", { timeout: 60_000 }, async () => {
+  const nonStreamingResult = await openai.customChatCompletionNonStreaming({
+    model: "gpt-4o-mini",
+    messages: [
+      { role: "system", content: "你是讲故事大王。" },
+      { role: "user", content: "讲一个小红帽吃掉大灰狼的故事。" },
+    ],
+  })
+  const [left, right] = eitherToTuple(nonStreamingResult)
+  if (left !== undefined) {
+    throw new Error(`请求失败: ${JSON.stringify(left)}`)
+  }
+  const contentLength = right.content.length
+  expect(contentLength).toBeGreaterThan(0)
+})
+
+test("customChatCompletionStreaming ", { timeout: 60_000 }, async () => {
+  const [left, right] = eitherToTuple(await openai.customChatCompletionStreaming({
+    model: "gpt-4o-mini",
+    messages: [
+      { role: "system", content: "你是讲故事大王。" },
+      { role: "user", content: "讲一个小红帽吃掉大灰狼的故事。" },
+    ],
+  }))
+  if (left !== undefined) {
+    throw new Error(`请求失败: ${JSON.stringify(left)}`)
+  }
+  else {
+    const stream = tubeToReadableStream(right.completionTube)
+    streamConsumeInMacroTask({
+      readableStream: stream,
+      onValue: (chunk) => {
+        console.log(JSON.stringify(chunk.content.total, null, 2))
+        // process.stdout.write()
+      },
+    })
+  }
+})

package/tests/unit/orchestration/coordination/barrier.spec.ts

@@ -0,0 +1,96 @@
+import { afterEach, expect, test, vi } from "vitest"
+
+import { Barrier, BrokenBarrierError, CoordinationAbortError, CoordinationTimeoutError } from "#Source/orchestration/index.ts"
+
+const getRejectedReason = async (promise: Promise<unknown>): Promise<unknown> => {
+  try {
+    await promise
+  }
+  catch (error: unknown) {
+    return error
+  }
+
+  throw new Error("Expected promise to reject.")
+}
+
+afterEach(() => {
+  vi.clearAllTimers()
+  vi.useRealTimers()
+})
+
+test("Barrier completes generations and can be reused", async () => {
+  const barrier = new Barrier(2)
+  const firstGenerationWait = barrier.signalAndWait()
+
+  expect(barrier.getParticipantCount()).toBe(2)
+  expect(barrier.getGeneration()).toBe(0)
+  expect(barrier.getPendingCount()).toBe(1)
+  expect(barrier.getRemainingCount()).toBe(1)
+
+  const secondArrivalGeneration = await barrier.signalAndWait()
+  const firstArrivalGeneration = await firstGenerationWait
+
+  expect(firstArrivalGeneration).toBe(0)
+  expect(secondArrivalGeneration).toBe(0)
+  expect(barrier.getGeneration()).toBe(1)
+  expect(barrier.getPendingCount()).toBe(0)
+  expect(barrier.getRemainingCount()).toBe(2)
+
+  const thirdArrivalGenerationPromise = barrier.signalAndWait()
+  const fourthArrivalGeneration = await barrier.signalAndWait()
+
+  expect(await thirdArrivalGenerationPromise).toBe(1)
+  expect(fourthArrivalGeneration).toBe(1)
+  expect(barrier.getGeneration()).toBe(2)
+})
+
+test("Barrier timeout breaks the current generation for all waiting participants", async () => {
+  vi.useFakeTimers()
+
+  const barrier = new Barrier(3)
+  const firstWait = barrier.signalAndWait()
+  const secondWait = barrier.signalAndWait({ timeout: 25 })
+
+  expect(barrier.getPendingCount()).toBe(2)
+  expect(barrier.getRemainingCount()).toBe(1)
+
+  await vi.advanceTimersByTimeAsync(25)
+
+  const timeoutError = await getRejectedReason(secondWait)
+  const brokenError = await getRejectedReason(firstWait)
+
+  expect(timeoutError).toBeInstanceOf(CoordinationTimeoutError)
+  expect(brokenError).toBeInstanceOf(BrokenBarrierError)
+
+  if (!(brokenError instanceof BrokenBarrierError)) {
+    throw new Error("Expected brokenError to be an instance of BrokenBarrierError.")
+  }
+
+  expect(brokenError.reason).toBe(timeoutError)
+  expect(barrier.getGeneration()).toBe(1)
+  expect(barrier.getPendingCount()).toBe(0)
+  expect(barrier.getRemainingCount()).toBe(3)
+})
+
+test("Barrier abort rejects the failing participant and breaks peers", async () => {
+  const barrier = new Barrier(3)
+  const abortController = new AbortController()
+  const firstWait = barrier.signalAndWait()
+  const secondWait = barrier.signalAndWait({ abortSignal: abortController.signal })
+
+  abortController.abort("cancelled")
+
+  const abortError = await getRejectedReason(secondWait)
+  const brokenError = await getRejectedReason(firstWait)
+
+  expect(abortError).toBeInstanceOf(CoordinationAbortError)
+  expect(brokenError).toBeInstanceOf(BrokenBarrierError)
+
+  if (!(brokenError instanceof BrokenBarrierError)) {
+    throw new Error("Expected brokenError to be an instance of BrokenBarrierError.")
+  }
+
+  expect(brokenError.reason).toBe(abortError)
+  expect(barrier.getGeneration()).toBe(1)
+  expect(barrier.getPendingCount()).toBe(0)
+})

package/tests/unit/orchestration/coordination/count-down-latch.spec.ts

@@ -0,0 +1,63 @@
+import { afterEach, expect, test, vi } from "vitest"
+
+import { CoordinationAbortError, CoordinationTimeoutError, CountDownLatch } from "#Source/orchestration/index.ts"
+
+afterEach(() => {
+  vi.clearAllTimers()
+  vi.useRealTimers()
+})
+
+test("CountDownLatch opens when the count reaches zero and resolves waiters", async () => {
+  const countDownLatch = new CountDownLatch(2)
+  const firstWait = countDownLatch.wait()
+  const secondWait = countDownLatch.wait()
+
+  expect(countDownLatch.isOpen()).toBe(false)
+  expect(countDownLatch.tryWait()).toBe(false)
+  expect(countDownLatch.getRemainingCount()).toBe(2)
+  expect(countDownLatch.getPendingCount()).toBe(2)
+
+  expect(countDownLatch.countDown()).toBe(1)
+  expect(countDownLatch.arrive()).toBe(0)
+
+  await Promise.all([firstWait, secondWait])
+
+  expect(countDownLatch.isOpen()).toBe(true)
+  expect(countDownLatch.tryWait()).toBe(true)
+  expect(countDownLatch.getRemainingCount()).toBe(0)
+  expect(countDownLatch.getPendingCount()).toBe(0)
+  await expect(countDownLatch.wait()).resolves.toBeUndefined()
+})
+
+test("CountDownLatch wait rejects on timeout and abort without leaking pending entries", async () => {
+  vi.useFakeTimers()
+
+  const countDownLatch = new CountDownLatch(1)
+  const timeoutPromise = countDownLatch.wait({ timeout: 30 })
+
+  expect(countDownLatch.getPendingCount()).toBe(1)
+
+  await vi.advanceTimersByTimeAsync(30)
+
+  await expect(timeoutPromise).rejects.toBeInstanceOf(CoordinationTimeoutError)
+  expect(countDownLatch.getPendingCount()).toBe(0)
+
+  const abortController = new AbortController()
+  const abortPromise = countDownLatch.wait({ abortSignal: abortController.signal })
+
+  expect(countDownLatch.getPendingCount()).toBe(1)
+
+  abortController.abort("cancelled")
+
+  await expect(abortPromise).rejects.toBeInstanceOf(CoordinationAbortError)
+  expect(countDownLatch.getPendingCount()).toBe(0)
+})
+
+test("CountDownLatch ignores further countdowns after opening", () => {
+  const countDownLatch = new CountDownLatch(1)
+
+  expect(countDownLatch.countDown()).toBe(0)
+  expect(countDownLatch.countDown()).toBe(0)
+  expect(countDownLatch.arrive()).toBe(0)
+  expect(countDownLatch.isOpen()).toBe(true)
+})

package/tests/unit/orchestration/coordination/errors.spec.ts

@@ -0,0 +1,29 @@
+import { expect, test } from "vitest"
+
+import { BrokenBarrierError, CoordinationAbortError, CoordinationTimeoutError } from "#Source/orchestration/index.ts"
+
+test("CoordinationAbortError stores operation, reason and formatted message", () => {
+  const error = new CoordinationAbortError("Mutex acquire", "cancelled")
+
+  expect(error.name).toBe("CoordinationAbortError")
+  expect(error.operation).toBe("Mutex acquire")
+  expect(error.reason).toBe("cancelled")
+  expect(error.message).toBe("Mutex acquire aborted. cancelled")
+})
+
+test("CoordinationTimeoutError stores operation, timeout and formatted message", () => {
+  const error = new CoordinationTimeoutError("Semaphore acquire", 25)
+
+  expect(error.name).toBe("CoordinationTimeoutError")
+  expect(error.operation).toBe("Semaphore acquire")
+  expect(error.timeout).toBe(25)
+  expect(error.message).toBe("Semaphore acquire timeout after 25ms.")
+})
+
+test("BrokenBarrierError stores reason and formatted message", () => {
+  const error = new BrokenBarrierError("peer aborted")
+
+  expect(error.name).toBe("BrokenBarrierError")
+  expect(error.reason).toBe("peer aborted")
+  expect(error.message).toBe("Barrier generation was broken by another participant. peer aborted")
+})

package/tests/unit/orchestration/coordination/keyed-lock.spec.ts

@@ -0,0 +1,109 @@
+import { expect, test, vi } from "vitest"
+
+import { CoordinationAbortError, KeyedLock } from "#Source/orchestration/index.ts"
+
+test("KeyedLock isolates different keys and cleans state after release", () => {
+  const keyedLock = new KeyedLock<string>()
+
+  expect(keyedLock.getKeyCount()).toBe(0)
+  expect(keyedLock.hasKey("alpha")).toBe(false)
+
+  const alphaPermit = keyedLock.tryAcquire("alpha")
+  const betaPermit = keyedLock.tryAcquire("beta")
+
+  expect(alphaPermit?.details).toEqual({ coordination: "keyed-lock", key: "alpha" })
+  expect(betaPermit?.details).toEqual({ coordination: "keyed-lock", key: "beta" })
+  expect(keyedLock.tryAcquire("alpha")).toBeUndefined()
+  expect(keyedLock.hasKey("alpha")).toBe(true)
+  expect(keyedLock.hasKey("beta")).toBe(true)
+  expect(keyedLock.getKeyCount()).toBe(2)
+
+  alphaPermit?.release()
+  betaPermit?.release()
+
+  expect(keyedLock.hasKey("alpha")).toBe(false)
+  expect(keyedLock.hasKey("beta")).toBe(false)
+  expect(keyedLock.getKeyCount()).toBe(0)
+})
+
+test("KeyedLock acquire cleans aborted waiters and releases state when idle", async () => {
+  const keyedLock = new KeyedLock<string>()
+  const blockingPermit = keyedLock.tryAcquire("alpha")
+  const abortController = new AbortController()
+
+  expect(blockingPermit).toBeDefined()
+
+  const waitingPermitPromise = keyedLock.acquire("alpha", { abortSignal: abortController.signal })
+
+  expect(keyedLock.hasKey("alpha")).toBe(true)
+  expect(keyedLock.getKeyCount()).toBe(1)
+
+  abortController.abort("cancelled")
+
+  await expect(waitingPermitPromise).rejects.toBeInstanceOf(CoordinationAbortError)
+
+  expect(keyedLock.hasKey("alpha")).toBe(true)
+
+  blockingPermit?.release()
+
+  expect(keyedLock.hasKey("alpha")).toBe(false)
+  expect(keyedLock.getKeyCount()).toBe(0)
+})
+
+test("KeyedLock runExclusive serializes callbacks for the same key", async () => {
+  const keyedLock = new KeyedLock<string>()
+  let activeCount = 0
+  let peakCount = 0
+
+  await Promise.all([
+    keyedLock.runExclusive("alpha", async () => {
+      activeCount = activeCount + 1
+      peakCount = Math.max(peakCount, activeCount)
+      await Promise.resolve()
+      activeCount = activeCount - 1
+    }),
+    keyedLock.runExclusive("alpha", async () => {
+      activeCount = activeCount + 1
+      peakCount = Math.max(peakCount, activeCount)
+      await Promise.resolve()
+      activeCount = activeCount - 1
+    }),
+  ])
+
+  expect(peakCount).toBe(1)
+  expect(keyedLock.hasKey("alpha")).toBe(false)
+})
+
+test("KeyedLock duplicate release stays silent by default and uses custom handler when provided", () => {
+  const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {
+    // no-op to silence warnings during test
+  })
+  const silentKeyedLock = new KeyedLock<string>()
+  const silentPermit = silentKeyedLock.tryAcquire("alpha")
+
+  expect(silentPermit).toBeDefined()
+
+  silentPermit?.release()
+  silentPermit?.release()
+  silentPermit?.release()
+
+  expect(silentKeyedLock.hasKey("alpha")).toBe(false)
+  expect(warnSpy).not.toHaveBeenCalled()
+
+  const onDuplicateRelease = vi.fn()
+  const customKeyedLock = new KeyedLock<string>({ onDuplicateRelease })
+  const customPermit = customKeyedLock.tryAcquire("alpha")
+
+  expect(customPermit).toBeDefined()
+
+  customPermit?.release()
+  customPermit?.release()
+  customPermit?.release()
+
+  expect(customKeyedLock.hasKey("alpha")).toBe(false)
+  expect(onDuplicateRelease).toHaveBeenCalledTimes(2)
+  expect(onDuplicateRelease).toHaveBeenCalledWith("KeyedLock permit release was called more than once.")
+  expect(warnSpy).not.toHaveBeenCalled()
+
+  warnSpy.mockRestore()
+})

package/tests/unit/orchestration/coordination/mutex.spec.ts

@@ -0,0 +1,132 @@
+import { afterEach, expect, test, vi } from "vitest"
+
+import { CoordinationAbortError, CoordinationTimeoutError, Mutex } from "#Source/orchestration/index.ts"
+
+afterEach(() => {
+  vi.clearAllTimers()
+  vi.useRealTimers()
+  vi.restoreAllMocks()
+})
+
+test("Mutex reports lock state and wakes queued acquirers in FIFO order", async () => {
+  const mutex = new Mutex()
+
+  expect(mutex.isLocked()).toBe(false)
+  expect(mutex.getPendingCount()).toBe(0)
+
+  const firstPermit = mutex.tryAcquire()
+
+  expect(firstPermit).toBeDefined()
+  expect(mutex.isLocked()).toBe(true)
+
+  const secondPermitPromise = mutex.acquire()
+  const thirdPermitPromise = mutex.acquire()
+
+  expect(mutex.getPendingCount()).toBe(2)
+  expect(mutex.tryAcquire()).toBeUndefined()
+
+  firstPermit?.release()
+
+  const secondPermit = await secondPermitPromise
+  let thirdResolved = false
+  void thirdPermitPromise.then(() => {
+    thirdResolved = true
+  })
+
+  await Promise.resolve()
+
+  expect(mutex.isLocked()).toBe(true)
+  expect(mutex.getPendingCount()).toBe(1)
+  expect(thirdResolved).toBe(false)
+
+  secondPermit.release()
+
+  const thirdPermit = await thirdPermitPromise
+
+  expect(mutex.getPendingCount()).toBe(0)
+  expect(mutex.isLocked()).toBe(true)
+
+  thirdPermit.release()
+
+  expect(mutex.isLocked()).toBe(false)
+})
+
+test("Mutex acquire rejects on timeout and abort while cleaning pending state", async () => {
+  vi.useFakeTimers()
+
+  const mutex = new Mutex()
+  const blockingPermit = mutex.tryAcquire()
+
+  expect(blockingPermit).toBeDefined()
+
+  const timeoutPromise = mutex.acquire({ timeout: 10 })
+
+  expect(mutex.getPendingCount()).toBe(1)
+
+  await vi.advanceTimersByTimeAsync(10)
+
+  await expect(timeoutPromise).rejects.toBeInstanceOf(CoordinationTimeoutError)
+  expect(mutex.getPendingCount()).toBe(0)
+
+  const abortController = new AbortController()
+  const abortPromise = mutex.acquire({ abortSignal: abortController.signal })
+
+  expect(mutex.getPendingCount()).toBe(1)
+
+  abortController.abort("cancelled")
+
+  await expect(abortPromise).rejects.toBeInstanceOf(CoordinationAbortError)
+  expect(mutex.getPendingCount()).toBe(0)
+
+  blockingPermit?.release()
+})
+
+test("Mutex runExclusive releases the lock after callback success or failure", async () => {
+  const mutex = new Mutex()
+
+  await expect(mutex.runExclusive(() => "done")).resolves.toBe("done")
+  expect(mutex.isLocked()).toBe(false)
+
+  const error = new Error("boom")
+
+  await expect(mutex.runExclusive(() => {
+    throw error
+  })).rejects.toThrow(error)
+
+  expect(mutex.isLocked()).toBe(false)
+})
+
+test("Mutex is silent by default when release is called more than once", () => {
+  const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {
+    // no-op to silence warnings during test
+  })
+  const mutex = new Mutex()
+
+  const permit = mutex.tryAcquire()
+  expect(permit).toBeDefined()
+
+  permit?.release()
+  permit?.release()
+  permit?.release()
+
+  expect(warnSpy).not.toHaveBeenCalled()
+})
+
+test("Mutex uses custom duplicate-release handler when provided", () => {
+  const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {
+    // no-op to silence warnings during test
+  })
+  const onDuplicateRelease = vi.fn()
+  const mutex = new Mutex({ onDuplicateRelease })
+
+  const permit = mutex.tryAcquire()
+  expect(permit).toBeDefined()
+
+  permit?.release()
+  permit?.release()
+  permit?.release()
+
+  expect(onDuplicateRelease).toHaveBeenCalledTimes(2)
+  expect(onDuplicateRelease).toHaveBeenCalledWith("Mutex permit release was called more than once.")
+  expect(warnSpy).not.toHaveBeenCalled()
+})

package/tests/unit/orchestration/coordination/permit.spec.ts

@@ -0,0 +1,43 @@
+import { expect, test, vi } from "vitest"
+
+import { Permit } from "#Source/orchestration/index.ts"
+
+test("Permit release updates lifecycle state and only calls handlers once", () => {
+  const onRelease = vi.fn()
+  const onDuplicateRelease = vi.fn()
+  const permit = new Permit({
+    details: { coordination: "custom" },
+    duplicateReleaseMessage: "duplicate release",
+    onDuplicateRelease,
+    onRelease,
+  })
+
+  expect(permit.details).toEqual({ coordination: "custom" })
+  expect(permit.isActive()).toBe(true)
+  expect(permit.isReleased()).toBe(false)
+
+  permit.release()
+
+  expect(onRelease).toHaveBeenCalledTimes(1)
+  expect(permit.isActive()).toBe(false)
+  expect(permit.isReleased()).toBe(true)
+
+  permit.release()
+
+  expect(onDuplicateRelease).toHaveBeenCalledTimes(1)
+  expect(onDuplicateRelease).toHaveBeenCalledWith("duplicate release")
+  expect(onRelease).toHaveBeenCalledTimes(1)
+})
+
+test("Permit dispose and Symbol.dispose delegate to release", () => {
+  const onRelease = vi.fn()
+  const onDuplicateRelease = vi.fn()
+  const permit = new Permit({ onDuplicateRelease, onRelease })
+
+  permit.dispose()
+  permit[Symbol.dispose]()
+
+  expect(onRelease).toHaveBeenCalledTimes(1)
+  expect(onDuplicateRelease).toHaveBeenCalledTimes(1)
+  expect(permit.isReleased()).toBe(true)
+})

package/tests/unit/orchestration/coordination/read-write-lock.spec.ts

@@ -0,0 +1,154 @@
+import { afterEach, expect, test, vi } from "vitest"
+
+import { CoordinationAbortError, CoordinationTimeoutError, ReadWriteLock } from "#Source/orchestration/index.ts"
+
+afterEach(() => {
+  vi.clearAllTimers()
+  vi.useRealTimers()
+  vi.restoreAllMocks()
+})
+
+test("ReadWriteLock tracks reader and writer state across immediate acquisitions", () => {
+  const readWriteLock = new ReadWriteLock()
+
+  expect(readWriteLock.isLocked()).toBe(false)
+  expect(readWriteLock.isReadLocked()).toBe(false)
+  expect(readWriteLock.isWriteLocked()).toBe(false)
+
+  const firstReader = readWriteLock.tryAcquireRead()
+  const secondReader = readWriteLock.tryAcquireRead()
+
+  expect(firstReader?.details).toEqual({ coordination: "read-write-lock", mode: "read" })
+  expect(secondReader?.details).toEqual({ coordination: "read-write-lock", mode: "read" })
+  expect(readWriteLock.getActiveReaderCount()).toBe(2)
+  expect(readWriteLock.isReadLocked()).toBe(true)
+  expect(readWriteLock.tryAcquireWrite()).toBeUndefined()
+
+  firstReader?.release()
+  secondReader?.release()
+
+  const writer = readWriteLock.tryAcquireWrite()
+
+  expect(writer?.details).toEqual({ coordination: "read-write-lock", mode: "write" })
+  expect(readWriteLock.isWriteLocked()).toBe(true)
+  expect(readWriteLock.isLocked()).toBe(true)
+
+  writer?.release()
+
+  expect(readWriteLock.isLocked()).toBe(false)
+})
+
+test("ReadWriteLock keeps queued writers ahead of later readers", async () => {
+  const readWriteLock = new ReadWriteLock()
+  const activeReader = readWriteLock.tryAcquireRead()
+
+  expect(activeReader).toBeDefined()
+
+  const writerPromise = readWriteLock.acquireWrite()
+  const lateReaderPromise = readWriteLock.acquireRead()
+
+  expect(readWriteLock.getPendingWriterCount()).toBe(1)
+  expect(readWriteLock.getPendingReaderCount()).toBe(1)
+  expect(readWriteLock.getPendingCount()).toBe(2)
+
+  activeReader?.release()
+
+  const writer = await writerPromise
+  let lateReaderResolved = false
+  void lateReaderPromise.then(() => {
+    lateReaderResolved = true
+  })
+
+  await Promise.resolve()
+
+  expect(readWriteLock.isWriteLocked()).toBe(true)
+  expect(lateReaderResolved).toBe(false)
+
+  writer.release()
+
+  const lateReader = await lateReaderPromise
+
+  expect(readWriteLock.getPendingCount()).toBe(0)
+  expect(readWriteLock.getActiveReaderCount()).toBe(1)
+
+  lateReader.release()
+
+  expect(readWriteLock.isLocked()).toBe(false)
+})
+
+test("ReadWriteLock acquire methods reject on timeout and abort without leaking counts", async () => {
+  vi.useFakeTimers()
+
+  const readWriteLock = new ReadWriteLock()
+  const writer = readWriteLock.tryAcquireWrite()
+
+  expect(writer).toBeDefined()
+
+  const timeoutPromise = readWriteLock.acquireRead({ timeout: 20 })
+
+  expect(readWriteLock.getPendingReaderCount()).toBe(1)
+
+  await vi.advanceTimersByTimeAsync(20)
+
+  await expect(timeoutPromise).rejects.toBeInstanceOf(CoordinationTimeoutError)
+  expect(readWriteLock.getPendingReaderCount()).toBe(0)
+
+  const abortController = new AbortController()
+  const abortPromise = readWriteLock.acquireWrite({ abortSignal: abortController.signal })
+
+  expect(readWriteLock.getPendingWriterCount()).toBe(1)
+
+  abortController.abort("cancelled")
+
+  await expect(abortPromise).rejects.toBeInstanceOf(CoordinationAbortError)
+  expect(readWriteLock.getPendingWriterCount()).toBe(0)
+
+  writer?.release()
+})
+
+test("ReadWriteLock runExclusive methods release permits after callback completion", async () => {
+  const readWriteLock = new ReadWriteLock()
+
+  await expect(readWriteLock.runExclusiveRead(() => "read")).resolves.toBe("read")
+  expect(readWriteLock.isLocked()).toBe(false)
+
+  const error = new Error("write failed")
+
+  await expect(readWriteLock.runExclusiveWrite(() => {
+    throw error
+  })).rejects.toThrow(error)
+
+  expect(readWriteLock.isLocked()).toBe(false)
+})
+
+test("ReadWriteLock duplicate release stays silent by default and uses custom handler when provided", () => {
+  const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {
+    // no-op to silence warnings during test
+  })
+  const silentReadWriteLock = new ReadWriteLock()
+  const silentPermit = silentReadWriteLock.tryAcquireWrite()
+
+  expect(silentPermit).toBeDefined()
+
+  silentPermit?.release()
+  silentPermit?.release()
+  silentPermit?.release()
+
+  expect(silentReadWriteLock.isLocked()).toBe(false)
+  expect(warnSpy).not.toHaveBeenCalled()
+
+  const onDuplicateRelease = vi.fn()
+  const customReadWriteLock = new ReadWriteLock({ onDuplicateRelease })
+  const customPermit = customReadWriteLock.tryAcquireRead()
+
+  expect(customPermit).toBeDefined()
+
+  customPermit?.release()
+  customPermit?.release()
+  customPermit?.release()
+
+  expect(customReadWriteLock.isLocked()).toBe(false)
+  expect(onDuplicateRelease).toHaveBeenCalledTimes(2)
+  expect(onDuplicateRelease).toHaveBeenCalledWith("ReadWriteLock permit release was called more than once.")
+  expect(warnSpy).not.toHaveBeenCalled()
+})