@fgv/ts-agent-memory 5.1.0-36

package/src/packlets/store/index.ts

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './fileTreeMemoryStore';
+export * from './scopeEncoding';

package/src/packlets/store/scopeEncoding.ts

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Result, fail, mapResults, succeed } from '@fgv/ts-utils';
+import { MemoryScopeKey, assertPortableFilenameStem } from '../types';
+
+/**
+ * Encode a {@link MemoryScopeKey} to its on-disk directory path. The scope may
+ * be multi-segment (`/`-separated) — each component is validated independently
+ * against the POSIX portable filename set (via
+ * {@link assertPortableFilenameStem}), then rejoined with `/`.
+ *
+ * @remarks
+ * This is the day-one multi-segment scope resolver design-lock §9.1 calls for:
+ * the knowledge scope is the single segment `knowledge`, while the Phase-C MTM
+ * scope `conversations/<conversationId>` is two segments. Validating each
+ * segment independently (rather than the whole path as one stem, which the
+ * `ts-prompt-assist` default encoding does) keeps the Phase-C codec additive —
+ * no scope-encoding change is needed when MTM ships.
+ * @public
+ */
+export function defaultMemoryScopeEncoding(scope: MemoryScopeKey): Result<string> {
+  // `''.split('/')` yields `['']`, never `[]`, so a single empty-segment check
+  // covers the empty-scope case too.
+  const segments: string[] = scope.split('/');
+  if (segments.some((s) => s.length === 0)) {
+    return fail(`scope '${scope}': must not contain empty path segments`);
+  }
+  return mapResults(
+    segments.map((segment) =>
+      assertPortableFilenameStem(segment).withErrorFormat((msg) => `scope '${scope}': ${msg}`)
+    )
+  ).onSuccess((validated) => succeed(validated.join('/')));
+}

package/src/packlets/types/envelope.ts

