@fgv/ts-agent-memory 5.1.0-36

package/lib/packlets/converters/bodyConverterRegistry.js

@@ -0,0 +1,55 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BodyConverterRegistry = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * Default in-memory {@link IBodyConverterRegistry}.
+ *
+ * @remarks
+ * Both `register` and `registerSchema` adapt the supplied converter/validator
+ * into a `Converter<unknown>` via `Converters.generic`, so the heterogeneous
+ * per-kind types are stored uniformly with no cast and no `any`. A
+ * `Converter<T>` is not structurally a `Converter<unknown>` (the `map` callback
+ * makes the type invariant), so the `generic` wrapper — whose callback returns
+ * `Result<T>` (assignable to `Result<unknown>`) — is the type-safe bridge.
+ * @public
+ */
+class BodyConverterRegistry {
+    constructor() {
+        this._converters = new Map();
+    }
+    /** Family-convention factory. */
+    static create() {
+        return (0, ts_utils_1.succeed)(new BodyConverterRegistry());
+    }
+    /** {@inheritDoc IBodyConverterRegistry.register} */
+    register(kind, converter) {
+        this._converters.set(kind, ts_utils_1.Converters.generic((from) => converter.convert(from)));
+    }
+    /** {@inheritDoc IBodyConverterRegistry.registerSchema} */
+    registerSchema(kind, schema) {
+        this._converters.set(kind, ts_utils_1.Converters.generic((from) => schema.convert(from)));
+    }
+    /** {@inheritDoc IBodyConverterRegistry.has} */
+    has(kind) {
+        return this._converters.has(kind);
+    }
+    /** {@inheritDoc IBodyConverterRegistry.getConverter} */
+    getConverter(kind) {
+        const converter = this._converters.get(kind);
+        if (converter === undefined) {
+            return (0, ts_utils_1.fail)(`no converter registered for kind '${kind}'`);
+        }
+        return (0, ts_utils_1.succeed)(converter);
+    }
+    /** {@inheritDoc IBodyConverterRegistry.convert} */
+    convert(kind, body) {
+        return this.getConverter(kind).onSuccess((converter) => converter.convert(body));
+    }
+}
+exports.BodyConverterRegistry = BodyConverterRegistry;
+//# sourceMappingURL=bodyConverterRegistry.js.map

