@namzu/sdk 0.4.2 → 0.4.3

package/src/bus/lock.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 1):
+ *
+ *   - `acquire(path, owner)` returns immediately when the file is
+ *     unlocked; creates a lock with `lockId = lock_<uuid>`,
+ *     `expiresAt = now + lockTimeoutMs`, emits `lock_acquired`.
+ *   - `acquire` on a file already held by the SAME owner is idempotent
+ *     — returns `{acquired: true, lock}` (the existing lock) and emits
+ *     nothing.
+ *   - `acquire` on a file held by a DIFFERENT owner emits `lock_denied`
+ *     and then polls at `LOCK_ACQUIRE_POLL_INTERVAL_MS` (100ms) intervals
+ *     until either the holder releases, the lock expires, or
+ *     `acquireTimeoutMs` elapses. No FIFO queue; retries race.
+ *   - When the holder releases before the deadline, the waiting acquire
+ *     succeeds on its next poll.
+ *   - When `acquireTimeoutMs` elapses, acquire returns
+ *     `{acquired: false, holder, filePath}` — holder is the current
+ *     lock holder's owner if the lock still exists, else empty string.
+ *   - `maxLocksPerAgent` blocks further acquisitions by the same owner.
+ *     The internal `tryAcquire` returns `{holder: owner}` (a
+ *     "yourself" sentinel) but the public `acquire()` swallows that and
+ *     keeps polling for `acquireTimeoutMs` (there's no short-circuit
+ *     for cap-exceeded). When the deadline expires and no lock exists
+ *     on the file, the final `holder` is `''` (empty `RunId`) because
+ *     the fallback reads `this.locks.get(filePath)?.owner ?? ''`.
+ *   - `release(path, owner)` deletes the lock + emits `lock_released`
+ *     when the current lock's owner matches; cleans up the per-owner
+ *     lock set (and prunes the set entry when it becomes empty).
+ *     Returns false without emitting when no lock or owner mismatch.
+ *   - `releaseAll(owner)` drops every lock owned by `owner`, emits
+ *     `lock_released` per lock, returns the count, and prunes the
+ *     per-owner set.
+ *   - `isLocked(path)` + `getHolder(path)` auto-expire any stale lock
+ *     they observe (and emit `lock_expired`) before returning the
+ *     current state.
+ *   - `expireStale()` sweeps every lock; expired ones are deleted and
+ *     emit `lock_expired`; returns the count.
+ *   - Re-acquiring a path after its lock expires succeeds and assigns
+ *     a FRESH `lockId` (the old id is never reused).
+ *   - Lock state is per-`RunId`; no tenant dimension (design.md §2.1
+ *     aspirational).
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import type { AgentBusEvent } from '../types/bus/index.js'
+import type { RunId } from '../types/ids/index.js'
+import type { Logger } from '../utils/logger.js'
+
+import { FileLockManager } from './lock.js'
+
+function makeLogger(): Logger {
+	const stub = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }
+	return { ...stub, child: vi.fn(() => ({ ...stub, child: vi.fn() })) } as unknown as Logger
+}
+
+function runId(n: number): RunId {
+	return `run_${n}` as RunId
+}
+
+function makeManager(
+	overrides: Partial<{
+		lockTimeoutMs: number
+		acquireTimeoutMs: number
+		maxLocksPerAgent: number
+	}> = {},
+) {
+	const events: AgentBusEvent[] = []
+	const mgr = new FileLockManager(makeLogger(), (e) => events.push(e), {
+		// short defaults keep acquire-retry tests under a second total
+		lockTimeoutMs: 60_000,
+		acquireTimeoutMs: 200,
+		maxLocksPerAgent: 10,
+		...overrides,
+	})
+	return { mgr, events }
+}
+
+describe('FileLockManager', () => {
+	afterEach(() => {
+		vi.useRealTimers()
+	})
+
+	describe('acquire (happy path)', () => {
+		it('acquires an unheld lock immediately + emits lock_acquired', async () => {
+			const { mgr, events } = makeManager()
+			const before = Date.now()
+			const result = await mgr.acquire('/tmp/a.txt', runId(1))
+			expect(result.acquired).toBe(true)
+			if (result.acquired) {
+				expect(result.lock.owner).toBe(runId(1))
+				expect(result.lock.filePath).toBe('/tmp/a.txt')
+				expect(result.lock.lockId).toMatch(/^lock_[0-9a-f-]+$/)
+				expect(result.lock.acquiredAt).toBeGreaterThanOrEqual(before)
+				expect(result.lock.expiresAt).toBeGreaterThan(result.lock.acquiredAt)
+			}
+			const acquired = events.filter((e) => e.type === 'lock_acquired')
+			expect(acquired).toHaveLength(1)
+		})
+
+		it('is idempotent for the same owner — returns the existing lock, emits nothing', async () => {
+			const { mgr, events } = makeManager()
+			const first = await mgr.acquire('/tmp/a.txt', runId(1))
+			events.length = 0
+			const second = await mgr.acquire('/tmp/a.txt', runId(1))
+			expect(second.acquired).toBe(true)
+			if (first.acquired && second.acquired) {
+				expect(second.lock.lockId).toBe(first.lock.lockId)
+			}
+			expect(events).toEqual([])
+		})
+	})
+
+	describe('acquire (contention)', () => {
+		it('emits lock_denied when another owner holds the lock and no release happens', async () => {
+			const { mgr, events } = makeManager({ acquireTimeoutMs: 120 })
+			await mgr.acquire('/tmp/a.txt', runId(1))
+			events.length = 0
+
+			const result = await mgr.acquire('/tmp/a.txt', runId(2))
+			expect(result.acquired).toBe(false)
+			if (!result.acquired) {
+				expect(result.holder).toBe(runId(1))
+				expect(result.filePath).toBe('/tmp/a.txt')
+			}
+			expect(events.some((e) => e.type === 'lock_denied')).toBe(true)
+		})
+
+		it('succeeds on a retry once the holder releases before the deadline', async () => {
+			const { mgr } = makeManager({ acquireTimeoutMs: 500 })
+			await mgr.acquire('/tmp/a.txt', runId(1))
+
+			const contender = mgr.acquire('/tmp/a.txt', runId(2))
+			setTimeout(() => mgr.release('/tmp/a.txt', runId(1)), 120)
+
+			const result = await contender
+			expect(result.acquired).toBe(true)
+			if (result.acquired) expect(result.lock.owner).toBe(runId(2))
+		})
+	})
+
+	describe('maxLocksPerAgent cap', () => {
+		it('denies a new acquisition when the owner is at cap — acquire polls to deadline then returns empty holder', async () => {
+			const { mgr } = makeManager({ maxLocksPerAgent: 2, acquireTimeoutMs: 60 })
+			await mgr.acquire('/tmp/a.txt', runId(1))
+			await mgr.acquire('/tmp/b.txt', runId(1))
+
+			const over = await mgr.acquire('/tmp/c.txt', runId(1))
+			expect(over.acquired).toBe(false)
+			if (!over.acquired) {
+				// No lock exists on /tmp/c.txt, so the fallback holder is ''.
+				expect(over.holder).toBe('' as RunId)
+				expect(over.filePath).toBe('/tmp/c.txt')
+			}
+		})
+	})
+
+	describe('release', () => {
+		it('releases an owned lock + emits lock_released', async () => {
+			const { mgr, events } = makeManager()
+			await mgr.acquire('/tmp/a.txt', runId(1))
+			events.length = 0
+
+			expect(mgr.release('/tmp/a.txt', runId(1))).toBe(true)
+			expect(mgr.isLocked('/tmp/a.txt')).toBe(false)
+			expect(events.some((e) => e.type === 'lock_released')).toBe(true)
+		})
+
+		it('returns false + emits nothing when the caller is not the holder', async () => {
+			const { mgr, events } = makeManager()
+			await mgr.acquire('/tmp/a.txt', runId(1))
+			events.length = 0
+
+			expect(mgr.release('/tmp/a.txt', runId(2))).toBe(false)
+			expect(mgr.isLocked('/tmp/a.txt')).toBe(true)
+			expect(events).toEqual([])
+		})
+
+		it('returns false when no lock exists', () => {
+			const { mgr, events } = makeManager()
+			expect(mgr.release('/tmp/never.txt', runId(1))).toBe(false)
+			expect(events).toEqual([])
+		})
+	})
+
+	describe('releaseAll', () => {
+		it('drops every lock owned by the runId, emits one event per lock, returns count', async () => {
+			const { mgr, events } = makeManager()
+			await mgr.acquire('/tmp/a.txt', runId(1))
+			await mgr.acquire('/tmp/b.txt', runId(1))
+			await mgr.acquire('/tmp/c.txt', runId(2))
+			events.length = 0
+
+			const count = mgr.releaseAll(runId(1))
+			expect(count).toBe(2)
+			expect(mgr.isLocked('/tmp/a.txt')).toBe(false)
+			expect(mgr.isLocked('/tmp/b.txt')).toBe(false)
+			expect(mgr.isLocked('/tmp/c.txt')).toBe(true)
+			expect(events.filter((e) => e.type === 'lock_released')).toHaveLength(2)
+		})
+
+		it('returns 0 when the owner has no locks', () => {
+			const { mgr } = makeManager()
+			expect(mgr.releaseAll(runId(99))).toBe(0)
+		})
+	})
+
+	describe('expiry', () => {
+		it('expireStale drops expired locks + emits lock_expired per drop', async () => {
+			vi.useFakeTimers()
+			const { mgr, events } = makeManager({ lockTimeoutMs: 10_000 })
+			await mgr.acquire('/tmp/a.txt', runId(1))
+			await mgr.acquire('/tmp/b.txt', runId(2))
+			events.length = 0
+
+			vi.advanceTimersByTime(10_001)
+			const expired = mgr.expireStale()
+			expect(expired).toBe(2)
+			expect(events.filter((e) => e.type === 'lock_expired')).toHaveLength(2)
+		})
+
+		it('isLocked / getHolder auto-expire a stale lock before answering', async () => {
+			vi.useFakeTimers()
+			const { mgr, events } = makeManager({ lockTimeoutMs: 5_000 })
+			await mgr.acquire('/tmp/a.txt', runId(1))
+
+			vi.advanceTimersByTime(5_001)
+			events.length = 0
+			expect(mgr.isLocked('/tmp/a.txt')).toBe(false)
+			expect(events.some((e) => e.type === 'lock_expired')).toBe(true)
+
+			events.length = 0
+			expect(mgr.getHolder('/tmp/a.txt')).toBeUndefined()
+			// already expired by the previous call; no second emit
+			expect(events).toEqual([])
+		})
+
+		it('a fresh acquire after expiry assigns a new lockId', async () => {
+			vi.useFakeTimers()
+			const { mgr } = makeManager({ lockTimeoutMs: 1_000 })
+			const first = await mgr.acquire('/tmp/a.txt', runId(1))
+			vi.advanceTimersByTime(1_001)
+			mgr.expireStale()
+
+			vi.useRealTimers()
+			const second = await mgr.acquire('/tmp/a.txt', runId(2))
+			expect(first.acquired && second.acquired).toBe(true)
+			if (first.acquired && second.acquired) {
+				expect(second.lock.lockId).not.toBe(first.lock.lockId)
+				expect(second.lock.owner).toBe(runId(2))
+			}
+		})
+	})
+
+	describe('per-runId isolation', () => {
+		it('different runIds can hold locks on different files concurrently', async () => {
+			const { mgr } = makeManager()
+			const a = await mgr.acquire('/tmp/a.txt', runId(1))
+			const b = await mgr.acquire('/tmp/b.txt', runId(2))
+			expect(a.acquired && b.acquired).toBe(true)
+			expect(mgr.getHolder('/tmp/a.txt')).toBe(runId(1))
+			expect(mgr.getHolder('/tmp/b.txt')).toBe(runId(2))
+		})
+	})
+})