@@ -0,0 +1,138 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { EntityId, Kind, LinkType, MemoryId, Tag } from './ids';
+
+/**
+ * Origin of a provenance attribution. Open vocabulary: the three named
+ * sources are conventional, but the `(string & {})` arm admits any other
+ * source string without resignature.
+ * @public
+ */
+export type ProvenanceSource = 'agent' | 'host-ingest' | 'human' | (string & {});
+
+/**
+ * Structured provenance for a record or an edge. Never a flat enum — the
+ * `[key: string]: unknown` index signature lets a consumer attach an opaque
+ * domain payload (e.g. PersonAIlity's sentiment / epistemic blocks) without
+ * changing this interface, while still satisfying the no-`any` rule.
+ * @public
+ */
+export interface IProvenance {
+  /** Where the attribution came from. */
+  readonly source: ProvenanceSource;
+  /** Optional human or agent identifier responsible for the write. */
+  readonly by?: string;
+  /** Optional model identifier, when a model produced the content. */
+  readonly model?: string;
+  /** Optional confidence in `[0, 1]`. */
+  readonly confidence?: number;
+  /** Back-link to the source experience record. Enables the cross-kind provenance spine. */
+  readonly derivedFrom?: MemoryId;
+  /** Opaque extension payload — consumer-owned, never interpreted by the store. */
+  readonly [key: string]: unknown;
+}
+
+/**
+ * An attributed link between two records. Carries the relation type, the
+ * target id, and optional confidence / provenance / world-truth validity.
+ * Replaces bare string references (e.g. PersonAIlity's `IMtmRef` becomes an
+ * `IEdge` with `type: LinkType('mtm-ref')`).
+ * @public
+ */
+export interface IEdge {
+  /** Open-vocabulary relation type. */
+  readonly type: LinkType;
+  /** The linked-to record. */
+  readonly target: MemoryId;
+  /** Optional confidence in `[0, 1]`. */
+  readonly confidence?: number;
+  /** Optional structured provenance for the link itself. */
+  readonly provenance?: IProvenance;
+  /** World-truth validity start (epoch ms). Present only on temporal edges. */
+  readonly valid_at?: number;
+  /**
+   * World-truth validity end (epoch ms). `null` = still valid; absent = no
+   * temporal extent.
+   */
+  // eslint-disable-next-line @rushstack/no-new-null -- null is a meaningful value here (still-valid) distinct from absent (no temporal extent); design-lock §2.3
+  readonly invalid_at?: number | null;
+}
+
+/**
+ * Optional bi-temporal validity block on an envelope. Present only on
+ * temporal kinds; absent = zero cost for atemporal kinds.
+ * @public
+ */
+export interface ITemporalBlock {
+  /** World-truth validity start (epoch ms). */
+  readonly valid_at?: number;
+  /** World-truth validity end (epoch ms). `null` = still valid. */
+  // eslint-disable-next-line @rushstack/no-new-null -- null is a meaningful value here (still-valid) distinct from absent; design-lock §2.4
+  readonly invalid_at?: number | null;
+}
+
+/**
+ * The invariant identity + transaction-time envelope carried by every memory
+ * record, independent of the per-kind body.
+ * @public
+ */
+export interface IMemoryEnvelope {
+  // --- Core identity ---
+  /** Stable file-stem identifier. MUST equal the on-disk filename stem. */
+  readonly id: MemoryId;
+  /** Consumer-supplied domain key. Equals {@link IMemoryEnvelope.id | id} for non-temporal kinds. */
+  readonly entityId: EntityId;
+  /** Consumer-registered kind; dispatches the body Converter. */
+  readonly kind: Kind;
+  /** Open-vocabulary tags. */
+  readonly tags: ReadonlyArray<Tag>;
+  /** Attributed outbound edges. */
+  readonly links: ReadonlyArray<IEdge>;
+
+  // --- Transaction-time metadata (always present) ---
+  /** Epoch ms of the first write. Immutable after creation. */
+  readonly created: number;
+  /** Epoch ms of the most recent write. */
+  readonly updated: number;
+  /**
+   * Monotonic write counter within the store instance, assigned by the store
+   * on every successful put. Enables stable cursor paging over observation
+   * records without a full walk.
+   */
+  readonly seq: number;
+  /**
+   * Content hash over the canonical `{ kind, body, links }`. The dedup key:
+   * an exact match is a no-op upsert that returns the existing record.
+   */
+  readonly contentHash: string;
+  /** Structured provenance (never a flat enum). */
+  readonly provenance: IProvenance;
+
+  // --- Optional temporal block ---
+  /** Bi-temporal validity. Present only on temporal kinds. */
+  readonly temporal?: ITemporalBlock;
+
+  /**
+   * Vector-index entry reference, set by the vector index on write. `null` =
+   * not embedded; absent = same as `null` (backwards-compat seam).
+   */
+  // eslint-disable-next-line @rushstack/no-new-null -- null is the explicit "not embedded" sentinel distinct from absent (backwards-compat seam); design-lock §2.5
+  readonly embeddingRef?: string | null;
+}
+
+/**
+ * A complete memory record: the invariant {@link IMemoryEnvelope} plus the
+ * typed, per-kind body. The store's public surface uses
+ * `IMemoryRecord<unknown>`; consumers narrow `TBody` by checking
+ * `envelope.kind` and validating through the registered Converter.
+ * @public
+ */
+export interface IMemoryRecord<TBody = unknown> {
+  /** The invariant identity + transaction-time envelope. */
+  readonly envelope: IMemoryEnvelope;
+  /** The per-kind, Converter-validated body. */
+  readonly body: TBody;
+}