package/lib/packlets/converters/bodyConverterRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bodyConverterRegistry.js","sourceRoot":"","sources":["../../../src/packlets/converters/bodyConverterRegistry.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,4CAA6E;AAyC7E;;;;;;;;;;;GAWG;AACH,MAAa,qBAAqB;IAGhC;QACE,IAAI,CAAC,WAAW,GAAG,IAAI,GAAG,EAA4B,CAAC;IACzD,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM;QAClB,OAAO,IAAA,kBAAO,EAAC,IAAI,qBAAqB,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,oDAAoD;IAC7C,QAAQ,CAAI,IAAU,EAAE,SAAuB;QACpD,IAAI,CAAC,WAAW,CAAC,GAAG,CAClB,IAAI,EACJ,qBAAU,CAAC,OAAO,CAAU,CAAC,IAAa,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CACxE,CAAC;IACJ,CAAC;IAED,0DAA0D;IACnD,cAAc,CAAI,IAAU,EAAE,MAAsC;QACzE,IAAI,CAAC,WAAW,CAAC,GAAG,CAClB,IAAI,EACJ,qBAAU,CAAC,OAAO,CAAU,CAAC,IAAa,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CACrE,CAAC;IACJ,CAAC;IAED,+CAA+C;IACxC,GAAG,CAAC,IAAU;QACnB,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,wDAAwD;IACjD,YAAY,CAAC,IAAU;QAC5B,MAAM,SAAS,GAAmC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC7E,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,IAAA,eAAI,EAAC,qCAAqC,IAAI,GAAG,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO,IAAA,kBAAO,EAAC,SAAS,CAAC,CAAC;IAC5B,CAAC;IAED,mDAAmD;IAC5C,OAAO,CAAC,IAAU,EAAE,IAAa;QACtC,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACnF,CAAC;CACF;AA9CD,sDA8CC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Converter, Converters, Result, fail, succeed } from '@fgv/ts-utils';\nimport { JsonSchema } from '@fgv/ts-json-base';\nimport { Kind } from '../types';\n\n/**\n * Registry of per-kind body Converters. Each memory {@link Kind} registers the\n * validated shape of its body; the store dispatches an `unknown` body through\n * the registered Converter on every write. Type-safe — no `any`.\n * @public\n */\nexport interface IBodyConverterRegistry {\n  /**\n   * Register a Converter for a kind. Replaces any prior registration for the\n   * same kind.\n   */\n  register<T>(kind: Kind, converter: Converter<T>): void;\n\n  /**\n   * Register a `JsonSchema` validator (from `@fgv/ts-json-base`) for a kind —\n   * the schema IS a Validator. Replaces any prior registration for the same\n   * kind.\n   */\n  registerSchema<T>(kind: Kind, schema: JsonSchema.ISchemaValidator<T>): void;\n\n  /** Returns `true` if a converter is registered for the kind. */\n  has(kind: Kind): boolean;\n\n  /**\n   * Get the raw converter registered for a kind. Fails if the kind is\n   * unregistered. Exposed for implementors that need to re-validate a patched\n   * body (e.g. a temporal-versioned policy's `applyUpdate`).\n   */\n  getConverter(kind: Kind): Result<Converter<unknown>>;\n\n  /**\n   * Convert an `unknown` body value for the given kind. Fails with\n   * `no converter registered for kind '<k>'` when unregistered.\n   */\n  convert(kind: Kind, body: unknown): Result<unknown>;\n}\n\n/**\n * Default in-memory {@link IBodyConverterRegistry}.\n *\n * @remarks\n * Both `register` and `registerSchema` adapt the supplied converter/validator\n * into a `Converter<unknown>` via `Converters.generic`, so the heterogeneous\n * per-kind types are stored uniformly with no cast and no `any`. A\n * `Converter<T>` is not structurally a `Converter<unknown>` (the `map` callback\n * makes the type invariant), so the `generic` wrapper — whose callback returns\n * `Result<T>` (assignable to `Result<unknown>`) — is the type-safe bridge.\n * @public\n */\nexport class BodyConverterRegistry implements IBodyConverterRegistry {\n  private readonly _converters: Map<Kind, Converter<unknown>>;\n\n  private constructor() {\n    this._converters = new Map<Kind, Converter<unknown>>();\n  }\n\n  /** Family-convention factory. */\n  public static create(): Result<BodyConverterRegistry> {\n    return succeed(new BodyConverterRegistry());\n  }\n\n  /** {@inheritDoc IBodyConverterRegistry.register} */\n  public register<T>(kind: Kind, converter: Converter<T>): void {\n    this._converters.set(\n      kind,\n      Converters.generic<unknown>((from: unknown) => converter.convert(from))\n    );\n  }\n\n  /** {@inheritDoc IBodyConverterRegistry.registerSchema} */\n  public registerSchema<T>(kind: Kind, schema: JsonSchema.ISchemaValidator<T>): void {\n    this._converters.set(\n      kind,\n      Converters.generic<unknown>((from: unknown) => schema.convert(from))\n    );\n  }\n\n  /** {@inheritDoc IBodyConverterRegistry.has} */\n  public has(kind: Kind): boolean {\n    return this._converters.has(kind);\n  }\n\n  /** {@inheritDoc IBodyConverterRegistry.getConverter} */\n  public getConverter(kind: Kind): Result<Converter<unknown>> {\n    const converter: Converter<unknown> | undefined = this._converters.get(kind);\n    if (converter === undefined) {\n      return fail(`no converter registered for kind '${kind}'`);\n    }\n    return succeed(converter);\n  }\n\n  /** {@inheritDoc IBodyConverterRegistry.convert} */\n  public convert(kind: Kind, body: unknown): Result<unknown> {\n    return this.getConverter(kind).onSuccess((converter) => converter.convert(body));\n  }\n}\n"]}

package/lib/packlets/converters/envelopeConverter.d.ts

