@fgv/ts-agent-memory 5.1.0-46 → 5.1.0-48

package/src/packlets/retrieve/structuredFilterRetriever.ts

@@ -1,58 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import { Result, succeed } from '@fgv/ts-utils';
-import { IMemoryRecord } from '../types';
-import { IMemoryIndex } from '../index';
-import {
-  IMemoryQuery,
-  IMemoryRetriever,
-  IMemoryRetrieverCapabilities,
-  NON_SEMANTIC_CAPABILITIES,
-  guardRetrieverCapabilities,
-  limitRecords,
-  orderingCompare,
-  selectByQuery
-} from './retriever';
-
-/**
- * Returns records matching `query.filter`, narrowed by any scope / kind / tag
- * pre-filter and recency-ordered. The predicate is this retriever's axis: a
- * query without a `filter` is not its concern and yields an empty success (so it
- * contributes nothing to a {@link HybridRetriever}, rather than failing).
- * @public
- */
-export class StructuredFilterRetriever implements IMemoryRetriever {
-  private readonly _index: IMemoryIndex;
-
-  private constructor(index: IMemoryIndex) {
-    this._index = index;
-  }
-
-  /** {@inheritDoc IMemoryRetriever.capabilities} */
-  public get capabilities(): IMemoryRetrieverCapabilities {
-    return NON_SEMANTIC_CAPABILITIES;
-  }
-
-  /** Family-convention factory. */
-  public static create(index: IMemoryIndex): Result<StructuredFilterRetriever> {
-    return succeed(new StructuredFilterRetriever(index));
-  }
-
-  /** {@inheritDoc IMemoryRetriever.retrieve} */
-  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {
-    return Promise.resolve(
-      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {
-        if (query.filter === undefined) {
-          return succeed([]);
-        }
-        const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(
-          orderingCompare(query.orderBy)
-        );
-        return succeed(limitRecords(ordered, query.limit, query.offset));
-      })
-    );
-  }
-}

package/src/packlets/retrieve/tagRetriever.ts

@@ -1,58 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import { Result, succeed } from '@fgv/ts-utils';
-import { IMemoryRecord } from '../types';
-import { IMemoryIndex } from '../index';
-import {
-  IMemoryQuery,
-  IMemoryRetriever,
-  IMemoryRetrieverCapabilities,
-  NON_SEMANTIC_CAPABILITIES,
-  guardRetrieverCapabilities,
-  limitRecords,
-  orderingCompare,
-  selectByQuery
-} from './retriever';
-
-/**
- * Returns records carrying `query.tag`, recency-ordered within the tag and
- * narrowed by any scope / kind / predicate filters. Tag is this retriever's
- * axis: a query without a `tag` is not its concern and yields an empty success
- * (so it contributes nothing to a {@link HybridRetriever}, rather than failing).
- * @public
- */
-export class TagRetriever implements IMemoryRetriever {
-  private readonly _index: IMemoryIndex;
-
-  private constructor(index: IMemoryIndex) {
-    this._index = index;
-  }
-
-  /** {@inheritDoc IMemoryRetriever.capabilities} */
-  public get capabilities(): IMemoryRetrieverCapabilities {
-    return NON_SEMANTIC_CAPABILITIES;
-  }
-
-  /** Family-convention factory. */
-  public static create(index: IMemoryIndex): Result<TagRetriever> {
-    return succeed(new TagRetriever(index));
-  }
-
-  /** {@inheritDoc IMemoryRetriever.retrieve} */
-  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {
-    return Promise.resolve(
-      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {
-        if (query.tag === undefined) {
-          return succeed([]);
-        }
-        const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(
-          orderingCompare(query.orderBy)
-        );
-        return succeed(limitRecords(ordered, query.limit, query.offset));
-      })
-    );
-  }
-}

package/src/packlets/retrieve/temporalRetrievers.ts

