@fgv/ts-agent-memory 5.1.0-36

package/lib/packlets/types/identityCodec.d.ts

@@ -0,0 +1,136 @@
+import { Result } from '@fgv/ts-utils';
+import { EntityId, MemoryScopeKey } from './ids';
+/**
+ * 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 declare class KnowledgeIdentityCodec implements IIdentityCodec {
+    /** The fixed scope for every knowledge entity. */
+    static readonly scope: MemoryScopeKey;
+    /** {@inheritDoc IIdentityCodec.encode} */
+    encode(entityId: EntityId): Result<IIdentityCodecResult>;
+    /** {@inheritDoc IIdentityCodec.decode} */
+    decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId>;
+    /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+    verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<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 declare class LtmIdentityCodec implements IIdentityCodec {
+    /** The fixed scope for every LTM entity. */
+    static readonly scope: MemoryScopeKey;
+    /** {@inheritDoc IIdentityCodec.encode} */
+    encode(entityId: EntityId): Result<IIdentityCodecResult>;
+    /** {@inheritDoc IIdentityCodec.decode} */
+    decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId>;
+    /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+    verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<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 declare class MtmIdentityCodec implements IIdentityCodec {
+    /** The top-level scope segment under which every MTM subtree lives. */
+    static readonly rootScopeSegment: string;
+    /** The fixed filename-stem prefix for a turn record. */
+    static readonly turnStemPrefix: string;
+    /** A non-negative integer string (the turn index), preserved verbatim. */
+    private static readonly _turnIndexRe;
+    /** {@inheritDoc IIdentityCodec.encode} */
+    encode(entityId: EntityId): Result<IIdentityCodecResult>;
+    /** {@inheritDoc IIdentityCodec.decode} */
+    decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId>;
+    /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+    verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true>;
+    /** Validate and extract the `conversationId` from a `conversations/<id>` scope. */
+    private static _conversationIdFromScope;
+    /** Validate and extract the turn-index digits from a `turn-<N>` stem. */
+    private static _turnIndexFromStem;
+    /** Assert a string is a non-negative integer (the turn index). */
+    private static _assertTurnIndex;
+}
+//# sourceMappingURL=identityCodec.d.ts.map

package/lib/packlets/types/identityCodec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identityCodec.d.ts","sourceRoot":"","sources":["../../../src/packlets/types/identityCodec.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAiB,MAAM,eAAe,CAAC;AACtD,OAAO,EAAW,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAG1D;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAEzD;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAErE;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;CACpE;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,kDAAkD;IAClD,gBAAuB,KAAK,EAAE,cAAc,CAAiC;IAE7E,0CAA0C;IACnC,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,oBAAoB,CAAC;IAM/D,0CAA0C;IACnC,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC;IAS3E,mDAAmD;IAC5C,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC;CAc1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAiB,YAAW,cAAc;IACrD,4CAA4C;IAC5C,gBAAuB,KAAK,EAAE,cAAc,CAAqC;IAEjF,0CAA0C;IACnC,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,oBAAoB,CAAC;IAM/D,0CAA0C;IACnC,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC;IAO3E,mDAAmD;IAC5C,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC;CAc1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,gBAAiB,YAAW,cAAc;IACrD,uEAAuE;IACvE,gBAAuB,gBAAgB,EAAE,MAAM,CAAmB;IAClE,wDAAwD;IACxD,gBAAuB,cAAc,EAAE,MAAM,CAAW;IAExD,0EAA0E;IAC1E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAmB;IAEvD,0CAA0C;IACnC,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,oBAAoB,CAAC;IAkB/D,0CAA0C;IACnC,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC;IAQ3E,mDAAmD;IAC5C,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC;IAezE,mFAAmF;IACnF,OAAO,CAAC,MAAM,CAAC,wBAAwB;IAavC,yEAAyE;IACzE,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAOjC,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAC,gBAAgB;CAMhC"}

package/lib/packlets/types/identityCodec.js

@@ -0,0 +1,190 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MtmIdentityCodec = exports.LtmIdentityCodec = exports.KnowledgeIdentityCodec = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const ids_1 = require("./ids");
+const filenameSafety_1 = require("./filenameSafety");
+/**
+/**
+ * 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
+ */
+class KnowledgeIdentityCodec {
+    /** {@inheritDoc IIdentityCodec.encode} */
+    encode(entityId) {
+        return (0, filenameSafety_1.assertPortableFilenameStem)(entityId).onSuccess((idStem) => (0, ts_utils_1.succeed)({ scope: KnowledgeIdentityCodec.scope, idStem, isVersioned: false }));
+    }
+    /** {@inheritDoc IIdentityCodec.decode} */
+    decode(scope, encodedStem) {
+        if (scope !== KnowledgeIdentityCodec.scope) {
+            return (0, ts_utils_1.fail)(`knowledge codec: scope '${scope}' does not match expected scope '${KnowledgeIdentityCodec.scope}'`);
+        }
+        return (0, filenameSafety_1.assertPortableFilenameStem)(encodedStem).onSuccess((stem) => ids_1.Convert.entityId.convert(stem));
+    }
+    /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+    verifyRoundTrip(scope, stem) {
+        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 (0, ts_utils_1.fail)(`knowledge codec: round-trip mismatch for stem '${stem}' (re-encoded to '${encoded.idStem}')`);
+            }
+            /* c8 ignore stop */
+            return (0, ts_utils_1.succeed)(true);
+        });
+    }
+}
+exports.KnowledgeIdentityCodec = KnowledgeIdentityCodec;
+/** The fixed scope for every knowledge entity. */
+KnowledgeIdentityCodec.scope = 'knowledge';
+/**
+ * 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
+ */
+class LtmIdentityCodec {
+    /** {@inheritDoc IIdentityCodec.encode} */
+    encode(entityId) {
+        return (0, filenameSafety_1.assertPortableFilenameStem)(entityId).onSuccess((idStem) => (0, ts_utils_1.succeed)({ scope: LtmIdentityCodec.scope, idStem, isVersioned: false }));
+    }
+    /** {@inheritDoc IIdentityCodec.decode} */
+    decode(scope, encodedStem) {
+        if (scope !== LtmIdentityCodec.scope) {
+            return (0, ts_utils_1.fail)(`LTM codec: scope '${scope}' does not match expected scope '${LtmIdentityCodec.scope}'`);
+        }
+        return (0, filenameSafety_1.assertPortableFilenameStem)(encodedStem).onSuccess((stem) => ids_1.Convert.entityId.convert(stem));
+    }
+    /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+    verifyRoundTrip(scope, stem) {
+        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 (0, ts_utils_1.fail)(`LTM codec: round-trip mismatch for stem '${stem}' (re-encoded to '${encoded.idStem}')`);
+            }
+            /* c8 ignore stop */
+            return (0, ts_utils_1.succeed)(true);
+        });
+    }
+}
+exports.LtmIdentityCodec = LtmIdentityCodec;
+/** The fixed scope for every LTM entity. */
+LtmIdentityCodec.scope = 'conversations';
+/**
+ * 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
+ */
+class MtmIdentityCodec {
+    /** {@inheritDoc IIdentityCodec.encode} */
+    encode(entityId) {
+        const parts = entityId.split(':');
+        if (parts.length !== 2) {
+            return (0, ts_utils_1.fail)(`MTM codec: entity id '${entityId}' must be a '<conversationId>:<turnIndex>' composite`);
+        }
+        const [conversationId, turnIndex] = parts;
+        return (0, filenameSafety_1.assertPortableFilenameStem)(conversationId)
+            .withErrorFormat((msg) => `MTM codec: conversationId '${conversationId}': ${msg}`)
+            .onSuccess(() => MtmIdentityCodec._assertTurnIndex(turnIndex))
+            .onSuccess(() => (0, ts_utils_1.succeed)({
+            scope: `${MtmIdentityCodec.rootScopeSegment}/${conversationId}`,
+            idStem: `${MtmIdentityCodec.turnStemPrefix}${turnIndex}`,
+            isVersioned: false
+        }));
+    }
+    /** {@inheritDoc IIdentityCodec.decode} */
+    decode(scope, encodedStem) {
+        return MtmIdentityCodec._conversationIdFromScope(scope).onSuccess((conversationId) => MtmIdentityCodec._turnIndexFromStem(encodedStem).onSuccess((turnIndex) => ids_1.Convert.entityId.convert(`${conversationId}:${turnIndex}`)));
+    }
+    /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+    verifyRoundTrip(scope, stem) {
+        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 (0, ts_utils_1.fail)(`MTM codec: round-trip mismatch for scope '${scope}' stem '${stem}' (re-encoded to scope '${encoded.scope}' stem '${encoded.idStem}')`);
+            }
+            /* c8 ignore stop */
+            return (0, ts_utils_1.succeed)(true);
+        });
+    }
+    /** Validate and extract the `conversationId` from a `conversations/<id>` scope. */
+    static _conversationIdFromScope(scope) {
+        const segments = scope.split('/');
+        if (segments.length !== 2 || segments[0] !== MtmIdentityCodec.rootScopeSegment) {
+            return (0, ts_utils_1.fail)(`MTM codec: scope '${scope}' must be '${MtmIdentityCodec.rootScopeSegment}/<conversationId>'`);
+        }
+        const conversationId = segments[1];
+        return (0, filenameSafety_1.assertPortableFilenameStem)(conversationId)
+            .withErrorFormat((msg) => `MTM codec: conversationId '${conversationId}': ${msg}`)
+            .onSuccess(() => (0, ts_utils_1.succeed)(conversationId));
+    }
+    /** Validate and extract the turn-index digits from a `turn-<N>` stem. */
+    static _turnIndexFromStem(stem) {
+        if (!stem.startsWith(MtmIdentityCodec.turnStemPrefix)) {
+            return (0, ts_utils_1.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). */
+    static _assertTurnIndex(turnIndex) {
+        if (!MtmIdentityCodec._turnIndexRe.test(turnIndex)) {
+            return (0, ts_utils_1.fail)(`MTM codec: turnIndex '${turnIndex}' must be a non-negative integer`);
+        }
+        return (0, ts_utils_1.succeed)(turnIndex);
+    }
+}
+exports.MtmIdentityCodec = MtmIdentityCodec;
+/** The top-level scope segment under which every MTM subtree lives. */
+MtmIdentityCodec.rootScopeSegment = 'conversations';
+/** The fixed filename-stem prefix for a turn record. */
+MtmIdentityCodec.turnStemPrefix = 'turn-';
+/** A non-negative integer string (the turn index), preserved verbatim. */
+MtmIdentityCodec._turnIndexRe = /^\d+$/;
+//# sourceMappingURL=identityCodec.js.map

package/lib/packlets/types/identityCodec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identityCodec.js","sourceRoot":"","sources":["../../../src/packlets/types/identityCodec.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,4CAAsD;AACtD,+BAA0D;AAC1D,qDAA8D;AA6C9D;;;;;;;;;;;;GAYG;AACH,MAAa,sBAAsB;IAIjC,0CAA0C;IACnC,MAAM,CAAC,QAAkB;QAC9B,OAAO,IAAA,2CAA0B,EAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE,CAC/D,IAAA,kBAAO,EAAC,EAAE,KAAK,EAAE,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAC7E,CAAC;IACJ,CAAC;IAED,0CAA0C;IACnC,MAAM,CAAC,KAAqB,EAAE,WAAmB;QACtD,IAAI,KAAK,KAAK,sBAAsB,CAAC,KAAK,EAAE,CAAC;YAC3C,OAAO,IAAA,eAAI,EACT,2BAA2B,KAAK,oCAAoC,sBAAsB,CAAC,KAAK,GAAG,CACpG,CAAC;QACJ,CAAC;QACD,OAAO,IAAA,2CAA0B,EAAC,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACrG,CAAC;IAED,mDAAmD;IAC5C,eAAe,CAAC,KAAqB,EAAE,IAAY;QACxD,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC;aAC5B,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;aAC9C,SAAS,CAAC,CAAC,OAAO,EAAE,EAAE;YACrB,kOAAkO;YAClO,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;gBAC5B,OAAO,IAAA,eAAI,EACT,kDAAkD,IAAI,qBAAqB,OAAO,CAAC,MAAM,IAAI,CAC9F,CAAC;YACJ,CAAC;YACD,oBAAoB;YACpB,OAAO,IAAA,kBAAO,EAAC,IAAI,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IACP,CAAC;;AAnCH,wDAoCC;AAnCC,kDAAkD;AAC3B,4BAAK,GAAmB,WAA6B,CAAC;AAoC/E;;;;;;;;;;;;;;;GAeG;AACH,MAAa,gBAAgB;IAI3B,0CAA0C;IACnC,MAAM,CAAC,QAAkB;QAC9B,OAAO,IAAA,2CAA0B,EAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE,CAC/D,IAAA,kBAAO,EAAC,EAAE,KAAK,EAAE,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CACvE,CAAC;IACJ,CAAC;IAED,0CAA0C;IACnC,MAAM,CAAC,KAAqB,EAAE,WAAmB;QACtD,IAAI,KAAK,KAAK,gBAAgB,CAAC,KAAK,EAAE,CAAC;YACrC,OAAO,IAAA,eAAI,EAAC,qBAAqB,KAAK,oCAAoC,gBAAgB,CAAC,KAAK,GAAG,CAAC,CAAC;QACvG,CAAC;QACD,OAAO,IAAA,2CAA0B,EAAC,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACrG,CAAC;IAED,mDAAmD;IAC5C,eAAe,CAAC,KAAqB,EAAE,IAAY;QACxD,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC;aAC5B,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;aAC9C,SAAS,CAAC,CAAC,OAAO,EAAE,EAAE;YACrB,4KAA4K;YAC5K,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;gBAC5B,OAAO,IAAA,eAAI,EACT,4CAA4C,IAAI,qBAAqB,OAAO,CAAC,MAAM,IAAI,CACxF,CAAC;YACJ,CAAC;YACD,oBAAoB;YACpB,OAAO,IAAA,kBAAO,EAAC,IAAI,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IACP,CAAC;;AAjCH,4CAkCC;AAjCC,4CAA4C;AACrB,sBAAK,GAAmB,eAAiC,CAAC;AAkCnF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAa,gBAAgB;IAS3B,0CAA0C;IACnC,MAAM,CAAC,QAAkB;QAC9B,MAAM,KAAK,GAAa,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,IAAA,eAAI,EAAC,yBAAyB,QAAQ,sDAAsD,CAAC,CAAC;QACvG,CAAC;QACD,MAAM,CAAC,cAAc,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC;QAC1C,OAAO,IAAA,2CAA0B,EAAC,cAAc,CAAC;aAC9C,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,8BAA8B,cAAc,MAAM,GAAG,EAAE,CAAC;aACjF,SAAS,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;aAC7D,SAAS,CAAC,GAAG,EAAE,CACd,IAAA,kBAAO,EAAC;YACN,KAAK,EAAE,GAAG,gBAAgB,CAAC,gBAAgB,IAAI,cAAc,EAAoB;YACjF,MAAM,EAAE,GAAG,gBAAgB,CAAC,cAAc,GAAG,SAAS,EAAE;YACxD,WAAW,EAAE,KAAK;SACnB,CAAC,CACH,CAAC;IACN,CAAC;IAED,0CAA0C;IACnC,MAAM,CAAC,KAAqB,EAAE,WAAmB;QACtD,OAAO,gBAAgB,CAAC,wBAAwB,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,cAAc,EAAE,EAAE,CACnF,gBAAgB,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE,CACvE,aAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,cAAc,IAAI,SAAS,EAAE,CAAC,CAC3D,CACF,CAAC;IACJ,CAAC;IAED,mDAAmD;IAC5C,eAAe,CAAC,KAAqB,EAAE,IAAY;QACxD,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC;aAC5B,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;aAC9C,SAAS,CAAC,CAAC,OAAO,EAAE,EAAE;YACrB,4LAA4L;YAC5L,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;gBACvD,OAAO,IAAA,eAAI,EACT,6CAA6C,KAAK,WAAW,IAAI,2BAA2B,OAAO,CAAC,KAAK,WAAW,OAAO,CAAC,MAAM,IAAI,CACvI,CAAC;YACJ,CAAC;YACD,oBAAoB;YACpB,OAAO,IAAA,kBAAO,EAAC,IAAI,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IACP,CAAC;IAED,mFAAmF;IAC3E,MAAM,CAAC,wBAAwB,CAAC,KAAqB;QAC3D,MAAM,QAAQ,GAAa,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,gBAAgB,CAAC,gBAAgB,EAAE,CAAC;YAC/E,OAAO,IAAA,eAAI,EACT,qBAAqB,KAAK,cAAc,gBAAgB,CAAC,gBAAgB,oBAAoB,CAC9F,CAAC;QACJ,CAAC;QACD,MAAM,cAAc,GAAW,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC3C,OAAO,IAAA,2CAA0B,EAAC,cAAc,CAAC;aAC9C,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,8BAA8B,cAAc,MAAM,GAAG,EAAE,CAAC;aACjF,SAAS,CAAC,GAAG,EAAE,CAAC,IAAA,kBAAO,EAAC,cAAc,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,yEAAyE;IACjE,MAAM,CAAC,kBAAkB,CAAC,IAAY;QAC5C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,cAAc,CAAC,EAAE,CAAC;YACtD,OAAO,IAAA,eAAI,EAAC,oBAAoB,IAAI,sBAAsB,gBAAgB,CAAC,cAAc,GAAG,CAAC,CAAC;QAChG,CAAC;QACD,OAAO,gBAAgB,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/F,CAAC;IAED,kEAAkE;IAC1D,MAAM,CAAC,gBAAgB,CAAC,SAAiB;QAC/C,IAAI,CAAC,gBAAgB,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACnD,OAAO,IAAA,eAAI,EAAC,yBAAyB,SAAS,kCAAkC,CAAC,CAAC;QACpF,CAAC;QACD,OAAO,IAAA,kBAAO,EAAC,SAAS,CAAC,CAAC;IAC5B,CAAC;;AAjFH,4CAkFC;AAjFC,uEAAuE;AAChD,iCAAgB,GAAW,eAAe,CAAC;AAClE,wDAAwD;AACjC,+BAAc,GAAW,OAAO,CAAC;AAExD,0EAA0E;AAClD,6BAAY,GAAW,OAAO,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { Convert, EntityId, MemoryScopeKey } from './ids';\nimport { assertPortableFilenameStem } from './filenameSafety';\n\n/**\n * The FileTree storage address an {@link IIdentityCodec} maps a domain key to.\n * @public\n */\nexport interface IIdentityCodecResult {\n  /** Scope path segment (may be multi-level, e.g. `conversations/<id>`). */\n  readonly scope: MemoryScopeKey;\n  /** Filename stem (the part before `.md`). Filename-safe after encoding. */\n  readonly idStem: string;\n  /**\n   * Whether this kind uses a versioned layout (temporal: multiple files per\n   * entity) vs. a flat layout (one file per entity). Non-temporal = always\n   * `false`.\n   */\n  readonly isVersioned: boolean;\n}\n\n/**\n * Maps a consumer-supplied domain key ⇄ a FileTree storage address. Injected\n * per kind so the store never touches raw domain keys: the codec owns all\n * filename escaping and the flat-vs-versioned layout dispatch.\n * @public\n */\nexport interface IIdentityCodec {\n  /**\n   * Encode a consumer-supplied entity id to a FileTree address. Deterministic\n   * and pure — no I/O.\n   */\n  encode(entityId: EntityId): Result<IIdentityCodecResult>;\n\n  /**\n   * Decode a FileTree address back to the original {@link EntityId}. The exact\n   * inverse of {@link IIdentityCodec.encode | encode} for non-versioned kinds.\n   */\n  decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId>;\n\n  /**\n   * Assert that `encode(decode(scope, stem)).idStem === stem`. Used by the\n   * store's `verifyFilenameId` check on load.\n   */\n  verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true>;\n}\n\n/**\n/**\n * Identity codec for the knowledge kind family. A knowledge entity is keyed\n * by its consumer-supplied `docId`, which is used verbatim as the filename\n * stem under the flat `knowledge` scope.\n *\n * @remarks\n * - `encode`: scope = `knowledge`, idStem = `docId`, `isVersioned = false`.\n * - `decode`: brands the stem back to an {@link EntityId}.\n * - Escaping: the `docId` must match the POSIX portable filename set.\n * - Layout: `vault/knowledge/<docId>.md`.\n * @public\n */\nexport class KnowledgeIdentityCodec implements IIdentityCodec {\n  /** The fixed scope for every knowledge entity. */\n  public static readonly scope: MemoryScopeKey = 'knowledge' as MemoryScopeKey;\n\n  /** {@inheritDoc IIdentityCodec.encode} */\n  public encode(entityId: EntityId): Result<IIdentityCodecResult> {\n    return assertPortableFilenameStem(entityId).onSuccess((idStem) =>\n      succeed({ scope: KnowledgeIdentityCodec.scope, idStem, isVersioned: false })\n    );\n  }\n\n  /** {@inheritDoc IIdentityCodec.decode} */\n  public decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId> {\n    if (scope !== KnowledgeIdentityCodec.scope) {\n      return fail(\n        `knowledge codec: scope '${scope}' does not match expected scope '${KnowledgeIdentityCodec.scope}'`\n      );\n    }\n    return assertPortableFilenameStem(encodedStem).onSuccess((stem) => Convert.entityId.convert(stem));\n  }\n\n  /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */\n  public verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true> {\n    return this.decode(scope, stem)\n      .onSuccess((entityId) => this.encode(entityId))\n      .onSuccess((encoded) => {\n        /* 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 */\n        if (encoded.idStem !== stem) {\n          return fail(\n            `knowledge codec: round-trip mismatch for stem '${stem}' (re-encoded to '${encoded.idStem}')`\n          );\n        }\n        /* c8 ignore stop */\n        return succeed(true);\n      });\n  }\n}\n\n/**\n * Identity codec for the long-term-memory (LTM) kind family. An LTM entity is\n * keyed by its `conversationId`, used verbatim as the filename stem under the\n * flat `conversations` scope.\n *\n * @remarks\n * - `encode`: scope = `conversations`, idStem = `conversationId`, `isVersioned = false`.\n * - `decode`: brands the stem back to an {@link EntityId}.\n * - Escaping: the `conversationId` must match the POSIX portable filename set.\n * - Layout: `vault/conversations/<conversationId>.md`.\n *\n * An LTM file (`conversations/<id>.md`) and the MTM subtree\n * (`conversations/<id>/turn-N.md`) coexist — a file and a same-named directory\n * are independent on every supported FileTree backend.\n * @public\n */\nexport class LtmIdentityCodec implements IIdentityCodec {\n  /** The fixed scope for every LTM entity. */\n  public static readonly scope: MemoryScopeKey = 'conversations' as MemoryScopeKey;\n\n  /** {@inheritDoc IIdentityCodec.encode} */\n  public encode(entityId: EntityId): Result<IIdentityCodecResult> {\n    return assertPortableFilenameStem(entityId).onSuccess((idStem) =>\n      succeed({ scope: LtmIdentityCodec.scope, idStem, isVersioned: false })\n    );\n  }\n\n  /** {@inheritDoc IIdentityCodec.decode} */\n  public decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId> {\n    if (scope !== LtmIdentityCodec.scope) {\n      return fail(`LTM codec: scope '${scope}' does not match expected scope '${LtmIdentityCodec.scope}'`);\n    }\n    return assertPortableFilenameStem(encodedStem).onSuccess((stem) => Convert.entityId.convert(stem));\n  }\n\n  /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */\n  public verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true> {\n    return this.decode(scope, stem)\n      .onSuccess((entityId) => this.encode(entityId))\n      .onSuccess((encoded) => {\n        /* c8 ignore start -- defensive: LTM encode(decode(stem)).idStem always equals stem when both succeed (identity mapping); guard preserves the contract for direct callers */\n        if (encoded.idStem !== stem) {\n          return fail(\n            `LTM codec: round-trip mismatch for stem '${stem}' (re-encoded to '${encoded.idStem}')`\n          );\n        }\n        /* c8 ignore stop */\n        return succeed(true);\n      });\n  }\n}\n\n/**\n * Identity codec for the medium-term-memory (MTM) kind family. An MTM entity is\n * keyed by the colon-composite `<conversationId>:<turnIndex>` and maps into a\n * per-conversation subtree.\n *\n * @remarks\n * - `encode`: splits the entity id on `:`; scope =\n *   `conversations/<conversationId>` (multi-segment), idStem = `turn-<turnIndex>`,\n *   `isVersioned = false`.\n * - `decode`: reverses scope `conversations/<id>` + stem `turn-<N>` to the\n *   composite `<id>:<N>`.\n * - Escaping: `conversationId` must match the POSIX portable filename set (so it\n *   contains no `/` or `:`); `turnIndex` must be a non-negative integer string,\n *   preserved verbatim so the round-trip is exact.\n * - Layout: `vault/conversations/<conversationId>/turn-<N>.md`. The `/` in the\n *   scope is handled by the store's multi-segment scope resolver.\n *\n * **Verbatim turn index (caller-canonicalization note).** The turn index is\n * preserved exactly — `conv-1:7` and `conv-1:007` are DISTINCT entities mapping\n * to distinct files (`turn-7.md` / `turn-007.md`). Verbatim preservation is what\n * makes the round-trip exact, but it means a caller that formats turn indices\n * inconsistently (some zero-padded, some not) will silently mint separate\n * entities. Callers should canonicalize to one form (e.g. no leading zeros).\n * @public\n */\nexport class MtmIdentityCodec implements IIdentityCodec {\n  /** The top-level scope segment under which every MTM subtree lives. */\n  public static readonly rootScopeSegment: string = 'conversations';\n  /** The fixed filename-stem prefix for a turn record. */\n  public static readonly turnStemPrefix: string = 'turn-';\n\n  /** A non-negative integer string (the turn index), preserved verbatim. */\n  private static readonly _turnIndexRe: RegExp = /^\\d+$/;\n\n  /** {@inheritDoc IIdentityCodec.encode} */\n  public encode(entityId: EntityId): Result<IIdentityCodecResult> {\n    const parts: string[] = entityId.split(':');\n    if (parts.length !== 2) {\n      return fail(`MTM codec: entity id '${entityId}' must be a '<conversationId>:<turnIndex>' composite`);\n    }\n    const [conversationId, turnIndex] = parts;\n    return assertPortableFilenameStem(conversationId)\n      .withErrorFormat((msg) => `MTM codec: conversationId '${conversationId}': ${msg}`)\n      .onSuccess(() => MtmIdentityCodec._assertTurnIndex(turnIndex))\n      .onSuccess(() =>\n        succeed({\n          scope: `${MtmIdentityCodec.rootScopeSegment}/${conversationId}` as MemoryScopeKey,\n          idStem: `${MtmIdentityCodec.turnStemPrefix}${turnIndex}`,\n          isVersioned: false\n        })\n      );\n  }\n\n  /** {@inheritDoc IIdentityCodec.decode} */\n  public decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId> {\n    return MtmIdentityCodec._conversationIdFromScope(scope).onSuccess((conversationId) =>\n      MtmIdentityCodec._turnIndexFromStem(encodedStem).onSuccess((turnIndex) =>\n        Convert.entityId.convert(`${conversationId}:${turnIndex}`)\n      )\n    );\n  }\n\n  /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */\n  public verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true> {\n    return this.decode(scope, stem)\n      .onSuccess((entityId) => this.encode(entityId))\n      .onSuccess((encoded) => {\n        /* 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 */\n        if (encoded.idStem !== stem || encoded.scope !== scope) {\n          return fail(\n            `MTM codec: round-trip mismatch for scope '${scope}' stem '${stem}' (re-encoded to scope '${encoded.scope}' stem '${encoded.idStem}')`\n          );\n        }\n        /* c8 ignore stop */\n        return succeed(true);\n      });\n  }\n\n  /** Validate and extract the `conversationId` from a `conversations/<id>` scope. */\n  private static _conversationIdFromScope(scope: MemoryScopeKey): Result<string> {\n    const segments: string[] = scope.split('/');\n    if (segments.length !== 2 || segments[0] !== MtmIdentityCodec.rootScopeSegment) {\n      return fail(\n        `MTM codec: scope '${scope}' must be '${MtmIdentityCodec.rootScopeSegment}/<conversationId>'`\n      );\n    }\n    const conversationId: string = segments[1];\n    return assertPortableFilenameStem(conversationId)\n      .withErrorFormat((msg) => `MTM codec: conversationId '${conversationId}': ${msg}`)\n      .onSuccess(() => succeed(conversationId));\n  }\n\n  /** Validate and extract the turn-index digits from a `turn-<N>` stem. */\n  private static _turnIndexFromStem(stem: string): Result<string> {\n    if (!stem.startsWith(MtmIdentityCodec.turnStemPrefix)) {\n      return fail(`MTM codec: stem '${stem}' must begin with '${MtmIdentityCodec.turnStemPrefix}'`);\n    }\n    return MtmIdentityCodec._assertTurnIndex(stem.slice(MtmIdentityCodec.turnStemPrefix.length));\n  }\n\n  /** Assert a string is a non-negative integer (the turn index). */\n  private static _assertTurnIndex(turnIndex: string): Result<string> {\n    if (!MtmIdentityCodec._turnIndexRe.test(turnIndex)) {\n      return fail(`MTM codec: turnIndex '${turnIndex}' must be a non-negative integer`);\n    }\n    return succeed(turnIndex);\n  }\n}\n"]}

package/lib/packlets/types/ids.d.ts

@@ -0,0 +1,55 @@
+import { Brand, Converter } from '@fgv/ts-utils';
+/**
+ * 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'>;
+/**
+ * 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 declare 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>;
+};
+//# sourceMappingURL=ids.d.ts.map

package/lib/packlets/types/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../../src/packlets/types/ids.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAqC,MAAM,eAAe,CAAC;AAGpF;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAEjD;;;;GAIG;AACH,MAAM,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAEvC;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAE7D;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAoCjD;;;;;GAKG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,cAAc,CAAC,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;CAwB/B,CAAC"}

package/lib/packlets/types/ids.js

@@ -0,0 +1,70 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Convert = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const filenameSafety_1 = require("./filenameSafety");
+/**
+ * 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 = 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(brand) {
+    return ts_utils_1.Converters.string.map((from) => {
+        if (from.length === 0) {
+            return (0, ts_utils_1.fail)(`${brand}: must be a non-empty string`);
+        }
+        if (from.length > MAX_BRAND_LENGTH) {
+            return (0, ts_utils_1.fail)(`${brand}: exceeds maximum length ${MAX_BRAND_LENGTH} (got ${from.length})`);
+        }
+        if (from !== from.trim()) {
+            return (0, ts_utils_1.fail)(`${brand}: must not have leading or trailing whitespace`);
+        }
+        return (0, ts_utils_1.succeed)(from);
+    });
+}
+/**
+ * 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
+ */
+exports.Convert = {
+    /**
+     * 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').map((id) => (0, filenameSafety_1.assertPortableFilenameStem)(id).onSuccess(() => (0, ts_utils_1.succeed)(id))),
+    /** Validates an `unknown` value as an {@link EntityId}. */
+    entityId: brandedIdConverter('EntityId'),
+    /** Validates an `unknown` value as a {@link Kind}. */
+    kind: brandedIdConverter('Kind'),
+    /** Validates an `unknown` value as a {@link Tag}. */
+    tag: brandedIdConverter('Tag'),
+    /** Validates an `unknown` value as a {@link MemoryScopeKey}. */
+    scopeKey: brandedIdConverter('MemoryScopeKey'),
+    /** Validates an `unknown` value as a {@link LinkType}. */
+    linkType: brandedIdConverter('LinkType')
+};
+//# sourceMappingURL=ids.js.map

package/lib/packlets/types/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../../src/packlets/types/ids.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,4CAAoF;AACpF,qDAA8D;AA+C9D;;;;GAIG;AACH,MAAM,gBAAgB,GAAW,GAAG,CAAC;AAErC;;;;;;;;;;;GAWG;AACH,SAAS,kBAAkB,CAAmB,KAAa;IACzD,OAAO,qBAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAY,EAAa,EAAE;QACvD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,IAAA,eAAI,EAAC,GAAG,KAAK,8BAA8B,CAAC,CAAC;QACtD,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,GAAG,gBAAgB,EAAE,CAAC;YACnC,OAAO,IAAA,eAAI,EAAC,GAAG,KAAK,4BAA4B,gBAAgB,SAAS,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAC3F,CAAC;QACD,IAAI,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACzB,OAAO,IAAA,eAAI,EAAC,GAAG,KAAK,gDAAgD,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,IAAA,kBAAO,EAAC,IAAoB,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACU,QAAA,OAAO,GAOhB;IACF;;;;;;;;OAQG;IACH,QAAQ,EAAE,kBAAkB,CAAW,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAC5D,IAAA,2CAA0B,EAAC,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,IAAA,kBAAO,EAAC,EAAE,CAAC,CAAC,CAC5D;IACD,2DAA2D;IAC3D,QAAQ,EAAE,kBAAkB,CAAW,UAAU,CAAC;IAClD,sDAAsD;IACtD,IAAI,EAAE,kBAAkB,CAAO,MAAM,CAAC;IACtC,qDAAqD;IACrD,GAAG,EAAE,kBAAkB,CAAM,KAAK,CAAC;IACnC,gEAAgE;IAChE,QAAQ,EAAE,kBAAkB,CAAiB,gBAAgB,CAAC;IAC9D,0DAA0D;IAC1D,QAAQ,EAAE,kBAAkB,CAAW,UAAU,CAAC;CAC1C,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Brand, Converter, Converters, Result, fail, succeed } from '@fgv/ts-utils';\nimport { assertPortableFilenameStem } from './filenameSafety';\n\n/**\n * Stable file-stem identifier for a memory record. Equals the codec-produced\n * `idStem` and the on-disk filename stem (`verifyFilenameId` enforces the\n * round-trip).\n * @public\n */\nexport type MemoryId = Brand<string, 'MemoryId'>;\n\n/**\n * Consumer-supplied domain key. The stable entity identity across versions;\n * the package never mints identity. Equals {@link MemoryId} for non-temporal\n * kinds.\n * @public\n */\nexport type EntityId = Brand<string, 'EntityId'>;\n\n/**\n * Open-vocabulary record classifier. Consumers register one body\n * {@link https://www.npmjs.com/package/@fgv/ts-utils | Converter} per kind.\n * @public\n */\nexport type Kind = Brand<string, 'Kind'>;\n\n/**\n * Open-vocabulary tag label.\n * @public\n */\nexport type Tag = Brand<string, 'Tag'>;\n\n/**\n * Scope path segment. May be multi-segment (`/`-separated) for kinds whose\n * codec maps an entity into a sub-tree (e.g. MTM: `conversations/<id>`). The\n * codec — not this brand — owns filename-safe escaping, so the converter\n * validates only the non-empty/length/whitespace hygiene shared by every\n * brand.\n * @public\n */\nexport type MemoryScopeKey = Brand<string, 'MemoryScopeKey'>;\n\n/**\n * Open-vocabulary link-relation type for an attributed {@link IEdge}.\n * @public\n */\nexport type LinkType = Brand<string, 'LinkType'>;\n\n/**\n * Maximum length of any branded identifier in the library. Picked to be\n * larger than any reasonable id a consumer would supply while still bounded\n * to defuse adversarial inputs (e.g. multi-megabyte ids used as map keys).\n */\nconst MAX_BRAND_LENGTH: number = 256;\n\n/**\n * Builds a `Converter` for one of the branded id scalars in this library.\n * All brands share the same hygiene: non-empty, length-capped, and free of\n * leading/trailing whitespace. Filename-safety and single-segment\n * constraints are intentionally NOT enforced here — the per-kind\n * {@link IIdentityCodec} owns escaping so that multi-segment scope keys\n * (`conversations/<id>`) and composite entity ids (`<id>:<turn>`) validate\n * cleanly.\n *\n * Not exported — the per-brand `Convert.<brand>` constants are the public\n * surface.\n */\nfunction brandedIdConverter<T extends string>(brand: string): Converter<T> {\n  return Converters.string.map((from: string): Result<T> => {\n    if (from.length === 0) {\n      return fail(`${brand}: must be a non-empty string`);\n    }\n    if (from.length > MAX_BRAND_LENGTH) {\n      return fail(`${brand}: exceeds maximum length ${MAX_BRAND_LENGTH} (got ${from.length})`);\n    }\n    if (from !== from.trim()) {\n      return fail(`${brand}: must not have leading or trailing whitespace`);\n    }\n    return succeed(from as unknown as T);\n  });\n}\n\n/**\n * Converters for the branded identifier scalars. Each validates an `unknown`\n * value into the corresponding brand, enforcing the shared hygiene\n * (non-empty, length-capped, trimmed).\n * @public\n */\nexport const Convert: {\n  readonly memoryId: Converter<MemoryId>;\n  readonly entityId: Converter<EntityId>;\n  readonly kind: Converter<Kind>;\n  readonly tag: Converter<Tag>;\n  readonly scopeKey: Converter<MemoryScopeKey>;\n  readonly linkType: Converter<LinkType>;\n} = {\n  /**\n   * Validates an `unknown` value as a {@link MemoryId}. Unlike the other\n   * brands, `MemoryId` IS the on-disk filename stem (`id === idStem`, enforced\n   * by the store's `verifyFilenameId`), so it additionally enforces the\n   * portable-filename-stem contract — rejecting path-unsafe ids (`a/b`,\n   * `conv-1:7`) at convert time rather than letting them surface as a file-path\n   * failure later. (`EntityId` stays relaxed: a domain key may legitimately be\n   * a composite like `conv-1:7`; the codec maps it to a safe stem.)\n   */\n  memoryId: brandedIdConverter<MemoryId>('MemoryId').map((id) =>\n    assertPortableFilenameStem(id).onSuccess(() => succeed(id))\n  ),\n  /** Validates an `unknown` value as an {@link EntityId}. */\n  entityId: brandedIdConverter<EntityId>('EntityId'),\n  /** Validates an `unknown` value as a {@link Kind}. */\n  kind: brandedIdConverter<Kind>('Kind'),\n  /** Validates an `unknown` value as a {@link Tag}. */\n  tag: brandedIdConverter<Tag>('Tag'),\n  /** Validates an `unknown` value as a {@link MemoryScopeKey}. */\n  scopeKey: brandedIdConverter<MemoryScopeKey>('MemoryScopeKey'),\n  /** Validates an `unknown` value as a {@link LinkType}. */\n  linkType: brandedIdConverter<LinkType>('LinkType')\n} as const;\n"]}

package/lib/packlets/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from './ids';
+export * from './envelope';
+export * from './filenameSafety';
+export * from './identityCodec';
+export * from './writePolicy';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/types/index.ts"],"names":[],"mappings":"AAKA,cAAc,OAAO,CAAC;AACtB,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC"}

package/lib/packlets/types/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ids"), exports);
+__exportStar(require("./envelope"), exports);
+__exportStar(require("./filenameSafety"), exports);
+__exportStar(require("./identityCodec"), exports);
+__exportStar(require("./writePolicy"), exports);
+//# sourceMappingURL=index.js.map

package/lib/packlets/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/types/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,wCAAsB;AACtB,6CAA2B;AAC3B,mDAAiC;AACjC,kDAAgC;AAChC,gDAA8B","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './ids';\nexport * from './envelope';\nexport * from './filenameSafety';\nexport * from './identityCodec';\nexport * from './writePolicy';\n"]}