package/src/packlets/types/filenameSafety.ts

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Result, fail, succeed } from '@fgv/ts-utils';
+
+/**
+ * Reserved Windows device basenames. Includes `COM0..9` and `LPT0..9` — the
+ * 0-suffixed variants were added in Windows 11 / Server 2022. Matched
+ * case-insensitively against the basename (text before the first `.`).
+ */
+const RESERVED_WIN_DEVICES: ReadonlySet<string> = new Set<string>([
+  'CON',
+  'PRN',
+  'AUX',
+  'NUL',
+  ...Array.from({ length: 10 }, (__v, i) => `COM${i}`),
+  ...Array.from({ length: 10 }, (__v, i) => `LPT${i}`)
+]);
+
+const PORTABLE_FILENAME_RE: RegExp = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Validates a single filename stem against the POSIX portable filename set
+ * (`[A-Za-z0-9._-]`), rejecting a leading or trailing `.` and reserved Windows
+ * device names. This is the cross-platform filename-stem contract for the
+ * package: {@link MemoryId} values, the concrete {@link IIdentityCodec}
+ * implementations, and the store's `verifyFilenameId` all gate on it.
+ *
+ * @remarks
+ * A trailing `.` is rejected because Windows silently strips trailing dots from
+ * filenames, so such a stem would not round-trip verbatim through the file
+ * layer even though it is otherwise portable-set-valid.
+ * @public
+ */
+export function assertPortableFilenameStem(stem: string): Result<string> {
+  if (stem.length === 0) {
+    return fail('idStem: must be a non-empty string');
+  }
+  if (stem.startsWith('.')) {
+    return fail(`idStem '${stem}': may not begin with '.'`);
+  }
+  if (stem.endsWith('.')) {
+    return fail(`idStem '${stem}': may not end with '.' (Windows strips trailing dots)`);
+  }
+  if (!PORTABLE_FILENAME_RE.test(stem)) {
+    return fail(
+      `idStem '${stem}': contains characters outside the POSIX portable filename set ([A-Za-z0-9._-])`
+    );
+  }
+  const basename: string = stem.split('.')[0];
+  if (RESERVED_WIN_DEVICES.has(basename.toUpperCase())) {
+    return fail(`idStem '${stem}': basename '${basename}' matches a reserved Windows device name`);
+  }
+  return succeed(stem);
+}

package/src/packlets/types/identityCodec.ts

