@fgv/ts-agent-memory 5.1.0-36

package/dist/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/dist/packlets/converters/index.js

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

package/dist/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,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './bodyConverterRegistry';\nexport * from './envelopeConverter';\n"]}

package/dist/packlets/index/index.js

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

package/dist/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,cAAc,eAAe,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './memoryIndex';\n"]}

package/dist/packlets/index/memoryIndex.js

@@ -0,0 +1,170 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import { succeed } from '@fgv/ts-utils';
+/** Shared empty key set for `byKind` / `byTag` misses (avoids per-call allocation). */
+const EMPTY_KEY_SET = new Set();
+/**
+ * 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 {
+    constructor() {
+        this._byKey = new Map();
+        this._byKind = new Map();
+        this._byTag = new Map();
+        this._backlinks = new Map();
+    }
+    /** Family-convention factory. */
+    static create() {
+        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.
+     */
+    static _keyOf(scope, id) {
+        return `${scope}\0${id}`;
+    }
+    /** {@inheritDoc IMemoryIndex.rebuild} */
+    rebuild(entries) {
+        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} */
+    patch(op, entry) {
+        const key = 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} */
+    entries() {
+        return Array.from(this._byKey.values());
+    }
+    /** {@inheritDoc IMemoryIndex.byKind} */
+    byKind(kind) {
+        var _a;
+        return this._recencyOrdered((_a = this._byKind.get(kind)) !== null && _a !== void 0 ? _a : EMPTY_KEY_SET);
+    }
+    /** {@inheritDoc IMemoryIndex.byTag} */
+    byTag(tag) {
+        var _a;
+        return this._recencyOrdered((_a = this._byTag.get(tag)) !== null && _a !== void 0 ? _a : EMPTY_KEY_SET);
+    }
+    /** {@inheritDoc IMemoryIndex.byRecency} */
+    byRecency() {
+        return this._recencyOrdered(this._byKey.keys());
+    }
+    /** {@inheritDoc IMemoryIndex.backlinks} */
+    backlinks(target) {
+        const sources = this._backlinks.get(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).
+     */
+    _recencyOrdered(keys) {
+        const records = [];
+        for (const key of keys) {
+            const entry = this._byKey.get(key);
+            if (entry !== undefined) {
+                records.push(entry.record);
+            }
+        }
+        return records.sort((a, b) => {
+            const byUpdated = 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. */
+    _add(entry) {
+        const key = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);
+        const 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, envelope.id);
+        }
+    }
+    /** Remove the entry at `key` (if present) and all its derived associations. */
+    _remove(key) {
+        const entry = this._byKey.get(key);
+        if (entry === undefined) {
+            return;
+        }
+        const 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 `sourceId` (keyed by its composite `sourceKey`) as linking at `target`. */
+    _addBacklink(target, sourceKey, sourceId) {
+        const existing = this._backlinks.get(target);
+        if (existing === undefined) {
+            this._backlinks.set(target, new Map([[sourceKey, sourceId]]));
+        }
+        else {
+            existing.set(sourceKey, sourceId);
+        }
+    }
+    /** Drop the backlink from `sourceKey` to `target`, removing the target map when empty. */
+    _removeBacklink(target, sourceKey) {
+        const existing = this._backlinks.get(target);
+        if (existing === undefined) {
+            return;
+        }
+        existing.delete(sourceKey);
+        if (existing.size === 0) {
+            this._backlinks.delete(target);
+        }
+    }
+    /** Add `member` to the set at `mapKey`, creating the set on first use. */
+    _addToSetMap(map, mapKey, member) {
+        const existing = map.get(mapKey);
+        if (existing === undefined) {
+            map.set(mapKey, new Set([member]));
+        }
+        else {
+            existing.add(member);
+        }
+    }
+    /** Remove `member` from the set at `mapKey`, dropping the set when empty. */
+    _removeFromSetMap(map, mapKey, member) {
+        const existing = map.get(mapKey);
+        if (existing === undefined) {
+            return;
+        }
+        existing.delete(member);
+        if (existing.size === 0) {
+            map.delete(mapKey);
+        }
+    }
+}
+//# sourceMappingURL=memoryIndex.js.map

package/dist/packlets/index/memoryIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryIndex.js","sourceRoot":"","sources":["../../../src/packlets/index/memoryIndex.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord, Kind, MemoryId, MemoryScopeKey, Tag } from '../types';\n\n/**\n * The mutation a {@link IMemoryIndex.patch | patch} applies: a record was\n * written (`'put'`) or removed (`'delete'`).\n * @public\n */\nexport type MemoryIndexPatchOp = 'put' | 'delete';\n\n/** Shared empty key set for `byKind` / `byTag` misses (avoids per-call allocation). */\nconst EMPTY_KEY_SET: ReadonlySet<string> = new Set<string>();\n\n/**\n * A memory record paired with the {@link MemoryScopeKey | scope} it lives\n * under. The scope is not carried on the {@link IMemoryEnvelope} (it is derived\n * from the entity id by the codec), so the store threads it alongside the\n * record when patching or rebuilding the index. The `(scope, id)` pair is the\n * index's primary key, keeping records distinct across scopes that reuse a\n * filename stem (e.g. `turn-0` under different conversations in Phase C).\n * @public\n */\nexport interface IIndexedMemoryRecord {\n  /** The scope the record is stored under. */\n  readonly scope: MemoryScopeKey;\n  /** The memory record itself. */\n  readonly record: IMemoryRecord<unknown>;\n}\n\n/**\n * The derived, in-memory secondary indexes the store maintains over its\n * records. Never the source of truth — the FileTree is. The index is fully\n * rebuildable from a walk of the store ({@link IMemoryIndex.rebuild}) and is\n * patched incrementally on every write ({@link IMemoryIndex.patch}).\n *\n * @remarks\n * B1 builds the maps; link-traversal BFS over {@link IMemoryIndex.backlinks}\n * is B2. The accessors return records (not bare ids) so the B2 retrievers can\n * consume them directly.\n * @public\n */\nexport interface IMemoryIndex {\n  /**\n   * Replace the entire index from a full set of records (a store walk).\n   * @returns The number of records indexed.\n   */\n  rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number>;\n\n  /**\n   * Apply a single incremental change. `'put'` inserts or replaces the entry\n   * at its `(scope, id)` key (removing any prior associations first); `'delete'`\n   * removes it.\n   * @returns The entry that was applied.\n   */\n  patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord>;\n\n  /** Every indexed entry (scope + record). Primary read surface for the store. */\n  entries(): ReadonlyArray<IIndexedMemoryRecord>;\n\n  /** Records of the given kind, in recency order (most-recently-updated first). */\n  byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>>;\n\n  /** Records carrying the given tag, in recency order. */\n  byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>>;\n\n  /** All records in recency order (most-recently-updated first). */\n  byRecency(): ReadonlyArray<IMemoryRecord<unknown>>;\n\n  /**\n   * The ids of records whose `links` point AT `target` (inbound edges).\n   * The seed map for B2 link-traversal.\n   */\n  backlinks(target: MemoryId): ReadonlyArray<MemoryId>;\n}\n\n/**\n * Default in-memory {@link IMemoryIndex}. Maintains the derived `byKind` /\n * `byTag` / `byRecency` / `backlinks` views incrementally; a `'put'` for an\n * already-indexed key first removes the prior entry's associations so a changed\n * kind / tag / link set never leaves a stale reference behind.\n * @public\n */\nexport class MemoryIndex implements IMemoryIndex {\n  /** Primary store: `(scope, id)` composite key → indexed entry. */\n  private readonly _byKey: Map<string, IIndexedMemoryRecord>;\n  /** kind → set of composite keys. */\n  private readonly _byKind: Map<Kind, Set<string>>;\n  /** tag → set of composite keys. */\n  private readonly _byTag: Map<Tag, Set<string>>;\n  /**\n   * link target id → (source composite key → source id). Keyed by the source's\n   * `(scope, id)` composite — NOT its bare id — so two distinct source records\n   * that share an id across scopes (e.g. `turn-0` in different conversations)\n   * are tracked independently and removing one never drops the other's edge.\n   */\n  private readonly _backlinks: Map<MemoryId, Map<string, MemoryId>>;\n\n  private constructor() {\n    this._byKey = new Map<string, IIndexedMemoryRecord>();\n    this._byKind = new Map<Kind, Set<string>>();\n    this._byTag = new Map<Tag, Set<string>>();\n    this._backlinks = new Map<MemoryId, Map<string, MemoryId>>();\n  }\n\n  /** Family-convention factory. */\n  public static create(): Result<MemoryIndex> {\n    return succeed(new MemoryIndex());\n  }\n\n  /**\n   * The composite primary key for an entry: scope + id, NUL-separated. NUL\n   * is excluded from both components (scope segments pass\n   * `assertPortableFilenameStem`; `MemoryId` is portable-filename-safe), so it\n   * is a collision-proof separator across every scope/id pair the codecs produce.\n   */\n  private static _keyOf(scope: MemoryScopeKey, id: MemoryId): string {\n    return `${scope}\\0${id}`;\n  }\n\n  /** {@inheritDoc IMemoryIndex.rebuild} */\n  public rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number> {\n    this._byKey.clear();\n    this._byKind.clear();\n    this._byTag.clear();\n    this._backlinks.clear();\n    for (const entry of entries) {\n      this._add(entry);\n    }\n    return succeed(this._byKey.size);\n  }\n\n  /** {@inheritDoc IMemoryIndex.patch} */\n  public patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord> {\n    const key: string = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);\n    // Always drop any prior associations for this key first, so a 'put' that\n    // changes kind/tags/links cannot strand a stale reference.\n    this._remove(key);\n    if (op === 'put') {\n      this._add(entry);\n    }\n    return succeed(entry);\n  }\n\n  /** {@inheritDoc IMemoryIndex.entries} */\n  public entries(): ReadonlyArray<IIndexedMemoryRecord> {\n    return Array.from(this._byKey.values());\n  }\n\n  /** {@inheritDoc IMemoryIndex.byKind} */\n  public byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>> {\n    return this._recencyOrdered(this._byKind.get(kind) ?? EMPTY_KEY_SET);\n  }\n\n  /** {@inheritDoc IMemoryIndex.byTag} */\n  public byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>> {\n    return this._recencyOrdered(this._byTag.get(tag) ?? EMPTY_KEY_SET);\n  }\n\n  /** {@inheritDoc IMemoryIndex.byRecency} */\n  public byRecency(): ReadonlyArray<IMemoryRecord<unknown>> {\n    return this._recencyOrdered(this._byKey.keys());\n  }\n\n  /** {@inheritDoc IMemoryIndex.backlinks} */\n  public backlinks(target: MemoryId): ReadonlyArray<MemoryId> {\n    const sources: Map<string, MemoryId> | undefined = this._backlinks.get(target);\n    return sources === undefined ? [] : Array.from(sources.values());\n  }\n\n  /**\n   * Resolve a set of composite keys to their records, ordered\n   * most-recently-updated first (with a `seq` tiebreak so equal-`updated`\n   * records sort deterministically).\n   */\n  private _recencyOrdered(keys: Iterable<string>): ReadonlyArray<IMemoryRecord<unknown>> {\n    const records: IMemoryRecord<unknown>[] = [];\n    for (const key of keys) {\n      const entry: IIndexedMemoryRecord | undefined = this._byKey.get(key);\n      if (entry !== undefined) {\n        records.push(entry.record);\n      }\n    }\n    return records.sort((a, b) => {\n      const byUpdated: number = b.envelope.updated - a.envelope.updated;\n      return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;\n    });\n  }\n\n  /** Insert an entry and register all its derived associations. */\n  private _add(entry: IIndexedMemoryRecord): void {\n    const key: string = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);\n    const envelope: IMemoryRecord<unknown>['envelope'] = entry.record.envelope;\n    this._byKey.set(key, entry);\n    this._addToSetMap(this._byKind, envelope.kind, key);\n    for (const tag of envelope.tags) {\n      this._addToSetMap(this._byTag, tag, key);\n    }\n    for (const edge of envelope.links) {\n      this._addBacklink(edge.target, key, envelope.id);\n    }\n  }\n\n  /** Remove the entry at `key` (if present) and all its derived associations. */\n  private _remove(key: string): void {\n    const entry: IIndexedMemoryRecord | undefined = this._byKey.get(key);\n    if (entry === undefined) {\n      return;\n    }\n    const envelope: IMemoryRecord<unknown>['envelope'] = entry.record.envelope;\n    this._byKey.delete(key);\n    this._removeFromSetMap(this._byKind, envelope.kind, key);\n    for (const tag of envelope.tags) {\n      this._removeFromSetMap(this._byTag, tag, key);\n    }\n    for (const edge of envelope.links) {\n      this._removeBacklink(edge.target, key);\n    }\n  }\n\n  /** Register `sourceId` (keyed by its composite `sourceKey`) as linking at `target`. */\n  private _addBacklink(target: MemoryId, sourceKey: string, sourceId: MemoryId): void {\n    const existing: Map<string, MemoryId> | undefined = this._backlinks.get(target);\n    if (existing === undefined) {\n      this._backlinks.set(target, new Map<string, MemoryId>([[sourceKey, sourceId]]));\n    } else {\n      existing.set(sourceKey, sourceId);\n    }\n  }\n\n  /** Drop the backlink from `sourceKey` to `target`, removing the target map when empty. */\n  private _removeBacklink(target: MemoryId, sourceKey: string): void {\n    const existing: Map<string, MemoryId> | undefined = this._backlinks.get(target);\n    if (existing === undefined) {\n      return;\n    }\n    existing.delete(sourceKey);\n    if (existing.size === 0) {\n      this._backlinks.delete(target);\n    }\n  }\n\n  /** Add `member` to the set at `mapKey`, creating the set on first use. */\n  private _addToSetMap<K, M>(map: Map<K, Set<M>>, mapKey: K, member: M): void {\n    const existing: Set<M> | undefined = map.get(mapKey);\n    if (existing === undefined) {\n      map.set(mapKey, new Set<M>([member]));\n    } else {\n      existing.add(member);\n    }\n  }\n\n  /** Remove `member` from the set at `mapKey`, dropping the set when empty. */\n  private _removeFromSetMap<K, M>(map: Map<K, Set<M>>, mapKey: K, member: M): void {\n    const existing: Set<M> | undefined = map.get(mapKey);\n    if (existing === undefined) {\n      return;\n    }\n    existing.delete(member);\n    if (existing.size === 0) {\n      map.delete(mapKey);\n    }\n  }\n}\n"]}

package/dist/packlets/observe/index.js

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+export * from './observer';
+export * from './memoryObservationStore';
+//# sourceMappingURL=index.js.map

package/dist/packlets/observe/index.js.map

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

package/dist/packlets/observe/memoryObservationStore.js

@@ -0,0 +1,119 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import { Collections, fail, succeed } from '@fgv/ts-utils';
+/**
+ * The default in-memory observation store: an {@link IMemoryObserver} that
+ * retains the records it observes in a bounded ring and answers schema-aware
+ * {@link MemoryObservationStore.query | queries} over them.
+ *
+ * @remarks
+ * **Privacy posture — this store is most-permissive by design.** It retains
+ * every field of every record verbatim, including any `provenance` and
+ * `querySnapshot`. The library bakes in **no** redaction, retention, or
+ * field-stripping policy — that is deployment policy, not library policy. A
+ * deployment that must redact wraps this store with its own
+ * {@link IMemoryObserver} that transforms records before forwarding, or
+ * substitutes a different observer entirely. Size is the only bounded
+ * dimension, via `maxRecords`.
+ *
+ * The store composes `RetainingRingBuffer` from `@fgv/ts-utils` (it does not
+ * hand-roll a ring) and implements {@link IMemoryObserver} directly — `observe`
+ * (the hook) and `query` (the read surface) live on the same class. Wire it via
+ * {@link IFileTreeMemoryStoreCreateParams.observers}. `seq` and `timestamp` are
+ * assigned by the firing authority (the store) before `observe`, so this store
+ * never mints them.
+ * @public
+ */
+export class MemoryObservationStore {
+    /**
+     * @param buffer - The pre-constructed backing ring buffer.
+     * @internal
+     */
+    constructor(buffer) {
+        this._buffer = buffer;
+    }
+    /**
+     * The highest `seq` observed so far. Hold this value and pass it as
+     * `sinceSeq` to {@link MemoryObservationStore.query | query} to page only
+     * records observed afterward. Stable across ring eviction and
+     * {@link MemoryObservationStore.clear | clear}.
+     */
+    get lastSeq() {
+        return this._buffer.lastSeq;
+    }
+    /**
+     * The number of records currently retained.
+     */
+    get size() {
+        return this._buffer.size;
+    }
+    /**
+     * Family-convention factory.
+     * @param params - {@link IMemoryObservationStoreCreateParams | Construction options}.
+     * @returns On success, a new store. Fails if `maxRecords` is supplied and is
+     * not a positive integer.
+     */
+    static create(params) {
+        const maxRecords = params === null || params === void 0 ? void 0 : params.maxRecords;
+        if (maxRecords !== undefined && (!Number.isInteger(maxRecords) || maxRecords < 1)) {
+            return fail(`MemoryObservationStore: maxRecords must be a positive integer (got ${maxRecords})`);
+        }
+        return succeed(new MemoryObservationStore(new Collections.RetainingRingBuffer({ maxRecords })));
+    }
+    /**
+     * {@inheritDoc IMemoryObserver.observe}
+     */
+    observe(record) {
+        this._buffer.push(record);
+        return Promise.resolve(succeed(record));
+    }
+    /**
+     * Returns retained records, oldest-first, narrowed by the supplied criteria.
+     * @param criteria - {@link IMemoryObservationQuery | AND-combined filter criteria}.
+     * @returns The matching records, oldest-first.
+     */
+    query(criteria) {
+        return this._buffer.query({
+            sinceSeq: criteria === null || criteria === void 0 ? void 0 : criteria.sinceSeq,
+            limit: criteria === null || criteria === void 0 ? void 0 : criteria.limit,
+            filter: criteria === undefined ? undefined : (record) => MemoryObservationStore._matches(record, criteria)
+        });
+    }
+    /**
+     * Clears all retained records. Does NOT reset
+     * {@link MemoryObservationStore.lastSeq | lastSeq}, so a held `sinceSeq`
+     * cursor never re-sees a sequence number.
+     */
+    clear() {
+        this._buffer.clear();
+    }
+    /**
+     * Tests a record against the non-`seq`/`limit` criteria (those are applied by
+     * the ring buffer itself).
+     * @internal
+     */
+    static _matches(record, criteria) {
+        if (criteria.since !== undefined && record.timestamp < criteria.since) {
+            return false;
+        }
+        if (criteria.until !== undefined && record.timestamp > criteria.until) {
+            return false;
+        }
+        if (criteria.scope !== undefined && record.scope !== criteria.scope) {
+            return false;
+        }
+        if (criteria.kind !== undefined && record.kind !== criteria.kind) {
+            return false;
+        }
+        if (criteria.phase !== undefined && record.phase !== criteria.phase) {
+            return false;
+        }
+        if (criteria.outcome !== undefined && record.outcome !== criteria.outcome) {
+            return false;
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=memoryObservationStore.js.map

package/dist/packlets/observe/memoryObservationStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryObservationStore.js","sourceRoot":"","sources":["../../../src/packlets/observe/memoryObservationStore.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Collections, Result, fail, succeed } from '@fgv/ts-utils';\nimport { IMemoryObservationQuery, IMemoryObservationRecord, IMemoryObserver } from './observer';\n\n/**\n * Construction options for {@link MemoryObservationStore.create}.\n * @public\n */\nexport interface IMemoryObservationStoreCreateParams {\n  /**\n   * Maximum number of observation records retained before the oldest is\n   * overwritten. Defaults to `1000`. Must be a positive integer if supplied.\n   */\n  readonly maxRecords?: number;\n}\n\n/**\n * The default in-memory observation store: an {@link IMemoryObserver} that\n * retains the records it observes in a bounded ring and answers schema-aware\n * {@link MemoryObservationStore.query | queries} over them.\n *\n * @remarks\n * **Privacy posture — this store is most-permissive by design.** It retains\n * every field of every record verbatim, including any `provenance` and\n * `querySnapshot`. The library bakes in **no** redaction, retention, or\n * field-stripping policy — that is deployment policy, not library policy. A\n * deployment that must redact wraps this store with its own\n * {@link IMemoryObserver} that transforms records before forwarding, or\n * substitutes a different observer entirely. Size is the only bounded\n * dimension, via `maxRecords`.\n *\n * The store composes `RetainingRingBuffer` from `@fgv/ts-utils` (it does not\n * hand-roll a ring) and implements {@link IMemoryObserver} directly — `observe`\n * (the hook) and `query` (the read surface) live on the same class. Wire it via\n * {@link IFileTreeMemoryStoreCreateParams.observers}. `seq` and `timestamp` are\n * assigned by the firing authority (the store) before `observe`, so this store\n * never mints them.\n * @public\n */\nexport class MemoryObservationStore implements IMemoryObserver {\n  /**\n   * The bounded ring of observed records. The firing authority assigns each\n   * record's `seq`, so the ring's monotonic-`seq` cursor contract is satisfied\n   * by that authority's per-instance counter.\n   * @internal\n   */\n  private readonly _buffer: Collections.RetainingRingBuffer<IMemoryObservationRecord>;\n\n  /**\n   * @param buffer - The pre-constructed backing ring buffer.\n   * @internal\n   */\n  private constructor(buffer: Collections.RetainingRingBuffer<IMemoryObservationRecord>) {\n    this._buffer = buffer;\n  }\n\n  /**\n   * The highest `seq` observed so far. Hold this value and pass it as\n   * `sinceSeq` to {@link MemoryObservationStore.query | query} to page only\n   * records observed afterward. Stable across ring eviction and\n   * {@link MemoryObservationStore.clear | clear}.\n   */\n  public get lastSeq(): number {\n    return this._buffer.lastSeq;\n  }\n\n  /**\n   * The number of records currently retained.\n   */\n  public get size(): number {\n    return this._buffer.size;\n  }\n\n  /**\n   * Family-convention factory.\n   * @param params - {@link IMemoryObservationStoreCreateParams | Construction options}.\n   * @returns On success, a new store. Fails if `maxRecords` is supplied and is\n   * not a positive integer.\n   */\n  public static create(params?: IMemoryObservationStoreCreateParams): Result<MemoryObservationStore> {\n    const maxRecords: number | undefined = params?.maxRecords;\n    if (maxRecords !== undefined && (!Number.isInteger(maxRecords) || maxRecords < 1)) {\n      return fail(`MemoryObservationStore: maxRecords must be a positive integer (got ${maxRecords})`);\n    }\n    return succeed(\n      new MemoryObservationStore(\n        new Collections.RetainingRingBuffer<IMemoryObservationRecord>({ maxRecords })\n      )\n    );\n  }\n\n  /**\n   * {@inheritDoc IMemoryObserver.observe}\n   */\n  public observe(record: IMemoryObservationRecord): Promise<Result<unknown>> {\n    this._buffer.push(record);\n    return Promise.resolve(succeed(record));\n  }\n\n  /**\n   * Returns retained records, oldest-first, narrowed by the supplied criteria.\n   * @param criteria - {@link IMemoryObservationQuery | AND-combined filter criteria}.\n   * @returns The matching records, oldest-first.\n   */\n  public query(criteria?: IMemoryObservationQuery): ReadonlyArray<IMemoryObservationRecord> {\n    return this._buffer.query({\n      sinceSeq: criteria?.sinceSeq,\n      limit: criteria?.limit,\n      filter:\n        criteria === undefined ? undefined : (record) => MemoryObservationStore._matches(record, criteria)\n    });\n  }\n\n  /**\n   * Clears all retained records. Does NOT reset\n   * {@link MemoryObservationStore.lastSeq | lastSeq}, so a held `sinceSeq`\n   * cursor never re-sees a sequence number.\n   */\n  public clear(): void {\n    this._buffer.clear();\n  }\n\n  /**\n   * Tests a record against the non-`seq`/`limit` criteria (those are applied by\n   * the ring buffer itself).\n   * @internal\n   */\n  private static _matches(record: IMemoryObservationRecord, criteria: IMemoryObservationQuery): boolean {\n    if (criteria.since !== undefined && record.timestamp < criteria.since) {\n      return false;\n    }\n    if (criteria.until !== undefined && record.timestamp > criteria.until) {\n      return false;\n    }\n    if (criteria.scope !== undefined && record.scope !== criteria.scope) {\n      return false;\n    }\n    if (criteria.kind !== undefined && record.kind !== criteria.kind) {\n      return false;\n    }\n    if (criteria.phase !== undefined && record.phase !== criteria.phase) {\n      return false;\n    }\n    if (criteria.outcome !== undefined && record.outcome !== criteria.outcome) {\n      return false;\n    }\n    return true;\n  }\n}\n"]}

package/dist/packlets/observe/observer.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+export {};
+//# sourceMappingURL=observer.js.map

package/dist/packlets/observe/observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.js","sourceRoot":"","sources":["../../../src/packlets/observe/observer.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result } from '@fgv/ts-utils';\nimport { IProvenance, Kind, MemoryId, MemoryScopeKey } from '../types';\n\n/**\n * The store/retriever operation an observation record describes.\n *\n * @remarks\n * `'read'` / `'write'` / `'delete'` are fired post-op by\n * {@link FileTreeMemoryStore} (on `get` / `put` / `delete` respectively) when\n * observers are wired. `'retrieve'` is reserved for retriever-fired\n * observations; no B2 retriever fires one (a single seq authority per\n * observation store is the supported topology), so it never appears in B2 but\n * is part of the vocabulary so a future retriever-firing hook is additive.\n * @public\n */\nexport type MemoryObservationPhase = 'read' | 'write' | 'delete' | 'retrieve';\n\n/**\n * The outcome of the observed operation.\n * @public\n */\nexport type MemoryObservationOutcome = 'success' | 'failure';\n\n/**\n * A single audit record produced by an observed store (or retriever) operation.\n *\n * @remarks\n * `seq` and `timestamp` are assigned by the firing authority (the store) before\n * fan-out, so the same record carries the same `seq` across every observer it\n * lands in. `seq` is strictly increasing per authority, satisfying the\n * `RetainingRingBuffer` cursor contract that {@link MemoryObservationStore}\n * relies on.\n * @public\n */\nexport interface IMemoryObservationRecord {\n  /**\n   * Monotonic 1-based sequence number assigned by the firing authority, stable\n   * across a store's ring eviction. The ordering / paging key.\n   */\n  readonly seq: number;\n  /** Milliseconds since epoch when the firing authority produced the record. */\n  readonly timestamp: number;\n  /** Which operation this record describes. */\n  readonly phase: MemoryObservationPhase;\n  /** The scope the operation touched, when resolvable. */\n  readonly scope?: MemoryScopeKey;\n  /** The record id the operation touched, when resolvable. */\n  readonly id?: MemoryId;\n  /** The kind the operation targeted, when known. */\n  readonly kind?: Kind;\n  /** Whether the operation succeeded. */\n  readonly outcome: MemoryObservationOutcome;\n  /** Present on failure: the failure `Result`'s message. */\n  readonly error?: string;\n  /** Structured provenance of the write, when the operation carried one. */\n  readonly provenance?: IProvenance;\n  /**\n   * For `'retrieve'` observations: an opaque snapshot of the query that drove\n   * the retrieval. Carried verbatim; never interpreted by the store.\n   */\n  readonly querySnapshot?: Readonly<Record<string, unknown>>;\n}\n\n/**\n * Single-method async observer hook. The store fires `observe` once per public\n * `get` / `put` / `delete` call when observers are wired.\n *\n * @remarks\n * Observer errors never affect the store operation — the store swallows a\n * failed `Result` or a thrown / rejected `observe`, logging it to the injected\n * diagnostic logger at `warn`.\n * @public\n */\nexport interface IMemoryObserver {\n  /**\n   * When `true`, the store dispatches `observe` without awaiting it, so a slow\n   * remote observer (SIEM, network sink) does not extend the store operation's\n   * latency. Defaults to `false` (awaited), which is correct for the cheap\n   * in-memory default {@link MemoryObservationStore}. Errors are swallowed\n   * either way.\n   */\n  readonly fireAndForget?: boolean;\n  /**\n   * Receives a fully-formed observation record.\n   * @param record - The observation record.\n   * @returns A `Result` whose failure is swallowed (logged to the store's\n   * diagnostic logger). A rejected promise is likewise swallowed.\n   */\n  observe(record: IMemoryObservationRecord): Promise<Result<unknown>>;\n}\n\n/**\n * Query criteria for {@link MemoryObservationStore.query}. All supplied criteria\n * are AND-combined.\n * @public\n */\nexport interface IMemoryObservationQuery {\n  /** Only records with `seq > sinceSeq` (incremental paging cursor). */\n  readonly sinceSeq?: number;\n  /** Return at most this many records — the most-recent N, still oldest-first. */\n  readonly limit?: number;\n  /** Only records with `timestamp >= since`. */\n  readonly since?: number;\n  /** Only records with `timestamp <= until`. */\n  readonly until?: number;\n  /** Only records that touched this scope. */\n  readonly scope?: MemoryScopeKey;\n  /** Only records that targeted this kind. */\n  readonly kind?: Kind;\n  /** Only records of this phase. */\n  readonly phase?: MemoryObservationPhase;\n  /** Only records with this outcome. */\n  readonly outcome?: MemoryObservationOutcome;\n}\n"]}

package/dist/packlets/retrieve/hybridRetriever.js

@@ -0,0 +1,135 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import { fail, mapResults, succeed } from '@fgv/ts-utils';
+import { guardRetrieverCapabilities, limitRecords, recencyCompare } from './retriever';
+/**
+ * The reference {@link IMergeStrategy}: a score-union. Every record is scored by
+ * the number of composed result sets it appears in (deduplicated by
+ * {@link IMemoryEnvelope.id | id}); the merged result is ordered by descending
+ * score, then by recency. Records surfaced by more retrievers rank higher.
+ *
+ * @remarks
+ * Dedup is by `id` alone, which is unambiguous for the flat (one-file-per-entity)
+ * kinds B2 ships. Phase-C versioned kinds that reuse a stem across scopes will
+ * extend the dedup key — additive, no API change.
+ * @public
+ */
+export class ScoreUnionMergeStrategy {
+    constructor() { }
+    /** Family-convention factory. */
+    static create() {
+        return succeed(new ScoreUnionMergeStrategy());
+    }
+    /** {@inheritDoc IMergeStrategy.merge} */
+    merge(resultSets) {
+        const scored = new Map();
+        for (const set of resultSets) {
+            // Count each id at most once per result set, so the score is "how many
+            // retrievers surfaced this record" rather than "how many copies total".
+            const seenInSet = new Set();
+            for (const record of set) {
+                const id = record.envelope.id;
+                if (seenInSet.has(id)) {
+                    continue;
+                }
+                seenInSet.add(id);
+                const existing = scored.get(id);
+                if (existing === undefined) {
+                    scored.set(id, { record, score: 1 });
+                }
+                else {
+                    existing.score += 1;
+                }
+            }
+        }
+        const merged = Array.from(scored.values())
+            .sort((a, b) => (b.score !== a.score ? b.score - a.score : recencyCompare(a.record, b.record)))
+            .map((entry) => entry.record);
+        return succeed(merged);
+    }
+}
+/**
+ * Composes several retrievers, dispatches a query to each, and merges their
+ * results via an injectable {@link IMergeStrategy}. Its capabilities are the
+ * union of the composed retrievers' capabilities.
+ *
+ * @remarks
+ * The hybrid enforces the loud-degradation contract against its OWN (union)
+ * capabilities, then projects the query for each child: a child that does not
+ * support the `semantic` (or `asOf`) axis is handed a query with that axis
+ * stripped, so it returns its normal results instead of loud-failing on a field
+ * a sibling handles. A child that genuinely fails (e.g. a wired semantic backend
+ * erroring) propagates — the hybrid never silently drops a failure.
+ * @public
+ */
+export class HybridRetriever {
+    constructor(retrievers, mergeStrategy, capabilities) {
+        this._retrievers = retrievers;
+        this._mergeStrategy = mergeStrategy;
+        this._capabilities = capabilities;
+    }
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities() {
+        return this._capabilities;
+    }
+    /**
+     * Family-convention factory.
+     * @param retrievers - The retrievers to compose (at least one).
+     * @param mergeStrategy - How to combine their results.
+     */
+    static create(retrievers, mergeStrategy) {
+        if (retrievers.length === 0) {
+            return fail('HybridRetriever: at least one retriever is required');
+        }
+        // Snapshot the caller's array so a later mutation cannot make `retrieve()`
+        // and the cached `capabilities` disagree.
+        const stableRetrievers = [...retrievers];
+        const capabilities = {
+            supportsSemanticRecall: stableRetrievers.some((r) => r.capabilities.supportsSemanticRecall),
+            supportsTemporalQuery: stableRetrievers.some((r) => r.capabilities.supportsTemporalQuery),
+            supportsLinkTraversal: stableRetrievers.some((r) => r.capabilities.supportsLinkTraversal)
+        };
+        return succeed(new HybridRetriever(stableRetrievers, mergeStrategy, capabilities));
+    }
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    async retrieve(query) {
+        return guardRetrieverCapabilities(query, this._capabilities).thenOnSuccess(async () => {
+            const perRetriever = await Promise.all(this._retrievers.map((retriever) => retriever.retrieve(this._projectQuery(query, retriever))));
+            return mapResults(perRetriever)
+                .onSuccess((resultSets) => this._mergeStrategy.merge(resultSets))
+                .onSuccess((merged) => succeed(limitRecords(merged, query.limit)));
+        });
+    }
+    /**
+     * Project the query for one child retriever. Two adjustments:
+     *
+     * - Strip axes the child does not support (`semantic` / `topK` for a
+     *   non-semantic child, `asOf` for a non-temporal child, the link axes for a
+     *   non-link child) so it returns its normal results rather than loud-failing
+     *   on a field a sibling handles.
+     * - Strip `limit` unconditionally: limit is a post-merge concern. A child that
+     *   pre-truncated its result set would starve the merge strategy of candidates
+     *   it needs to score correctly (a record both children would surface must
+     *   reach the merge to score 2). The hybrid applies `limit` once, after merge.
+     */
+    _projectQuery(query, retriever) {
+        const projected = Object.assign({}, query);
+        delete projected.limit;
+        if (!retriever.capabilities.supportsSemanticRecall) {
+            delete projected.semantic;
+            delete projected.topK;
+        }
+        if (!retriever.capabilities.supportsTemporalQuery) {
+            delete projected.asOf;
+        }
+        if (!retriever.capabilities.supportsLinkTraversal) {
+            delete projected.linkedFrom;
+            delete projected.linkedTo;
+            delete projected.hops;
+        }
+        return projected;
+    }
+}
+//# sourceMappingURL=hybridRetriever.js.map

package/dist/packlets/retrieve/hybridRetriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybridRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/hybridRetriever.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, mapResults, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord, MemoryId } from '../types';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  guardRetrieverCapabilities,\n  limitRecords,\n  recencyCompare\n} from './retriever';\n\n/**\n * Strategy for combining the result sets of the retrievers a\n * {@link HybridRetriever} composes. Injectable so a consumer can weight,\n * re-rank, or intersect instead of the default union.\n * @public\n */\nexport interface IMergeStrategy {\n  /**\n   * Merge the per-retriever result sets into a single ordered result.\n   * @param resultSets - One entry per composed retriever, in composition order.\n   */\n  merge(\n    resultSets: ReadonlyArray<ReadonlyArray<IMemoryRecord<unknown>>>\n  ): Result<ReadonlyArray<IMemoryRecord<unknown>>>;\n}\n\n/**\n * The reference {@link IMergeStrategy}: a score-union. Every record is scored by\n * the number of composed result sets it appears in (deduplicated by\n * {@link IMemoryEnvelope.id | id}); the merged result is ordered by descending\n * score, then by recency. Records surfaced by more retrievers rank higher.\n *\n * @remarks\n * Dedup is by `id` alone, which is unambiguous for the flat (one-file-per-entity)\n * kinds B2 ships. Phase-C versioned kinds that reuse a stem across scopes will\n * extend the dedup key — additive, no API change.\n * @public\n */\nexport class ScoreUnionMergeStrategy implements IMergeStrategy {\n  private constructor() {}\n\n  /** Family-convention factory. */\n  public static create(): Result<ScoreUnionMergeStrategy> {\n    return succeed(new ScoreUnionMergeStrategy());\n  }\n\n  /** {@inheritDoc IMergeStrategy.merge} */\n  public merge(\n    resultSets: ReadonlyArray<ReadonlyArray<IMemoryRecord<unknown>>>\n  ): Result<ReadonlyArray<IMemoryRecord<unknown>>> {\n    const scored: Map<MemoryId, { readonly record: IMemoryRecord<unknown>; score: number }> = new Map();\n    for (const set of resultSets) {\n      // Count each id at most once per result set, so the score is \"how many\n      // retrievers surfaced this record\" rather than \"how many copies total\".\n      const seenInSet: Set<MemoryId> = new Set<MemoryId>();\n      for (const record of set) {\n        const id: MemoryId = record.envelope.id;\n        if (seenInSet.has(id)) {\n          continue;\n        }\n        seenInSet.add(id);\n        const existing = scored.get(id);\n        if (existing === undefined) {\n          scored.set(id, { record, score: 1 });\n        } else {\n          existing.score += 1;\n        }\n      }\n    }\n    const merged: IMemoryRecord<unknown>[] = Array.from(scored.values())\n      .sort((a, b) => (b.score !== a.score ? b.score - a.score : recencyCompare(a.record, b.record)))\n      .map((entry) => entry.record);\n    return succeed(merged);\n  }\n}\n\n/**\n * Composes several retrievers, dispatches a query to each, and merges their\n * results via an injectable {@link IMergeStrategy}. Its capabilities are the\n * union of the composed retrievers' capabilities.\n *\n * @remarks\n * The hybrid enforces the loud-degradation contract against its OWN (union)\n * capabilities, then projects the query for each child: a child that does not\n * support the `semantic` (or `asOf`) axis is handed a query with that axis\n * stripped, so it returns its normal results instead of loud-failing on a field\n * a sibling handles. A child that genuinely fails (e.g. a wired semantic backend\n * erroring) propagates — the hybrid never silently drops a failure.\n * @public\n */\nexport class HybridRetriever implements IMemoryRetriever {\n  private readonly _retrievers: ReadonlyArray<IMemoryRetriever>;\n  private readonly _mergeStrategy: IMergeStrategy;\n  private readonly _capabilities: IMemoryRetrieverCapabilities;\n\n  private constructor(\n    retrievers: ReadonlyArray<IMemoryRetriever>,\n    mergeStrategy: IMergeStrategy,\n    capabilities: IMemoryRetrieverCapabilities\n  ) {\n    this._retrievers = retrievers;\n    this._mergeStrategy = mergeStrategy;\n    this._capabilities = capabilities;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return this._capabilities;\n  }\n\n  /**\n   * Family-convention factory.\n   * @param retrievers - The retrievers to compose (at least one).\n   * @param mergeStrategy - How to combine their results.\n   */\n  public static create(\n    retrievers: ReadonlyArray<IMemoryRetriever>,\n    mergeStrategy: IMergeStrategy\n  ): Result<HybridRetriever> {\n    if (retrievers.length === 0) {\n      return fail('HybridRetriever: at least one retriever is required');\n    }\n    // Snapshot the caller's array so a later mutation cannot make `retrieve()`\n    // and the cached `capabilities` disagree.\n    const stableRetrievers: ReadonlyArray<IMemoryRetriever> = [...retrievers];\n    const capabilities: IMemoryRetrieverCapabilities = {\n      supportsSemanticRecall: stableRetrievers.some((r) => r.capabilities.supportsSemanticRecall),\n      supportsTemporalQuery: stableRetrievers.some((r) => r.capabilities.supportsTemporalQuery),\n      supportsLinkTraversal: stableRetrievers.some((r) => r.capabilities.supportsLinkTraversal)\n    };\n    return succeed(new HybridRetriever(stableRetrievers, mergeStrategy, capabilities));\n  }\n\n  /** {@inheritDoc IMemoryRetriever.retrieve} */\n  public async retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {\n    return guardRetrieverCapabilities(query, this._capabilities).thenOnSuccess(async () => {\n      const perRetriever: Result<ReadonlyArray<IMemoryRecord<unknown>>>[] = await Promise.all(\n        this._retrievers.map((retriever) => retriever.retrieve(this._projectQuery(query, retriever)))\n      );\n      return mapResults(perRetriever)\n        .onSuccess((resultSets) => this._mergeStrategy.merge(resultSets))\n        .onSuccess((merged) => succeed(limitRecords(merged, query.limit)));\n    });\n  }\n\n  /**\n   * Project the query for one child retriever. Two adjustments:\n   *\n   * - Strip axes the child does not support (`semantic` / `topK` for a\n   *   non-semantic child, `asOf` for a non-temporal child, the link axes for a\n   *   non-link child) so it returns its normal results rather than loud-failing\n   *   on a field a sibling handles.\n   * - Strip `limit` unconditionally: limit is a post-merge concern. A child that\n   *   pre-truncated its result set would starve the merge strategy of candidates\n   *   it needs to score correctly (a record both children would surface must\n   *   reach the merge to score 2). The hybrid applies `limit` once, after merge.\n   */\n  private _projectQuery(query: IMemoryQuery, retriever: IMemoryRetriever): IMemoryQuery {\n    const projected: { -readonly [K in keyof IMemoryQuery]: IMemoryQuery[K] } = { ...query };\n    delete projected.limit;\n    if (!retriever.capabilities.supportsSemanticRecall) {\n      delete projected.semantic;\n      delete projected.topK;\n    }\n    if (!retriever.capabilities.supportsTemporalQuery) {\n      delete projected.asOf;\n    }\n    if (!retriever.capabilities.supportsLinkTraversal) {\n      delete projected.linkedFrom;\n      delete projected.linkedTo;\n      delete projected.hops;\n    }\n    return projected;\n  }\n}\n"]}

package/dist/packlets/retrieve/index.js

@@ -0,0 +1,12 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+export * from './retriever';
+export * from './recencyRetriever';
+export * from './linkTraversalRetriever';
+export * from './tagRetriever';
+export * from './structuredFilterRetriever';
+export * from './semanticRetriever';
+export * from './hybridRetriever';
+//# sourceMappingURL=index.js.map

package/dist/packlets/retrieve/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './retriever';\nexport * from './recencyRetriever';\nexport * from './linkTraversalRetriever';\nexport * from './tagRetriever';\nexport * from './structuredFilterRetriever';\nexport * from './semanticRetriever';\nexport * from './hybridRetriever';\n"]}