@namzu/sdk 0.4.2 → 0.4.3

package/src/rag/vector-store.test.ts

@@ -0,0 +1,196 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   This file doubles as the VectorStore contract — the tests here run
+ *   against `InMemoryVectorStore` as the reference implementation, and
+ *   are the spec a future `@namzu/vector-store-conformance` package will
+ *   be built around (D4 ratification + Q5 refinement: contract first,
+ *   not "whatever the reference happens to do").
+ *
+ *   **VectorStore contract (derived from current code, 2026-04-21):**
+ *
+ *   - `upsert(chunks[])`: stores each chunk keyed by `chunk.id`. Re-upsert
+ *     of a chunk with the same id REPLACES — no merge, no error. Tenant
+ *     scoping is carried on each chunk, not enforced at upsert (the
+ *     caller is trusted).
+ *   - `search(query)`: returns `VectorSearchResult[]`:
+ *     - Filters by `tenantId` (EXACT match).
+ *     - If `knowledgeBaseId` is set, filters by that too.
+ *     - Skips chunks with `embedding === undefined`.
+ *     - Applies `filter` as metadata-equality AND across the whole
+ *       filter object.
+ *     - Computes similarity via `cosineSimilarity(query, chunk.embedding)`.
+ *     - If `minScore` is set, drops scores below it.
+ *     - Sorts descending by score and returns the top `topK` results.
+ *   - `delete(chunkIds[])`: deletes by exact chunk id. Unknown ids are
+ *     silently ignored.
+ *   - `deleteByDocument(documentId)`: NOT tenant-scoped in the
+ *     current API — deletes every chunk with matching `documentId`
+ *     ACROSS tenants. This is an asymmetry with `search` /
+ *     `deleteByKnowledgeBase` and is intentional to pin (Codex #9 flag).
+ *   - `deleteByKnowledgeBase(kbId, tenantId)`: tenant-scoped deletion
+ *     by knowledge base.
+ *   - `cosineSimilarity(a, b)`: returns 0 when arrays differ in length
+ *     OR when either has zero norm. Otherwise returns the standard
+ *     dot-product / (‖a‖·‖b‖) result.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { ChunkId, DocumentId, KnowledgeBaseId, TenantId } from '../types/ids/index.js'
+import type { Chunk, VectorStoreQuery } from '../types/rag/index.js'
+
+import { InMemoryVectorStore, cosineSimilarity } from './vector-store.js'
+
+const T1 = 'tenant_1' as TenantId
+const T2 = 'tenant_2' as TenantId
+const KB1 = 'kb_1' as KnowledgeBaseId
+const KB2 = 'kb_2' as KnowledgeBaseId
+const D1 = 'doc_1' as DocumentId
+const D2 = 'doc_2' as DocumentId
+
+function chunk(id: string, overrides: Partial<Chunk> = {}): Chunk {
+	return {
+		id: id as ChunkId,
+		documentId: D1,
+		knowledgeBaseId: KB1,
+		tenantId: T1,
+		content: `content of ${id}`,
+		index: 0,
+		tokenCount: 10,
+		embedding: [1, 0, 0],
+		metadata: {},
+		createdAt: Date.now(),
+		...overrides,
+	}
+}
+
+const baseQuery: VectorStoreQuery = {
+	embedding: [1, 0, 0],
+	topK: 10,
+	tenantId: T1,
+}
+
+describe('InMemoryVectorStore — upsert', () => {
+	it('stores chunks by id; re-upsert replaces', async () => {
+		const s = new InMemoryVectorStore()
+		await s.upsert([chunk('c1', { content: 'v1' })])
+		await s.upsert([chunk('c1', { content: 'v2' })])
+		const results = await s.search(baseQuery)
+		expect(results).toHaveLength(1)
+		expect(results[0]?.chunk.content).toBe('v2')
+	})
+})
+
+describe('InMemoryVectorStore — search', () => {
+	it('enforces tenant isolation on the query path', async () => {
+		const s = new InMemoryVectorStore()
+		await s.upsert([
+			chunk('a', { tenantId: T1, embedding: [1, 0, 0] }),
+			chunk('b', { tenantId: T2, embedding: [1, 0, 0] }),
+		])
+		const results = await s.search({ ...baseQuery, tenantId: T1 })
+		expect(results.map((r) => r.chunk.id)).toEqual(['a'])
+	})
+
+	it('filters by knowledgeBaseId when provided', async () => {
+		const s = new InMemoryVectorStore()
+		await s.upsert([chunk('a', { knowledgeBaseId: KB1 }), chunk('b', { knowledgeBaseId: KB2 })])
+		const results = await s.search({ ...baseQuery, knowledgeBaseId: KB1 })
+		expect(results.map((r) => r.chunk.id)).toEqual(['a'])
+	})
+
+	it('skips chunks with no embedding', async () => {
+		const s = new InMemoryVectorStore()
+		await s.upsert([chunk('a', { embedding: [1, 0, 0] }), chunk('b', { embedding: undefined })])
+		const results = await s.search(baseQuery)
+		expect(results.map((r) => r.chunk.id)).toEqual(['a'])
+	})
+
+	it('applies AND-of-equalities across filter keys', async () => {
+		const s = new InMemoryVectorStore()
+		await s.upsert([
+			chunk('a', { metadata: { lang: 'en', year: 2026 } }),
+			chunk('b', { metadata: { lang: 'en', year: 2024 } }),
+			chunk('c', { metadata: { lang: 'tr', year: 2026 } }),
+		])
+		const results = await s.search({
+			...baseQuery,
+			filter: { lang: 'en', year: 2026 },
+		})
+		expect(results.map((r) => r.chunk.id)).toEqual(['a'])
+	})
+
+	it('applies minScore cutoff', async () => {
+		const s = new InMemoryVectorStore()
+		await s.upsert([
+			chunk('same', { embedding: [1, 0, 0] }),
+			chunk('orthogonal', { embedding: [0, 1, 0] }),
+		])
+		const results = await s.search({ ...baseQuery, minScore: 0.5 })
+		expect(results.map((r) => r.chunk.id)).toEqual(['same'])
+	})
+
+	it('sorts descending by score and slices to topK', async () => {
+		const s = new InMemoryVectorStore()
+		await s.upsert([
+			chunk('strong', { embedding: [1, 0, 0] }),
+			chunk('medium', { embedding: [0.5, 0.5, 0] }),
+			chunk('weak', { embedding: [0.1, 0.9, 0] }),
+		])
+		const results = await s.search({ ...baseQuery, topK: 2 })
+		expect(results.map((r) => r.chunk.id)).toEqual(['strong', 'medium'])
+	})
+})
+
+describe('InMemoryVectorStore — delete', () => {
+	it('delete(chunkIds) removes each id; unknown ids are silent', async () => {
+		const s = new InMemoryVectorStore()
+		await s.upsert([chunk('a'), chunk('b')])
+		await s.delete(['a' as ChunkId, 'missing' as ChunkId])
+		expect((await s.search(baseQuery)).map((r) => r.chunk.id)).toEqual(['b'])
+	})
+
+	it('deleteByDocument removes every chunk of the document ACROSS tenants (asymmetry per Codex #9)', async () => {
+		const s = new InMemoryVectorStore()
+		await s.upsert([
+			chunk('a', { documentId: D1, tenantId: T1 }),
+			chunk('b', { documentId: D1, tenantId: T2 }),
+			chunk('c', { documentId: D2, tenantId: T1 }),
+		])
+		await s.deleteByDocument(D1)
+		// Both D1 chunks gone even though we didn't pass a tenant.
+		expect((await s.search({ ...baseQuery, tenantId: T1 })).map((r) => r.chunk.id)).toEqual(['c'])
+		expect(await s.search({ ...baseQuery, tenantId: T2 })).toEqual([])
+	})
+
+	it('deleteByKnowledgeBase is tenant-scoped', async () => {
+		const s = new InMemoryVectorStore()
+		await s.upsert([
+			chunk('a', { knowledgeBaseId: KB1, tenantId: T1 }),
+			chunk('b', { knowledgeBaseId: KB1, tenantId: T2 }),
+		])
+		await s.deleteByKnowledgeBase(KB1, T1)
+		expect(await s.search({ ...baseQuery, tenantId: T1 })).toEqual([])
+		expect((await s.search({ ...baseQuery, tenantId: T2 })).map((r) => r.chunk.id)).toEqual(['b'])
+	})
+})
+
+describe('cosineSimilarity', () => {
+	it('is 1 for identical non-zero vectors', () => {
+		expect(cosineSimilarity([1, 2, 3], [1, 2, 3])).toBeCloseTo(1)
+	})
+
+	it('is 0 for orthogonal vectors', () => {
+		expect(cosineSimilarity([1, 0], [0, 1])).toBe(0)
+	})
+
+	it('is 0 when vectors differ in length', () => {
+		expect(cosineSimilarity([1, 0], [1, 0, 0])).toBe(0)
+	})
+
+	it('is 0 when either vector has zero norm', () => {
+		expect(cosineSimilarity([0, 0], [1, 1])).toBe(0)
+		expect(cosineSimilarity([1, 1], [0, 0])).toBe(0)
+	})
+})

package/src/registry/ManagedRegistry.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 3):
+ *
+ *   - `ManagedRegistry` extends `Registry` with a component-named
+ *     logger + two optional id-extraction strategies: `idField` or
+ *     `computeId`. `computeId` takes precedence when both are set.
+ *   - `register(id, item)` (2-arg): throws when `item` is missing;
+ *     warn-logs + overwrites on duplicate id (no typed error).
+ *   - `register(item)` (1-arg): extracts id via computeId/idField;
+ *     throws when neither is configured.
+ *   - `register(items[])`: batch-registers (recursively calls the
+ *     single-arg path for each). Any failure in a single register
+ *     throws and aborts the batch (no partial-success semantics).
+ *   - `getOrThrow(id)`: returns the item; throws
+ *     `new Error("Not found: <id>. Available: <csv of known ids>")`
+ *     — a plain `Error`, NOT a typed `XYZNotFoundError` (Codex #1).
+ *   - No start / stop lifecycle exists (design §2.3 claim was
+ *     fictional).
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import type { Logger } from '../utils/logger.js'
+
+import { ManagedRegistry } from './ManagedRegistry.js'
+
+function makeLogger(): Logger {
+	const self = {
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		debug: vi.fn(),
+		child: vi.fn(),
+	} as unknown as Logger
+	;(self as { child: (ctx: unknown) => Logger }).child = vi.fn(() => self)
+	return self
+}
+
+interface Item {
+	id: string
+	info: { id: string }
+	value: number
+}
+
+describe('ManagedRegistry', () => {
+	describe('register (2-arg form)', () => {
+		it('throws when called with (id) only', () => {
+			const r = new ManagedRegistry<Item>({ componentName: 't' })
+			// biome-ignore lint/suspicious/noExplicitAny: exercises the no-item-arg path
+			expect(() => (r as any).register('a')).toThrow(/requires an item argument/)
+		})
+
+		it('warn-logs then overwrites on duplicate id', () => {
+			const logger = makeLogger()
+			const r = new ManagedRegistry<Item>({ componentName: 't', logger })
+			const a = { id: 'a', info: { id: 'a' }, value: 1 }
+			const b = { id: 'a', info: { id: 'a' }, value: 2 }
+			r.register('a', a)
+			r.register('a', b)
+			expect(r.get('a')?.value).toBe(2)
+			expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('"a" already registered'))
+		})
+	})
+
+	describe('register (single-item form)', () => {
+		it('uses idField when computeId is not set', () => {
+			const r = new ManagedRegistry<Item>({ componentName: 't', idField: 'id' })
+			r.register({ id: 'a', info: { id: 'nested' }, value: 1 })
+			expect(r.get('a')).toBeDefined()
+			expect(r.get('nested')).toBeUndefined()
+		})
+
+		it('computeId takes precedence over idField when both are set', () => {
+			const r = new ManagedRegistry<Item>({
+				componentName: 't',
+				idField: 'id',
+				computeId: (item) => item.info.id,
+			})
+			r.register({ id: 'top', info: { id: 'nested' }, value: 1 })
+			expect(r.get('nested')).toBeDefined()
+			expect(r.get('top')).toBeUndefined()
+		})
+
+		it('throws when neither idField nor computeId is configured', () => {
+			const r = new ManagedRegistry<Item>({ componentName: 't' })
+			expect(() => r.register({ id: 'a', info: { id: 'a' }, value: 1 })).toThrow(
+				/requires idField or computeId/,
+			)
+		})
+	})
+
+	describe('register (array form)', () => {
+		it('batch-registers via the single-item path', () => {
+			const r = new ManagedRegistry<Item>({ componentName: 't', idField: 'id' })
+			r.register([
+				{ id: 'a', info: { id: 'a' }, value: 1 },
+				{ id: 'b', info: { id: 'b' }, value: 2 },
+			])
+			expect(r.listIds()).toEqual(['a', 'b'])
+		})
+	})
+
+	describe('getOrThrow', () => {
+		it('returns the item when present', () => {
+			const r = new ManagedRegistry<Item>({ componentName: 't', idField: 'id' })
+			const a = { id: 'a', info: { id: 'a' }, value: 1 }
+			r.register(a)
+			expect(r.getOrThrow('a')).toBe(a)
+		})
+
+		it('throws a plain Error naming the missing id + available ids', () => {
+			const r = new ManagedRegistry<Item>({ componentName: 't', idField: 'id' })
+			r.register({ id: 'a', info: { id: 'a' }, value: 1 })
+			r.register({ id: 'b', info: { id: 'b' }, value: 2 })
+			expect(() => r.getOrThrow('missing')).toThrow(/Not found: "missing"\. Available: a, b/)
+		})
+	})
+})