@@ -0,0 +1,263 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Result, fail, succeed } from '@fgv/ts-utils';
+import { Convert, EntityId, MemoryScopeKey } from './ids';
+import { assertPortableFilenameStem } from './filenameSafety';
+
+/**
+ * The FileTree storage address an {@link IIdentityCodec} maps a domain key to.
+ * @public
+ */
+export interface IIdentityCodecResult {
+  /** Scope path segment (may be multi-level, e.g. `conversations/<id>`). */
+  readonly scope: MemoryScopeKey;
+  /** Filename stem (the part before `.md`). Filename-safe after encoding. */
+  readonly idStem: string;
+  /**
+   * Whether this kind uses a versioned layout (temporal: multiple files per
+   * entity) vs. a flat layout (one file per entity). Non-temporal = always
+   * `false`.
+   */
+  readonly isVersioned: boolean;
+}
+
+/**
+ * Maps a consumer-supplied domain key ⇄ a FileTree storage address. Injected
+ * per kind so the store never touches raw domain keys: the codec owns all
+ * filename escaping and the flat-vs-versioned layout dispatch.
+ * @public
+ */
+export interface IIdentityCodec {
+  /**
+   * Encode a consumer-supplied entity id to a FileTree address. Deterministic
+   * and pure — no I/O.
+   */
+  encode(entityId: EntityId): Result<IIdentityCodecResult>;
+
+  /**
+   * Decode a FileTree address back to the original {@link EntityId}. The exact
+   * inverse of {@link IIdentityCodec.encode | encode} for non-versioned kinds.
+   */
+  decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId>;
+
+  /**
+   * Assert that `encode(decode(scope, stem)).idStem === stem`. Used by the
+   * store's `verifyFilenameId` check on load.
+   */
+  verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true>;
+}
+
+/**
+/**
+ * Identity codec for the knowledge kind family. A knowledge entity is keyed
+ * by its consumer-supplied `docId`, which is used verbatim as the filename
+ * stem under the flat `knowledge` scope.
+ *
+ * @remarks
+ * - `encode`: scope = `knowledge`, idStem = `docId`, `isVersioned = false`.
+ * - `decode`: brands the stem back to an {@link EntityId}.
+ * - Escaping: the `docId` must match the POSIX portable filename set.
+ * - Layout: `vault/knowledge/<docId>.md`.
+ * @public
+ */
+export class KnowledgeIdentityCodec implements IIdentityCodec {
+  /** The fixed scope for every knowledge entity. */
+  public static readonly scope: MemoryScopeKey = 'knowledge' as MemoryScopeKey;
+
+  /** {@inheritDoc IIdentityCodec.encode} */
+  public encode(entityId: EntityId): Result<IIdentityCodecResult> {
+    return assertPortableFilenameStem(entityId).onSuccess((idStem) =>
+      succeed({ scope: KnowledgeIdentityCodec.scope, idStem, isVersioned: false })
+    );
+  }
+
+  /** {@inheritDoc IIdentityCodec.decode} */
+  public decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId> {
+    if (scope !== KnowledgeIdentityCodec.scope) {
+      return fail(
+        `knowledge codec: scope '${scope}' does not match expected scope '${KnowledgeIdentityCodec.scope}'`
+      );
+    }
+    return assertPortableFilenameStem(encodedStem).onSuccess((stem) => Convert.entityId.convert(stem));
+  }
+
+  /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+  public verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true> {
+    return this.decode(scope, stem)
+      .onSuccess((entityId) => this.encode(entityId))
+      .onSuccess((encoded) => {
+        /* c8 ignore start -- defensive: for the identity (knowledge) codec, encode(decode(stem)).idStem always equals stem when both succeed; the guard exists for the non-identity codecs (LTM/MTM, Phase C) that reuse this contract */
+        if (encoded.idStem !== stem) {
+          return fail(
+            `knowledge codec: round-trip mismatch for stem '${stem}' (re-encoded to '${encoded.idStem}')`
+          );
+        }
+        /* c8 ignore stop */
+        return succeed(true);
+      });
+  }
+}
+
+/**
+ * Identity codec for the long-term-memory (LTM) kind family. An LTM entity is
+ * keyed by its `conversationId`, used verbatim as the filename stem under the
+ * flat `conversations` scope.
+ *
+ * @remarks
+ * - `encode`: scope = `conversations`, idStem = `conversationId`, `isVersioned = false`.
+ * - `decode`: brands the stem back to an {@link EntityId}.
+ * - Escaping: the `conversationId` must match the POSIX portable filename set.
+ * - Layout: `vault/conversations/<conversationId>.md`.
+ *
+ * An LTM file (`conversations/<id>.md`) and the MTM subtree
+ * (`conversations/<id>/turn-N.md`) coexist — a file and a same-named directory
+ * are independent on every supported FileTree backend.
+ * @public
+ */
+export class LtmIdentityCodec implements IIdentityCodec {
+  /** The fixed scope for every LTM entity. */
+  public static readonly scope: MemoryScopeKey = 'conversations' as MemoryScopeKey;
+
+  /** {@inheritDoc IIdentityCodec.encode} */
+  public encode(entityId: EntityId): Result<IIdentityCodecResult> {
+    return assertPortableFilenameStem(entityId).onSuccess((idStem) =>
+      succeed({ scope: LtmIdentityCodec.scope, idStem, isVersioned: false })
+    );
+  }
+
+  /** {@inheritDoc IIdentityCodec.decode} */
+  public decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId> {
+    if (scope !== LtmIdentityCodec.scope) {
+      return fail(`LTM codec: scope '${scope}' does not match expected scope '${LtmIdentityCodec.scope}'`);
+    }
+    return assertPortableFilenameStem(encodedStem).onSuccess((stem) => Convert.entityId.convert(stem));
+  }
+
+  /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+  public verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true> {
+    return this.decode(scope, stem)
+      .onSuccess((entityId) => this.encode(entityId))
+      .onSuccess((encoded) => {
+        /* c8 ignore start -- defensive: LTM encode(decode(stem)).idStem always equals stem when both succeed (identity mapping); guard preserves the contract for direct callers */
+        if (encoded.idStem !== stem) {
+          return fail(
+            `LTM codec: round-trip mismatch for stem '${stem}' (re-encoded to '${encoded.idStem}')`
+          );
+        }
+        /* c8 ignore stop */
+        return succeed(true);
+      });
+  }
+}
+
+/**
+ * Identity codec for the medium-term-memory (MTM) kind family. An MTM entity is
+ * keyed by the colon-composite `<conversationId>:<turnIndex>` and maps into a
+ * per-conversation subtree.
+ *
+ * @remarks
+ * - `encode`: splits the entity id on `:`; scope =
+ *   `conversations/<conversationId>` (multi-segment), idStem = `turn-<turnIndex>`,
+ *   `isVersioned = false`.
+ * - `decode`: reverses scope `conversations/<id>` + stem `turn-<N>` to the
+ *   composite `<id>:<N>`.
+ * - Escaping: `conversationId` must match the POSIX portable filename set (so it
+ *   contains no `/` or `:`); `turnIndex` must be a non-negative integer string,
+ *   preserved verbatim so the round-trip is exact.
+ * - Layout: `vault/conversations/<conversationId>/turn-<N>.md`. The `/` in the
+ *   scope is handled by the store's multi-segment scope resolver.
+ *
+ * **Verbatim turn index (caller-canonicalization note).** The turn index is
+ * preserved exactly — `conv-1:7` and `conv-1:007` are DISTINCT entities mapping
+ * to distinct files (`turn-7.md` / `turn-007.md`). Verbatim preservation is what
+ * makes the round-trip exact, but it means a caller that formats turn indices
+ * inconsistently (some zero-padded, some not) will silently mint separate
+ * entities. Callers should canonicalize to one form (e.g. no leading zeros).
+ * @public
+ */
+export class MtmIdentityCodec implements IIdentityCodec {
+  /** The top-level scope segment under which every MTM subtree lives. */
+  public static readonly rootScopeSegment: string = 'conversations';
+  /** The fixed filename-stem prefix for a turn record. */
+  public static readonly turnStemPrefix: string = 'turn-';
+
+  /** A non-negative integer string (the turn index), preserved verbatim. */
+  private static readonly _turnIndexRe: RegExp = /^\d+$/;
+
+  /** {@inheritDoc IIdentityCodec.encode} */
+  public encode(entityId: EntityId): Result<IIdentityCodecResult> {
+    const parts: string[] = entityId.split(':');
+    if (parts.length !== 2) {
+      return fail(`MTM codec: entity id '${entityId}' must be a '<conversationId>:<turnIndex>' composite`);
+    }
+    const [conversationId, turnIndex] = parts;
+    return assertPortableFilenameStem(conversationId)
+      .withErrorFormat((msg) => `MTM codec: conversationId '${conversationId}': ${msg}`)
+      .onSuccess(() => MtmIdentityCodec._assertTurnIndex(turnIndex))
+      .onSuccess(() =>
+        succeed({
+          scope: `${MtmIdentityCodec.rootScopeSegment}/${conversationId}` as MemoryScopeKey,
+          idStem: `${MtmIdentityCodec.turnStemPrefix}${turnIndex}`,
+          isVersioned: false
+        })
+      );
+  }
+
+  /** {@inheritDoc IIdentityCodec.decode} */
+  public decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId> {
+    return MtmIdentityCodec._conversationIdFromScope(scope).onSuccess((conversationId) =>
+      MtmIdentityCodec._turnIndexFromStem(encodedStem).onSuccess((turnIndex) =>
+        Convert.entityId.convert(`${conversationId}:${turnIndex}`)
+      )
+    );
+  }
+
+  /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+  public verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true> {
+    return this.decode(scope, stem)
+      .onSuccess((entityId) => this.encode(entityId))
+      .onSuccess((encoded) => {
+        /* c8 ignore start -- defensive: MTM encode(decode(scope, stem)) reproduces the same scope+stem whenever both succeed (no normalization); guard preserves the contract for direct callers */
+        if (encoded.idStem !== stem || encoded.scope !== scope) {
+          return fail(
+            `MTM codec: round-trip mismatch for scope '${scope}' stem '${stem}' (re-encoded to scope '${encoded.scope}' stem '${encoded.idStem}')`
+          );
+        }
+        /* c8 ignore stop */
+        return succeed(true);
+      });
+  }
+
+  /** Validate and extract the `conversationId` from a `conversations/<id>` scope. */
+  private static _conversationIdFromScope(scope: MemoryScopeKey): Result<string> {
+    const segments: string[] = scope.split('/');
+    if (segments.length !== 2 || segments[0] !== MtmIdentityCodec.rootScopeSegment) {
+      return fail(
+        `MTM codec: scope '${scope}' must be '${MtmIdentityCodec.rootScopeSegment}/<conversationId>'`
+      );
+    }
+    const conversationId: string = segments[1];
+    return assertPortableFilenameStem(conversationId)
+      .withErrorFormat((msg) => `MTM codec: conversationId '${conversationId}': ${msg}`)
+      .onSuccess(() => succeed(conversationId));
+  }
+
+  /** Validate and extract the turn-index digits from a `turn-<N>` stem. */
+  private static _turnIndexFromStem(stem: string): Result<string> {
+    if (!stem.startsWith(MtmIdentityCodec.turnStemPrefix)) {
+      return fail(`MTM codec: stem '${stem}' must begin with '${MtmIdentityCodec.turnStemPrefix}'`);
+    }
+    return MtmIdentityCodec._assertTurnIndex(stem.slice(MtmIdentityCodec.turnStemPrefix.length));
+  }
+
+  /** Assert a string is a non-negative integer (the turn index). */
+  private static _assertTurnIndex(turnIndex: string): Result<string> {
+    if (!MtmIdentityCodec._turnIndexRe.test(turnIndex)) {
+      return fail(`MTM codec: turnIndex '${turnIndex}' must be a non-negative integer`);
+    }
+    return succeed(turnIndex);
+  }
+}

