@namzu/sdk 0.4.2 → 0.4.4

package/src/rag/rag-tool.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   - `createRAGTool(config)` returns a `defineTool`-wrapped
+ *     `knowledge_search` tool with `category: 'analysis'`,
+ *     `permissions: ['network_access']`, read-only.
+ *   - Knowledge base selection:
+ *     - If `input.knowledge_base_id` is set, looks up by it.
+ *     - Else uses `config.defaultKnowledgeBaseId`.
+ *     - Else picks the first value from
+ *       `config.knowledgeBases.values().next()`.
+ *   - Returns `{success: false, error: ...}` if no knowledge base is
+ *     resolved.
+ *   - When the query returns no chunks, returns the literal
+ *     "No relevant information found..." message.
+ *   - When chunks exist, assembles them via `assembleRAGContext` and
+ *     returns `{success: true, output: content, data: {sources, mode, durationMs}}`.
+ *   - `top_k` override precedence: input > config.topK > 5.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import type { ChunkId, DocumentId, KnowledgeBaseId, TenantId } from '../types/ids/index.js'
+import type { KnowledgeBase, RetrievalResult, VectorSearchResult } from '../types/rag/index.js'
+import type { ToolContext } from '../types/tool/index.js'
+
+import { createRAGTool } from './rag-tool.js'
+
+const TENANT = 't_1' as TenantId
+const KB_A = 'kb_a' as KnowledgeBaseId
+const KB_B = 'kb_b' as KnowledgeBaseId
+
+function makeKB(retrievalResult: RetrievalResult): KnowledgeBase {
+	const kb = {
+		id: KB_A,
+		config: { id: KB_A, tenantId: TENANT },
+		ingest: vi.fn(),
+		remove: vi.fn(),
+		query: vi.fn(async () => retrievalResult),
+		clear: vi.fn(),
+	} as unknown as KnowledgeBase
+	return kb
+}
+
+function searchResult(content: string): VectorSearchResult {
+	return {
+		chunk: {
+			id: 'c_1' as ChunkId,
+			documentId: 'd_1' as DocumentId,
+			knowledgeBaseId: KB_A,
+			tenantId: TENANT,
+			content,
+			index: 0,
+			tokenCount: 0,
+			metadata: {},
+			createdAt: 0,
+		},
+		score: 0.9,
+	}
+}
+
+const ctx: ToolContext = {} as ToolContext
+
+describe('createRAGTool', () => {
+	it('is named knowledge_search + read-only', () => {
+		const tool = createRAGTool({ knowledgeBases: new Map() })
+		expect(tool.name).toBe('knowledge_search')
+		expect(tool.isReadOnly?.({ query: 'x' })).toBe(true)
+	})
+
+	it('returns an error when no knowledge base is resolved', async () => {
+		const tool = createRAGTool({ knowledgeBases: new Map() })
+		const result = await tool.execute({ query: 'hi' }, ctx)
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/Knowledge base not found/)
+	})
+
+	it('picks KB by explicit input.knowledge_base_id when set', async () => {
+		const kbA = makeKB({
+			chunks: [searchResult('from A')],
+			query: 'hi',
+			mode: 'vector',
+			durationMs: 1,
+		})
+		const kbB = makeKB({
+			chunks: [searchResult('from B')],
+			query: 'hi',
+			mode: 'vector',
+			durationMs: 1,
+		})
+		const tool = createRAGTool({
+			knowledgeBases: new Map([
+				[KB_A, kbA],
+				[KB_B, kbB],
+			]),
+		})
+		const out = await tool.execute({ query: 'hi', knowledge_base_id: KB_B }, ctx)
+		expect(out.success).toBe(true)
+		expect(kbB.query).toHaveBeenCalled()
+		expect(kbA.query).not.toHaveBeenCalled()
+	})
+
+	it('falls back to defaultKnowledgeBaseId when input.knowledge_base_id is absent', async () => {
+		const kbA = makeKB({
+			chunks: [searchResult('from A')],
+			query: 'hi',
+			mode: 'vector',
+			durationMs: 1,
+		})
+		const kbB = makeKB({
+			chunks: [],
+			query: 'hi',
+			mode: 'vector',
+			durationMs: 1,
+		})
+		const tool = createRAGTool({
+			knowledgeBases: new Map([
+				[KB_A, kbA],
+				[KB_B, kbB],
+			]),
+			defaultKnowledgeBaseId: KB_B,
+		})
+		await tool.execute({ query: 'hi' }, ctx)
+		expect(kbB.query).toHaveBeenCalled()
+		expect(kbA.query).not.toHaveBeenCalled()
+	})
+
+	it('returns "No relevant information..." when the query returns zero chunks', async () => {
+		const kb = makeKB({ chunks: [], query: 'hi', mode: 'vector', durationMs: 1 })
+		const tool = createRAGTool({ knowledgeBases: new Map([[KB_A, kb]]) })
+		const result = await tool.execute({ query: 'hi' }, ctx)
+		expect(result.success).toBe(true)
+		expect(result.output).toBe(
+			'No relevant information found in the knowledge base for this query.',
+		)
+	})
+
+	it('returns assembled content + metadata on hit', async () => {
+		const kb = makeKB({
+			chunks: [searchResult('answer text')],
+			query: 'hi',
+			mode: 'vector',
+			durationMs: 42,
+		})
+		const tool = createRAGTool({ knowledgeBases: new Map([[KB_A, kb]]) })
+		const result = await tool.execute({ query: 'hi' }, ctx)
+		expect(result.success).toBe(true)
+		expect(result.output).toContain('answer text')
+		expect((result.data as { mode?: string })?.mode).toBe('vector')
+		expect((result.data as { durationMs?: number })?.durationMs).toBe(42)
+	})
+
+	it('top_k override: input > config.topK > 5 default', async () => {
+		const kb = makeKB({
+			chunks: [searchResult('x')],
+			query: 'hi',
+			mode: 'vector',
+			durationMs: 1,
+		})
+		const tool = createRAGTool({
+			knowledgeBases: new Map([[KB_A, kb]]),
+			topK: 8,
+		})
+		await tool.execute({ query: 'hi', top_k: 3 }, ctx)
+		expect(kb.query).toHaveBeenCalledWith(expect.objectContaining({ config: { topK: 3 } }))
+	})
+})