package/src/registry/Registry.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 3):
+ *
+ *   - `register(id, item)` silently overwrites an existing entry —
+ *     NO duplicate-error is thrown (Codex #1 verified the design
+ *     §2.3 "typed DuplicateRegistrationError" claim was fiction).
+ *   - `get(id)` returns `undefined` for an unknown id (NOT a typed
+ *     error). `getAll`, `listIds`, `has`, `size` reflect the current
+ *     `Map` state; iteration order follows insertion order.
+ *   - `unregister(id)` returns true if the entry existed (and was
+ *     deleted), false otherwise.
+ *   - `clear()` empties the map.
+ *   - The generic `Registry<T>` has no component name, no logger, no
+ *     lifecycle. All enrichment (logs, idField inference, lifecycle)
+ *     happens in `ManagedRegistry`, not here.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { Registry } from './Registry.js'
+
+interface Item {
+	id: string
+	value: number
+}
+
+describe('Registry', () => {
+	it('register + get + has roundtrip', () => {
+		const r = new Registry<Item>()
+		const a: Item = { id: 'a', value: 1 }
+		r.register('a', a)
+		expect(r.get('a')).toBe(a)
+		expect(r.has('a')).toBe(true)
+		expect(r.get('b')).toBeUndefined()
+		expect(r.has('b')).toBe(false)
+	})
+
+	it('register silently overwrites an existing key', () => {
+		const r = new Registry<Item>()
+		r.register('a', { id: 'a', value: 1 })
+		r.register('a', { id: 'a', value: 2 })
+		expect(r.get('a')?.value).toBe(2)
+		expect(r.size()).toBe(1)
+	})
+
+	it('listIds reflects insertion order', () => {
+		const r = new Registry<Item>()
+		r.register('x', { id: 'x', value: 1 })
+		r.register('y', { id: 'y', value: 2 })
+		r.register('z', { id: 'z', value: 3 })
+		expect(r.listIds()).toEqual(['x', 'y', 'z'])
+	})
+
+	it('getAll returns every item in insertion order', () => {
+		const r = new Registry<Item>()
+		const items = [
+			{ id: 'a', value: 1 },
+			{ id: 'b', value: 2 },
+		]
+		for (const item of items) r.register(item.id, item)
+		expect(r.getAll()).toEqual(items)
+	})
+
+	it('unregister returns true iff the key existed', () => {
+		const r = new Registry<Item>()
+		r.register('a', { id: 'a', value: 1 })
+		expect(r.unregister('a')).toBe(true)
+		expect(r.unregister('a')).toBe(false)
+		expect(r.get('a')).toBeUndefined()
+	})
+
+	it('clear empties the map', () => {
+		const r = new Registry<Item>()
+		r.register('a', { id: 'a', value: 1 })
+		r.register('b', { id: 'b', value: 2 })
+		r.clear()
+		expect(r.size()).toBe(0)
+		expect(r.getAll()).toEqual([])
+	})
+
+	it('size matches the map size', () => {
+		const r = new Registry<Item>()
+		expect(r.size()).toBe(0)
+		r.register('a', { id: 'a', value: 1 })
+		expect(r.size()).toBe(1)
+		r.register('a', { id: 'a', value: 2 }) // overwrite
+		expect(r.size()).toBe(1)
+		r.register('b', { id: 'b', value: 3 })
+		expect(r.size()).toBe(2)
+	})
+})