package/src/packlets/types/ids.ts

@@ -0,0 +1,124 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Brand, Converter, Converters, Result, fail, succeed } from '@fgv/ts-utils';
+import { assertPortableFilenameStem } from './filenameSafety';
+
+/**
+ * Stable file-stem identifier for a memory record. Equals the codec-produced
+ * `idStem` and the on-disk filename stem (`verifyFilenameId` enforces the
+ * round-trip).
+ * @public
+ */
+export type MemoryId = Brand<string, 'MemoryId'>;
+
+/**
+ * Consumer-supplied domain key. The stable entity identity across versions;
+ * the package never mints identity. Equals {@link MemoryId} for non-temporal
+ * kinds.
+ * @public
+ */
+export type EntityId = Brand<string, 'EntityId'>;
+
+/**
+ * Open-vocabulary record classifier. Consumers register one body
+ * {@link https://www.npmjs.com/package/@fgv/ts-utils | Converter} per kind.
+ * @public
+ */
+export type Kind = Brand<string, 'Kind'>;
+
+/**
+ * Open-vocabulary tag label.
+ * @public
+ */
+export type Tag = Brand<string, 'Tag'>;
+
+/**
+ * Scope path segment. May be multi-segment (`/`-separated) for kinds whose
+ * codec maps an entity into a sub-tree (e.g. MTM: `conversations/<id>`). The
+ * codec — not this brand — owns filename-safe escaping, so the converter
+ * validates only the non-empty/length/whitespace hygiene shared by every
+ * brand.
+ * @public
+ */
+export type MemoryScopeKey = Brand<string, 'MemoryScopeKey'>;
+
+/**
+ * Open-vocabulary link-relation type for an attributed {@link IEdge}.
+ * @public
+ */
+export type LinkType = Brand<string, 'LinkType'>;
+
+/**
+ * Maximum length of any branded identifier in the library. Picked to be
+ * larger than any reasonable id a consumer would supply while still bounded
+ * to defuse adversarial inputs (e.g. multi-megabyte ids used as map keys).
+ */
+const MAX_BRAND_LENGTH: number = 256;
+
+/**
+ * Builds a `Converter` for one of the branded id scalars in this library.
+ * All brands share the same hygiene: non-empty, length-capped, and free of
+ * leading/trailing whitespace. Filename-safety and single-segment
+ * constraints are intentionally NOT enforced here — the per-kind
+ * {@link IIdentityCodec} owns escaping so that multi-segment scope keys
+ * (`conversations/<id>`) and composite entity ids (`<id>:<turn>`) validate
+ * cleanly.
+ *
+ * Not exported — the per-brand `Convert.<brand>` constants are the public
+ * surface.
+ */
+function brandedIdConverter<T extends string>(brand: string): Converter<T> {
+  return Converters.string.map((from: string): Result<T> => {
+    if (from.length === 0) {
+      return fail(`${brand}: must be a non-empty string`);
+    }
+    if (from.length > MAX_BRAND_LENGTH) {
+      return fail(`${brand}: exceeds maximum length ${MAX_BRAND_LENGTH} (got ${from.length})`);
+    }
+    if (from !== from.trim()) {
+      return fail(`${brand}: must not have leading or trailing whitespace`);
+    }
+    return succeed(from as unknown as T);
+  });
+}
+
+/**
+ * Converters for the branded identifier scalars. Each validates an `unknown`
+ * value into the corresponding brand, enforcing the shared hygiene
+ * (non-empty, length-capped, trimmed).
+ * @public
+ */
+export const Convert: {
+  readonly memoryId: Converter<MemoryId>;
+  readonly entityId: Converter<EntityId>;
+  readonly kind: Converter<Kind>;
+  readonly tag: Converter<Tag>;
+  readonly scopeKey: Converter<MemoryScopeKey>;
+  readonly linkType: Converter<LinkType>;
+} = {
+  /**
+   * Validates an `unknown` value as a {@link MemoryId}. Unlike the other
+   * brands, `MemoryId` IS the on-disk filename stem (`id === idStem`, enforced
+   * by the store's `verifyFilenameId`), so it additionally enforces the
+   * portable-filename-stem contract — rejecting path-unsafe ids (`a/b`,
+   * `conv-1:7`) at convert time rather than letting them surface as a file-path
+   * failure later. (`EntityId` stays relaxed: a domain key may legitimately be
+   * a composite like `conv-1:7`; the codec maps it to a safe stem.)
+   */
+  memoryId: brandedIdConverter<MemoryId>('MemoryId').map((id) =>
+    assertPortableFilenameStem(id).onSuccess(() => succeed(id))
+  ),
+  /** Validates an `unknown` value as an {@link EntityId}. */
+  entityId: brandedIdConverter<EntityId>('EntityId'),
+  /** Validates an `unknown` value as a {@link Kind}. */
+  kind: brandedIdConverter<Kind>('Kind'),
+  /** Validates an `unknown` value as a {@link Tag}. */
+  tag: brandedIdConverter<Tag>('Tag'),
+  /** Validates an `unknown` value as a {@link MemoryScopeKey}. */
+  scopeKey: brandedIdConverter<MemoryScopeKey>('MemoryScopeKey'),
+  /** Validates an `unknown` value as a {@link LinkType}. */
+  linkType: brandedIdConverter<LinkType>('LinkType')
+} as const;

package/src/packlets/types/index.ts

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './ids';
+export * from './envelope';
+export * from './filenameSafety';
+export * from './identityCodec';
+export * from './writePolicy';