@fgv/ts-agent-memory 5.1.0-47 → 5.1.0-49

package/src/packlets/converters/bodyConverterRegistry.ts

@@ -1,105 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import { Converter, Converters, Result, fail, succeed } from '@fgv/ts-utils';
-import { JsonSchema } from '@fgv/ts-json-base';
-import { Kind } from '../types';
-
-/**
- * Registry of per-kind body Converters. Each memory {@link Kind} registers the
- * validated shape of its body; the store dispatches an `unknown` body through
- * the registered Converter on every write. Type-safe — no `any`.
- * @public
- */
-export interface IBodyConverterRegistry {
-  /**
-   * Register a Converter for a kind. Replaces any prior registration for the
-   * same kind.
-   */
-  register<T>(kind: Kind, converter: Converter<T>): void;
-
-  /**
-   * Register a `JsonSchema` validator (from `@fgv/ts-json-base`) for a kind —
-   * the schema IS a Validator. Replaces any prior registration for the same
-   * kind.
-   */
-  registerSchema<T>(kind: Kind, schema: JsonSchema.ISchemaValidator<T>): void;
-
-  /** Returns `true` if a converter is registered for the kind. */
-  has(kind: Kind): boolean;
-
-  /**
-   * Get the raw converter registered for a kind. Fails if the kind is
-   * unregistered. Exposed for implementors that need to re-validate a patched
-   * body (e.g. a temporal-versioned policy's `applyUpdate`).
-   */
-  getConverter(kind: Kind): Result<Converter<unknown>>;
-
-  /**
-   * Convert an `unknown` body value for the given kind. Fails with
-   * `no converter registered for kind '<k>'` when unregistered.
-   */
-  convert(kind: Kind, body: unknown): Result<unknown>;
-}
-
-/**
- * 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
- */
-export class BodyConverterRegistry implements IBodyConverterRegistry {
-  private readonly _converters: Map<Kind, Converter<unknown>>;
-
-  private constructor() {
-    this._converters = new Map<Kind, Converter<unknown>>();
-  }
-
-  /** Family-convention factory. */
-  public static create(): Result<BodyConverterRegistry> {
-    return succeed(new BodyConverterRegistry());
-  }
-
-  /** {@inheritDoc IBodyConverterRegistry.register} */
-  public register<T>(kind: Kind, converter: Converter<T>): void {
-    this._converters.set(
-      kind,
-      Converters.generic<unknown>((from: unknown) => converter.convert(from))
-    );
-  }
-
-  /** {@inheritDoc IBodyConverterRegistry.registerSchema} */
-  public registerSchema<T>(kind: Kind, schema: JsonSchema.ISchemaValidator<T>): void {
-    this._converters.set(
-      kind,
-      Converters.generic<unknown>((from: unknown) => schema.convert(from))
-    );
-  }
-
-  /** {@inheritDoc IBodyConverterRegistry.has} */
-  public has(kind: Kind): boolean {
-    return this._converters.has(kind);
-  }
-
-  /** {@inheritDoc IBodyConverterRegistry.getConverter} */
-  public getConverter(kind: Kind): Result<Converter<unknown>> {
-    const converter: Converter<unknown> | undefined = this._converters.get(kind);
-    if (converter === undefined) {
-      return fail(`no converter registered for kind '${kind}'`);
-    }
-    return succeed(converter);
-  }
-
-  /** {@inheritDoc IBodyConverterRegistry.convert} */
-  public convert(kind: Kind, body: unknown): Result<unknown> {
-    return this.getConverter(kind).onSuccess((converter) => converter.convert(body));
-  }
-}

package/src/packlets/converters/envelopeConverter.ts