package/src/registry/agent/definitions.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 3):
+ *
+ *   - `AgentRegistry` extends `ManagedRegistry<AgentDefinition>` and
+ *     keys by `def.info.id` via `computeId` (NOT by the top-level id
+ *     field — there isn't one on AgentDefinition).
+ *   - `resolve(agentId)` returns `.typedAgent`; delegates to
+ *     `getOrThrow` and therefore throws a plain `Error` when missing.
+ *   - `listByType(type)` filters by `typedAgent.type`.
+ *   - `search({category?, query?})` filters by info.category then by
+ *     case-insensitive match against name OR description. An empty
+ *     query matches all.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { AgentInfo } from '../../contracts/api.js'
+import type { AgentType, BaseAgentConfig, BaseAgentResult } from '../../types/agent/base.js'
+import type { Agent } from '../../types/agent/core.js'
+import type { AgentDefinition } from '../../types/agent/factory.js'
+
+import { AgentRegistry } from './definitions.js'
+
+function makeDef(id: string, type: AgentType, overrides: Partial<AgentInfo> = {}): AgentDefinition {
+	const info: AgentInfo = {
+		id,
+		name: `Agent ${id}`,
+		version: '1.0.0',
+		category: 'general',
+		description: `agent ${id} does stuff`,
+		tools: [],
+		defaults: { model: 'opus', tokenBudget: 1000 },
+		...overrides,
+	}
+	const typedAgent = { type } as unknown as Agent<BaseAgentConfig, BaseAgentResult>
+	return { info, typedAgent }
+}
+
+describe('AgentRegistry', () => {
+	it('keys by info.id (computeId), not by a top-level id field', () => {
+		const r = new AgentRegistry()
+		r.register(makeDef('coder', 'reactive'))
+		expect(r.get('coder')).toBeDefined()
+	})
+
+	it('resolve returns typedAgent', () => {
+		const r = new AgentRegistry()
+		const def = makeDef('coder', 'reactive')
+		r.register(def)
+		expect(r.resolve('coder')).toBe(def.typedAgent)
+	})
+
+	it('resolve throws (plain Error) on unknown agentId', () => {
+		const r = new AgentRegistry()
+		expect(() => r.resolve('nope')).toThrow(/Not found/)
+	})
+
+	it('listByType filters by typedAgent.type', () => {
+		const r = new AgentRegistry()
+		r.register(makeDef('a', 'reactive'))
+		r.register(makeDef('b', 'pipeline'))
+		r.register(makeDef('c', 'reactive'))
+		expect(r.listByType('reactive').map((d) => d.info.id)).toEqual(['a', 'c'])
+		expect(r.listByType('pipeline').map((d) => d.info.id)).toEqual(['b'])
+	})
+
+	describe('search', () => {
+		it('empty query returns all', () => {
+			const r = new AgentRegistry()
+			r.register(makeDef('a', 'reactive'))
+			r.register(makeDef('b', 'pipeline'))
+			expect(r.search({})).toHaveLength(2)
+		})
+
+		it('category filter is strict-equal', () => {
+			const r = new AgentRegistry()
+			r.register(makeDef('coder', 'reactive', { category: 'coding' }))
+			r.register(makeDef('writer', 'reactive', { category: 'writing' }))
+			expect(r.search({ category: 'coding' }).map((d) => d.info.id)).toEqual(['coder'])
+		})
+
+		it('query matches name OR description case-insensitively', () => {
+			const r = new AgentRegistry()
+			r.register(makeDef('alpha', 'reactive', { name: 'CoderBot', description: 'writes code' }))
+			r.register(makeDef('beta', 'reactive', { name: 'Other', description: 'tests CODE' }))
+			r.register(makeDef('gamma', 'reactive', { name: 'Third', description: 'documentation' }))
+
+			const hits = r.search({ query: 'code' }).map((d) => d.info.id)
+			expect(hits).toEqual(['alpha', 'beta'])
+		})
+
+		it('combines category + query', () => {
+			const r = new AgentRegistry()
+			r.register(makeDef('alpha', 'reactive', { category: 'coding', name: 'CoderBot' }))
+			r.register(makeDef('beta', 'reactive', { category: 'writing', name: 'CoderWriter' }))
+			const hits = r.search({ category: 'coding', query: 'coder' }).map((d) => d.info.id)
+			expect(hits).toEqual(['alpha'])
+		})
+	})
+})

package/src/registry/connector/definitions.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 3):
+ *
+ *   - `ConnectorRegistry` extends `ManagedRegistry<ConnectorDefinition>`
+ *     with `idField: 'id'` — it keys by the top-level `id` field, NOT
+ *     a nested path.
+ *   - `listByType(connectionType)` filters by `connectionType`.
+ *   - As a global (non-tenant-scoped) registry, ConnectorRegistry is
+ *     shared across tenants; tenant isolation lives in
+ *     `TenantConnectorManager` per Codex #5.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import type { ConnectorDefinition } from '../../types/connector/index.js'
+import type { ConnectorId } from '../../types/ids/index.js'
+
+import { ConnectorRegistry } from './definitions.js'
+
+function makeDef(
+	id: string,
+	connectionType: ConnectorDefinition['connectionType'],
+): ConnectorDefinition {
+	return {
+		id: id as ConnectorId,
+		name: id,
+		description: `${id} connector`,
+		connectionType,
+		configSchema: z.object({}),
+		methods: [],
+	}
+}
+
+describe('ConnectorRegistry', () => {
+	it('keys by top-level id', () => {
+		const r = new ConnectorRegistry()
+		r.register(makeDef('conn_a', 'http'))
+		expect(r.get('conn_a')).toBeDefined()
+	})
+
+	it('listByType filters by connectionType', () => {
+		const r = new ConnectorRegistry()
+		r.register(makeDef('conn_a', 'http'))
+		r.register(makeDef('conn_b', 'webhook'))
+		r.register(makeDef('conn_c', 'http'))
+		expect(r.listByType('http').map((d) => d.id)).toEqual(['conn_a', 'conn_c'])
+		expect(r.listByType('webhook').map((d) => d.id)).toEqual(['conn_b'])
+		expect(r.listByType('custom')).toEqual([])
+	})
+})