package/src/bus/ownership.test.ts

@@ -0,0 +1,243 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 1):
+ *
+ *   - `claim(path, owner)` on an unowned file creates ownership, emits
+ *     `ownership_claimed`, returns `{claimed: true, ownership}`.
+ *   - `claim(path, owner)` by the same owner is idempotent — returns
+ *     `{claimed: true, ownership}` WITHOUT re-emitting.
+ *   - `claim(path, owner)` by a different owner is denied — emits
+ *     `ownership_denied`, returns `{claimed: false, currentOwner, filePath}`.
+ *   - `release(path, owner)` on the current owner deletes + emits; returns
+ *     true. On mismatch or missing entry: returns false; no emit.
+ *   - `transfer(path, from, to)` requires the current owner to equal
+ *     `from`. Success replaces the entry with a new `claimedAt`, emits
+ *     `ownership_transferred`; no intervening `ownership_released` or
+ *     `ownership_claimed` events. Failure returns false; no emit.
+ *   - `releaseAll(owner)` sweeps every ownership for `owner`, emits
+ *     `ownership_released` per entry, returns the count. Other owners'
+ *     entries are untouched.
+ *   - File paths are normalised via `path.resolve` before keying —
+ *     `./foo/bar` and the absolute resolution of the same path collide
+ *     into one ownership slot.
+ *   - Ownership is not per-tenant; only per-`RunId`. There is no tenant
+ *     isolation at this layer (design.md §2.1 aspirational; see §2.7).
+ */
+
+import path from 'node:path'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { AgentBusEvent } from '../types/bus/index.js'
+import type { RunId } from '../types/ids/index.js'
+import type { Logger } from '../utils/logger.js'
+
+import { EditOwnershipTracker } from './ownership.js'
+
+function makeLogger(): Logger {
+	const stub = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }
+	return { ...stub, child: vi.fn(() => ({ ...stub, child: vi.fn() })) } as unknown as Logger
+}
+
+function runId(n: number): RunId {
+	return `run_${n}` as RunId
+}
+
+describe('EditOwnershipTracker', () => {
+	let events: AgentBusEvent[]
+	let tracker: EditOwnershipTracker
+
+	beforeEach(() => {
+		events = []
+		tracker = new EditOwnershipTracker(makeLogger(), (e) => events.push(e))
+	})
+
+	describe('claim', () => {
+		it('claims an unowned file, emits ownership_claimed, returns ownership', () => {
+			const before = Date.now()
+			const result = tracker.claim('/tmp/file.txt', runId(1))
+			const after = Date.now()
+
+			expect(result.claimed).toBe(true)
+			if (result.claimed) {
+				expect(result.ownership.owner).toBe(runId(1))
+				expect(result.ownership.filePath).toBe(path.resolve('/tmp/file.txt'))
+				expect(result.ownership.claimedAt).toBeGreaterThanOrEqual(before)
+				expect(result.ownership.claimedAt).toBeLessThanOrEqual(after)
+			}
+			expect(events).toEqual([
+				{ type: 'ownership_claimed', filePath: path.resolve('/tmp/file.txt'), owner: runId(1) },
+			])
+		})
+
+		it('is idempotent when the same owner re-claims — no re-emit', () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			events.length = 0
+
+			const result = tracker.claim('/tmp/file.txt', runId(1))
+			expect(result.claimed).toBe(true)
+			expect(events).toEqual([])
+		})
+
+		it('denies a claim by a different owner, emits ownership_denied', () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			events.length = 0
+
+			const result = tracker.claim('/tmp/file.txt', runId(2))
+			expect(result.claimed).toBe(false)
+			if (!result.claimed) {
+				expect(result.currentOwner).toBe(runId(1))
+				expect(result.filePath).toBe(path.resolve('/tmp/file.txt'))
+			}
+			expect(events).toEqual([
+				{
+					type: 'ownership_denied',
+					filePath: path.resolve('/tmp/file.txt'),
+					requester: runId(2),
+					currentOwner: runId(1),
+				},
+			])
+		})
+
+		it('normalises file paths — equivalent paths collide', () => {
+			tracker.claim('/tmp/foo/../file.txt', runId(1))
+			const result = tracker.claim('/tmp/file.txt', runId(2))
+			expect(result.claimed).toBe(false)
+		})
+	})
+
+	describe('release', () => {
+		it('releases an owned file, emits ownership_released, returns true', () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			events.length = 0
+
+			const ok = tracker.release('/tmp/file.txt', runId(1))
+			expect(ok).toBe(true)
+			expect(tracker.getOwner('/tmp/file.txt')).toBeUndefined()
+			expect(events).toEqual([
+				{
+					type: 'ownership_released',
+					filePath: path.resolve('/tmp/file.txt'),
+					previousOwner: runId(1),
+				},
+			])
+		})
+
+		it('returns false when no ownership exists — no emit', () => {
+			const ok = tracker.release('/tmp/never-claimed.txt', runId(1))
+			expect(ok).toBe(false)
+			expect(events).toEqual([])
+		})
+
+		it('returns false when owner mismatches — no emit', () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			events.length = 0
+
+			const ok = tracker.release('/tmp/file.txt', runId(2))
+			expect(ok).toBe(false)
+			expect(tracker.getOwner('/tmp/file.txt')).toBe(runId(1))
+			expect(events).toEqual([])
+		})
+	})
+
+	describe('transfer', () => {
+		it('transfers ownership from current owner to another — atomic, single event', () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			events.length = 0
+
+			const ok = tracker.transfer('/tmp/file.txt', runId(1), runId(2))
+			expect(ok).toBe(true)
+			expect(tracker.getOwner('/tmp/file.txt')).toBe(runId(2))
+			expect(events).toEqual([
+				{
+					type: 'ownership_transferred',
+					filePath: path.resolve('/tmp/file.txt'),
+					from: runId(1),
+					to: runId(2),
+				},
+			])
+		})
+
+		it('returns false when the `from` argument is not the current owner — no emit', () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			events.length = 0
+
+			const ok = tracker.transfer('/tmp/file.txt', runId(99), runId(2))
+			expect(ok).toBe(false)
+			expect(tracker.getOwner('/tmp/file.txt')).toBe(runId(1))
+			expect(events).toEqual([])
+		})
+
+		it('returns false when no ownership exists — no emit', () => {
+			const ok = tracker.transfer('/tmp/file.txt', runId(1), runId(2))
+			expect(ok).toBe(false)
+			expect(events).toEqual([])
+		})
+
+		it('refreshes claimedAt on successful transfer', async () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			const t0 = tracker.getOwner('/tmp/file.txt')
+			expect(t0).toBe(runId(1))
+
+			await new Promise((r) => setTimeout(r, 2))
+			tracker.transfer('/tmp/file.txt', runId(1), runId(2))
+			const list = tracker.listByOwner(runId(2))
+			expect(list).toHaveLength(1)
+			const after = list[0]
+			expect(after?.claimedAt).toBeGreaterThan(0)
+			expect(after?.owner).toBe(runId(2))
+		})
+	})
+
+	describe('releaseAll', () => {
+		it('releases every ownership for the owner, returns count, emits per-entry', () => {
+			tracker.claim('/tmp/a.txt', runId(1))
+			tracker.claim('/tmp/b.txt', runId(1))
+			tracker.claim('/tmp/c.txt', runId(2))
+			events.length = 0
+
+			const count = tracker.releaseAll(runId(1))
+			expect(count).toBe(2)
+			expect(tracker.getOwner('/tmp/a.txt')).toBeUndefined()
+			expect(tracker.getOwner('/tmp/b.txt')).toBeUndefined()
+			expect(tracker.getOwner('/tmp/c.txt')).toBe(runId(2))
+
+			const released = events.filter((e) => e.type === 'ownership_released')
+			expect(released.length).toBe(2)
+			for (const e of released) {
+				if (e.type === 'ownership_released') {
+					expect(e.previousOwner).toBe(runId(1))
+				}
+			}
+		})
+
+		it('returns 0 when the owner has no entries', () => {
+			const count = tracker.releaseAll(runId(99))
+			expect(count).toBe(0)
+			expect(events).toEqual([])
+		})
+	})
+
+	describe('read helpers', () => {
+		it('getOwner returns undefined for unclaimed paths', () => {
+			expect(tracker.getOwner('/tmp/anything.txt')).toBeUndefined()
+		})
+
+		it('listByOwner returns all ownerships for a given owner', () => {
+			tracker.claim('/tmp/a.txt', runId(1))
+			tracker.claim('/tmp/b.txt', runId(1))
+			tracker.claim('/tmp/c.txt', runId(2))
+
+			const list = tracker.listByOwner(runId(1))
+			expect(list.length).toBe(2)
+			expect(new Set(list.map((o) => o.filePath))).toEqual(
+				new Set([path.resolve('/tmp/a.txt'), path.resolve('/tmp/b.txt')]),
+			)
+		})
+
+		it('checkConflict returns the current owner iff a different owner holds the file', () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			expect(tracker.checkConflict('/tmp/file.txt', runId(1))).toBeUndefined()
+			expect(tracker.checkConflict('/tmp/file.txt', runId(2))).toBe(runId(1))
+			expect(tracker.checkConflict('/tmp/other.txt', runId(2))).toBeUndefined()
+		})
+	})
+})

