@namzu/sdk 0.4.1 → 0.4.3

package/dist/rag/retriever.test.js

@@ -0,0 +1,180 @@
+/**
+ * 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 { DefaultRetriever } from './retriever.js';
+const TENANT = 't_1';
+const KB = 'kb_1';
+const scope = { tenantId: TENANT };
+function chunk(id, content) {
+    return {
+        id: id,
+        documentId: 'doc_1',
+        knowledgeBaseId: KB,
+        tenantId: TENANT,
+        content,
+        index: 0,
+        tokenCount: 0,
+        embedding: [1, 0, 0],
+        metadata: {},
+        createdAt: 0,
+    };
+}
+function r(id, content, score) {
+    return { chunk: chunk(id, content), score };
+}
+function makeStore(searchResults) {
+    return {
+        search: vi.fn(async () => searchResults),
+        upsert: vi.fn(),
+        delete: vi.fn(),
+        deleteByDocument: vi.fn(),
+        deleteByKnowledgeBase: vi.fn(),
+    };
+}
+function makeEmbedder() {
+    return {
+        id: 'mock',
+        model: 'x',
+        dimensions: 3,
+        embed: vi.fn(async (texts) => 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')).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 }));
+    });
+});
+//# sourceMappingURL=retriever.test.js.map

package/dist/rag/retriever.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retriever.test.js","sourceRoot":"","sources":["../../src/rag/retriever.test.ts"],"names":[],"mappings":"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"}

package/dist/rag/vector-store.test.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=vector-store.test.d.ts.map

package/dist/rag/vector-store.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store.test.d.ts","sourceRoot":"","sources":["../../src/rag/vector-store.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG"}

package/dist/rag/vector-store.test.js

@@ -0,0 +1,175 @@
+/**
+ * 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 { InMemoryVectorStore, cosineSimilarity } from './vector-store.js';
+const T1 = 'tenant_1';
+const T2 = 'tenant_2';
+const KB1 = 'kb_1';
+const KB2 = 'kb_2';
+const D1 = 'doc_1';
+const D2 = 'doc_2';
+function chunk(id, overrides = {}) {
+    return {
+        id: id,
+        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 = {
+    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', 'missing']);
+        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);
+    });
+});
+//# sourceMappingURL=vector-store.test.js.map

package/dist/rag/vector-store.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store.test.js","sourceRoot":"","sources":["../../src/rag/vector-store.test.ts"],"names":[],"mappings":"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"}

package/dist/registry/ManagedRegistry.test.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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).
+ */
+export {};
+//# sourceMappingURL=ManagedRegistry.test.d.ts.map

package/dist/registry/ManagedRegistry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ManagedRegistry.test.d.ts","sourceRoot":"","sources":["../../src/registry/ManagedRegistry.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/registry/ManagedRegistry.test.js

@@ -0,0 +1,98 @@
+/**
+ * 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 { ManagedRegistry } from './ManagedRegistry.js';
+function makeLogger() {
+    const self = {
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        debug: vi.fn(),
+        child: vi.fn(),
+    };
+    self.child = vi.fn(() => self);
+    return self;
+}
+describe('ManagedRegistry', () => {
+    describe('register (2-arg form)', () => {
+        it('throws when called with (id) only', () => {
+            const r = new ManagedRegistry({ componentName: 't' });
+            // biome-ignore lint/suspicious/noExplicitAny: exercises the no-item-arg path
+            expect(() => r.register('a')).toThrow(/requires an item argument/);
+        });
+        it('warn-logs then overwrites on duplicate id', () => {
+            const logger = makeLogger();
+            const r = new ManagedRegistry({ 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({ 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({
+                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({ 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({ 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({ 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({ 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/);
+        });
+    });
+});
+//# sourceMappingURL=ManagedRegistry.test.js.map

package/dist/registry/ManagedRegistry.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ManagedRegistry.test.js","sourceRoot":"","sources":["../../src/registry/ManagedRegistry.test.ts"],"names":[],"mappings":"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"}

package/dist/registry/Registry.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=Registry.test.d.ts.map

package/dist/registry/Registry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Registry.test.d.ts","sourceRoot":"","sources":["../../src/registry/Registry.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}