package/src/rag/retriever.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   - `DefaultRetriever.retrieve(query, scope, kbId)` dispatches by
+ *     `effectiveConfig.mode` (query.config overrides instance config).
+ *   - Query expansion: if `recentMessages` is present and non-empty,
+ *     appends the last 3 messages joined with spaces after a
+ *     `\n\nContext: ` marker. Otherwise passes `query.text` verbatim.
+ *   - `vector` mode: embeds the (expanded) query once, forwards
+ *     `{embedding, topK, tenantId, knowledgeBaseId, minScore}` to the
+ *     store, returns store results unchanged.
+ *   - `keyword` mode: fetches `topK * 2` results from vector search with
+ *     `minScore: 0`, then rescores via BM25 against the query's
+ *     tokenized form. Filters score > 0, sorts desc, slices to topK.
+ *     Tokenization: lowercase, strip non-`\w\s`, split by whitespace,
+ *     drop tokens length ≤ 1.
+ *   - `hybrid` mode: runs vector + keyword in parallel, merges by
+ *     `chunk.id`, weights vector by `alpha` and keyword by `1 - alpha`
+ *     (default alpha = 0.7). Sorts desc, slices to topK.
+ *   - Result shape: `{chunks, query, expandedQuery?, mode, durationMs}`.
+ *     `expandedQuery` is omitted when equal to original `query.text`.
+ *   - Unknown mode would hit the exhaustive throw (unreachable via
+ *     types; not asserted).
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import type { ChunkId, DocumentId, KnowledgeBaseId, TenantId } from '../types/ids/index.js'
+import type {
+	Chunk,
+	EmbeddingProvider,
+	TenantScope,
+	VectorSearchResult,
+	VectorStore,
+} from '../types/rag/index.js'
+
+import { DefaultRetriever } from './retriever.js'
+
+const TENANT = 't_1' as TenantId
+const KB = 'kb_1' as KnowledgeBaseId
+const scope: TenantScope = { tenantId: TENANT }
+
+function chunk(id: string, content: string): Chunk {
+	return {
+		id: id as ChunkId,
+		documentId: 'doc_1' as DocumentId,
+		knowledgeBaseId: KB,
+		tenantId: TENANT,
+		content,
+		index: 0,
+		tokenCount: 0,
+		embedding: [1, 0, 0],
+		metadata: {},
+		createdAt: 0,
+	}
+}
+
+function r(id: string, content: string, score: number): VectorSearchResult {
+	return { chunk: chunk(id, content), score }
+}
+
+function makeStore(searchResults: VectorSearchResult[]): VectorStore {
+	return {
+		search: vi.fn(async () => searchResults),
+		upsert: vi.fn(),
+		delete: vi.fn(),
+		deleteByDocument: vi.fn(),
+		deleteByKnowledgeBase: vi.fn(),
+	}
+}
+
+function makeEmbedder(): EmbeddingProvider {
+	return {
+		id: 'mock',
+		model: 'x',
+		dimensions: 3,
+		embed: vi.fn(async (texts: string[]) => texts.map(() => [1, 0, 0])),
+		embedQuery: vi.fn(async () => [1, 0, 0]),
+	}
+}
+
+describe('DefaultRetriever — vector mode', () => {
+	it('forwards embedded query + topK + tenant + minScore to store', async () => {
+		const store = makeStore([r('a', 'x', 0.9)])
+		const emb = makeEmbedder()
+		const retriever = new DefaultRetriever(store, emb, {
+			mode: 'vector',
+			topK: 3,
+			minScore: 0.2,
+		})
+		await retriever.retrieve({ text: 'hi' }, scope, KB)
+		expect(store.search).toHaveBeenCalledWith(
+			expect.objectContaining({
+				embedding: [1, 0, 0],
+				topK: 3,
+				tenantId: TENANT,
+				knowledgeBaseId: KB,
+				minScore: 0.2,
+			}),
+		)
+	})
+
+	it('returns mode + durationMs + chunks without mutation', async () => {
+		const results = [r('a', 'x', 0.9)]
+		const store = makeStore(results)
+		const retriever = new DefaultRetriever(store, makeEmbedder(), {
+			mode: 'vector',
+			topK: 5,
+		})
+		const out = await retriever.retrieve({ text: 'hi' }, scope)
+		expect(out.mode).toBe('vector')
+		expect(out.chunks).toEqual(results)
+		expect(typeof out.durationMs).toBe('number')
+	})
+})
+
+describe('DefaultRetriever — query expansion', () => {
+	it('when recentMessages exists, appends "Context: " + last 3 joined', async () => {
+		const store = makeStore([])
+		const emb = makeEmbedder()
+		const retriever = new DefaultRetriever(store, emb, { mode: 'vector', topK: 3 })
+
+		const out = await retriever.retrieve(
+			{ text: 'query', recentMessages: ['m1', 'm2', 'm3', 'm4'] },
+			scope,
+		)
+		expect(out.expandedQuery).toBe('query\n\nContext: m2 m3 m4')
+		expect(emb.embedQuery).toHaveBeenCalledWith('query\n\nContext: m2 m3 m4')
+	})
+
+	it('when no recentMessages, expandedQuery is undefined (original == expanded)', async () => {
+		const store = makeStore([])
+		const retriever = new DefaultRetriever(store, makeEmbedder(), {
+			mode: 'vector',
+			topK: 3,
+		})
+		const out = await retriever.retrieve({ text: 'plain' }, scope)
+		expect(out.expandedQuery).toBeUndefined()
+	})
+})
+
+describe('DefaultRetriever — keyword mode', () => {
+	it('fetches 2*topK from store, rescores via BM25, slices to topK', async () => {
+		// 6 candidate chunks (topK * 2 with topK=3) — retriever requests 2*topK with minScore 0.
+		const store = makeStore([
+			r('a', 'apple orange', 0.1),
+			r('b', 'banana apple apple', 0.1),
+			r('c', 'unrelated text', 0.1),
+			r('d', 'apple apple apple', 0.1),
+			r('e', 'nothing here', 0.1),
+			r('f', 'apple', 0.1),
+		])
+		const retriever = new DefaultRetriever(store, makeEmbedder(), {
+			mode: 'keyword',
+			topK: 3,
+		})
+		const out = await retriever.retrieve({ text: 'apple' }, scope)
+		expect(out.chunks.length).toBeLessThanOrEqual(3)
+		expect(out.chunks.every((c) => c.score > 0)).toBe(true)
+		// Tokenization: 'nothing' + 'here' — doesn't contain 'apple' → score 0 → filtered.
+		expect(out.chunks.every((c) => c.chunk.id !== ('e' as ChunkId))).toBe(true)
+	})
+
+	it('query store is called with minScore: 0 + topK*2', async () => {
+		const store = makeStore([r('a', 'apple', 0.5)])
+		const retriever = new DefaultRetriever(store, makeEmbedder(), {
+			mode: 'keyword',
+			topK: 2,
+		})
+		await retriever.retrieve({ text: 'apple' }, scope)
+		expect(store.search).toHaveBeenCalledWith(expect.objectContaining({ topK: 4, minScore: 0 }))
+	})
+})
+
+describe('DefaultRetriever — hybrid mode', () => {
+	it('merges by chunk.id, weighted by alpha (default 0.7)', async () => {
+		const store = makeStore([r('a', 'apple', 1), r('b', 'banana', 0.5)])
+		const retriever = new DefaultRetriever(store, makeEmbedder(), {
+			mode: 'hybrid',
+			topK: 5,
+		})
+		const out = await retriever.retrieve({ text: 'apple' }, scope)
+		// Vector side: a=0.7, b=0.35. Keyword side (BM25): a matches → >0; b=0.
+		// Hybrid: a stays high; b gets only vector weight.
+		expect(out.chunks[0]?.chunk.id).toBe('a')
+	})
+
+	it('chunks in only one side still appear with partial weight', async () => {
+		const store = makeStore([r('a', 'apple', 1)])
+		const retriever = new DefaultRetriever(store, makeEmbedder(), {
+			mode: 'hybrid',
+			topK: 5,
+		})
+		const out = await retriever.retrieve({ text: 'apple' }, scope)
+		expect(out.chunks.length).toBe(1)
+		expect(out.chunks[0]?.score).toBeGreaterThan(0)
+	})
+})
+
+describe('DefaultRetriever — config merge', () => {
+	it('query.config overrides instance config per-call', async () => {
+		const store = makeStore([r('a', 'x', 0.9)])
+		const retriever = new DefaultRetriever(store, makeEmbedder(), {
+			mode: 'vector',
+			topK: 5,
+		})
+		await retriever.retrieve({ text: 'hi', config: { topK: 1 } }, scope)
+		expect(store.search).toHaveBeenCalledWith(expect.objectContaining({ topK: 1 }))
+	})
+})

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/)
+		})
+	})
+})