@@ -1,233 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import { Converter, Converters, Result, fail, succeed } from '@fgv/ts-utils';
-import { Yaml } from '@fgv/ts-extras';
-import {
-  Convert,
-  IEdge,
-  IEdgeTarget,
-  IMemoryEnvelope,
-  IMemoryRecord,
-  IProvenance,
-  ITemporalBlock
-} from '../types';
-import { IBodyConverterRegistry } from './bodyConverterRegistry';
-
-/** 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: Converter<null> = Converters.generic<null>((from: unknown) =>
-  from === null ? succeed(null) : 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: Converter<number | null> = Converters.oneOf<number | null>([
-  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: Converter<string | null> = Converters.oneOf<string | null>([
-  Converters.string,
-  nullConverter
-]);
-
-/**
- * Converter for a scope-qualified {@link IEdgeTarget}. Both `scope` and `id`
- * are required — the whole point of the scoped target is that a bare id is
- * ambiguous across scopes.
- * @public
- */
-export const edgeTargetConverter: Converter<IEdgeTarget> = Converters.object<IEdgeTarget>({
-  scope: Convert.scopeKey,
-  id: Convert.memoryId
-});
-
-/**
- * Converter for the known {@link IProvenance} fields. The full
- * {@link provenanceConverter} layers extension-key preservation on top.
- * `derivedFrom` is serialized as the nested `{ scope, id }` object (mirroring
- * {@link edgeConverter | edge}'s scope-qualified `target`) so the provenance
- * back-reference is unambiguous across scopes.
- */
-const knownProvenanceConverter: Converter<IProvenance> = Converters.object<IProvenance>(
-  {
-    source: Converters.string,
-    by: Converters.string.optional(),
-    model: Converters.string.optional(),
-    confidence: Converters.number.optional(),
-    derivedFrom: edgeTargetConverter.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
- */
-export const provenanceConverter: Converter<IProvenance> = Converters.generic<IProvenance>(
-  (from: unknown): Result<IProvenance> =>
-    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: IProvenance = { ...(from as Record<string, unknown>), ...known };
-      return succeed(merged);
-    })
-);
-
-/**
- * Converter for an attributed {@link IEdge}.
- * @public
- */
-export const edgeConverter: Converter<IEdge> = Converters.object<IEdge>(
-  {
-    type: Convert.linkType,
-    target: edgeTargetConverter,
-    confidence: Converters.number.optional(),
-    provenance: provenanceConverter.optional(),
-    valid_at: Converters.number.optional(),
-    invalid_at: numberOrNull.optional()
-  },
-  { optionalFields: ['confidence', 'provenance', 'valid_at', 'invalid_at'] }
-);
-
-/**
- * Converter for the optional {@link ITemporalBlock}.
- * @public
- */
-export const temporalConverter: Converter<ITemporalBlock> = Converters.object<ITemporalBlock>(
-  {
-    valid_at: 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
- */
-export const envelopeConverter: Converter<IMemoryEnvelope> = Converters.object<IMemoryEnvelope>(
-  {
-    id: Convert.memoryId,
-    entityId: Convert.entityId,
-    kind: Convert.kind,
-    tags: Converters.arrayOf(Convert.tag),
-    links: Converters.arrayOf(edgeConverter),
-    created: Converters.number,
-    updated: Converters.number,
-    seq: Converters.number,
-    contentHash: Converters.string,
-    rank: Converters.number.optional(),
-    provenance: provenanceConverter,
-    temporal: temporalConverter.optional(),
-    embeddingRef: stringOrNull.optional()
-  },
-  { optionalFields: ['rank', 'temporal', 'embeddingRef'] }
-);
-
-/**
- * Converter that parses a YAML frontmatter string into an
- * {@link IMemoryEnvelope}.
- * @public
- */
-export const envelopeYamlConverter: Converter<IMemoryEnvelope> = Yaml.yamlConverter(envelopeConverter);
-
-/** The frontmatter delimiter line. */
-const FRONTMATTER_DELIMITER: string = '---';
-
-/**
- * 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 function splitFrontmatter(raw: string): Result<IMemoryFileParts> {
-  // 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: string[] = raw.split('\n').map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line));
-  if (lines[0].trim() !== FRONTMATTER_DELIMITER) {
-    return fail("memory file: missing opening frontmatter delimiter '---'");
-  }
-  let closeIndex: number = -1;
-  for (let i = 1; i < lines.length; i++) {
-    if (lines[i].trim() === FRONTMATTER_DELIMITER) {
-      closeIndex = i;
-      break;
-    }
-  }
-  if (closeIndex === -1) {
-    return fail("memory file: missing closing frontmatter delimiter '---'");
-  }
-  return 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
- */
-export function joinFrontmatter(frontmatter: string, body: string): string {
-  const normalized: string = 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
- */
-export function parseMemoryFile(
-  raw: string,
-  registry: IBodyConverterRegistry
-): Result<IMemoryRecord<unknown>> {
-  return splitFrontmatter(raw).onSuccess((parts) =>
-    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) => 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
- */
-export function serializeMemoryFile(envelope: IMemoryEnvelope, body: string): Result<string> {
-  return Yaml.yamlStringify(envelope)
-    .withErrorFormat((msg) => `memory file '${envelope.id}': failed to serialize envelope: ${msg}`)
-    .onSuccess((frontmatter) => succeed(joinFrontmatter(frontmatter, body)));
-}

package/src/packlets/converters/index.ts

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

package/src/packlets/index/index.ts

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

package/src/packlets/index/memoryIndex.ts

@@ -1,332 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import { Result, succeed } from '@fgv/ts-utils';
-import { IEdgeTarget, IMemoryRecord, Kind, MemoryId, MemoryScopeKey, Tag, edgeTargetKey } from '../types';
-
-/**
- * The mutation a {@link IMemoryIndex.patch | patch} applies: a record was
- * written (`'put'`) or removed (`'delete'`).
- * @public
- */
-export type MemoryIndexPatchOp = 'put' | 'delete';
-
-/** Shared empty key set for `byKind` / `byTag` misses (avoids per-call allocation). */
-const EMPTY_KEY_SET: ReadonlySet<string> = new Set<string>();
-
-/**
- * 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>>;
-
-  /**
-   * All records ordered by store-computed {@link IMemoryEnvelope.rank} descending,
-   * with recency (most-recently-updated, then `seq`) as a tiebreak. Records with
-   * an absent `rank` sort LAST (after every ranked record), then by recency among
-   * themselves. Serves a bounded top-M ({@link IMemoryEnvelope.rank}-ordered) page
-   * from the in-memory index with no full-vault (filesystem) scan.
-   */
-  byRank(): ReadonlyArray<IMemoryRecord<unknown>>;
-
-  /**
-   * The scope-qualified sources of records whose `links` point AT `target`
-   * (inbound edges), keyed on the target's `(scope, id)` address. The seed map
-   * for B2 link-traversal; results are {@link IEdgeTarget}s so a caller can feed
-   * them straight back in as further traversal seeds.
-   */
-  backlinks(target: IEdgeTarget): ReadonlyArray<IEdgeTarget>;
-}
-
-/**
- * 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 class MemoryIndex implements IMemoryIndex {
-  /** Primary store: `(scope, id)` composite key → indexed entry. */
-  private readonly _byKey: Map<string, IIndexedMemoryRecord>;
-  /** kind → set of composite keys. */
-  private readonly _byKind: Map<Kind, Set<string>>;
-  /** tag → set of composite keys. */
-  private readonly _byTag: Map<Tag, Set<string>>;
-  /**
-   * canonical target key (`edgeTargetKey`) → (source composite key → source
-   * {@link IEdgeTarget}). The OUTER map is keyed on the scope-qualified target's
-   * canonical `(scope, id)` string — NOT the target's bare id — so an edge to
-   * `turn-3` in one conversation is tracked separately from `turn-3` in another.
-   * The INNER map is keyed by the source's `(scope, id)` composite so two distinct
-   * source records that share an id across scopes are tracked independently and
-   * removing one never drops the other's edge.
-   */
-  private readonly _backlinks: Map<string, Map<string, IEdgeTarget>>;
-
-  private constructor() {
-    this._byKey = new Map<string, IIndexedMemoryRecord>();
-    this._byKind = new Map<Kind, Set<string>>();
-    this._byTag = new Map<Tag, Set<string>>();
-    this._backlinks = new Map<string, Map<string, IEdgeTarget>>();
-  }
-
-  /** Family-convention factory. */
-  public static create(): Result<MemoryIndex> {
-    return succeed(new 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(scope: MemoryScopeKey, id: MemoryId): string {
-    return edgeTargetKey({ scope, id });
-  }
-
-  /** {@inheritDoc IMemoryIndex.rebuild} */
-  public rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number> {
-    this._byKey.clear();
-    this._byKind.clear();
-    this._byTag.clear();
-    this._backlinks.clear();
-    for (const entry of entries) {
-      this._add(entry);
-    }
-    return succeed(this._byKey.size);
-  }
-
-  /** {@inheritDoc IMemoryIndex.patch} */
-  public patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord> {
-    const key: string = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);
-    // Always drop any prior associations for this key first, so a 'put' that
-    // changes kind/tags/links cannot strand a stale reference.
-    this._remove(key);
-    if (op === 'put') {
-      this._add(entry);
-    }
-    return succeed(entry);
-  }
-
-  /** {@inheritDoc IMemoryIndex.entries} */
-  public entries(): ReadonlyArray<IIndexedMemoryRecord> {
-    return Array.from(this._byKey.values());
-  }
-
-  /** {@inheritDoc IMemoryIndex.byKind} */
-  public byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>> {
-    return this._recencyOrdered(this._byKind.get(kind) ?? EMPTY_KEY_SET);
-  }
-
-  /** {@inheritDoc IMemoryIndex.byTag} */
-  public byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>> {
-    return this._recencyOrdered(this._byTag.get(tag) ?? EMPTY_KEY_SET);
-  }
-
-  /** {@inheritDoc IMemoryIndex.byRecency} */
-  public byRecency(): ReadonlyArray<IMemoryRecord<unknown>> {
-    return this._recencyOrdered(this._byKey.keys());
-  }
-
-  /** {@inheritDoc IMemoryIndex.byRank} */
-  public byRank(): ReadonlyArray<IMemoryRecord<unknown>> {
-    return this._rankOrdered(this._byKey.keys());
-  }
-
-  /** {@inheritDoc IMemoryIndex.backlinks} */
-  public backlinks(target: IEdgeTarget): ReadonlyArray<IEdgeTarget> {
-    const sources: Map<string, IEdgeTarget> | undefined = this._backlinks.get(edgeTargetKey(target));
-    return sources === undefined ? [] : Array.from(sources.values());
-  }
-
-  /**
-   * 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(keys: Iterable<string>): ReadonlyArray<IMemoryRecord<unknown>> {
-    const records: IMemoryRecord<unknown>[] = [];
-    for (const key of keys) {
-      const entry: IIndexedMemoryRecord | undefined = this._byKey.get(key);
-      if (entry !== undefined) {
-        records.push(entry.record);
-      }
-    }
-    return records.sort((a, b) => {
-      const byUpdated: number = b.envelope.updated - a.envelope.updated;
-      return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;
-    });
-  }
-
-  /**
-   * Resolve a set of composite keys to their records, ordered by
-   * {@link IMemoryEnvelope.rank} descending with recency (`updated`, then `seq`)
-   * as the tiebreak. Records with an absent `rank` sort LAST, then by recency
-   * among themselves. Computed on call (mirrors {@link MemoryIndex._recencyOrdered}) —
-   * no incremental rank-ordered view is maintained, matching the recency view's
-   * approach; the sort is over the in-memory index, never a filesystem walk.
-   */
-  private _rankOrdered(keys: Iterable<string>): ReadonlyArray<IMemoryRecord<unknown>> {
-    const records: IMemoryRecord<unknown>[] = [];
-    for (const key of keys) {
-      const entry: IIndexedMemoryRecord | undefined = this._byKey.get(key);
-      if (entry !== undefined) {
-        records.push(entry.record);
-      }
-    }
-    return records.sort(MemoryIndex._compareByRank);
-  }
-
-  /**
-   * Rank-descending comparator with an absent-`rank`-last rule and a recency
-   * (`updated`, then `seq`) tiebreak. Duplicated from the retrieve packlet's
-   * `rankCompare` deliberately: the index must not depend on `retrieve` (that
-   * package depends on the index), mirroring how `_recencyOrdered` inlines the
-   * recency ordering rather than importing `recencyCompare`.
-   */
-  private static _compareByRank(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number {
-    const ra: number | undefined = a.envelope.rank;
-    const rb: number | undefined = b.envelope.rank;
-    // Absent rank sorts last; two absent ranks fall through to the recency tiebreak.
-    if (ra === undefined && rb !== undefined) {
-      return 1;
-    }
-    if (rb === undefined && ra !== undefined) {
-      return -1;
-    }
-    if (ra !== undefined && rb !== undefined && ra !== rb) {
-      return rb - ra;
-    }
-    const byUpdated: number = b.envelope.updated - a.envelope.updated;
-    return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;
-  }
-
-  /** Insert an entry and register all its derived associations. */
-  private _add(entry: IIndexedMemoryRecord): void {
-    const key: string = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);
-    const envelope: IMemoryRecord<unknown>['envelope'] = entry.record.envelope;
-    this._byKey.set(key, entry);
-    this._addToSetMap(this._byKind, envelope.kind, key);
-    for (const tag of envelope.tags) {
-      this._addToSetMap(this._byTag, tag, key);
-    }
-    for (const edge of envelope.links) {
-      this._addBacklink(edge.target, key, { scope: entry.scope, id: envelope.id });
-    }
-  }
-
-  /** Remove the entry at `key` (if present) and all its derived associations. */
-  private _remove(key: string): void {
-    const entry: IIndexedMemoryRecord | undefined = this._byKey.get(key);
-    if (entry === undefined) {
-      return;
-    }
-    const envelope: IMemoryRecord<unknown>['envelope'] = entry.record.envelope;
-    this._byKey.delete(key);
-    this._removeFromSetMap(this._byKind, envelope.kind, key);
-    for (const tag of envelope.tags) {
-      this._removeFromSetMap(this._byTag, tag, key);
-    }
-    for (const edge of envelope.links) {
-      this._removeBacklink(edge.target, key);
-    }
-  }
-
-  /** Register `source` (keyed by its composite `sourceKey`) as linking at `target`. */
-  private _addBacklink(target: IEdgeTarget, sourceKey: string, source: IEdgeTarget): void {
-    const targetKey: string = edgeTargetKey(target);
-    const existing: Map<string, IEdgeTarget> | undefined = this._backlinks.get(targetKey);
-    if (existing === undefined) {
-      this._backlinks.set(targetKey, new Map<string, IEdgeTarget>([[sourceKey, source]]));
-    } else {
-      existing.set(sourceKey, source);
-    }
-  }
-
-  /** Drop the backlink from `sourceKey` to `target`, removing the target map when empty. */
-  private _removeBacklink(target: IEdgeTarget, sourceKey: string): void {
-    const targetKey: string = edgeTargetKey(target);
-    const existing: Map<string, IEdgeTarget> | undefined = this._backlinks.get(targetKey);
-    if (existing === undefined) {
-      return;
-    }
-    existing.delete(sourceKey);
-    if (existing.size === 0) {
-      this._backlinks.delete(targetKey);
-    }
-  }
-
-  /** Add `member` to the set at `mapKey`, creating the set on first use. */
-  private _addToSetMap<K, M>(map: Map<K, Set<M>>, mapKey: K, member: M): void {
-    const existing: Set<M> | undefined = map.get(mapKey);
-    if (existing === undefined) {
-      map.set(mapKey, new Set<M>([member]));
-    } else {
-      existing.add(member);
-    }
-  }
-
-  /** Remove `member` from the set at `mapKey`, dropping the set when empty. */
-  private _removeFromSetMap<K, M>(map: Map<K, Set<M>>, mapKey: K, member: M): void {
-    const existing: Set<M> | undefined = map.get(mapKey);
-    if (existing === undefined) {
-      return;
-    }
-    existing.delete(member);
-    if (existing.size === 0) {
-      map.delete(mapKey);
-    }
-  }
-}