@fgv/ts-agent-memory 5.1.0-36

package/lib/test/unit/types/identityCodec.test.js

@@ -0,0 +1,189 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+require("@fgv/ts-utils-jest");
+const types_1 = require("../../../packlets/types");
+describe('assertPortableFilenameStem', () => {
+    test('accepts a POSIX portable filename stem', () => {
+        expect((0, types_1.assertPortableFilenameStem)('intro-to-rust.v2')).toSucceedWith('intro-to-rust.v2');
+    });
+    test('rejects an empty stem', () => {
+        expect((0, types_1.assertPortableFilenameStem)('')).toFailWith(/must be a non-empty string/i);
+    });
+    test('rejects a leading dot', () => {
+        expect((0, types_1.assertPortableFilenameStem)('.hidden')).toFailWith(/may not begin with '\.'/i);
+    });
+    test('rejects a trailing dot (Windows strips trailing dots)', () => {
+        expect((0, types_1.assertPortableFilenameStem)('topic.')).toFailWith(/may not end with '\.'/i);
+    });
+    test('rejects characters outside the portable set', () => {
+        expect((0, types_1.assertPortableFilenameStem)('has/slash')).toFailWith(/POSIX portable filename set/i);
+        expect((0, types_1.assertPortableFilenameStem)('has space')).toFailWith(/POSIX portable filename set/i);
+    });
+    test('rejects a reserved Windows device basename (case-insensitive, with extension)', () => {
+        expect((0, types_1.assertPortableFilenameStem)('CON')).toFailWith(/reserved Windows device name/i);
+        expect((0, types_1.assertPortableFilenameStem)('con.md')).toFailWith(/reserved Windows device name/i);
+        expect((0, types_1.assertPortableFilenameStem)('COM1')).toFailWith(/reserved Windows device name/i);
+        expect((0, types_1.assertPortableFilenameStem)('lpt0.txt')).toFailWith(/reserved Windows device name/i);
+    });
+    test('rejects the 0-suffixed device variants (Windows 11 / Server 2022)', () => {
+        expect((0, types_1.assertPortableFilenameStem)('COM0')).toFailWith(/reserved Windows device name/i);
+        expect((0, types_1.assertPortableFilenameStem)('LPT0')).toFailWith(/reserved Windows device name/i);
+        expect((0, types_1.assertPortableFilenameStem)('COM9')).toFailWith(/reserved Windows device name/i);
+    });
+});
+describe('KnowledgeIdentityCodec', () => {
+    const codec = new types_1.KnowledgeIdentityCodec();
+    const knowledgeScope = types_1.KnowledgeIdentityCodec.scope;
+    describe('encode', () => {
+        test('maps a docId to the flat knowledge scope, passthrough stem, non-versioned', () => {
+            expect(codec.encode('intro-to-rust')).toSucceedWith({
+                scope: knowledgeScope,
+                idStem: 'intro-to-rust',
+                isVersioned: false
+            });
+        });
+        test('fails when the docId is not filename-safe', () => {
+            expect(codec.encode('bad/id')).toFailWith(/POSIX portable filename set/i);
+        });
+    });
+    describe('decode', () => {
+        test('recovers the EntityId from a valid address', () => {
+            expect(codec.decode(knowledgeScope, 'intro-to-rust')).toSucceedWith('intro-to-rust');
+        });
+        test('fails when the scope is not the knowledge scope', () => {
+            expect(codec.decode('conversations', 'intro-to-rust')).toFailWith(/does not match expected scope 'knowledge'/i);
+        });
+        test('fails when the stem is not filename-safe', () => {
+            expect(codec.decode(knowledgeScope, 'bad stem')).toFailWith(/POSIX portable filename set/i);
+        });
+    });
+    describe('verifyRoundTrip', () => {
+        test('succeeds for a stem that decodes and re-encodes cleanly', () => {
+            expect(codec.verifyRoundTrip(knowledgeScope, 'intro-to-rust')).toSucceedWith(true);
+        });
+        test('fails when the stem cannot be decoded', () => {
+            expect(codec.verifyRoundTrip(knowledgeScope, 'bad stem')).toFailWith(/POSIX portable filename set/i);
+        });
+        test('fails when the scope does not match', () => {
+            expect(codec.verifyRoundTrip('conversations', 'intro-to-rust')).toFailWith(/does not match expected scope/i);
+        });
+    });
+    test('the fixed knowledge scope is a valid MemoryScopeKey', () => {
+        expect(types_1.Convert.scopeKey.convert(types_1.KnowledgeIdentityCodec.scope)).toSucceedWith(knowledgeScope);
+    });
+});
+describe('LtmIdentityCodec', () => {
+    const codec = new types_1.LtmIdentityCodec();
+    const conversationsScope = types_1.LtmIdentityCodec.scope;
+    describe('encode', () => {
+        test('maps a conversationId to the flat conversations scope, passthrough stem, non-versioned', () => {
+            expect(codec.encode('conv-42')).toSucceedWith({
+                scope: conversationsScope,
+                idStem: 'conv-42',
+                isVersioned: false
+            });
+        });
+        test('fails when the conversationId is not filename-safe', () => {
+            expect(codec.encode('conv/42')).toFailWith(/POSIX portable filename set/i);
+        });
+    });
+    describe('decode', () => {
+        test('recovers the EntityId from a valid address', () => {
+            expect(codec.decode(conversationsScope, 'conv-42')).toSucceedWith('conv-42');
+        });
+        test('fails when the scope is not the conversations scope', () => {
+            expect(codec.decode('knowledge', 'conv-42')).toFailWith(/does not match expected scope 'conversations'/i);
+        });
+        test('fails when the stem is not filename-safe', () => {
+            expect(codec.decode(conversationsScope, 'bad stem')).toFailWith(/POSIX portable filename set/i);
+        });
+    });
+    describe('verifyRoundTrip', () => {
+        test('succeeds for a stem that decodes and re-encodes cleanly', () => {
+            expect(codec.verifyRoundTrip(conversationsScope, 'conv-42')).toSucceedWith(true);
+        });
+        test('fails when the scope does not match', () => {
+            expect(codec.verifyRoundTrip('knowledge', 'conv-42')).toFailWith(/does not match expected scope/i);
+        });
+    });
+    test('the fixed conversations scope is a valid MemoryScopeKey', () => {
+        expect(types_1.Convert.scopeKey.convert(types_1.LtmIdentityCodec.scope)).toSucceedWith(conversationsScope);
+    });
+});
+describe('MtmIdentityCodec', () => {
+    const codec = new types_1.MtmIdentityCodec();
+    describe('encode', () => {
+        test('maps a <conversationId>:<turnIndex> composite to a per-conversation subtree', () => {
+            expect(codec.encode('conv-1:5')).toSucceedWith({
+                scope: 'conversations/conv-1',
+                idStem: 'turn-5',
+                isVersioned: false
+            });
+        });
+        test('preserves the turn index verbatim (turn 0)', () => {
+            expect(codec.encode('conv-1:0')).toSucceedWith({
+                scope: 'conversations/conv-1',
+                idStem: 'turn-0',
+                isVersioned: false
+            });
+        });
+        test('fails when the entity id is not a colon composite', () => {
+            expect(codec.encode('conv-1')).toFailWith(/must be a '<conversationId>:<turnIndex>'/i);
+        });
+        test('fails when the entity id has more than two segments', () => {
+            expect(codec.encode('conv-1:5:extra')).toFailWith(/must be a '<conversationId>:<turnIndex>'/i);
+        });
+        test('fails when the conversationId is not filename-safe', () => {
+            expect(codec.encode('bad id:5')).toFailWith(/conversationId.*POSIX portable filename set/i);
+        });
+        test('fails when the turn index is not a non-negative integer', () => {
+            expect(codec.encode('conv-1:x')).toFailWith(/turnIndex 'x' must be a non-negative integer/i);
+            expect(codec.encode('conv-1:-1')).toFailWith(/must be a non-negative integer/i);
+            expect(codec.encode('conv-1:1.5')).toFailWith(/must be a non-negative integer/i);
+        });
+    });
+    describe('decode', () => {
+        test('reverses the scope + stem to the composite entity id', () => {
+            expect(codec.decode('conversations/conv-1', 'turn-5')).toSucceedWith('conv-1:5');
+        });
+        test('fails when the scope is a single segment', () => {
+            expect(codec.decode('conversations', 'turn-5')).toFailWith(/must be 'conversations\/<conversationId>'/i);
+        });
+        test('fails when the scope root segment is wrong', () => {
+            expect(codec.decode('knowledge/conv-1', 'turn-5')).toFailWith(/must be 'conversations\/<conversationId>'/i);
+        });
+        test('fails when the scope has too many segments', () => {
+            expect(codec.decode('conversations/conv-1/extra', 'turn-5')).toFailWith(/must be 'conversations\/<conversationId>'/i);
+        });
+        test('fails when the conversationId in the scope is not filename-safe', () => {
+            expect(codec.decode('conversations/bad id', 'turn-5')).toFailWith(/conversationId.*POSIX portable filename set/i);
+        });
+        test('fails when the stem does not have the turn- prefix', () => {
+            expect(codec.decode('conversations/conv-1', 'message-5')).toFailWith(/must begin with 'turn-'/i);
+        });
+        test('fails when the stem turn index is not an integer', () => {
+            expect(codec.decode('conversations/conv-1', 'turn-x')).toFailWith(/must be a non-negative integer/i);
+        });
+    });
+    describe('verifyRoundTrip', () => {
+        test('succeeds for a composite key under a conversations/<id> scope', () => {
+            expect(codec.verifyRoundTrip('conversations/conv-1', 'turn-5')).toSucceedWith(true);
+        });
+        test('fails when the scope is malformed', () => {
+            expect(codec.verifyRoundTrip('conversations', 'turn-5')).toFailWith(/must be 'conversations\/<conversationId>'/i);
+        });
+    });
+    test('encode/decode round-trips the composite key and the conversations/<id> scope', () => {
+        const entityId = 'conv-9:17';
+        expect(codec.encode(entityId)).toSucceedAndSatisfy((addr) => {
+            expect(addr.scope).toBe('conversations/conv-9');
+            expect(addr.idStem).toBe('turn-17');
+            expect(codec.decode(addr.scope, addr.idStem)).toSucceedWith(entityId);
+        });
+    });
+});
+//# sourceMappingURL=identityCodec.test.js.map

