@fgv/ts-agent-memory 5.1.0-39 → 5.1.0-41

package/src/packlets/retrieve/retriever.ts

@@ -4,7 +4,7 @@
  */
 
 import { Result, fail, succeed } from '@fgv/ts-utils';
-import { IMemoryRecord, Kind, MemoryId, MemoryScopeKey, Tag } from '../types';
+import { IEdgeTarget, IMemoryRecord, Kind, MemoryScopeKey, Tag } from '../types';
 import { IIndexedMemoryRecord } from '../index';
 
 /**
@@ -34,12 +34,24 @@ export interface IMemoryQuery {
   readonly scope?: MemoryScopeKey;
   /** Restrict to records carrying this tag (exact match). */
   readonly tag?: Tag;
-  /** Restrict to records of this kind. */
+  /**
+   * Restrict to records of this kind — the single-kind shorthand for
+   * {@link IMemoryQuery.kinds | kinds}. When both are set they compose as AND
+   * (the record's kind must satisfy both), so `kind` must itself be a member of
+   * `kinds` for anything to match.
+   */
   readonly kind?: Kind;
-  /** Restrict to records linked FROM this id (outbound). */
-  readonly linkedFrom?: MemoryId;
-  /** Restrict to records linked TO this id (inbound / backlinks). */
-  readonly linkedTo?: MemoryId;
+  /**
+   * Restrict to records in ANY of these kinds — the general (multi-kind) form of
+   * {@link IMemoryQuery.kind | kind}. Absent → no kind-set constraint (today's
+   * behavior). An explicit empty array `[]` matches NOTHING (mirroring the
+   * non-positive-`limit` "explicit empty" convention), never "match all".
+   */
+  readonly kinds?: ReadonlyArray<Kind>;
+  /** Restrict to records linked FROM this scope-qualified seed (outbound). */
+  readonly linkedFrom?: IEdgeTarget;
+  /** Restrict to records linked TO this scope-qualified seed (inbound / backlinks). */
+  readonly linkedTo?: IEdgeTarget;
   /** BFS hop count for link traversal. Default: 1. */
   readonly hops?: number;
   /**
@@ -56,8 +68,32 @@ export interface IMemoryQuery {
    * `Result.fail` — never a silent empty.
    */
   readonly asOf?: number;
+  /**
+   * Ordering for the result set. `'recency'` (the default when absent — today's
+   * exact behavior) orders most-recently-updated first; `'rank'` orders by the
+   * store-computed {@link IMemoryEnvelope.rank} descending (records with an absent
+   * `rank` last), with recency as the tiebreak. Combined with `{ limit, offset }`
+   * this yields a bounded top-M rank-ordered page with no full-vault scan.
+   *
+   * @remarks
+   * `orderBy` governs the ordered non-semantic retrievers (recency / tag /
+   * structured-filter / link-traversal) and the {@link HybridRetriever}'s
+   * post-merge ordering. The {@link SemanticRetriever} is the sole exception: it
+   * preserves its native vector-similarity order regardless of `orderBy` —
+   * re-sorting semantic hits by `rank` would discard the similarity ranking that
+   * is the whole point of that path; a consumer that wants rank ordering uses a
+   * non-semantic query.
+   */
+  readonly orderBy?: 'recency' | 'rank';
   /** Maximum records to return. Applied after all other filters. */
   readonly limit?: number;
+  /**
+   * Records to skip after ordering, before `limit` — so `{ offset, limit }` is a
+   * stable page window over the ordered result set. Default 0. A non-positive or
+   * absent offset is today's behavior (no skip); an offset past the end yields an
+   * empty page, never a throw.
+   */
+  readonly offset?: number;
   /** Arbitrary predicate applied after the scope / kind / tag pre-filter. */
   readonly filter?: (record: IMemoryRecord<unknown>) => boolean;
 }
@@ -152,6 +188,40 @@ export function recencyCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<unkno
   return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;
 }
 
