@remnic/core 9.49.0 → 9.50.0

package/src/cue-anchors.ts

@@ -1,6 +1,8 @@
+import { mkdir, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { mkdir, writeFile } from "node:fs/promises";
-import { listJsonFiles, readJsonFile } from "./json-store.js";
+import { resolveAbstractionNodeStoreDir, validateAbstractionNode, type AbstractionNode } from "./abstraction-nodes.js";
+import { listJsonFilesStrict, readJsonFile, withJsonStoreMutationLock, writeJsonFileAtomic } from "./json-store.js";
+import { compareDeterministicStrings, mergeSortedUniqueStrings } from "./deterministic-order.js";
 import {
   assertIsoRecordedAt,
   assertSafePathSegment,
@@ -21,6 +23,7 @@ export interface CueAnchor {
   recordedAt: string;
   sessionKey: string;
   nodeRefs: string[];
+  sourceMemoryIdsByNodeRef?: Record<string, string[]>;
   tags?: string[];
   metadata?: Record<string, string>;
 }
@@ -62,10 +65,58 @@ function validateNodeRefs(raw: unknown): string[] {
   return nodeRefs.map((nodeRef, index) => assertSafePathSegment(nodeRef, `nodeRefs[${index}]`));
 }
 
-export function resolveCueAnchorStoreDir(
-  abstractionNodeStoreDir: string,
-  overrideDir?: string,
-): string {
+function validateSourceMemoryIdsByNodeRef(raw: unknown): Record<string, string[]> | undefined {
+  if (raw === undefined) return undefined;
+  if (!isRecord(raw)) throw new Error("sourceMemoryIdsByNodeRef must be an object of string arrays");
+  const entries: Array<[string, string[]]> = [];
+  for (const [rawNodeRef, rawSourceMemoryIds] of Object.entries(raw)) {
+    const nodeRef = assertSafePathSegment(
+      assertString(rawNodeRef, "sourceMemoryIdsByNodeRef key"),
+      "sourceMemoryIdsByNodeRef.nodeRef"
+    );
+    const sourceMemoryIds = optionalStringArray(rawSourceMemoryIds, `sourceMemoryIdsByNodeRef.${nodeRef}`);
+    if (sourceMemoryIds) entries.push([nodeRef, mergeSortedUniqueStrings(sourceMemoryIds)]);
+  }
+  if (entries.length === 0) return undefined;
+  return Object.fromEntries(entries.sort(([left], [right]) => compareDeterministicStrings(left, right)));
+}
+
+function mergeSourceMemoryIdsByNodeRef(
+  existing: Record<string, string[]> | undefined,
+  incoming: Record<string, string[]> | undefined
+): Record<string, string[]> | undefined {
+  const merged = new Map<string, string[]>();
+  for (const [nodeRef, sourceMemoryIds] of Object.entries(existing ?? {})) {
+    merged.set(nodeRef, [...sourceMemoryIds]);
+  }
+  for (const [nodeRef, sourceMemoryIds] of Object.entries(incoming ?? {})) {
+    merged.set(nodeRef, mergeSortedUniqueStrings(merged.get(nodeRef), sourceMemoryIds));
+  }
+  return validateSourceMemoryIdsByNodeRef(Object.fromEntries(merged));
+}
+
+function boundSourceMemoryIdsByNodeRef(
+  sourceMemoryIdsByNodeRef: Record<string, string[]> | undefined,
+  nodeRefs: string[],
+  liveNodes?: Map<string, AbstractionNode>
+): Record<string, string[]> | undefined {
+  if (!sourceMemoryIdsByNodeRef) return undefined;
+  const retained = Object.fromEntries(
+    nodeRefs.flatMap((nodeRef) => {
+      const sourceMemoryIds = sourceMemoryIdsByNodeRef[nodeRef];
+      if (!sourceMemoryIds) return [];
+      const liveSourceMemoryIds = liveNodes?.get(nodeRef)?.sourceMemoryIds;
+      if (liveNodes && !liveSourceMemoryIds) return [];
+      const retainedSourceMemoryIds = mergeSortedUniqueStrings(sourceMemoryIds).filter((sourceMemoryId) =>
+        liveSourceMemoryIds ? liveSourceMemoryIds.includes(sourceMemoryId) : true
+      );
+      return retainedSourceMemoryIds.length > 0 ? [[nodeRef, retainedSourceMemoryIds] as const] : [];
+    })
+  );
+  return validateSourceMemoryIdsByNodeRef(retained);
+}
+
+export function resolveCueAnchorStoreDir(abstractionNodeStoreDir: string, overrideDir?: string): string {
   if (typeof overrideDir === "string" && overrideDir.trim().length > 0) {
     return overrideDir.trim();
   }
@@ -85,6 +136,7 @@ export function validateCueAnchor(raw: unknown): CueAnchor {
     recordedAt: assertIsoRecordedAt(assertString(raw.recordedAt, "recordedAt")),
     sessionKey: assertString(raw.sessionKey, "sessionKey"),
     nodeRefs: validateNodeRefs(raw.nodeRefs),
+    sourceMemoryIdsByNodeRef: validateSourceMemoryIdsByNodeRef(raw.sourceMemoryIdsByNodeRef),
     tags: optionalStringArray(raw.tags, "tags"),
     metadata: validateStringRecord(raw.metadata, "metadata"),
   };
@@ -101,13 +153,212 @@ export async function recordCueAnchor(options: {
     : path.join(options.memoryDir, "state", "abstraction-nodes");
   const rootDir = resolveCueAnchorStoreDir(abstractionNodeStoreDir, options.cueAnchorStoreDir);
   const validated = validateCueAnchor(options.anchor);
-  const anchorDir = path.join(rootDir, validated.anchorType);
-  const filePath = path.join(anchorDir, `${validated.anchorId}.json`);
+  const boundedNodeRefs = boundNodeRefs(validated.nodeRefs);
+  const bounded = validateCueAnchor({
+    ...validated,
+    nodeRefs: boundedNodeRefs,
+    sourceMemoryIdsByNodeRef: boundSourceMemoryIdsByNodeRef(validated.sourceMemoryIdsByNodeRef, boundedNodeRefs),
+  });
+  const anchorDir = path.join(rootDir, bounded.anchorType);
+  const filePath = path.join(anchorDir, `${bounded.anchorId}.json`);
   await mkdir(anchorDir, { recursive: true });
-  await writeFile(filePath, JSON.stringify(validated, null, 2), "utf8");
+  await writeFile(filePath, JSON.stringify(bounded, null, 2), "utf8");
+  return filePath;
+}
+
+function mergeSortedValues(existing: string[] | undefined, incoming: string[] | undefined): string[] {
+  return mergeSortedUniqueStrings(existing, incoming);
+}
+
+function isNotFoundError(error: unknown): boolean {
+  return (
+    typeof error === "object" && error !== null && "code" in error && (error as { code?: unknown }).code === "ENOENT"
+  );
+}
+
+function boundNodeRefs(nodeRefs: string[], liveNodes?: Map<string, AbstractionNode>): string[] {
+  const uniqueRefs = mergeSortedUniqueStrings(nodeRefs);
+  if (!liveNodes) return uniqueRefs.slice(0, 50);
+  return uniqueRefs
+    .filter((nodeRef) => liveNodes.has(nodeRef))
+    .sort(
+      (left, right) =>
+        Date.parse(liveNodes.get(right)?.recordedAt ?? "") - Date.parse(liveNodes.get(left)?.recordedAt ?? "") ||
+        compareDeterministicStrings(left, right)
+    )
+    .slice(0, 50);
+}
+
+async function readLiveNodes(nodesDir: string): Promise<Map<string, AbstractionNode> | undefined> {
+  const liveNodes = new Map<string, AbstractionNode>();
+  let nodeFiles: string[];
+  try {
+    nodeFiles = await listJsonFilesStrict(nodesDir);
+  } catch (error) {
+    if (isNotFoundError(error)) return undefined;
+    throw error;
+  }
+  for (const filePath of nodeFiles) {
+    const node = validateAbstractionNode(await readJsonFile(filePath));
+    const previous = liveNodes.get(node.nodeId);
+    if (
+      !previous ||
+      Date.parse(previous.recordedAt) < Date.parse(node.recordedAt) ||
+      (Date.parse(previous.recordedAt) === Date.parse(node.recordedAt) &&
+        compareDeterministicStrings(previous.sessionKey, node.sessionKey) < 0)
+    ) {
+      liveNodes.set(node.nodeId, node);
+    }
+  }
+  return liveNodes;
+}
+
+export async function upsertCueAnchors(options: {
+  memoryDir: string;
+  abstractionNodeStoreDir?: string;
+  cueAnchorStoreDir?: string;
+  anchors: CueAnchor[];
+}): Promise<string[]> {
+  const abstractionNodeStoreDir = resolveAbstractionNodeStoreDir(options.memoryDir, options.abstractionNodeStoreDir);
+  const incomingAnchors = options.anchors.map(validateCueAnchor);
+  if (incomingAnchors.length === 0) return [];
+
+  return withJsonStoreMutationLock(abstractionNodeStoreDir, async () => {
+    const rootDir = resolveCueAnchorStoreDir(abstractionNodeStoreDir, options.cueAnchorStoreDir);
+    const liveNodes = await readLiveNodes(path.join(abstractionNodeStoreDir, "nodes"));
+    const incomingByKey = new Map<string, CueAnchor[]>();
+    for (const anchor of incomingAnchors) {
+      const key = `${anchor.anchorType}\u0000${anchor.anchorId}`;
+      const grouped = incomingByKey.get(key) ?? [];
+      grouped.push(anchor);
+      incomingByKey.set(key, grouped);
+    }
+    const filePaths: string[] = [];
+    for (const key of [...incomingByKey.keys()].sort(compareDeterministicStrings)) {
+      const grouped = incomingByKey.get(key) ?? [];
+      grouped.sort(compareIncomingCueAnchors);
+      const incoming = grouped.shift();
+      if (!incoming) throw new Error(`cue anchor batch has no anchor: ${key}`);
+      const filePath = path.join(rootDir, incoming.anchorType, `${incoming.anchorId}.json`);
+      let existing: CueAnchor | undefined;
+      try {
+        existing = validateCueAnchor(await readJsonFile(filePath));
+      } catch (error) {
+        if (!isNotFoundError(error)) throw error;
+      }
+      let merged = mergeCueAnchors(existing, incoming, liveNodes);
+      for (const next of grouped) merged = mergeCueAnchors(merged, next, liveNodes);
+      await writeJsonFileAtomic(filePath, merged);
+      filePaths.push(filePath);
+    }
+    return filePaths;
+  });
+}
+
+function compareIncomingCueAnchors(left: CueAnchor, right: CueAnchor): number {
+  const recordedAtComparison = Date.parse(left.recordedAt) - Date.parse(right.recordedAt);
+  if (recordedAtComparison < 0) return -1;
+  if (recordedAtComparison > 0) return 1;
+  return compareDeterministicStrings(canonicalCueAnchorKey(left), canonicalCueAnchorKey(right));
+}
+
+function canonicalMetadata(metadata: Record<string, string> | undefined): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(metadata ?? {}).sort(([left], [right]) => compareDeterministicStrings(left, right))
+  );
+}
+
+function canonicalCueAnchorKey(anchor: CueAnchor): string {
+  return JSON.stringify({
+    ...anchor,
+    metadata: canonicalMetadata(anchor.metadata),
+  });
+}
+
+function mergeCueAnchors(
+  existing: CueAnchor | undefined,
+  incoming: CueAnchor,
+  liveNodes: Map<string, AbstractionNode> | undefined
+): CueAnchor {
+  const incomingIsNewest = !existing || Date.parse(existing.recordedAt) <= Date.parse(incoming.recordedAt);
+  const newest = incomingIsNewest ? incoming : existing;
+  const older = incomingIsNewest ? existing : incoming;
+  const mergedMetadata = canonicalMetadata({
+    ...(older?.metadata ?? {}),
+    ...(newest.metadata ?? {}),
+  });
+  const nodeRefs = boundNodeRefs(mergeSortedValues(existing?.nodeRefs, incoming.nodeRefs), liveNodes);
+  return validateCueAnchor({
+    ...newest,
+    nodeRefs,
+    sourceMemoryIdsByNodeRef: boundSourceMemoryIdsByNodeRef(
+      mergeSourceMemoryIdsByNodeRef(existing?.sourceMemoryIdsByNodeRef, incoming.sourceMemoryIdsByNodeRef),
+      nodeRefs,
+      liveNodes
+    ),
+    tags: mergeSortedValues(existing?.tags, incoming.tags),
+    metadata: mergedMetadata,
+  });
+}
+
+export async function upsertCueAnchor(options: {
+  memoryDir: string;
+  abstractionNodeStoreDir?: string;
+  cueAnchorStoreDir?: string;
+  anchor: CueAnchor;
+}): Promise<string> {
+  const [filePath] = await upsertCueAnchors({ ...options, anchors: [options.anchor] });
+  if (!filePath) throw new Error("cue anchor upsert did not write a file");
   return filePath;
 }
 
+export async function pruneOrphanCueAnchors(options: {
+  memoryDir: string;
+  abstractionNodeStoreDir?: string;
+  cueAnchorStoreDir?: string;
+}): Promise<number> {
+  const abstractionNodeStoreDir = resolveAbstractionNodeStoreDir(options.memoryDir, options.abstractionNodeStoreDir);
+  return withJsonStoreMutationLock(abstractionNodeStoreDir, async () => {
+    const cueAnchorStoreDir = resolveCueAnchorStoreDir(abstractionNodeStoreDir, options.cueAnchorStoreDir);
+    const liveNodes = (await readLiveNodes(path.join(abstractionNodeStoreDir, "nodes"))) ?? new Map();
+    let removed = 0;
+    const anchorFiles = await listJsonFilesStrict(cueAnchorStoreDir, {
+      allowMissingDirectory: true,
+    });
+    for (const filePath of anchorFiles) {
+      let anchor: CueAnchor;
+      try {
+        anchor = validateCueAnchor(await readJsonFile(filePath));
+      } catch {
+        continue;
+      }
+      const nodeRefs = boundNodeRefs(anchor.nodeRefs, liveNodes);
+      const sourceMemoryIdsByNodeRef = boundSourceMemoryIdsByNodeRef(
+        anchor.sourceMemoryIdsByNodeRef,
+        nodeRefs,
+        liveNodes
+      );
+      if (nodeRefs.length === 0) {
+        try {
+          await unlink(filePath);
+          removed++;
+        } catch (error) {
+          if (!isNotFoundError(error)) throw error;
+        }
+        continue;
+      }
+      if (
+        nodeRefs.length !== anchor.nodeRefs.length ||
+        nodeRefs.some((nodeRef, index) => nodeRef !== anchor.nodeRefs[index]) ||
+        JSON.stringify(sourceMemoryIdsByNodeRef) !== JSON.stringify(anchor.sourceMemoryIdsByNodeRef)
+      ) {
+        await writeJsonFileAtomic(filePath, validateCueAnchor({ ...anchor, nodeRefs, sourceMemoryIdsByNodeRef }));
+      }
+    }
+    return removed;
+  });
+}
+
 export async function getCueAnchorStoreStatus(options: {
   memoryDir: string;
   abstractionNodeStoreDir?: string;
@@ -119,7 +370,7 @@ export async function getCueAnchorStoreStatus(options: {
     ? options.abstractionNodeStoreDir.trim()
     : path.join(options.memoryDir, "state", "abstraction-nodes");
   const rootDir = resolveCueAnchorStoreDir(abstractionNodeStoreDir, options.cueAnchorStoreDir);
-  const files = await listJsonFiles(rootDir);
+  const files = await listJsonFilesStrict(rootDir, { allowMissingDirectory: true });
   const anchors: CueAnchor[] = [];
   const invalidAnchors: Array<{ path: string; error: string }> = [];
 
@@ -134,7 +385,9 @@ export async function getCueAnchorStoreStatus(options: {
     }
   }
 
-  anchors.sort((a, b) => b.recordedAt.localeCompare(a.recordedAt));
+  anchors.sort(
+    (a, b) => Date.parse(b.recordedAt) - Date.parse(a.recordedAt) || compareDeterministicStrings(a.anchorId, b.anchorId)
+  );
 
   const byType: Partial<Record<CueAnchorType, number>> = {};
   let totalNodeRefs = 0;

package/src/dependency-frontmatter.test.ts

@@ -0,0 +1,83 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { clearMemoryCache } from "./memory-cache.js";
+import { StorageManager } from "./storage.js";
+
+async function writeFactFile(storage: StorageManager, body: string): Promise<{ id: string; filePath: string }> {
+  const today = new Date().toISOString().slice(0, 10);
+  const id = `fact-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const factsDir = path.join(storage.dir, "facts", today);
+  const filePath = path.join(factsDir, `${id}.md`);
+  const now = new Date().toISOString();
+  await mkdir(factsDir, { recursive: true });
+  await writeFile(
+    filePath,
+    [
+      "---",
+      `id: ${id}`,
+      "category: fact",
+      `created: ${now}`,
+      `updated: ${now}`,
+      "source: extraction",
+      "confidence: 0.8",
+      "confidenceTier: high",
+      "tags: []",
+      "---",
+      "",
+      body,
+      "",
+    ].join("\n"),
+    "utf-8",
+  );
+  clearMemoryCache(storage.dir);
+  return { id, filePath };
+}
+
+test("dependency supersession fields survive serialize and parse", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-dependency-frontmatter-"));
+  try {
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const { id, filePath } = await writeFactFile(storage, "A dependent claim.");
+
+    await storage.updateMemoryFrontmatter(id, {
+      supersessionCause: "dependency",
+      invalidatedBy: "fact-support-1",
+    });
+
+    const raw = await readFile(filePath, "utf-8");
+    assert.match(raw, /\nsupersessionCause: dependency\n/);
+    assert.match(raw, /\ninvalidatedBy: fact-support-1\n/);
+
+    const memory = (await storage.readAllMemories()).find(
+      (candidate) => candidate.frontmatter.id === id,
+    );
+    assert.ok(memory);
+    assert.equal(memory.frontmatter.supersessionCause, "dependency");
+    assert.equal(memory.frontmatter.invalidatedBy, "fact-support-1");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("legacy memory omits dependency supersession fields", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-dependency-legacy-"));
+  try {
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const { id } = await writeFactFile(storage, "A legacy claim.");
+
+    const memory = (await storage.readAllMemories()).find(
+      (candidate) => candidate.frontmatter.id === id,
+    );
+    assert.ok(memory);
+    assert.equal(memory.frontmatter.supersessionCause, undefined);
+    assert.equal(memory.frontmatter.invalidatedBy, undefined);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/dependency-propagation-config.ts

@@ -0,0 +1,94 @@
+import { coerceBooleanLike, coerceNumber } from "./connectors/coerce.js";
+import type { DependencyPropagationConfig } from "./types.js";
+
+const DEFAULT_LINK_TYPES: DependencyPropagationConfig["linkTypes"] = ["supports", "follows"];
+const ALLOWED_LINK_TYPES: Record<DependencyPropagationConfig["linkTypes"][number], true> = {
+  supports: true,
+  follows: true,
+  references: true,
+};
+
+function parseBoolean(value: unknown, fallback: boolean, keyName: string): boolean {
+  if (value === undefined) return fallback;
+  const parsed = coerceBooleanLike(value, keyName);
+  if (parsed === undefined) {
+    throw new Error(`${keyName} must be a boolean; got ${JSON.stringify(value)}`);
+  }
+  return parsed;
+}
+
+function parseIntegerAtLeast(value: unknown, min: number, fallback: number, keyName: string): number {
+  if (value === undefined) return fallback;
+  const parsed = coerceNumber(value, keyName);
+  if (
+    parsed === undefined ||
+    !Number.isFinite(parsed) ||
+    !Number.isInteger(parsed) ||
+    parsed < min
+  ) {
+    throw new Error(
+      `${keyName} must be ${min === 0 ? "a non-negative" : "a positive"} integer; got ${JSON.stringify(value)}`,
+    );
+  }
+  return parsed;
+}
+
+function parseLinkTypes(value: unknown): DependencyPropagationConfig["linkTypes"] {
+  if (value === undefined) return [...DEFAULT_LINK_TYPES];
+  if (!Array.isArray(value)) {
+    throw new Error(`dependencyPropagation.linkTypes must be an array; got ${JSON.stringify(value)}`);
+  }
+  const linkTypes: DependencyPropagationConfig["linkTypes"] = [];
+  for (const linkType of value) {
+    if (
+      typeof linkType !== "string" ||
+      !Object.hasOwn(ALLOWED_LINK_TYPES, linkType)
+    ) {
+      throw new Error(
+        "dependencyPropagation.linkTypes must contain only supports, follows, references",
+      );
+    }
+    if (!linkTypes.includes(linkType as DependencyPropagationConfig["linkTypes"][number])) {
+      linkTypes.push(linkType as DependencyPropagationConfig["linkTypes"][number]);
+    }
+  }
+  return linkTypes;
+}
+
+export function parseDependencyPropagationConfig(
+  cfg: Record<string, unknown>,
+): DependencyPropagationConfig {
+  const raw = cfg.dependencyPropagation;
+  if (raw === undefined) {
+    return {
+      enabled: false,
+      linkTypes: [...DEFAULT_LINK_TYPES],
+      maxDependents: 10,
+      timeoutMs: 20_000,
+      dryRun: false,
+    };
+  }
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`dependencyPropagation must be a plain object; got ${JSON.stringify(raw)}`);
+  }
+
+  const block = raw as Record<string, unknown>;
+
+  return {
+    enabled: parseBoolean(block.enabled, false, "dependencyPropagation.enabled"),
+    linkTypes: parseLinkTypes(block.linkTypes),
+    maxDependents: parseIntegerAtLeast(
+      block.maxDependents,
+      0,
+      10,
+      "dependencyPropagation.maxDependents",
+    ),
+    timeoutMs: parseIntegerAtLeast(
+      block.timeoutMs,
+      1,
+      20_000,
+      "dependencyPropagation.timeoutMs",
+    ),
+    dryRun: parseBoolean(block.dryRun, false, "dependencyPropagation.dryRun"),
+  };
+}

package/src/deterministic-order.ts

@@ -0,0 +1,14 @@
+export function compareDeterministicStrings(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+export function mergeSortedUniqueStrings(...collections: Array<Iterable<string> | undefined>): string[] {
+  const values = new Set<string>();
+  for (const collection of collections) {
+    if (!collection) continue;
+    for (const value of collection) values.add(value);
+  }
+  return [...values].sort(compareDeterministicStrings);
+}

package/src/extraction-normalization.ts

@@ -0,0 +1,71 @@
+import { EXTRACTION_RESPONSE_PLACEHOLDERS } from "./extraction-prompt.js";
+import { normalizeRecallTokens } from "./recall-tokenization.js";
+import { sanitizeMemoryContent } from "./sanitize.js";
+import type { ExtractedFact } from "./types.js";
+
+export function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function containsExtractionPlaceholder(value: unknown): boolean {
+  if (typeof value === "string") return EXTRACTION_RESPONSE_PLACEHOLDERS[value.trim()] === true;
+  if (Array.isArray(value)) return value.some(containsExtractionPlaceholder);
+  return isPlainRecord(value) && Object.values(value).some(containsExtractionPlaceholder);
+}
+
+export function extractionText(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const text = value.trim();
+  return text.length > 0 && !containsExtractionPlaceholder(text) ? text : undefined;
+}
+
+export function extractionAttributes(value: unknown): Record<string, string> | undefined {
+  if (!isPlainRecord(value)) return undefined;
+  const attributes: Record<string, string> = {};
+  for (const [key, candidate] of Object.entries(value).sort(([left], [right]) => left.localeCompare(right))) {
+    const normalizedKey = extractionText(key);
+    const normalizedValue = extractionText(candidate);
+    if (normalizedKey !== undefined && normalizedValue !== undefined) {
+      attributes[normalizedKey] = normalizedValue;
+    }
+  }
+  return Object.keys(attributes).length > 0 ? attributes : undefined;
+}
+
+const EXTRACTION_CUE_ANCHOR_TYPES = new Set(["entity", "file", "tool", "outcome", "constraint", "date"]);
+
+export function extractionCueAnchors(value: unknown): NonNullable<ExtractedFact["cueAnchors"]> | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const anchorsByIdentity = new Map<string, NonNullable<ExtractedFact["cueAnchors"]>[number]>();
+  for (const candidate of value) {
+    if (!isPlainRecord(candidate)) continue;
+    const type = extractionText(candidate.type);
+    const anchorValue = extractionText(candidate.value);
+    const sanitizedAnchor = anchorValue === undefined ? undefined : sanitizeMemoryContent(anchorValue);
+    const sanitizedAnchorValue = sanitizedAnchor?.clean === true ? sanitizedAnchor.text.trim() : undefined;
+    if (
+      type === undefined ||
+      sanitizedAnchorValue === undefined ||
+      sanitizedAnchorValue.length === 0 ||
+      sanitizedAnchorValue.length > 120 ||
+      !EXTRACTION_CUE_ANCHOR_TYPES.has(type)
+    ) {
+      continue;
+    }
+    const normalizedCue = normalizeRecallTokens(sanitizedAnchorValue).join(" ");
+    if (normalizedCue.length === 0) continue;
+    const identity = `${type}:${normalizedCue}`;
+    const existing = anchorsByIdentity.get(identity);
+    if (!existing || sanitizedAnchorValue.localeCompare(existing.value) < 0) {
+      anchorsByIdentity.set(identity, {
+        type: type as NonNullable<ExtractedFact["cueAnchors"]>[number]["type"],
+        value: sanitizedAnchorValue,
+      });
+    }
+  }
+  const anchors = [...anchorsByIdentity.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .slice(0, 3)
+    .map(([, anchor]) => anchor);
+  return anchors.length > 0 ? anchors : undefined;
+}