package/lib/test/unit/types/identityCodec.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identityCodec.test.js","sourceRoot":"","sources":["../../../../src/test/unit/types/identityCodec.test.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport '@fgv/ts-utils-jest';\nimport {\n  Convert,\n  EntityId,\n  KnowledgeIdentityCodec,\n  LtmIdentityCodec,\n  MemoryScopeKey,\n  MtmIdentityCodec,\n  assertPortableFilenameStem\n} from '../../../packlets/types';\n\ndescribe('assertPortableFilenameStem', () => {\n  test('accepts a POSIX portable filename stem', () => {\n    expect(assertPortableFilenameStem('intro-to-rust.v2')).toSucceedWith('intro-to-rust.v2');\n  });\n\n  test('rejects an empty stem', () => {\n    expect(assertPortableFilenameStem('')).toFailWith(/must be a non-empty string/i);\n  });\n\n  test('rejects a leading dot', () => {\n    expect(assertPortableFilenameStem('.hidden')).toFailWith(/may not begin with '\\.'/i);\n  });\n\n  test('rejects a trailing dot (Windows strips trailing dots)', () => {\n    expect(assertPortableFilenameStem('topic.')).toFailWith(/may not end with '\\.'/i);\n  });\n\n  test('rejects characters outside the portable set', () => {\n    expect(assertPortableFilenameStem('has/slash')).toFailWith(/POSIX portable filename set/i);\n    expect(assertPortableFilenameStem('has space')).toFailWith(/POSIX portable filename set/i);\n  });\n\n  test('rejects a reserved Windows device basename (case-insensitive, with extension)', () => {\n    expect(assertPortableFilenameStem('CON')).toFailWith(/reserved Windows device name/i);\n    expect(assertPortableFilenameStem('con.md')).toFailWith(/reserved Windows device name/i);\n    expect(assertPortableFilenameStem('COM1')).toFailWith(/reserved Windows device name/i);\n    expect(assertPortableFilenameStem('lpt0.txt')).toFailWith(/reserved Windows device name/i);\n  });\n\n  test('rejects the 0-suffixed device variants (Windows 11 / Server 2022)', () => {\n    expect(assertPortableFilenameStem('COM0')).toFailWith(/reserved Windows device name/i);\n    expect(assertPortableFilenameStem('LPT0')).toFailWith(/reserved Windows device name/i);\n    expect(assertPortableFilenameStem('COM9')).toFailWith(/reserved Windows device name/i);\n  });\n});\n\ndescribe('KnowledgeIdentityCodec', () => {\n  const codec: KnowledgeIdentityCodec = new KnowledgeIdentityCodec();\n  const knowledgeScope: MemoryScopeKey = KnowledgeIdentityCodec.scope;\n\n  describe('encode', () => {\n    test('maps a docId to the flat knowledge scope, passthrough stem, non-versioned', () => {\n      expect(codec.encode('intro-to-rust' as EntityId)).toSucceedWith({\n        scope: knowledgeScope,\n        idStem: 'intro-to-rust',\n        isVersioned: false\n      });\n    });\n\n    test('fails when the docId is not filename-safe', () => {\n      expect(codec.encode('bad/id' as EntityId)).toFailWith(/POSIX portable filename set/i);\n    });\n  });\n\n  describe('decode', () => {\n    test('recovers the EntityId from a valid address', () => {\n      expect(codec.decode(knowledgeScope, 'intro-to-rust')).toSucceedWith('intro-to-rust' as EntityId);\n    });\n\n    test('fails when the scope is not the knowledge scope', () => {\n      expect(codec.decode('conversations' as MemoryScopeKey, 'intro-to-rust')).toFailWith(\n        /does not match expected scope 'knowledge'/i\n      );\n    });\n\n    test('fails when the stem is not filename-safe', () => {\n      expect(codec.decode(knowledgeScope, 'bad stem')).toFailWith(/POSIX portable filename set/i);\n    });\n  });\n\n  describe('verifyRoundTrip', () => {\n    test('succeeds for a stem that decodes and re-encodes cleanly', () => {\n      expect(codec.verifyRoundTrip(knowledgeScope, 'intro-to-rust')).toSucceedWith(true);\n    });\n\n    test('fails when the stem cannot be decoded', () => {\n      expect(codec.verifyRoundTrip(knowledgeScope, 'bad stem')).toFailWith(/POSIX portable filename set/i);\n    });\n\n    test('fails when the scope does not match', () => {\n      expect(codec.verifyRoundTrip('conversations' as MemoryScopeKey, 'intro-to-rust')).toFailWith(\n        /does not match expected scope/i\n      );\n    });\n  });\n\n  test('the fixed knowledge scope is a valid MemoryScopeKey', () => {\n    expect(Convert.scopeKey.convert(KnowledgeIdentityCodec.scope)).toSucceedWith(knowledgeScope as never);\n  });\n});\n\ndescribe('LtmIdentityCodec', () => {\n  const codec: LtmIdentityCodec = new LtmIdentityCodec();\n  const conversationsScope: MemoryScopeKey = LtmIdentityCodec.scope;\n\n  describe('encode', () => {\n    test('maps a conversationId to the flat conversations scope, passthrough stem, non-versioned', () => {\n      expect(codec.encode('conv-42' as EntityId)).toSucceedWith({\n        scope: conversationsScope,\n        idStem: 'conv-42',\n        isVersioned: false\n      });\n    });\n\n    test('fails when the conversationId is not filename-safe', () => {\n      expect(codec.encode('conv/42' as EntityId)).toFailWith(/POSIX portable filename set/i);\n    });\n  });\n\n  describe('decode', () => {\n    test('recovers the EntityId from a valid address', () => {\n      expect(codec.decode(conversationsScope, 'conv-42')).toSucceedWith('conv-42' as EntityId);\n    });\n\n    test('fails when the scope is not the conversations scope', () => {\n      expect(codec.decode('knowledge' as MemoryScopeKey, 'conv-42')).toFailWith(\n        /does not match expected scope 'conversations'/i\n      );\n    });\n\n    test('fails when the stem is not filename-safe', () => {\n      expect(codec.decode(conversationsScope, 'bad stem')).toFailWith(/POSIX portable filename set/i);\n    });\n  });\n\n  describe('verifyRoundTrip', () => {\n    test('succeeds for a stem that decodes and re-encodes cleanly', () => {\n      expect(codec.verifyRoundTrip(conversationsScope, 'conv-42')).toSucceedWith(true);\n    });\n\n    test('fails when the scope does not match', () => {\n      expect(codec.verifyRoundTrip('knowledge' as MemoryScopeKey, 'conv-42')).toFailWith(\n        /does not match expected scope/i\n      );\n    });\n  });\n\n  test('the fixed conversations scope is a valid MemoryScopeKey', () => {\n    expect(Convert.scopeKey.convert(LtmIdentityCodec.scope)).toSucceedWith(conversationsScope as never);\n  });\n});\n\ndescribe('MtmIdentityCodec', () => {\n  const codec: MtmIdentityCodec = new MtmIdentityCodec();\n\n  describe('encode', () => {\n    test('maps a <conversationId>:<turnIndex> composite to a per-conversation subtree', () => {\n      expect(codec.encode('conv-1:5' as EntityId)).toSucceedWith({\n        scope: 'conversations/conv-1' as MemoryScopeKey,\n        idStem: 'turn-5',\n        isVersioned: false\n      });\n    });\n\n    test('preserves the turn index verbatim (turn 0)', () => {\n      expect(codec.encode('conv-1:0' as EntityId)).toSucceedWith({\n        scope: 'conversations/conv-1' as MemoryScopeKey,\n        idStem: 'turn-0',\n        isVersioned: false\n      });\n    });\n\n    test('fails when the entity id is not a colon composite', () => {\n      expect(codec.encode('conv-1' as EntityId)).toFailWith(/must be a '<conversationId>:<turnIndex>'/i);\n    });\n\n    test('fails when the entity id has more than two segments', () => {\n      expect(codec.encode('conv-1:5:extra' as EntityId)).toFailWith(\n        /must be a '<conversationId>:<turnIndex>'/i\n      );\n    });\n\n    test('fails when the conversationId is not filename-safe', () => {\n      expect(codec.encode('bad id:5' as EntityId)).toFailWith(/conversationId.*POSIX portable filename set/i);\n    });\n\n    test('fails when the turn index is not a non-negative integer', () => {\n      expect(codec.encode('conv-1:x' as EntityId)).toFailWith(\n        /turnIndex 'x' must be a non-negative integer/i\n      );\n      expect(codec.encode('conv-1:-1' as EntityId)).toFailWith(/must be a non-negative integer/i);\n      expect(codec.encode('conv-1:1.5' as EntityId)).toFailWith(/must be a non-negative integer/i);\n    });\n  });\n\n  describe('decode', () => {\n    test('reverses the scope + stem to the composite entity id', () => {\n      expect(codec.decode('conversations/conv-1' as MemoryScopeKey, 'turn-5')).toSucceedWith(\n        'conv-1:5' as EntityId\n      );\n    });\n\n    test('fails when the scope is a single segment', () => {\n      expect(codec.decode('conversations' as MemoryScopeKey, 'turn-5')).toFailWith(\n        /must be 'conversations\\/<conversationId>'/i\n      );\n    });\n\n    test('fails when the scope root segment is wrong', () => {\n      expect(codec.decode('knowledge/conv-1' as MemoryScopeKey, 'turn-5')).toFailWith(\n        /must be 'conversations\\/<conversationId>'/i\n      );\n    });\n\n    test('fails when the scope has too many segments', () => {\n      expect(codec.decode('conversations/conv-1/extra' as MemoryScopeKey, 'turn-5')).toFailWith(\n        /must be 'conversations\\/<conversationId>'/i\n      );\n    });\n\n    test('fails when the conversationId in the scope is not filename-safe', () => {\n      expect(codec.decode('conversations/bad id' as MemoryScopeKey, 'turn-5')).toFailWith(\n        /conversationId.*POSIX portable filename set/i\n      );\n    });\n\n    test('fails when the stem does not have the turn- prefix', () => {\n      expect(codec.decode('conversations/conv-1' as MemoryScopeKey, 'message-5')).toFailWith(\n        /must begin with 'turn-'/i\n      );\n    });\n\n    test('fails when the stem turn index is not an integer', () => {\n      expect(codec.decode('conversations/conv-1' as MemoryScopeKey, 'turn-x')).toFailWith(\n        /must be a non-negative integer/i\n      );\n    });\n  });\n\n  describe('verifyRoundTrip', () => {\n    test('succeeds for a composite key under a conversations/<id> scope', () => {\n      expect(codec.verifyRoundTrip('conversations/conv-1' as MemoryScopeKey, 'turn-5')).toSucceedWith(true);\n    });\n\n    test('fails when the scope is malformed', () => {\n      expect(codec.verifyRoundTrip('conversations' as MemoryScopeKey, 'turn-5')).toFailWith(\n        /must be 'conversations\\/<conversationId>'/i\n      );\n    });\n  });\n\n  test('encode/decode round-trips the composite key and the conversations/<id> scope', () => {\n    const entityId: EntityId = 'conv-9:17' as EntityId;\n    expect(codec.encode(entityId)).toSucceedAndSatisfy((addr) => {\n      expect(addr.scope).toBe('conversations/conv-9');\n      expect(addr.idStem).toBe('turn-17');\n      expect(codec.decode(addr.scope, addr.idStem)).toSucceedWith(entityId);\n    });\n  });\n});\n"]}