+/**
+ * Rank comparator: store-computed {@link IMemoryEnvelope.rank} descending, with
+ * {@link recencyCompare} as the tiebreak. Records with an absent `rank` sort LAST
+ * (after every ranked record), then by recency among themselves. Mirrors the
+ * index's rank-view ordering.
+ * @public
+ */
+export function rankCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number {
+  const ra: number | undefined = a.envelope.rank;
+  const rb: number | undefined = b.envelope.rank;
+  if (ra === undefined && rb !== undefined) {
+    return 1;
+  }
+  if (rb === undefined && ra !== undefined) {
+    return -1;
+  }
+  if (ra !== undefined && rb !== undefined && ra !== rb) {
+    return rb - ra;
+  }
+  return recencyCompare(a, b);
+}
+
+/**
+ * Select the record comparator for a query's {@link IMemoryQuery.orderBy | orderBy}
+ * axis: {@link rankCompare} for `'rank'`, {@link recencyCompare} otherwise (the
+ * default, byte-identical to the pre-`orderBy` behavior).
+ * @public
+ */
+export function orderingCompare(
+  orderBy?: IMemoryQuery['orderBy']
+): (a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>) => number {
+  return orderBy === 'rank' ? rankCompare : recencyCompare;
+}
+
 /**
  * Whether an indexed entry satisfies a query's scope / kind / tag / predicate
  * pre-filter (the axes shared by every v1 retriever). The `semantic` / `asOf` /
@@ -165,6 +235,9 @@ export function indexedRecordMatchesQuery(entry: IIndexedMemoryRecord, query: IM
   if (query.kind !== undefined && entry.record.envelope.kind !== query.kind) {
     return false;
   }
+  if (query.kinds !== undefined && !query.kinds.includes(entry.record.envelope.kind)) {
+    return false;
+  }
   if (query.tag !== undefined && !entry.record.envelope.tags.includes(query.tag)) {
     return false;
   }
@@ -187,21 +260,32 @@ export function selectByQuery(
 }
 
 /**
- * Truncate to `query.limit` records (a no-op when `limit` is absent). Applied
- * last, after ordering, so it always takes the top-N of the ordered result. A
- * non-positive `limit` is public query input and means "no records" — it returns
- * an empty array rather than letting a negative value slip into `slice`.
+ * Apply the `{ offset, limit }` page window to an ordered record set. Applied
+ * last, after ordering, so it always takes a stable window of the ordered
+ * result. `offset` is applied first (records to skip), then `limit` (top-N of
+ * the remainder).
+ *
+ * @remarks
+ * Both bounds are public query input and are guarded against non-positive
+ * values slipping into `slice`:
+ * - `offset` absent or non-positive → no skip (today's behavior). An offset past
+ *   the end yields an empty page rather than a throw.
+ * - `limit` absent → no truncation; a non-positive `limit` means "no records"
+ *   and returns an empty array.
  * @public
  */
 export function limitRecords(
   records: ReadonlyArray<IMemoryRecord<unknown>>,
-  limit?: number
+  limit?: number,
+  offset?: number
 ): ReadonlyArray<IMemoryRecord<unknown>> {
+  const skip: number = offset !== undefined && offset > 0 ? offset : 0;
+  const windowed: ReadonlyArray<IMemoryRecord<unknown>> = skip > 0 ? records.slice(skip) : records;
   if (limit === undefined) {
-    return records;
+    return windowed;
   }
   if (limit <= 0) {
     return [];
   }
-  return records.length > limit ? records.slice(0, limit) : records;
+  return windowed.length > limit ? windowed.slice(0, limit) : windowed;
 }

package/src/packlets/retrieve/semanticRetriever.ts

@@ -4,7 +4,7 @@
  */
 
 import { Result, fail, succeed } from '@fgv/ts-utils';