@@ -0,0 +1,70 @@
+import { Converter, Result } from '@fgv/ts-utils';
+import { IEdge, IMemoryEnvelope, IMemoryRecord, IProvenance, ITemporalBlock } from '../types';
+import { IBodyConverterRegistry } from './bodyConverterRegistry';
+/**
+ * Converter for {@link IProvenance}. Validates the known fields and preserves
+ * any extension keys verbatim (the `[key: string]: unknown` opaque payload),
+ * so a round-trip never drops consumer-attached data.
+ * @public
+ */
+export declare const provenanceConverter: Converter<IProvenance>;
+/**
+ * Converter for an attributed {@link IEdge}.
+ * @public
+ */
+export declare const edgeConverter: Converter<IEdge>;
+/**
+ * Converter for the optional {@link ITemporalBlock}.
+ * @public
+ */
+export declare const temporalConverter: Converter<ITemporalBlock>;
+/**
+ * Converter for the invariant {@link IMemoryEnvelope}. Validates a plain
+ * object (e.g. parsed YAML frontmatter) into a typed envelope.
+ * @public
+ */
+export declare const envelopeConverter: Converter<IMemoryEnvelope>;
+/**
+ * Converter that parses a YAML frontmatter string into an
+ * {@link IMemoryEnvelope}.
+ * @public
+ */
+export declare const envelopeYamlConverter: Converter<IMemoryEnvelope>;
+/**
+ * The two parts of a memory file: the YAML frontmatter (between the `---`
+ * delimiters) and the markdown body (everything after the closing delimiter).
+ * @public
+ */
+export interface IMemoryFileParts {
+    /** The raw YAML frontmatter (delimiters stripped). */
+    readonly frontmatter: string;
+    /** The raw body text following the closing delimiter. */
+    readonly body: string;
+}
+/**
+ * Split a `---\n<yaml>\n---\n<body>` memory file into its frontmatter and
+ * body parts. Pure string handling — no external dependency.
+ * @public
+ */
+export declare function splitFrontmatter(raw: string): Result<IMemoryFileParts>;
+/**
+ * Join a YAML frontmatter string and a body into the canonical
+ * `---\n<yaml>\n---\n<body>` memory-file format.
+ * @public
+ */
+export declare function joinFrontmatter(frontmatter: string, body: string): string;
+/**
+ * Parse a complete memory file into a typed {@link IMemoryRecord}. Splits the
+ * frontmatter, validates the envelope, and dispatches the body through the
+ * registered Converter for the envelope's kind.
+ * @public
+ */
+export declare function parseMemoryFile(raw: string, registry: IBodyConverterRegistry): Result<IMemoryRecord<unknown>>;
+/**
+ * Serialize an envelope and its rendered body text into a memory file. The
+ * envelope is emitted as YAML frontmatter; the body is written verbatim after
+ * the closing delimiter.
+ * @public
+ */
+export declare function serializeMemoryFile(envelope: IMemoryEnvelope, body: string): Result<string>;
+//# sourceMappingURL=envelopeConverter.d.ts.map

package/lib/packlets/converters/envelopeConverter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelopeConverter.d.ts","sourceRoot":"","sources":["../../../src/packlets/converters/envelopeConverter.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,SAAS,EAAc,MAAM,EAAiB,MAAM,eAAe,CAAC;AAE7E,OAAO,EAAW,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACvG,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAqCjE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,CAAC,WAAW,CAUtD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,CAAC,KAAK,CAU1C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,CAAC,cAAc,CAMvD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,CAAC,eAAe,CAgBxD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,CAAC,eAAe,CAAyC,CAAC;AAKvG;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAuBtE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,sBAAsB,GAC/B,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAYhC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAI3F"}

package/lib/packlets/converters/envelopeConverter.js