package/lib/test/unit/types/ids.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=ids.test.d.ts.map

package/lib/test/unit/types/ids.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.test.d.ts","sourceRoot":"","sources":["../../../../src/test/unit/types/ids.test.ts"],"names":[],"mappings":"AAKA,OAAO,oBAAoB,CAAC"}

package/lib/test/unit/types/ids.test.js

@@ -0,0 +1,86 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+require("@fgv/ts-utils-jest");
+const types_1 = require("../../../packlets/types");
+describe('branded id converters', () => {
+    describe('shared hygiene', () => {
+        test.each([
+            ['memoryId', types_1.Convert.memoryId],
+            ['entityId', types_1.Convert.entityId],
+            ['kind', types_1.Convert.kind],
+            ['tag', types_1.Convert.tag],
+            ['scopeKey', types_1.Convert.scopeKey],
+            ['linkType', types_1.Convert.linkType]
+        ])('%s rejects an empty string', (__name, converter) => {
+            expect(converter.convert('')).toFailWith(/must be a non-empty string/i);
+        });
+        test.each([
+            ['memoryId', types_1.Convert.memoryId],
+            ['entityId', types_1.Convert.entityId],
+            ['kind', types_1.Convert.kind],
+            ['tag', types_1.Convert.tag],
+            ['scopeKey', types_1.Convert.scopeKey],
+            ['linkType', types_1.Convert.linkType]
+        ])('%s rejects a value over the length cap', (__name, converter) => {
+            expect(converter.convert('a'.repeat(257))).toFailWith(/exceeds maximum length 256/i);
+        });
+        test.each([
+            ['memoryId', types_1.Convert.memoryId],
+            ['entityId', types_1.Convert.entityId],
+            ['kind', types_1.Convert.kind],
+            ['tag', types_1.Convert.tag],
+            ['scopeKey', types_1.Convert.scopeKey],
+            ['linkType', types_1.Convert.linkType]
+        ])('%s rejects leading/trailing whitespace', (__name, converter) => {
+            expect(converter.convert(' value ')).toFailWith(/leading or trailing whitespace/i);
+        });
+        test.each([
+            ['memoryId', types_1.Convert.memoryId],
+            ['entityId', types_1.Convert.entityId],
+            ['kind', types_1.Convert.kind],
+            ['tag', types_1.Convert.tag],
+            ['scopeKey', types_1.Convert.scopeKey],
+            ['linkType', types_1.Convert.linkType]
+        ])('%s rejects a non-string', (__name, converter) => {
+            expect(converter.convert(42)).toFail();
+        });
+        test.each([
+            ['memoryId', types_1.Convert.memoryId, 'doc-123'],
+            ['entityId', types_1.Convert.entityId, 'doc-123'],
+            ['kind', types_1.Convert.kind, 'knowledge'],
+            ['tag', types_1.Convert.tag, 'topic:rust'],
+            ['scopeKey', types_1.Convert.scopeKey, 'knowledge'],
+            ['linkType', types_1.Convert.linkType, 'mtm-ref']
+        ])('%s accepts a valid value at the length cap boundary', (__name, converter, value) => {
+            expect(converter.convert(value)).toSucceedWith(value);
+            expect(converter.convert('a'.repeat(256))).toSucceedWith('a'.repeat(256));
+        });
+    });
+    describe('relaxed-constraint brands', () => {
+        test('scopeKey accepts a multi-segment, slash-separated path', () => {
+            expect(types_1.Convert.scopeKey.convert('conversations/conv-1')).toSucceedWith('conversations/conv-1');
+        });
+        test('entityId accepts a colon-separated composite key', () => {
+            expect(types_1.Convert.entityId.convert('conv-1:7')).toSucceedWith('conv-1:7');
+        });
+    });
+    describe('memoryId filename-stem constraint', () => {
+        test('accepts a portable filename stem', () => {
+            expect(types_1.Convert.memoryId.convert('intro-to-rust.v2')).toSucceedWith('intro-to-rust.v2');
+        });
+        test('rejects path-unsafe ids that the relaxed brands accept (id IS the filename stem)', () => {
+            expect(types_1.Convert.memoryId.convert('a/b')).toFailWith(/POSIX portable filename set/i);
+            expect(types_1.Convert.memoryId.convert('conv-1:7')).toFailWith(/POSIX portable filename set/i);
+            // sanity: EntityId stays relaxed for the same composite domain key
+            expect(types_1.Convert.entityId.convert('conv-1:7')).toSucceed();
+        });
+        test('still applies the shared hygiene before the stem check', () => {
+            expect(types_1.Convert.memoryId.convert('')).toFailWith(/must be a non-empty string/i);
+        });
+    });
+});
+//# sourceMappingURL=ids.test.js.map