package/src/connector/BaseConnector.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 5):
+ *
+ *   - `BaseConnector` is abstract. Each concrete subclass sets id /
+ *     name / description / connectionType / configSchema / methods
+ *     and implements connect / disconnect / healthCheck / execute.
+ *   - `toDefinition()` projects the abstract readonly fields into a
+ *     `ConnectorDefinition<TConfig>` — used to register the connector
+ *     with the `ConnectorRegistry`.
+ *   - `findMethod(name)` returns the method by name or undefined.
+ *   - `requireMethod(name)` throws with the method name + available
+ *     names when not found.
+ *   - `validateInput(method, input)`: zod.safeParse; on failure
+ *     throws `Invalid input for method "<name>": <joined issues>`.
+ *   - `measureExecution(fn)` returns `{result, durationMs}` with
+ *     durationMs rounded.
+ *   - Auth resolution lives in subclasses (see HttpConnector tests),
+ *     not in the base class.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import type {
+	AuthConfig,
+	ConnectionType,
+	ConnectorExecuteResult,
+	ConnectorMethod,
+} from '../types/connector/index.js'
+import type { ConnectorId } from '../types/ids/index.js'
+
+import { BaseConnector } from './BaseConnector.js'
+
+class TestConnector extends BaseConnector<{ base: string }> {
+	readonly id = 'conn_test' as ConnectorId
+	readonly name = 'Test'
+	readonly description = 'Test connector'
+	readonly connectionType: ConnectionType = 'custom'
+	readonly configSchema = z.object({ base: z.string() })
+	readonly methods: ConnectorMethod[] = [
+		{
+			name: 'echo',
+			description: 'echo',
+			inputSchema: z.object({ value: z.string() }),
+		},
+	]
+
+	async connect(): Promise<void> {}
+	async disconnect(): Promise<void> {}
+	async healthCheck(): Promise<boolean> {
+		return true
+	}
+	async execute(): Promise<ConnectorExecuteResult> {
+		return { success: true, output: 'ok', durationMs: 0 }
+	}
+
+	// Expose protected methods for direct tests:
+	publicRequireMethod(name: string): ConnectorMethod {
+		return this.requireMethod(name)
+	}
+	publicValidateInput(method: ConnectorMethod, input: unknown): unknown {
+		return this.validateInput(method, input)
+	}
+	publicMeasureExecution<T>(fn: () => Promise<T>) {
+		return this.measureExecution(fn)
+	}
+
+	// Exposed internal auth resolver on a subclass is a sibling concern —
+	// `BaseConnector` does not define any auth handling; the field is
+	// just stored.
+	getStoredAuth(): AuthConfig | undefined {
+		return this.auth
+	}
+}
+
+describe('BaseConnector', () => {
+	it('toDefinition projects abstract readonly fields', () => {
+		const c = new TestConnector()
+		const def = c.toDefinition()
+		expect(def.id).toBe('conn_test')
+		expect(def.name).toBe('Test')
+		expect(def.description).toBe('Test connector')
+		expect(def.connectionType).toBe('custom')
+		expect(def.methods).toHaveLength(1)
+	})
+
+	it('findMethod returns undefined for an unknown name', () => {
+		const c = new TestConnector()
+		expect(c.publicRequireMethod).toBeDefined()
+		// findMethod is invoked indirectly via requireMethod — we cover the
+		// positive + negative paths below.
+	})
+
+	it('requireMethod returns the method when present', () => {
+		const c = new TestConnector()
+		const method = c.publicRequireMethod('echo')
+		expect(method.name).toBe('echo')
+	})
+
+	it('requireMethod throws naming the missing method + available names', () => {
+		const c = new TestConnector()
+		expect(() => c.publicRequireMethod('nope')).toThrow(/Method "nope" not found/)
+		expect(() => c.publicRequireMethod('nope')).toThrow(/Available: echo/)
+	})
+
+	it('validateInput passes through parsed data on success', () => {
+		const c = new TestConnector()
+		const method = c.publicRequireMethod('echo')
+		expect(c.publicValidateInput(method, { value: 'hi' })).toEqual({ value: 'hi' })
+	})
+
+	it('validateInput throws with joined issue messages on failure', () => {
+		const c = new TestConnector()
+		const method = c.publicRequireMethod('echo')
+		expect(() => c.publicValidateInput(method, { value: 123 })).toThrow(
+			/Invalid input for method "echo"/,
+		)
+	})
+
+	it('measureExecution returns the result + rounded durationMs', async () => {
+		const c = new TestConnector()
+		const { result, durationMs } = await c.publicMeasureExecution(async () => {
+			await new Promise((r) => setTimeout(r, 5))
+			return 42
+		})
+		expect(result).toBe(42)
+		expect(durationMs).toBeGreaterThanOrEqual(0)
+		expect(Number.isInteger(durationMs)).toBe(true)
+	})
+})