@@ -1,210 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import { Result, succeed } from '@fgv/ts-utils';
-import { IMemoryRecord, isTemporalRecord, selectCurrentVersion, selectVersionAsOf } from '../types';
-import { IMemoryIndex } from '../index';
-import {
-  IMemoryQuery,
-  IMemoryRetriever,
-  IMemoryRetrieverCapabilities,
-  guardRetrieverCapabilities,
-  indexedRecordMatchesQuery,
-  limitRecords,
-  recencyCompare
-} from './retriever';
-
-/**
- * The capabilities every temporal retriever exposes: temporal "as-of" queries
- * are operational (semantic recall and link traversal are not this retriever's
- * concern).
- * @public
- */
-export const TEMPORAL_CAPABILITIES: IMemoryRetrieverCapabilities = {
-  supportsSemanticRecall: false,
-  supportsTemporalQuery: true,
-  supportsLinkTraversal: false
-};
-
-/**
- * Group the temporal records surviving a query's scope / kind / tag / predicate
- * pre-filter by entity (`kind` + `entityId`). Non-temporal records are excluded —
- * the temporal retrievers operate only over versioned entities. The map values
- * are each entity's versions (unordered).
- */
-function groupTemporalVersionsByEntity(
-  index: IMemoryIndex,
-  query: IMemoryQuery
-): Map<string, IMemoryRecord<unknown>[]> {
-  const groups: Map<string, IMemoryRecord<unknown>[]> = new Map<string, IMemoryRecord<unknown>[]>();
-  for (const entry of index.entries()) {
-    if (!isTemporalRecord(entry.record) || !indexedRecordMatchesQuery(entry, query)) {
-      continue;
-    }
-    const key: string = `${entry.record.envelope.kind}\0${entry.record.envelope.entityId}`;
-    const existing: IMemoryRecord<unknown>[] | undefined = groups.get(key);
-    if (existing === undefined) {
-      groups.set(key, [entry.record]);
-    } else {
-      existing.push(entry.record);
-    }
-  }
-  return groups;
-}
-
-/**
- * Temporal retriever returning the **current** version of each temporal entity
- * matching the query (the newest version whose `invalid_at` is null/absent),
- * recency-ordered and limited. A fully-invalidated (soft-deleted) entity
- * contributes nothing. Non-temporal records are not this retriever's concern.
- * @public
- */
-export class CurrentValidRetriever implements IMemoryRetriever {
-  private readonly _index: IMemoryIndex;
-
-  private constructor(index: IMemoryIndex) {
-    this._index = index;
-  }
-
-  /** {@inheritDoc IMemoryRetriever.capabilities} */
-  public get capabilities(): IMemoryRetrieverCapabilities {
-    return TEMPORAL_CAPABILITIES;
-  }
-
-  /** Family-convention factory. */
-  public static create(index: IMemoryIndex): Result<CurrentValidRetriever> {
-    return succeed(new CurrentValidRetriever(index));
-  }
-
-  /** {@inheritDoc IMemoryRetriever.retrieve} */
-  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {
-    return Promise.resolve(
-      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {
-        const selected: IMemoryRecord<unknown>[] = [];
-        for (const versions of groupTemporalVersionsByEntity(this._index, query).values()) {
-          const current: IMemoryRecord<unknown> | undefined = selectCurrentVersion(versions);
-          if (current !== undefined) {
-            selected.push(current);
-          }
-        }
-        selected.sort(recencyCompare);
-        return succeed(limitRecords(selected, query.limit, query.offset));
-      })
-    );
-  }
-}
-
-/**
- * Temporal retriever returning, for each temporal entity matching the query, the
- * version valid at `query.asOf` (epoch ms). `asOf` is this retriever's axis: a
- * query without it yields an empty success (a no-op contribution to a
- * {@link HybridRetriever}, not a failure). Results are recency-ordered and
- * limited.
- * @public
- */
-export class AsOfRetriever implements IMemoryRetriever {
-  private readonly _index: IMemoryIndex;
-
-  private constructor(index: IMemoryIndex) {
-    this._index = index;
-  }
-
-  /** {@inheritDoc IMemoryRetriever.capabilities} */
-  public get capabilities(): IMemoryRetrieverCapabilities {
-    return TEMPORAL_CAPABILITIES;
-  }
-
-  /** Family-convention factory. */
-  public static create(index: IMemoryIndex): Result<AsOfRetriever> {
-    return succeed(new AsOfRetriever(index));
-  }
-
-  /** {@inheritDoc IMemoryRetriever.retrieve} */
-  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {
-    return Promise.resolve(
-      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {
-        if (query.asOf === undefined) {
-          return succeed([]);
-        }
-        const asOf: number = query.asOf;
-        const selected: IMemoryRecord<unknown>[] = [];
-        for (const versions of groupTemporalVersionsByEntity(this._index, query).values()) {
-          const valid: IMemoryRecord<unknown> | undefined = selectVersionAsOf(versions, asOf);
-          if (valid !== undefined) {
-            selected.push(valid);
-          }
-        }
-        selected.sort(recencyCompare);
-        return succeed(limitRecords(selected, query.limit, query.offset));
-      })
-    );
-  }
-}
-
-/**
- * Temporal retriever returning **every** version of each temporal entity matching
- * the query, ordered ascending by `valid_at` (then `seq` as a stable tiebreak) —
- * the entity's full history. Limited after ordering.
- *
- * @remarks
- * When the query matches more than one entity, the result is a single
- * CROSS-entity list globally sorted by `valid_at` — versions of different
- * entities interleave, NOT grouped per entity — so `limit` truncates that
- * globally-sorted list. Constrain to one entity (e.g. via `query.scope`) for a
- * single entity's contiguous history.
- * @public
- */
-export class HistoryRetriever implements IMemoryRetriever {
-  private readonly _index: IMemoryIndex;
-
-  private constructor(index: IMemoryIndex) {
-    this._index = index;
-  }
-
-  /** {@inheritDoc IMemoryRetriever.capabilities} */
-  public get capabilities(): IMemoryRetrieverCapabilities {
-    return TEMPORAL_CAPABILITIES;
-  }
-
-  /** Family-convention factory. */
-  public static create(index: IMemoryIndex): Result<HistoryRetriever> {
-    return succeed(new HistoryRetriever(index));
-  }
-
-  /** {@inheritDoc IMemoryRetriever.retrieve} */
-  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {
-    return Promise.resolve(
-      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {
-        const history: IMemoryRecord<unknown>[] = [];
-        for (const versions of groupTemporalVersionsByEntity(this._index, query).values()) {
-          history.push(...versions);
-        }
-        history.sort(HistoryRetriever._byValidAtAscending);
-        return succeed(limitRecords(history, query.limit, query.offset));
-      })
-    );
-  }
-
-  /** A version's world-truth start: its `valid_at`, defaulting to `created` when absent. */
-  private static _startOf(record: IMemoryRecord<unknown>): number {
-    const temporal: IMemoryRecord<unknown>['envelope']['temporal'] = record.envelope.temporal;
-    /* c8 ignore next 3 -- unreachable: HistoryRetriever orders only temporal records (pre-filtered by isTemporalRecord), so `temporal` is always present; the guard keeps the type honest */
-    if (temporal === undefined) {
-      return record.envelope.created;
-    }
-    return temporal.valid_at ?? record.envelope.created;
-  }
-
-  /**
-   * Ascending-by-`valid_at` comparator (a version's `valid_at` defaults to its
-   * `created` when absent), with `seq` as a stable ascending tiebreak so
-   * same-instant versions order by write sequence.
-   */
-  private static _byValidAtAscending(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number {
-    const aStart: number = HistoryRetriever._startOf(a);
-    const bStart: number = HistoryRetriever._startOf(b);
-    return aStart !== bStart ? aStart - bStart : a.envelope.seq - b.envelope.seq;
-  }
-}