package/lib/test/unit/types/ids.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.test.js","sourceRoot":"","sources":["../../../../src/test/unit/types/ids.test.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport '@fgv/ts-utils-jest';\nimport { Convert } from '../../../packlets/types';\n\ndescribe('branded id converters', () => {\n  describe('shared hygiene', () => {\n    test.each([\n      ['memoryId', Convert.memoryId],\n      ['entityId', Convert.entityId],\n      ['kind', Convert.kind],\n      ['tag', Convert.tag],\n      ['scopeKey', Convert.scopeKey],\n      ['linkType', Convert.linkType]\n    ] as const)('%s rejects an empty string', (__name, converter) => {\n      expect(converter.convert('')).toFailWith(/must be a non-empty string/i);\n    });\n\n    test.each([\n      ['memoryId', Convert.memoryId],\n      ['entityId', Convert.entityId],\n      ['kind', Convert.kind],\n      ['tag', Convert.tag],\n      ['scopeKey', Convert.scopeKey],\n      ['linkType', Convert.linkType]\n    ] as const)('%s rejects a value over the length cap', (__name, converter) => {\n      expect(converter.convert('a'.repeat(257))).toFailWith(/exceeds maximum length 256/i);\n    });\n\n    test.each([\n      ['memoryId', Convert.memoryId],\n      ['entityId', Convert.entityId],\n      ['kind', Convert.kind],\n      ['tag', Convert.tag],\n      ['scopeKey', Convert.scopeKey],\n      ['linkType', Convert.linkType]\n    ] as const)('%s rejects leading/trailing whitespace', (__name, converter) => {\n      expect(converter.convert(' value ')).toFailWith(/leading or trailing whitespace/i);\n    });\n\n    test.each([\n      ['memoryId', Convert.memoryId],\n      ['entityId', Convert.entityId],\n      ['kind', Convert.kind],\n      ['tag', Convert.tag],\n      ['scopeKey', Convert.scopeKey],\n      ['linkType', Convert.linkType]\n    ] as const)('%s rejects a non-string', (__name, converter) => {\n      expect(converter.convert(42)).toFail();\n    });\n\n    test.each([\n      ['memoryId', Convert.memoryId, 'doc-123'],\n      ['entityId', Convert.entityId, 'doc-123'],\n      ['kind', Convert.kind, 'knowledge'],\n      ['tag', Convert.tag, 'topic:rust'],\n      ['scopeKey', Convert.scopeKey, 'knowledge'],\n      ['linkType', Convert.linkType, 'mtm-ref']\n    ] as const)('%s accepts a valid value at the length cap boundary', (__name, converter, value) => {\n      expect(converter.convert(value)).toSucceedWith(value as never);\n      expect(converter.convert('a'.repeat(256))).toSucceedWith('a'.repeat(256) as never);\n    });\n  });\n\n  describe('relaxed-constraint brands', () => {\n    test('scopeKey accepts a multi-segment, slash-separated path', () => {\n      expect(Convert.scopeKey.convert('conversations/conv-1')).toSucceedWith('conversations/conv-1' as never);\n    });\n\n    test('entityId accepts a colon-separated composite key', () => {\n      expect(Convert.entityId.convert('conv-1:7')).toSucceedWith('conv-1:7' as never);\n    });\n  });\n\n  describe('memoryId filename-stem constraint', () => {\n    test('accepts a portable filename stem', () => {\n      expect(Convert.memoryId.convert('intro-to-rust.v2')).toSucceedWith('intro-to-rust.v2' as never);\n    });\n\n    test('rejects path-unsafe ids that the relaxed brands accept (id IS the filename stem)', () => {\n      expect(Convert.memoryId.convert('a/b')).toFailWith(/POSIX portable filename set/i);\n      expect(Convert.memoryId.convert('conv-1:7')).toFailWith(/POSIX portable filename set/i);\n      // sanity: EntityId stays relaxed for the same composite domain key\n      expect(Convert.entityId.convert('conv-1:7')).toSucceed();\n    });\n\n    test('still applies the shared hygiene before the stem check', () => {\n      expect(Convert.memoryId.convert('')).toFailWith(/must be a non-empty string/i);\n    });\n  });\n});\n"]}

package/lib/test/unit/types/writePolicy.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=writePolicy.test.d.ts.map

package/lib/test/unit/types/writePolicy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writePolicy.test.d.ts","sourceRoot":"","sources":["../../../../src/test/unit/types/writePolicy.test.ts"],"names":[],"mappings":"AAKA,OAAO,oBAAoB,CAAC"}

package/lib/test/unit/types/writePolicy.test.js

@@ -0,0 +1,243 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+require("@fgv/ts-utils-jest");
+const types_1 = require("../../../packlets/types");
+function makeRecord(overrides, body) {
+    const envelope = Object.assign({ id: 'intro-to-rust', entityId: 'intro-to-rust', kind: 'knowledge', tags: ['rust'], links: [], created: 1000, updated: 1000, seq: 1, contentHash: 'hash-1', provenance: { source: 'agent' } }, overrides);
+    return {
+        envelope,
+        body: body !== null && body !== void 0 ? body : { title: 'Intro', text: 'original' }
+    };
+}
+describe('KnowledgeLwwPolicy', () => {
+    let policy;
+    beforeEach(() => {
+        policy = types_1.KnowledgeLwwPolicy.create().orThrow();
+    });
+    test('create succeeds and exposes the knowledge mutable surface', () => {
+        expect(policy.mutableFields).toEqual(['body', 'tags', 'links', 'provenance', 'embeddingRef']);
+    });
+    test('declares content-scoped dedup (knowledge collapses identical content across ids)', () => {
+        expect(policy.dedupScope).toBe('content');
+    });
+    describe('admit', () => {
+        test('always accepts (last-write-wins, no cap)', () => {
+            expect(policy.admit(makeRecord(), [])).toSucceedWith({ decision: 'accept' });
+            expect(policy.admit(makeRecord(), [makeRecord(), makeRecord()])).toSucceedWith({
+                decision: 'accept'
+            });
+        });
+    });
+    describe('applyUpdate', () => {
+        test('deep-merges a body change', () => {
+            const existing = makeRecord(undefined, { title: 'Intro', text: 'original' });
+            expect(policy.applyUpdate(existing, { body: { text: 'revised' } })).toSucceedAndSatisfy((updated) => {
+                expect(updated.body).toEqual({ title: 'Intro', text: 'revised' });
+            });
+        });
+        test('replaces arrays wholesale (RFC-7386 array semantics)', () => {
+            const existing = makeRecord({ tags: ['rust', 'systems'] });
+            expect(policy.applyUpdate(existing, { tags: ['rust'] })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.tags).toEqual(['rust']);
+            });
+        });
+        test('deep-merges provenance and preserves untouched keys', () => {
+            const existing = makeRecord({ provenance: { source: 'agent', by: 'curator' } });
+            expect(policy.applyUpdate(existing, { provenance: { model: 'gpt' } })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.provenance).toEqual({ source: 'agent', by: 'curator', model: 'gpt' });
+            });
+        });
+        test('sets embeddingRef when present in the patch', () => {
+            const existing = makeRecord({ embeddingRef: 'vec-1' });
+            expect(policy.applyUpdate(existing, { embeddingRef: 'vec-2' })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.embeddingRef).toBe('vec-2');
+            });
+        });
+        test('clears embeddingRef (to absent) when the patch deletes it (null = delete, RFC-7386)', () => {
+            const existing = makeRecord({ embeddingRef: 'vec-1' });
+            expect(policy.applyUpdate(existing, { embeddingRef: null })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.embeddingRef).toBeUndefined();
+            });
+        });
+        test('preserves an absent embeddingRef as absent on an unrelated update (hash-stable)', () => {
+            const existing = makeRecord(); // no embeddingRef
+            expect(policy.applyUpdate(existing, { body: { text: 'revised' } })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.embeddingRef).toBeUndefined();
+            });
+        });
+        test('preserves an explicit null embeddingRef when the patch does not touch it', () => {
+            const existing = makeRecord({ embeddingRef: null });
+            expect(policy.applyUpdate(existing, { body: { text: 'revised' } })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.embeddingRef).toBeNull();
+            });
+        });
+        test('ignores patch keys outside the mutable surface', () => {
+            const existing = makeRecord();
+            expect(policy.applyUpdate(existing, { id: 'tampered', created: 9999, body: { text: 'revised' } })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.id).toBe('intro-to-rust');
+                expect(updated.envelope.created).toBe(1000);
+                expect(updated.body).toEqual({ title: 'Intro', text: 'revised' });
+            });
+        });
+        test('preserves identity and transaction-time envelope fields', () => {
+            const existing = makeRecord();
+            expect(policy.applyUpdate(existing, { tags: ['updated'] })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.id).toBe('intro-to-rust');
+                expect(updated.envelope.entityId).toBe('intro-to-rust');
+                expect(updated.envelope.kind).toBe('knowledge');
+                expect(updated.envelope.created).toBe(1000);
+                expect(updated.envelope.seq).toBe(1);
+                expect(updated.envelope.contentHash).toBe('hash-1');
+            });
+        });
+        test('fails when a patch deletes a required mutable field', () => {
+            const existing = makeRecord();
+            expect(policy.applyUpdate(existing, { body: null })).toFailWith(/may not delete required field\(s\): body/i);
+        });
+    });
+});
+describe('MemoryCapCullPolicy', () => {
+    const memoryFields = ['body', 'tags', 'links', 'provenance', 'embeddingRef'];
+    /** Build a memory record with a distinct id and creation time. */
+    function memoryRecord(id, created, body) {
+        return makeRecord({
+            id: id,
+            entityId: id,
+            kind: 'summarized-turn',
+            created,
+            updated: created
+        }, body);
+    }
+    test('create succeeds and exposes the supplied mutable surface + entity dedup scope', () => {
+        const policy = types_1.MemoryCapCullPolicy.create({ maxRecords: 3, mutableFields: memoryFields }).orThrow();
+        expect(policy.mutableFields).toEqual(memoryFields);
+        expect(policy.dedupScope).toBe('entity');
+    });
+    describe('admit', () => {
+        test('accepts unconditionally when no cap is configured', () => {
+            const policy = types_1.MemoryCapCullPolicy.create({ mutableFields: memoryFields }).orThrow();
+            const cohort = [memoryRecord('turn-0', 1), memoryRecord('turn-1', 2), memoryRecord('turn-2', 3)];
+            expect(policy.admit(memoryRecord('turn-3', 4), cohort)).toSucceedWith({ decision: 'accept' });
+        });
+        test('accepts while the cohort is below the cap', () => {
+            const policy = types_1.MemoryCapCullPolicy.create({ maxRecords: 3, mutableFields: memoryFields }).orThrow();
+            const cohort = [memoryRecord('turn-0', 1), memoryRecord('turn-1', 2)];
+            expect(policy.admit(memoryRecord('turn-2', 3), cohort)).toSucceedWith({ decision: 'accept' });
+        });
+        test('culls the single oldest (by created ascending) when the cohort is at the cap', () => {
+            const policy = types_1.MemoryCapCullPolicy.create({ maxRecords: 3, mutableFields: memoryFields }).orThrow();
+            // Deliberately out of created order to prove the sort, not the input order.
+            const cohort = [memoryRecord('turn-c', 30), memoryRecord('turn-a', 10), memoryRecord('turn-b', 20)];
+            expect(policy.admit(memoryRecord('turn-new', 40), cohort)).toSucceedWith({
+                decision: 'cull-oldest',
+                evict: ['turn-a']
+            });
+        });
+        test('culls enough oldest records to land exactly at the cap when over it', () => {
+            const policy = types_1.MemoryCapCullPolicy.create({ maxRecords: 2, mutableFields: memoryFields }).orThrow();
+            const cohort = [
+                memoryRecord('turn-a', 10),
+                memoryRecord('turn-b', 20),
+                memoryRecord('turn-c', 30),
+                memoryRecord('turn-d', 40)
+            ];
+            // cohort 4, cap 2 → evict 4 - 2 + 1 = 3 oldest, leaving 1 + the incoming = 2.
+            expect(policy.admit(memoryRecord('turn-new', 50), cohort)).toSucceedWith({
+                decision: 'cull-oldest',
+                evict: ['turn-a', 'turn-b', 'turn-c']
+            });
+        });
+    });
+    describe('applyUpdate', () => {
+        let policy;
+        beforeEach(() => {
+            policy = types_1.MemoryCapCullPolicy.create({ maxRecords: 5, mutableFields: memoryFields }).orThrow();
+        });
+        test('deep-merges a body change over the declared mutable surface', () => {
+            const existing = memoryRecord('turn-0', 1, { summary: 'first draft', turn: 0 });
+            expect(policy.applyUpdate(existing, { body: { summary: 'revised' } })).toSucceedAndSatisfy((updated) => {
+                expect(updated.body).toEqual({ summary: 'revised', turn: 0 });
+            });
+        });
+        test('replaces arrays wholesale (RFC-7386 array semantics)', () => {
+            const existing = makeRecord({
+                id: 'turn-0',
+                kind: 'summarized-turn',
+                tags: ['draft', 'pending']
+            });
+            expect(policy.applyUpdate(existing, { tags: ['final'] })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.tags).toEqual(['final']);
+            });
+        });
+        test('sets embeddingRef when present in the patch', () => {
+            const existing = makeRecord({
+                id: 'turn-0',
+                kind: 'summarized-turn',
+                embeddingRef: 'vec-1'
+            });
+            expect(policy.applyUpdate(existing, { embeddingRef: 'vec-2' })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.embeddingRef).toBe('vec-2');
+            });
+        });
+        test('clears embeddingRef (to absent) when the patch deletes it (null = delete)', () => {
+            const existing = makeRecord({
+                id: 'turn-0',
+                kind: 'summarized-turn',
+                embeddingRef: 'vec-1'
+            });
+            expect(policy.applyUpdate(existing, { embeddingRef: null })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.embeddingRef).toBeUndefined();
+            });
+        });
+        test('fails when a patch deletes a required mutable field', () => {
+            const existing = memoryRecord('turn-0', 1);
+            expect(policy.applyUpdate(existing, { tags: null })).toFailWith(/may not delete required field\(s\): tags/i);
+        });
+        test('preserves a field that is not declared mutable', () => {
+            // mutableFields omits 'links', so a links patch is ignored and the
+            // existing links are preserved verbatim.
+            const narrow = types_1.MemoryCapCullPolicy.create({ maxRecords: 5, mutableFields: ['body'] }).orThrow();
+            const existing = makeRecord({
+                id: 'turn-0',
+                kind: 'summarized-turn',
+                links: [{ type: 'derived-from', target: 'doc-1' }]
+            }, { summary: 'old' });
+            expect(narrow.applyUpdate(existing, { body: { summary: 'x' }, links: [] })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.links).toEqual([{ type: 'derived-from', target: 'doc-1' }]);
+                expect(updated.body).toEqual({ summary: 'x' });
+            });
+        });
+        test('preserves the body when body is not a declared mutable field', () => {
+            // mutableFields is tags-only: a body patch is ignored and the existing
+            // body is preserved verbatim (the `else existing.body` rebuild branch).
+            const tagsOnly = types_1.MemoryCapCullPolicy.create({ maxRecords: 5, mutableFields: ['tags'] }).orThrow();
+            const existing = makeRecord({ id: 'turn-0', kind: 'summarized-turn', tags: ['old'] }, { summary: 'keep me' });
+            expect(tagsOnly.applyUpdate(existing, { tags: ['new'], body: { summary: 'ignored' } })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.tags).toEqual(['new']);
+                expect(updated.body).toEqual({ summary: 'keep me' });
+            });
+        });
+        test('preserves an absent embeddingRef as absent on an unrelated update (hash-stable)', () => {
+            const existing = memoryRecord('turn-0', 1, { summary: 's' });
+            expect(policy.applyUpdate(existing, { body: { summary: 't' } })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.embeddingRef).toBeUndefined();
+            });
+        });
+        test('preserves embeddingRef when it is not in the declared mutable surface', () => {
+            const narrow = types_1.MemoryCapCullPolicy.create({ maxRecords: 5, mutableFields: ['body'] }).orThrow();
+            const existing = makeRecord({
+                id: 'turn-0',
+                kind: 'summarized-turn',
+                embeddingRef: 'vec-keep'
+            });
+            expect(narrow.applyUpdate(existing, { body: { summary: 'x' } })).toSucceedAndSatisfy((updated) => {
+                expect(updated.envelope.embeddingRef).toBe('vec-keep');
+            });
+        });
+    });
+});
+//# sourceMappingURL=writePolicy.test.js.map