@fgv/ts-agent-memory 5.1.0-36

package/src/test/unit/store/observations.test.ts

@@ -0,0 +1,290 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import '@fgv/ts-utils-jest';
+import { Converters, Logging, fail, succeed } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+import {
+  BodyConverterRegistry,
+  EntityId,
+  FileTreeMemoryStore,
+  IBodyConverterRegistry,
+  IIdentityCodec,
+  IMemoryObservationRecord,
+  IMemoryObserver,
+  IMemoryRecord,
+  IWritePolicy,
+  Kind,
+  KnowledgeIdentityCodec,
+  MemoryCapCullPolicy,
+  MemoryId,
+  MemoryObservationStore,
+  MtmIdentityCodec,
+  envelopeConverter
+} from '../../../index';
+
+const knowledgeKind: Kind = 'knowledge' as Kind;
+
+function makeRecord(id: string, body: string = `body for ${id}`): IMemoryRecord<unknown> {
+  return {
+    envelope: envelopeConverter
+      .convert({
+        id,
+        entityId: id,
+        kind: 'knowledge',
+        tags: [],
+        links: [],
+        created: 0,
+        updated: 0,
+        seq: 0,
+        contentHash: '',
+        provenance: { source: 'agent' }
+      })
+      .orThrow(),
+    body
+  };
+}
+
+function mutableRoot(): FileTree.IMutableFileTreeDirectoryItem {
+  const tree = FileTree.inMemory([], { mutable: true }).orThrow();
+  const root = tree.getDirectory('/').orThrow();
+  if (!FileTree.isMutableDirectoryItem(root)) {
+    throw new Error('expected a mutable root directory');
+  }
+  return root;
+}
+
+function knowledgeRegistry(): IBodyConverterRegistry {
+  const registry = BodyConverterRegistry.create().orThrow();
+  registry.register(knowledgeKind, Converters.string);
+  return registry;
+}
+
+const knowledgeCodecs: ReadonlyMap<Kind, IIdentityCodec> = new Map<Kind, IIdentityCodec>([
+  [knowledgeKind, new KnowledgeIdentityCodec()]
+]);
+
+let clockValue: number;
+const clock = (): number => clockValue;
+
+function createStore(
+  observers?: ReadonlyArray<IMemoryObserver>,
+  logger?: Logging.ILogger
+): FileTreeMemoryStore {
+  return FileTreeMemoryStore.create({
+    root: mutableRoot(),
+    registry: knowledgeRegistry(),
+    codecs: knowledgeCodecs,
+    clock,
+    observers,
+    logger
+  }).orThrow();
+}
+
+describe('FileTreeMemoryStore observations', () => {
+  beforeEach(() => {
+    clockValue = 1000;
+  });
+
+  describe('when no observers are wired (B1 behavior unchanged)', () => {
+    test('put / get / delete still succeed and produce no records', async () => {
+      const store = createStore();
+      expect(await store.put(makeRecord('doc-a'))).toSucceed();
+      expect(await store.get(knowledgeKind, 'doc-a' as EntityId)).toSucceedAndSatisfy(
+        (rec: IMemoryRecord<unknown> | undefined) => {
+          expect(rec?.envelope.id).toBe('doc-a');
+        }
+      );
+      expect(await store.delete(knowledgeKind, 'doc-a' as EntityId)).toSucceedWith(
+        'doc-a' as unknown as MemoryId
+      );
+    });
+  });
+
+  describe('when an observation store is wired', () => {
+    let observations: MemoryObservationStore;
+    let store: FileTreeMemoryStore;
+
+    beforeEach(() => {
+      observations = MemoryObservationStore.create().orThrow();
+      store = createStore([observations]);
+    });
+
+    test('fires a write observation on put', async () => {
+      await store.put(makeRecord('doc-a'));
+      const records: ReadonlyArray<IMemoryObservationRecord> = observations.query({ phase: 'write' });
+      expect(records).toHaveLength(1);
+      expect(records[0]).toMatchObject({
+        seq: 1,
+        timestamp: 1000,
+        phase: 'write',
+        scope: 'knowledge',
+        id: 'doc-a',
+        kind: 'knowledge',
+        outcome: 'success'
+      });
+      expect(records[0].provenance).toEqual({ source: 'agent' });
+    });
+
+    test('fires a read observation on get (found and not-found)', async () => {
+      await store.put(makeRecord('doc-a'));
+      await store.get(knowledgeKind, 'doc-a' as EntityId);
+      await store.get(knowledgeKind, 'missing' as EntityId);
+      const reads: ReadonlyArray<IMemoryObservationRecord> = observations.query({ phase: 'read' });
+      expect(reads).toHaveLength(2);
+      expect(reads[0]).toMatchObject({ outcome: 'success', id: 'doc-a' });
+      expect(reads[1]).toMatchObject({ outcome: 'success', scope: 'knowledge' });
+      expect(reads[1].id).toBeUndefined();
+    });
+
+    test('fires a delete observation on delete', async () => {
+      await store.put(makeRecord('doc-a'));
+      await store.delete(knowledgeKind, 'doc-a' as EntityId);
+      const deletes: ReadonlyArray<IMemoryObservationRecord> = observations.query({ phase: 'delete' });
+      expect(deletes).toHaveLength(1);
+      expect(deletes[0]).toMatchObject({ outcome: 'success', id: 'doc-a', kind: 'knowledge' });
+    });
+
+    test('records a failure outcome with the error message', async () => {
+      const result = await store.delete(knowledgeKind, 'never-written' as EntityId);
+      expect(result).toFail();
+      const deletes: ReadonlyArray<IMemoryObservationRecord> = observations.query({ phase: 'delete' });
+      expect(deletes).toHaveLength(1);
+      expect(deletes[0].outcome).toBe('failure');
+      expect(deletes[0].error).toMatch(/no record found/i);
+    });
+
+    test('assigns strictly increasing observation seq across ops', async () => {
+      await store.put(makeRecord('doc-a'));
+      await store.get(knowledgeKind, 'doc-a' as EntityId);
+      await store.delete(knowledgeKind, 'doc-a' as EntityId);
+      expect(observations.query().map((r) => r.seq)).toEqual([1, 2, 3]);
+      expect(observations.lastSeq).toBe(3);
+    });
+  });
+
+  describe('cap-cull eviction observations', () => {
+    const mtmKind: Kind = 'mtm' as Kind;
+
+    function mtmRegistry(): IBodyConverterRegistry {
+      const registry = BodyConverterRegistry.create().orThrow();
+      registry.register(mtmKind, Converters.string);
+      return registry;
+    }
+
+    function makeMtmRecord(turn: number, body: string): IMemoryRecord<unknown> {
+      return {
+        envelope: envelopeConverter
+          .convert({
+            id: `turn-${turn}`,
+            entityId: `conv-1:${turn}`,
+            kind: 'mtm',
+            tags: [],
+            links: [],
+            created: 0,
+            updated: 0,
+            seq: 0,
+            contentHash: '',
+            provenance: { source: 'agent' }
+          })
+          .orThrow(),
+        body
+      };
+    }
+
+    test('fires a delete observation for each record evicted by cap-cull', async () => {
+      const observations = MemoryObservationStore.create().orThrow();
+      const capCull: IWritePolicy = MemoryCapCullPolicy.create({
+        maxRecords: 2,
+        mutableFields: ['body', 'tags', 'links', 'provenance', 'embeddingRef']
+      }).orThrow();
+      const store = FileTreeMemoryStore.create({
+        root: mutableRoot(),
+        registry: mtmRegistry(),
+        codecs: new Map<Kind, IIdentityCodec>([[mtmKind, new MtmIdentityCodec()]]),
+        writePolicies: new Map<Kind, IWritePolicy>([[mtmKind, capCull]]),
+        clock,
+        observers: [observations]
+      }).orThrow();
+
+      for (let turn = 0; turn < 3; turn++) {
+        clockValue = 1000 + turn; // distinct `created` so turn-0 is unambiguously oldest.
+        (await store.put(makeMtmRecord(turn, `turn ${turn}`))).orThrow();
+      }
+
+      // The third put admits turn-2 and evicts the oldest (turn-0): the audit
+      // stream must carry a `'delete'` observation naming the evicted record,
+      // in the same (scope, kind) as the write that triggered it.
+      const deletes: ReadonlyArray<IMemoryObservationRecord> = observations.query({ phase: 'delete' });
+      expect(deletes).toHaveLength(1);
+      expect(deletes[0]).toMatchObject({
+        phase: 'delete',
+        outcome: 'success',
+        id: 'turn-0',
+        kind: 'mtm',
+        scope: 'conversations/conv-1'
+      });
+
+      // Three writes + one eviction delete = four observations, strictly
+      // increasing seq (the store is the single seq authority).
+      expect(observations.query({ phase: 'write' })).toHaveLength(3);
+      expect(observations.query().map((r) => r.seq)).toEqual([1, 2, 3, 4]);
+    });
+  });
+
+  describe('observer error handling', () => {
+    test('a failing observer never affects the store op and is logged', async () => {
+      const logger = new Logging.InMemoryLogger();
+      const failing: IMemoryObserver = {
+        observe: () => Promise.resolve(fail('observer boom'))
+      };
+      const store = createStore([failing], logger);
+      expect(await store.put(makeRecord('doc-a'))).toSucceed();
+      expect(logger.logged.some((m) => /observer failed \(swallowed\): observer boom/i.test(m))).toBe(true);
+    });
+
+    test('a throwing observer never affects the store op and is logged', async () => {
+      const logger = new Logging.InMemoryLogger();
+      const throwing: IMemoryObserver = {
+        observe: () => {
+          throw new Error('observer kaboom');
+        }
+      };
+      const store = createStore([throwing], logger);
+      expect(await store.put(makeRecord('doc-a'))).toSucceed();
+      expect(logger.logged.some((m) => /observer threw \(swallowed\): .*kaboom/i.test(m))).toBe(true);
+    });
+
+    test('a logger that throws while reporting a failed observer never breaks the store op', async () => {
+      class ThrowingWarnLogger extends Logging.NoOpLogger {
+        public warn(): never {
+          throw new Error('logger down');
+        }
+      }
+      const failing: IMemoryObserver = {
+        observe: () => Promise.resolve(fail('observer boom'))
+      };
+      const store = createStore([failing], new ThrowingWarnLogger());
+      expect(await store.put(makeRecord('doc-a'))).toSucceed();
+    });
+
+    test('a fire-and-forget observer is dispatched without blocking and errors are swallowed', async () => {
+      const seen: IMemoryObservationRecord[] = [];
+      const observer: IMemoryObserver = {
+        fireAndForget: true,
+        observe: (record) => {
+          seen.push(record);
+          return Promise.resolve(succeed(record));
+        }
+      };
+      const store = createStore([observer]);
+      expect(await store.put(makeRecord('doc-a'))).toSucceed();
+      // Allow the detached dispatch to run.
+      await Promise.resolve();
+      expect(seen).toHaveLength(1);
+      expect(seen[0].phase).toBe('write');
+    });
+  });
+});