@@ -0,0 +1,166 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envelopeYamlConverter = exports.envelopeConverter = exports.temporalConverter = exports.edgeConverter = exports.provenanceConverter = void 0;
+exports.splitFrontmatter = splitFrontmatter;
+exports.joinFrontmatter = joinFrontmatter;
+exports.parseMemoryFile = parseMemoryFile;
+exports.serializeMemoryFile = serializeMemoryFile;
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_extras_1 = require("@fgv/ts-extras");
+const types_1 = require("../types");
+/** Matches exactly the JSON `null` literal. */
+// eslint-disable-next-line @rushstack/no-new-null -- the envelope nullable fields (invalid_at, embeddingRef) carry meaningful null; design-lock §2.3-2.5
+const nullConverter = ts_utils_1.Converters.generic((from) => from === null ? (0, ts_utils_1.succeed)(null) : (0, ts_utils_1.fail)('expected null'));
+/** A nullable epoch-ms value (`number | null`). */
+// eslint-disable-next-line @rushstack/no-new-null -- meaningful null for IEdge/ITemporalBlock.invalid_at; design-lock §2.3-2.4
+const numberOrNull = ts_utils_1.Converters.oneOf([
+    ts_utils_1.Converters.number,
+    nullConverter
+]);
+/** A nullable string value (`string | null`). */
+// eslint-disable-next-line @rushstack/no-new-null -- meaningful null for IMemoryEnvelope.embeddingRef; design-lock §2.5
+const stringOrNull = ts_utils_1.Converters.oneOf([
+    ts_utils_1.Converters.string,
+    nullConverter
+]);
+/**
+ * Converter for the known {@link IProvenance} fields. The full
+ * {@link provenanceConverter} layers extension-key preservation on top.
+ */
+const knownProvenanceConverter = ts_utils_1.Converters.object({
+    source: ts_utils_1.Converters.string,
+    by: ts_utils_1.Converters.string.optional(),
+    model: ts_utils_1.Converters.string.optional(),
+    confidence: ts_utils_1.Converters.number.optional(),
+    derivedFrom: types_1.Convert.memoryId.optional()
+}, { optionalFields: ['by', 'model', 'confidence', 'derivedFrom'] });
+/**
+ * Converter for {@link IProvenance}. Validates the known fields and preserves
+ * any extension keys verbatim (the `[key: string]: unknown` opaque payload),
+ * so a round-trip never drops consumer-attached data.
+ * @public
+ */
+exports.provenanceConverter = ts_utils_1.Converters.generic((from) => knownProvenanceConverter.convert(from).onSuccess((known) => {
+    // `from` is guaranteed to be a non-null object here — the known-field
+    // converter only succeeds on objects. Spread the original keys first,
+    // then the validated/normalized known fields on top, so extension keys
+    // survive while the known fields carry their converted values.
+    const merged = Object.assign(Object.assign({}, from), known);
+    return (0, ts_utils_1.succeed)(merged);
+}));
+/**
+ * Converter for an attributed {@link IEdge}.
+ * @public
+ */
+exports.edgeConverter = ts_utils_1.Converters.object({
+    type: types_1.Convert.linkType,
+    target: types_1.Convert.memoryId,
+    confidence: ts_utils_1.Converters.number.optional(),
+    provenance: exports.provenanceConverter.optional(),
+    valid_at: ts_utils_1.Converters.number.optional(),
+    invalid_at: numberOrNull.optional()
+}, { optionalFields: ['confidence', 'provenance', 'valid_at', 'invalid_at'] });
+/**
+ * Converter for the optional {@link ITemporalBlock}.
+ * @public
+ */
+exports.temporalConverter = ts_utils_1.Converters.object({
+    valid_at: ts_utils_1.Converters.number.optional(),
+    invalid_at: numberOrNull.optional()
+}, { optionalFields: ['valid_at', 'invalid_at'] });
+/**
+ * Converter for the invariant {@link IMemoryEnvelope}. Validates a plain
+ * object (e.g. parsed YAML frontmatter) into a typed envelope.
+ * @public
+ */
+exports.envelopeConverter = ts_utils_1.Converters.object({
+    id: types_1.Convert.memoryId,
+    entityId: types_1.Convert.entityId,
+    kind: types_1.Convert.kind,
+    tags: ts_utils_1.Converters.arrayOf(types_1.Convert.tag),
+    links: ts_utils_1.Converters.arrayOf(exports.edgeConverter),
+    created: ts_utils_1.Converters.number,
+    updated: ts_utils_1.Converters.number,
+    seq: ts_utils_1.Converters.number,
+    contentHash: ts_utils_1.Converters.string,
+    provenance: exports.provenanceConverter,
+    temporal: exports.temporalConverter.optional(),
+    embeddingRef: stringOrNull.optional()
+}, { optionalFields: ['temporal', 'embeddingRef'] });
+/**
+ * Converter that parses a YAML frontmatter string into an
+ * {@link IMemoryEnvelope}.
+ * @public
+ */
+exports.envelopeYamlConverter = ts_extras_1.Yaml.yamlConverter(exports.envelopeConverter);
+/** The frontmatter delimiter line. */
+const FRONTMATTER_DELIMITER = '---';
+/**
+ * Split a `---\n<yaml>\n---\n<body>` memory file into its frontmatter and
+ * body parts. Pure string handling — no external dependency.
+ * @public
+ */
+function splitFrontmatter(raw) {
+    // Split on '\n' and strip a trailing '\r' per line so CRLF-authored files
+    // parse identically to LF — otherwise the '\r' would ride along into the
+    // returned frontmatter (perturbing YAML parsing) and body (corrupting
+    // round-trip fidelity).
+    const lines = raw.split('\n').map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line));
+    if (lines[0].trim() !== FRONTMATTER_DELIMITER) {
+        return (0, ts_utils_1.fail)("memory file: missing opening frontmatter delimiter '---'");
+    }
+    let closeIndex = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === FRONTMATTER_DELIMITER) {
+            closeIndex = i;
+            break;
+        }
+    }
+    if (closeIndex === -1) {
+        return (0, ts_utils_1.fail)("memory file: missing closing frontmatter delimiter '---'");
+    }
+    return (0, ts_utils_1.succeed)({
+        frontmatter: lines.slice(1, closeIndex).join('\n'),
+        body: lines.slice(closeIndex + 1).join('\n')
+    });
+}
+/**
+ * Join a YAML frontmatter string and a body into the canonical
+ * `---\n<yaml>\n---\n<body>` memory-file format.
+ * @public
+ */
+function joinFrontmatter(frontmatter, body) {
+    const normalized = frontmatter.endsWith('\n') ? frontmatter : `${frontmatter}\n`;
+    return `${FRONTMATTER_DELIMITER}\n${normalized}${FRONTMATTER_DELIMITER}\n${body}`;
+}
+/**
+ * Parse a complete memory file into a typed {@link IMemoryRecord}. Splits the
+ * frontmatter, validates the envelope, and dispatches the body through the
+ * registered Converter for the envelope's kind.
+ * @public
+ */
+function parseMemoryFile(raw, registry) {
+    return splitFrontmatter(raw).onSuccess((parts) => exports.envelopeYamlConverter
+        .convert(parts.frontmatter)
+        .withErrorFormat((msg) => `memory file: invalid envelope: ${msg}`)
+        .onSuccess((envelope) => registry
+        .convert(envelope.kind, parts.body)
+        .withErrorFormat((msg) => `memory file '${envelope.id}': invalid body: ${msg}`)
+        .onSuccess((body) => (0, ts_utils_1.succeed)({ envelope, body }))));
+}
+/**
+ * Serialize an envelope and its rendered body text into a memory file. The
+ * envelope is emitted as YAML frontmatter; the body is written verbatim after
+ * the closing delimiter.
+ * @public
+ */
+function serializeMemoryFile(envelope, body) {
+    return ts_extras_1.Yaml.yamlStringify(envelope)
+        .withErrorFormat((msg) => `memory file '${envelope.id}': failed to serialize envelope: ${msg}`)
+        .onSuccess((frontmatter) => (0, ts_utils_1.succeed)(joinFrontmatter(frontmatter, body)));
+}
+//# sourceMappingURL=envelopeConverter.js.map