package/src/registry/connector/scoped.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 3):
+ *
+ *   - `ScopedConnectorRegistry` stores per-scope config by a composite
+ *     key `<scope>:<scopeId>:<connectorId>`. Multiple configs at
+ *     different scopes for the same connector coexist.
+ *   - `set`, `remove`, `getAt` round-trip through the same key.
+ *   - `resolve(connectorId, chain)` iterates in `CONNECTOR_SCOPE_ORDER`
+ *     (org → environment → team → project → agent) and merges layers
+ *     — later scopes override earlier ones. Specifically:
+ *     - `options` are shallow-merged across layers.
+ *     - `auth` is last-wins (any layer with an explicit auth replaces).
+ *     - `enabled` is last-wins (defaulting to true when no layer sets it).
+ *     - The final `ConnectorConfig.name` falls back to `connectorId`
+ *       when no layer sets a name.
+ *   - `resolve` returns undefined when no layer matches the chain.
+ *   - `listForConnector` returns every config for a connector across
+ *     all scopes; `listAtScope` returns every connector at a given scope.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { ConnectorId } from '../../types/ids/index.js'
+
+import { ScopedConnectorRegistry } from './scoped.js'
+
+const CID = 'conn_http' as ConnectorId
+
+describe('ScopedConnectorRegistry', () => {
+	describe('set + getAt + remove', () => {
+		it('round-trips via the composite key', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({
+				scope: { scope: 'org', scopeId: 'org_1' },
+				connectorId: CID,
+				options: { k: 'v' },
+			})
+			expect(r.getAt({ scope: 'org', scopeId: 'org_1' }, CID)?.options).toEqual({ k: 'v' })
+		})
+
+		it('remove returns true iff an entry existed', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({ scope: { scope: 'org', scopeId: 'org_1' }, connectorId: CID })
+			expect(r.remove({ scope: 'org', scopeId: 'org_1' }, CID)).toBe(true)
+			expect(r.remove({ scope: 'org', scopeId: 'org_1' }, CID)).toBe(false)
+		})
+
+		it('different scopes coexist for the same connector', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({ scope: { scope: 'org', scopeId: 'org_1' }, connectorId: CID })
+			r.set({ scope: { scope: 'project', scopeId: 'proj_1' }, connectorId: CID })
+			expect(r.listForConnector(CID)).toHaveLength(2)
+		})
+	})
+
+	describe('resolve layering', () => {
+		it('merges options shallow; later scopes override', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({
+				scope: { scope: 'org', scopeId: 'org_1' },
+				connectorId: CID,
+				options: { host: 'api.org', timeout: 30 },
+			})
+			r.set({
+				scope: { scope: 'project', scopeId: 'proj_1' },
+				connectorId: CID,
+				options: { host: 'api.project' },
+			})
+			const resolved = r.resolve(CID, { org: 'org_1', project: 'proj_1' })
+			expect(resolved?.options).toEqual({ host: 'api.project', timeout: 30 })
+		})
+
+		it('auth is last-wins (CONNECTOR_SCOPE_ORDER)', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({
+				scope: { scope: 'org', scopeId: 'org_1' },
+				connectorId: CID,
+				auth: { type: 'none' },
+			})
+			r.set({
+				scope: { scope: 'project', scopeId: 'proj_1' },
+				connectorId: CID,
+				auth: { type: 'api_key', credentials: { apiKey: 'secret' } },
+			})
+			const resolved = r.resolve(CID, { org: 'org_1', project: 'proj_1' })
+			expect(resolved?.auth).toEqual({ type: 'api_key', credentials: { apiKey: 'secret' } })
+		})
+
+		it('enabled defaults to true and is last-wins', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({ scope: { scope: 'org', scopeId: 'org_1' }, connectorId: CID, enabled: false })
+			const resolved = r.resolve(CID, { org: 'org_1' })
+			expect(resolved?.enabled).toBe(false)
+		})
+
+		it('config.name falls back to connectorId when no layer sets a name', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({ scope: { scope: 'org', scopeId: 'org_1' }, connectorId: CID })
+			const resolved = r.resolve(CID, { org: 'org_1' })
+			expect(resolved?.config.name).toBe(CID)
+		})
+
+		it('resolvedFrom preserves layer order by CONNECTOR_SCOPE_ORDER', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({ scope: { scope: 'project', scopeId: 'proj_1' }, connectorId: CID })
+			r.set({ scope: { scope: 'org', scopeId: 'org_1' }, connectorId: CID })
+			const resolved = r.resolve(CID, { org: 'org_1', project: 'proj_1' })
+			expect(resolved?.resolvedFrom.map((s) => s.scope)).toEqual(['org', 'project'])
+		})
+
+		it('returns undefined when no layer matches the chain', () => {
+			const r = new ScopedConnectorRegistry()
+			expect(r.resolve(CID, { org: 'org_none' })).toBeUndefined()
+		})
+	})
+
+	describe('list operations', () => {
+		it('listAtScope filters by scope prefix', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({ scope: { scope: 'org', scopeId: 'org_1' }, connectorId: CID })
+			r.set({
+				scope: { scope: 'org', scopeId: 'org_1' },
+				connectorId: 'conn_other' as ConnectorId,
+			})
+			r.set({ scope: { scope: 'project', scopeId: 'proj_1' }, connectorId: CID })
+			expect(r.listAtScope({ scope: 'org', scopeId: 'org_1' })).toHaveLength(2)
+		})
+	})
+})