package/src/test/unit/store/scopeEncoding.test.ts

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import '@fgv/ts-utils-jest';
+import { MemoryScopeKey, defaultMemoryScopeEncoding } from '../../../index';
+
+describe('defaultMemoryScopeEncoding', () => {
+  test('passes a single portable segment through', () => {
+    expect(defaultMemoryScopeEncoding('knowledge' as MemoryScopeKey)).toSucceedWith('knowledge');
+  });
+
+  test('validates and rejoins a multi-segment scope', () => {
+    expect(defaultMemoryScopeEncoding('conversations/conv-1' as MemoryScopeKey)).toSucceedWith(
+      'conversations/conv-1'
+    );
+  });
+
+  test('rejects a segment outside the portable filename set', () => {
+    expect(defaultMemoryScopeEncoding('conversations/bad:seg' as MemoryScopeKey)).toFailWith(
+      /portable filename set/i
+    );
+  });
+
+  test('rejects an empty path segment', () => {
+    expect(defaultMemoryScopeEncoding('conversations//c1' as MemoryScopeKey)).toFailWith(
+      /empty path segment/i
+    );
+  });
+
+  test('rejects a reserved Windows device segment', () => {
+    expect(defaultMemoryScopeEncoding('conversations/CON' as MemoryScopeKey)).toFailWith(
+      /reserved Windows device/i
+    );
+  });
+});

package/src/test/unit/types/identityCodec.test.ts

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

package/src/test/unit/types/ids.test.ts

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