package/lib/packlets/converters/envelopeConverter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelopeConverter.js","sourceRoot":"","sources":["../../../src/packlets/converters/envelopeConverter.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Converter, Converters, Result, fail, succeed } from '@fgv/ts-utils';\nimport { Yaml } from '@fgv/ts-extras';\nimport { Convert, IEdge, IMemoryEnvelope, IMemoryRecord, IProvenance, ITemporalBlock } from '../types';\nimport { IBodyConverterRegistry } from './bodyConverterRegistry';\n\n/** Matches exactly the JSON `null` literal. */\n// eslint-disable-next-line @rushstack/no-new-null -- the envelope nullable fields (invalid_at, embeddingRef) carry meaningful null; design-lock §2.3-2.5\nconst nullConverter: Converter<null> = Converters.generic<null>((from: unknown) =>\n  from === null ? succeed(null) : fail('expected null')\n);\n\n/** A nullable epoch-ms value (`number | null`). */\n// eslint-disable-next-line @rushstack/no-new-null -- meaningful null for IEdge/ITemporalBlock.invalid_at; design-lock §2.3-2.4\nconst numberOrNull: Converter<number | null> = Converters.oneOf<number | null>([\n  Converters.number,\n  nullConverter\n]);\n\n/** A nullable string value (`string | null`). */\n// eslint-disable-next-line @rushstack/no-new-null -- meaningful null for IMemoryEnvelope.embeddingRef; design-lock §2.5\nconst stringOrNull: Converter<string | null> = Converters.oneOf<string | null>([\n  Converters.string,\n  nullConverter\n]);\n\n/**\n * Converter for the known {@link IProvenance} fields. The full\n * {@link provenanceConverter} layers extension-key preservation on top.\n */\nconst knownProvenanceConverter: Converter<IProvenance> = Converters.object<IProvenance>(\n  {\n    source: Converters.string,\n    by: Converters.string.optional(),\n    model: Converters.string.optional(),\n    confidence: Converters.number.optional(),\n    derivedFrom: Convert.memoryId.optional()\n  },\n  { optionalFields: ['by', 'model', 'confidence', 'derivedFrom'] }\n);\n\n/**\n * Converter for {@link IProvenance}. Validates the known fields and preserves\n * any extension keys verbatim (the `[key: string]: unknown` opaque payload),\n * so a round-trip never drops consumer-attached data.\n * @public\n */\nexport const provenanceConverter: Converter<IProvenance> = Converters.generic<IProvenance>(\n  (from: unknown): Result<IProvenance> =>\n    knownProvenanceConverter.convert(from).onSuccess((known) => {\n      // `from` is guaranteed to be a non-null object here — the known-field\n      // converter only succeeds on objects. Spread the original keys first,\n      // then the validated/normalized known fields on top, so extension keys\n      // survive while the known fields carry their converted values.\n      const merged: IProvenance = { ...(from as Record<string, unknown>), ...known };\n      return succeed(merged);\n    })\n);\n\n/**\n * Converter for an attributed {@link IEdge}.\n * @public\n */\nexport const edgeConverter: Converter<IEdge> = Converters.object<IEdge>(\n  {\n    type: Convert.linkType,\n    target: Convert.memoryId,\n    confidence: Converters.number.optional(),\n    provenance: provenanceConverter.optional(),\n    valid_at: Converters.number.optional(),\n    invalid_at: numberOrNull.optional()\n  },\n  { optionalFields: ['confidence', 'provenance', 'valid_at', 'invalid_at'] }\n);\n\n/**\n * Converter for the optional {@link ITemporalBlock}.\n * @public\n */\nexport const temporalConverter: Converter<ITemporalBlock> = Converters.object<ITemporalBlock>(\n  {\n    valid_at: Converters.number.optional(),\n    invalid_at: numberOrNull.optional()\n  },\n  { optionalFields: ['valid_at', 'invalid_at'] }\n);\n\n/**\n * Converter for the invariant {@link IMemoryEnvelope}. Validates a plain\n * object (e.g. parsed YAML frontmatter) into a typed envelope.\n * @public\n */\nexport const envelopeConverter: Converter<IMemoryEnvelope> = Converters.object<IMemoryEnvelope>(\n  {\n    id: Convert.memoryId,\n    entityId: Convert.entityId,\n    kind: Convert.kind,\n    tags: Converters.arrayOf(Convert.tag),\n    links: Converters.arrayOf(edgeConverter),\n    created: Converters.number,\n    updated: Converters.number,\n    seq: Converters.number,\n    contentHash: Converters.string,\n    provenance: provenanceConverter,\n    temporal: temporalConverter.optional(),\n    embeddingRef: stringOrNull.optional()\n  },\n  { optionalFields: ['temporal', 'embeddingRef'] }\n);\n\n/**\n * Converter that parses a YAML frontmatter string into an\n * {@link IMemoryEnvelope}.\n * @public\n */\nexport const envelopeYamlConverter: Converter<IMemoryEnvelope> = Yaml.yamlConverter(envelopeConverter);\n\n/** The frontmatter delimiter line. */\nconst FRONTMATTER_DELIMITER: string = '---';\n\n/**\n * The two parts of a memory file: the YAML frontmatter (between the `---`\n * delimiters) and the markdown body (everything after the closing delimiter).\n * @public\n */\nexport interface IMemoryFileParts {\n  /** The raw YAML frontmatter (delimiters stripped). */\n  readonly frontmatter: string;\n  /** The raw body text following the closing delimiter. */\n  readonly body: string;\n}\n\n/**\n * Split a `---\\n<yaml>\\n---\\n<body>` memory file into its frontmatter and\n * body parts. Pure string handling — no external dependency.\n * @public\n */\nexport function splitFrontmatter(raw: string): Result<IMemoryFileParts> {\n  // Split on '\\n' and strip a trailing '\\r' per line so CRLF-authored files\n  // parse identically to LF — otherwise the '\\r' would ride along into the\n  // returned frontmatter (perturbing YAML parsing) and body (corrupting\n  // round-trip fidelity).\n  const lines: string[] = raw.split('\\n').map((line) => (line.endsWith('\\r') ? line.slice(0, -1) : line));\n  if (lines[0].trim() !== FRONTMATTER_DELIMITER) {\n    return fail(\"memory file: missing opening frontmatter delimiter '---'\");\n  }\n  let closeIndex: number = -1;\n  for (let i = 1; i < lines.length; i++) {\n    if (lines[i].trim() === FRONTMATTER_DELIMITER) {\n      closeIndex = i;\n      break;\n    }\n  }\n  if (closeIndex === -1) {\n    return fail(\"memory file: missing closing frontmatter delimiter '---'\");\n  }\n  return succeed({\n    frontmatter: lines.slice(1, closeIndex).join('\\n'),\n    body: lines.slice(closeIndex + 1).join('\\n')\n  });\n}\n\n/**\n * Join a YAML frontmatter string and a body into the canonical\n * `---\\n<yaml>\\n---\\n<body>` memory-file format.\n * @public\n */\nexport function joinFrontmatter(frontmatter: string, body: string): string {\n  const normalized: string = frontmatter.endsWith('\\n') ? frontmatter : `${frontmatter}\\n`;\n  return `${FRONTMATTER_DELIMITER}\\n${normalized}${FRONTMATTER_DELIMITER}\\n${body}`;\n}\n\n/**\n * Parse a complete memory file into a typed {@link IMemoryRecord}. Splits the\n * frontmatter, validates the envelope, and dispatches the body through the\n * registered Converter for the envelope's kind.\n * @public\n */\nexport function parseMemoryFile(\n  raw: string,\n  registry: IBodyConverterRegistry\n): Result<IMemoryRecord<unknown>> {\n  return splitFrontmatter(raw).onSuccess((parts) =>\n    envelopeYamlConverter\n      .convert(parts.frontmatter)\n      .withErrorFormat((msg) => `memory file: invalid envelope: ${msg}`)\n      .onSuccess((envelope) =>\n        registry\n          .convert(envelope.kind, parts.body)\n          .withErrorFormat((msg) => `memory file '${envelope.id}': invalid body: ${msg}`)\n          .onSuccess((body) => succeed({ envelope, body }))\n      )\n  );\n}\n\n/**\n * Serialize an envelope and its rendered body text into a memory file. The\n * envelope is emitted as YAML frontmatter; the body is written verbatim after\n * the closing delimiter.\n * @public\n */\nexport function serializeMemoryFile(envelope: IMemoryEnvelope, body: string): Result<string> {\n  return Yaml.yamlStringify(envelope)\n    .withErrorFormat((msg) => `memory file '${envelope.id}': failed to serialize envelope: ${msg}`)\n    .onSuccess((frontmatter) => succeed(joinFrontmatter(frontmatter, body)));\n}\n"]}

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