-import { IMemoryRecord, MemoryId } from '../types';
+import { IMemoryRecord, edgeTargetKey } from '../types';
 import { IIndexedMemoryRecord, IMemoryIndex } from '../index';
 import { IVectorIndex, IVectorQueryHit } from '../vector';
 import {
@@ -118,17 +118,22 @@ export class SemanticRetriever implements IMemoryRetriever {
     if (hits.isFailure()) {
       return fail(hits.message);
     }
-    const byId: Map<MemoryId, IIndexedMemoryRecord> = new Map(
-      this._index.entries().map((entry) => [entry.record.envelope.id, entry])
+    // Key by the canonical scope-qualified target so a hit re-resolves to the
+    // exact record it scored against — a bare id would alias two records that
+    // share a filename stem across scopes.
+    const byKey: Map<string, IIndexedMemoryRecord> = new Map(
+      this._index
+        .entries()
+        .map((entry) => [edgeTargetKey({ scope: entry.scope, id: entry.record.envelope.id }), entry])
     );
     const records: IMemoryRecord<unknown>[] = [];
     for (const hit of hits.value) {
-      const entry: IIndexedMemoryRecord | undefined = byId.get(hit.id);
+      const entry: IIndexedMemoryRecord | undefined = byKey.get(edgeTargetKey(hit.target));
       if (entry !== undefined && indexedRecordMatchesQuery(entry, query)) {
         records.push(entry.record);
       }
     }
-    return succeed(limitRecords(records, query.limit));
+    return succeed(limitRecords(records, query.limit, query.offset));
   }
 
   /**

package/src/packlets/retrieve/structuredFilterRetriever.ts

@@ -13,7 +13,7 @@ import {
   NON_SEMANTIC_CAPABILITIES,
   guardRetrieverCapabilities,
   limitRecords,
-  recencyCompare,
+  orderingCompare,
   selectByQuery
 } from './retriever';
 
@@ -49,9 +49,9 @@ export class StructuredFilterRetriever implements IMemoryRetriever {
           return succeed([]);
         }
         const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(
-          recencyCompare
+          orderingCompare(query.orderBy)
         );
-        return succeed(limitRecords(ordered, query.limit));
+        return succeed(limitRecords(ordered, query.limit, query.offset));
       })
     );
   }

package/src/packlets/retrieve/tagRetriever.ts

@@ -13,7 +13,7 @@ import {
   NON_SEMANTIC_CAPABILITIES,
   guardRetrieverCapabilities,
   limitRecords,
-  recencyCompare,
+  orderingCompare,
   selectByQuery
 } from './retriever';
 
@@ -49,9 +49,9 @@ export class TagRetriever implements IMemoryRetriever {
           return succeed([]);
         }
         const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(
-          recencyCompare
+          orderingCompare(query.orderBy)
         );
-        return succeed(limitRecords(ordered, query.limit));
+        return succeed(limitRecords(ordered, query.limit, query.offset));
       })
     );
   }

package/src/packlets/retrieve/temporalRetrievers.ts

@@ -90,7 +90,7 @@ export class CurrentValidRetriever implements IMemoryRetriever {
           }
         }
         selected.sort(recencyCompare);
-        return succeed(limitRecords(selected, query.limit));
+        return succeed(limitRecords(selected, query.limit, query.offset));
       })
     );
   }
@@ -137,7 +137,7 @@ export class AsOfRetriever implements IMemoryRetriever {
           }
         }
         selected.sort(recencyCompare);
-        return succeed(limitRecords(selected, query.limit));
+        return succeed(limitRecords(selected, query.limit, query.offset));
       })
     );
   }
@@ -182,7 +182,7 @@ export class HistoryRetriever implements IMemoryRetriever {
           history.push(...versions);
         }
         history.sort(HistoryRetriever._byValidAtAscending);
-        return succeed(limitRecords(history, query.limit));
+        return succeed(limitRecords(history, query.limit, query.offset));
       })
     );
   }

package/src/packlets/store/fileTreeMemoryStore.ts

@@ -10,6 +10,7 @@ import {
   DEFAULT_DEDUP_SCOPE,
   DedupScope,
   EntityId,
+  IEdgeTarget,
   IIdentityCodec,
   IMemoryEnvelope,
   IMemoryRecord,
@@ -20,6 +21,7 @@ import {
   KnowledgeLwwPolicy,
   MemoryId,
   MemoryScopeKey,
+  RankProjector,
   Tag,
   isTemporalIdentityCodec,
   isTemporalRecord,
@@ -35,7 +37,7 @@ import {
   MemoryObservationOutcome,
   MemoryObservationPhase
 } from '../observe';
-import { IVectorIndex, MemoryEmbedder } from '../vector';
+import { IMemoryRecordSource, IScopedMemoryRecord, IVectorIndex, MemoryEmbedder } from '../vector';
 import { defaultMemoryScopeEncoding } from './scopeEncoding';
 
 /** The on-disk extension for a memory record file. */
@@ -84,6 +86,26 @@ export interface IMemoryStore {
    */
   list(filter?: IMemoryStoreListFilter): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
 
+  /**
+   * List EVERY record in the vault, each paired with its scope-qualified
+   * `(scope, id)` address — the projection {@link IMemoryRecordSource} requires.
+   * Unlike {@link IMemoryStore.list | list}, it takes no filter (whole-vault) and
+   * returns {@link IScopedMemoryRecord}s so a re-index keys each entry on the same
+   * scoped target the incremental embed-on-write path uses. Two records that share
+   * a filename stem across scopes appear as distinct entries.
+   */
+  listScoped(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;
+
+  /**
+   * Adapt this store to the {@link IMemoryRecordSource} seam so it can drive
+   * {@link IVectorIndex} rebuilds (e.g. `InMemoryCosineIndex.rebuild`). The
+   * returned source's `list()` delegates to {@link IMemoryStore.listScoped}. The
+   * store cannot implement {@link IMemoryRecordSource} directly because its
+   * `list(filter?)` returns bare records (the ergonomic query surface) while the
+   * seam's `list()` returns scope-qualified records.
+   */
+  asRecordSource(): IMemoryRecordSource;
+
   /**
    * Write a record. Validates the body, computes a content hash, deduplicates
    * (scope-wide, before policy), applies the kind's {@link IWritePolicy}, stamps
@@ -116,6 +138,19 @@ export interface IFileTreeMemoryStoreCreateParams {
   readonly writePolicies?: ReadonlyMap<Kind, IWritePolicy>;
   /** Per-kind identity codecs. */
   readonly codecs?: ReadonlyMap<Kind, IIdentityCodec>;
+  /**
+   * Optional per-kind host projector map. When a kind has an entry, the store
+   * runs the projector on the fully-resolved (post-merge) record on every put
+   * AND every update — in the same pass that recomputes `contentHash` — and
+   * stamps the numeric result into {@link IMemoryEnvelope.rank}, which the index's
+   * rank view and `orderBy: 'rank'` retrieval sort by (descending, absent last).
+   * Absent for a kind → that kind's records carry no `rank`. Purely additive and
+   * zero-overhead when unwired: an absent map leaves every write byte-identical.
+   * The projector is a host callback — a throw is logged at `warn` and the record
+   * is stamped with no `rank`, never failing the write (mirrors the store's other
+   * guard-host-callbacks conventions).
+   */
+  readonly rankProjectors?: ReadonlyMap<Kind, RankProjector>;
   /** Default codec for kinds without an explicit entry. */
   readonly defaultCodec?: IIdentityCodec;
   /** Scope encoding. Defaults to {@link defaultMemoryScopeEncoding}. */
@@ -182,6 +217,7 @@ interface IInternalParams {
   readonly registry: IRegistry;
   readonly writePolicies: ReadonlyMap<Kind, IWritePolicy>;
   readonly codecs: ReadonlyMap<Kind, IIdentityCodec>;
+  readonly rankProjectors: ReadonlyMap<Kind, RankProjector>;
   readonly defaultCodec?: IIdentityCodec;
   readonly defaultPolicy: IWritePolicy;
   readonly scopeEncoding: (scope: MemoryScopeKey) => Result<string>;
@@ -212,6 +248,7 @@ export class FileTreeMemoryStore implements IMemoryStore {
   private readonly _registry: IRegistry;
   private readonly _writePolicies: ReadonlyMap<Kind, IWritePolicy>;
   private readonly _codecs: ReadonlyMap<Kind, IIdentityCodec>;
+  private readonly _rankProjectors: ReadonlyMap<Kind, RankProjector>;
   private readonly _defaultCodec: IIdentityCodec | undefined;
   private readonly _defaultPolicy: IWritePolicy;
   private readonly _scopeEncoding: (scope: MemoryScopeKey) => Result<string>;
@@ -258,6 +295,7 @@ export class FileTreeMemoryStore implements IMemoryStore {
     this._registry = params.registry;
     this._writePolicies = params.writePolicies;
     this._codecs = params.codecs;
+    this._rankProjectors = params.rankProjectors;
     this._defaultCodec = params.defaultCodec;
     this._defaultPolicy = params.defaultPolicy;
     this._scopeEncoding = params.scopeEncoding;
@@ -286,6 +324,7 @@ export class FileTreeMemoryStore implements IMemoryStore {
           registry: params.registry,
           writePolicies: params.writePolicies ?? new Map<Kind, IWritePolicy>(),
           codecs: params.codecs ?? new Map<Kind, IIdentityCodec>(),
+          rankProjectors: params.rankProjectors ?? new Map<Kind, RankProjector>(),
           defaultCodec: params.defaultCodec,
           defaultPolicy,
           scopeEncoding: params.scopeEncoding ?? defaultMemoryScopeEncoding,
@@ -361,6 +400,25 @@ export class FileTreeMemoryStore implements IMemoryStore {
     return succeed(FileTreeMemoryStore._projectAsOf(matches, filter.asOf));
   }
 
+  /** {@inheritDoc IMemoryStore.listScoped} */
+  public async listScoped(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>> {
+    // The derived index already carries each record's scope
+    // ({@link IIndexedMemoryRecord.scope}), so the scoped projection is a direct
+    // map — the record's `(scope, id)` is exactly the address the vector index
+    // keys on. No filter/temporal projection: the seam re-embeds the whole vault.
+    return succeed(
+      this._index.entries().map((entry) => ({
+        target: { scope: entry.scope, id: entry.record.envelope.id },
+        record: entry.record
+      }))
+    );
+  }
+
+  /** {@inheritDoc IMemoryStore.asRecordSource} */
+  public asRecordSource(): IMemoryRecordSource {
+    return { list: (): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>> => this.listScoped() };
+  }
+
   /**
    * Collapse temporal records to the single version valid at `asOf` per entity;
    * non-temporal records are timeless and pass through unchanged (valid-time
@@ -669,7 +727,8 @@ export class FileTreeMemoryStore implements IMemoryStore {
       return fail(`memory put: rejected by policy: ${decision.reason}`);
     }
     return this._buildRecord(record, body, existing, policy, hash)
-      .thenOnSuccess((built) => this._embedOnWrite(built))
+      .onSuccess((built) => succeed(this._stampRank(built)))
+      .thenOnSuccess((built) => this._embedOnWrite(built, scope))
       .onSuccess((embeddedBuilt) => this._persist(embeddedBuilt, scope, idStem))
       .thenOnSuccess(async (persisted) => {
         // Everything after the authoritative `_persist` commit is best-effort and
@@ -679,7 +738,7 @@ export class FileTreeMemoryStore implements IMemoryStore {
         //     it), and only the successfully-evicted ids flow onward;
         //   - vector pruning of the evicted cohort is likewise best-effort.
         const evicted: ReadonlyArray<MemoryId> = this._applyEvictions(decision, scope);
-        await this._removeEvictedVectors(evicted);
+        await this._removeEvictedVectors(evicted, scope);
         return succeed({ record: persisted, evicted });
       });
   }
@@ -696,12 +755,16 @@ export class FileTreeMemoryStore implements IMemoryStore {
    * Always succeeds (`Result` is the chain's shape, never a vector-induced
    * failure).
    */
-  private async _embedOnWrite(built: IMemoryRecord<string>): Promise<Result<IMemoryRecord<string>>> {
+  private async _embedOnWrite(
+    built: IMemoryRecord<string>,
+    scope: MemoryScopeKey
+  ): Promise<Result<IMemoryRecord<string>>> {
     if (this._vectorIndex === undefined || this._embed === undefined) {
       return succeed(built);
     }
     const vectorIndex: IVectorIndex = this._vectorIndex;
     const embed: MemoryEmbedder = this._embed;
+    const target: IEdgeTarget = { scope, id: built.envelope.id };
     const embedded: Result<Float32Array> = await this._tryVectorOp(
       () => embed(built),
       `embedding '${built.envelope.id}'`
@@ -710,7 +773,7 @@ export class FileTreeMemoryStore implements IMemoryStore {
       return succeed(built);
     }
     const added: Result<string> = await this._tryVectorOp(
-      () => vectorIndex.add(built.envelope.id, embedded.value),
+      () => vectorIndex.add(target, embedded.value),
       `vector add for '${built.envelope.id}'`
     );
     if (added.isFailure()) {
@@ -744,10 +807,18 @@ export class FileTreeMemoryStore implements IMemoryStore {
     return evicted;
   }
 
-  /** Best-effort vector removal for each evicted record (never fails the put). */
-  private async _removeEvictedVectors(evicted: ReadonlyArray<MemoryId>): Promise<void> {
+  /**
+   * Best-effort vector removal for each evicted record (never fails the put).
+   * Every evicted record is in the same `scope` as the incoming write (the
+   * cull-oldest cohort is the incoming record's `(scope, kind)` cohort), so that
+   * scope qualifies each removal target.
+   */
+  private async _removeEvictedVectors(
+    evicted: ReadonlyArray<MemoryId>,
+    scope: MemoryScopeKey
+  ): Promise<void> {
     for (const id of evicted) {
-      await this._removeVectorBestEffort(id);
+      await this._removeVectorBestEffort({ scope, id });
     }
   }
 
@@ -777,12 +848,12 @@ export class FileTreeMemoryStore implements IMemoryStore {
    * behaves byte-identically. Failures are logged, never surfaced — a committed
    * delete/eviction must not fail because a derived index could not be pruned.
    */
-  private async _removeVectorBestEffort(id: MemoryId): Promise<void> {
+  private async _removeVectorBestEffort(target: IEdgeTarget): Promise<void> {
     if (this._vectorIndex === undefined || this._embed === undefined) {
       return;
     }
     const vectorIndex: IVectorIndex = this._vectorIndex;
-    await this._tryVectorOp(() => vectorIndex.remove(id), `vector removal for '${id}'`);
+    await this._tryVectorOp(() => vectorIndex.remove(target), `vector removal for '${target.id}'`);
   }
 
   /**
@@ -888,7 +959,7 @@ export class FileTreeMemoryStore implements IMemoryStore {
       return this._deleteFile(scope, idStem)
         .onSuccess(() => this._index.patch('delete', { scope, record: existing }))
         .thenOnSuccess(async () => {
-          await this._removeVectorBestEffort(existing.envelope.id);
+          await this._removeVectorBestEffort({ scope, id: existing.envelope.id });
           return succeed(existing.envelope.id);
         });
     });
@@ -982,7 +1053,8 @@ export class FileTreeMemoryStore implements IMemoryStore {
           .withErrorFormat((msg) => `memory put '${entityId}': ${msg}`)
           .thenOnSuccess((versionStem) =>
             this._buildVersionedRecord(record, body, current, policy, hash, versionStem, validAt, now, seq)
-              .thenOnSuccess((built) => this._embedOnWrite(built))
+              .onSuccess((built) => succeed(this._stampRank(built)))
+              .thenOnSuccess((built) => this._embedOnWrite(built, scope))
               .onSuccess((embeddedBuilt) => this._persist(embeddedBuilt, scope, versionStem))
               .onSuccess((persisted) =>
                 this._invalidateCurrents(scope, priorCurrents, validAt, now).onSuccess(() =>
@@ -1241,6 +1313,39 @@ export class FileTreeMemoryStore implements IMemoryStore {
     return this._hasher.computeHash({ kind, body, links });
   }
 
+  /**
+   * Stamp the store-computed {@link IMemoryEnvelope.rank} onto a fully-built,
+   * fully-stamped record by running the kind's registered {@link RankProjector}.
+   * Runs on the SAME resolved (post-merge) record whose `contentHash` was just
+   * computed, so `rank` is always consistent with the current body — no separate
+   * write path and no consumer write-discipline rule. A no-op pass-through
+   * (byte-identical record) when the kind has no projector — the additive,
+   * zero-overhead-when-unwired default. The projector is a host callback: a throw
+   * is logged at `warn` and the record is stamped with NO `rank` (the field is
+   * explicitly cleared, so a throw on an update drops a now-stale prior rank rather
+   * than preserving it), so a ranking bug never loses an authoritative write.
+   */
+  private _stampRank(record: IMemoryRecord<string>): IMemoryRecord<string> {
+    const projector: RankProjector | undefined = this._rankProjectors.get(record.envelope.kind);
+    if (projector === undefined) {
+      return record;
+    }
+    try {
+      const rank: number = projector(record);
+      return { envelope: { ...record.envelope, rank }, body: record.body };
+    } catch (err) {
+      this._warnSwallowed(
+        `memory put '${record.envelope.id}': rank projector threw (swallowed; rank cleared): ${String(err)}`
+      );
+      // Explicitly CLEAR `rank` (not `return record`): on an update the merged
+      // envelope carries the prior version's `rank` (the write-policy merge does
+      // not touch `rank`), so returning it verbatim would keep a stale value
+      // inconsistent with the revised body. Clearing honors the staleness
+      // contract — an uncomputable rank means the record sorts last as "unranked".
+      return { envelope: { ...record.envelope, rank: undefined }, body: record.body };
+    }
+  }
+
   private _codecFor(kind: Kind): Result<IIdentityCodec> {
     const codec: IIdentityCodec | undefined = this._codecs.get(kind) ?? this._defaultCodec;
     if (codec === undefined) {