@@ -0,0 +1,3 @@
+export * from './bodyConverterRegistry';
+export * from './envelopeConverter';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/converters/index.ts"],"names":[],"mappings":"AAKA,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC"}

package/lib/packlets/converters/index.js

@@ -0,0 +1,23 @@
+"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("./bodyConverterRegistry"), exports);
+__exportStar(require("./envelopeConverter"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/converters/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,0DAAwC;AACxC,sDAAoC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './bodyConverterRegistry';\nexport * from './envelopeConverter';\n"]}

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

@@ -0,0 +1,2 @@
+export * from './memoryIndex';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/index/index.ts"],"names":[],"mappings":"AAKA,cAAc,eAAe,CAAC"}

package/lib/packlets/index/index.js

@@ -0,0 +1,22 @@
+"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("./memoryIndex"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/index/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,gDAA8B","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './memoryIndex';\n"]}

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

@@ -0,0 +1,127 @@
+import { Result } from '@fgv/ts-utils';
+import { IMemoryRecord, Kind, MemoryId, MemoryScopeKey, Tag } from '../types';
+/**
+ * The mutation a {@link IMemoryIndex.patch | patch} applies: a record was
+ * written (`'put'`) or removed (`'delete'`).
+ * @public
+ */
+export type MemoryIndexPatchOp = 'put' | 'delete';
+/**
+ * A memory record paired with the {@link MemoryScopeKey | scope} it lives
+ * under. The scope is not carried on the {@link IMemoryEnvelope} (it is derived
+ * from the entity id by the codec), so the store threads it alongside the
+ * record when patching or rebuilding the index. The `(scope, id)` pair is the
+ * index's primary key, keeping records distinct across scopes that reuse a
+ * filename stem (e.g. `turn-0` under different conversations in Phase C).
+ * @public
+ */
+export interface IIndexedMemoryRecord {
+    /** The scope the record is stored under. */
+    readonly scope: MemoryScopeKey;
+    /** The memory record itself. */
+    readonly record: IMemoryRecord<unknown>;
+}
+/**
+ * The derived, in-memory secondary indexes the store maintains over its
+ * records. Never the source of truth — the FileTree is. The index is fully
+ * rebuildable from a walk of the store ({@link IMemoryIndex.rebuild}) and is
+ * patched incrementally on every write ({@link IMemoryIndex.patch}).
+ *
+ * @remarks
+ * B1 builds the maps; link-traversal BFS over {@link IMemoryIndex.backlinks}
+ * is B2. The accessors return records (not bare ids) so the B2 retrievers can
+ * consume them directly.
+ * @public
+ */
+export interface IMemoryIndex {
+    /**
+     * Replace the entire index from a full set of records (a store walk).
+     * @returns The number of records indexed.
+     */
+    rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number>;
+    /**
+     * Apply a single incremental change. `'put'` inserts or replaces the entry
+     * at its `(scope, id)` key (removing any prior associations first); `'delete'`
+     * removes it.
+     * @returns The entry that was applied.
+     */
+    patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord>;
+    /** Every indexed entry (scope + record). Primary read surface for the store. */
+    entries(): ReadonlyArray<IIndexedMemoryRecord>;
+    /** Records of the given kind, in recency order (most-recently-updated first). */
+    byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>>;
+    /** Records carrying the given tag, in recency order. */
+    byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>>;
+    /** All records in recency order (most-recently-updated first). */
+    byRecency(): ReadonlyArray<IMemoryRecord<unknown>>;
+    /**
+     * The ids of records whose `links` point AT `target` (inbound edges).
+     * The seed map for B2 link-traversal.
+     */
+    backlinks(target: MemoryId): ReadonlyArray<MemoryId>;
+}
+/**
+ * Default in-memory {@link IMemoryIndex}. Maintains the derived `byKind` /
+ * `byTag` / `byRecency` / `backlinks` views incrementally; a `'put'` for an
+ * already-indexed key first removes the prior entry's associations so a changed
+ * kind / tag / link set never leaves a stale reference behind.
+ * @public
+ */
+export declare class MemoryIndex implements IMemoryIndex {
+    /** Primary store: `(scope, id)` composite key → indexed entry. */
+    private readonly _byKey;
+    /** kind → set of composite keys. */
+    private readonly _byKind;
+    /** tag → set of composite keys. */
+    private readonly _byTag;
+    /**
+     * link target id → (source composite key → source id). Keyed by the source's
+     * `(scope, id)` composite — NOT its bare id — so two distinct source records
+     * that share an id across scopes (e.g. `turn-0` in different conversations)
+     * are tracked independently and removing one never drops the other's edge.
+     */
+    private readonly _backlinks;
+    private constructor();
+    /** Family-convention factory. */
+    static create(): Result<MemoryIndex>;
+    /**
+     * The composite primary key for an entry: scope + id, NUL-separated. NUL
+     * is excluded from both components (scope segments pass
+     * `assertPortableFilenameStem`; `MemoryId` is portable-filename-safe), so it
+     * is a collision-proof separator across every scope/id pair the codecs produce.
+     */
+    private static _keyOf;
+    /** {@inheritDoc IMemoryIndex.rebuild} */
+    rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number>;
+    /** {@inheritDoc IMemoryIndex.patch} */
+    patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord>;
+    /** {@inheritDoc IMemoryIndex.entries} */
+    entries(): ReadonlyArray<IIndexedMemoryRecord>;
+    /** {@inheritDoc IMemoryIndex.byKind} */
+    byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>>;
+    /** {@inheritDoc IMemoryIndex.byTag} */
+    byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>>;
+    /** {@inheritDoc IMemoryIndex.byRecency} */
+    byRecency(): ReadonlyArray<IMemoryRecord<unknown>>;
+    /** {@inheritDoc IMemoryIndex.backlinks} */
+    backlinks(target: MemoryId): ReadonlyArray<MemoryId>;
+    /**
+     * Resolve a set of composite keys to their records, ordered
+     * most-recently-updated first (with a `seq` tiebreak so equal-`updated`
+     * records sort deterministically).
+     */
+    private _recencyOrdered;
+    /** Insert an entry and register all its derived associations. */
+    private _add;
+    /** Remove the entry at `key` (if present) and all its derived associations. */
+    private _remove;
+    /** Register `sourceId` (keyed by its composite `sourceKey`) as linking at `target`. */
+    private _addBacklink;
+    /** Drop the backlink from `sourceKey` to `target`, removing the target map when empty. */
+    private _removeBacklink;
+    /** Add `member` to the set at `mapKey`, creating the set on first use. */
+    private _addToSetMap;
+    /** Remove `member` from the set at `mapKey`, dropping the set when empty. */
+    private _removeFromSetMap;
+}
+//# sourceMappingURL=memoryIndex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memoryIndex.d.ts","sourceRoot":"","sources":["../../../src/packlets/index/memoryIndex.ts"],"names":[],"mappings":"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"}