@remnic/core 9.49.0 → 9.49.1

package/src/harmonic-construction.ts

@@ -0,0 +1,367 @@
+import { createHash } from "node:crypto";
+import {
+  type AbstractionNode,
+  HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY,
+  upsertAbstractionNodes,
+} from "./abstraction-nodes.js";
+import { type CueAnchor, type CueAnchorType, upsertCueAnchors } from "./cue-anchors.js";
+import { compareDeterministicStrings } from "./deterministic-order.js";
+import { normalizeRecallTokens } from "./recall-tokenization.js";
+import { sanitizeMemoryContent } from "./sanitize.js";
+
+export interface HarmonicCueAnchorInput {
+  type: CueAnchorType;
+  value: string;
+}
+
+export interface HarmonicConstructionInput {
+  sessionKey: string;
+  recordedAt: string;
+  episodeTitle?: string | null;
+  persistedFacts: Array<{
+    memoryId: string;
+    content: string;
+    category: string;
+    tags: string[];
+    insertedAt?: string;
+    entityRef?: string | null;
+    cueAnchors?: HarmonicCueAnchorInput[] | null;
+    validAt?: string | null;
+  }>;
+  entityMentions: Array<{
+    name: string;
+    type: string;
+    facts?: string[];
+  }>;
+}
+
+const CUE_ANCHOR_TYPES: Record<CueAnchorType, true> = {
+  entity: true,
+  file: true,
+  tool: true,
+  outcome: true,
+  constraint: true,
+  date: true,
+};
+
+function safeHarmonicDisplayText(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const candidate = value.trim();
+  if (candidate.length === 0) return undefined;
+  const sanitized = sanitizeMemoryContent(candidate);
+  if (!sanitized.clean) return undefined;
+  const clean = sanitized.text.trim();
+  return clean.length > 0 ? clean : undefined;
+}
+function hashId(prefix: string, value: string): string {
+  return `${prefix}${createHash("sha256").update(value).digest("hex").slice(0, 16)}`;
+}
+
+function truncate(value: string, maxChars: number): string {
+  return value.length <= maxChars ? value : value.slice(0, maxChars);
+}
+
+function sortedUnique(values: Iterable<string>): string[] {
+  return [...new Set(values)].sort(compareDeterministicStrings);
+}
+
+export function harmonicEntitySegment(name: string): string {
+  const normalized = name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+  const start = normalized.startsWith("-") ? 1 : 0;
+  const end = normalized.endsWith("-") ? normalized.length - 1 : normalized.length;
+  const segment = normalized.slice(start, end);
+  return segment || hashId("entity-", name).slice(0, 23);
+}
+
+export function normalizedHarmonicEntityIdentity(name: string): string {
+  return name.trim().toLowerCase().replace(/\s+/g, " ");
+}
+export function harmonicEntityReferenceMatches(
+  entityRef: string,
+  entityName: string,
+  allowSegmentFallback: boolean
+): boolean {
+  if (normalizedHarmonicEntityIdentity(entityRef) === normalizedHarmonicEntityIdentity(entityName)) {
+    return true;
+  }
+  return allowSegmentFallback && harmonicEntitySegment(entityRef) === harmonicEntitySegment(entityName);
+}
+
+export function normalizeCueAnchorInputs(value: unknown, maxAnchors = 3): HarmonicCueAnchorInput[] {
+  if (!Array.isArray(value) || maxAnchors <= 0) return [];
+  const byIdentity = new Map<string, HarmonicCueAnchorInput>();
+  for (const candidate of value) {
+    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) continue;
+    const record = candidate as Record<string, unknown>;
+    if (typeof record.type !== "string" || !Object.hasOwn(CUE_ANCHOR_TYPES, record.type)) {
+      continue;
+    }
+    const anchorValue = safeHarmonicDisplayText(record.value);
+    if (anchorValue === undefined || anchorValue.length > 120) continue;
+    const type = record.type as CueAnchorType;
+    const normalizedCue = normalizeRecallTokens(anchorValue).join(" ");
+    if (normalizedCue.length === 0) continue;
+    const identity = `${type}:${normalizedCue}`;
+    const existing = byIdentity.get(identity);
+    if (!existing || compareDeterministicStrings(anchorValue, existing.value) < 0) {
+      byIdentity.set(identity, { type, value: anchorValue });
+    }
+  }
+  return [...byIdentity.entries()]
+    .sort(([left], [right]) => compareDeterministicStrings(left, right))
+    .slice(0, maxAnchors)
+    .map(([, anchor]) => anchor);
+}
+
+function validAtDate(validAt: string | null | undefined): string | undefined {
+  if (typeof validAt !== "string") return undefined;
+  const match = /^(\d{4})-(\d{2})-(\d{2})/.exec(validAt);
+  if (!match) return undefined;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const date = new Date(0);
+  date.setUTCFullYear(year, month - 1, day);
+  if (
+    !Number.isFinite(date.getTime()) ||
+    date.getUTCFullYear() !== year ||
+    date.getUTCMonth() !== month - 1 ||
+    date.getUTCDate() !== day
+  ) {
+    return undefined;
+  }
+  return match[0];
+}
+
+function sourceMemoryInsertedAtMetadata(
+  facts: Array<{ memoryId: string; insertedAt: string }>
+): Record<string, string> {
+  const insertedAtById = Object.fromEntries(
+    facts
+      .map((fact) => [fact.memoryId, fact.insertedAt] as const)
+      .sort(([left], [right]) => compareDeterministicStrings(left, right))
+  );
+  return {
+    [HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY]: JSON.stringify(insertedAtById),
+  };
+}
+
+export function deriveHarmonicRecords(input: HarmonicConstructionInput): {
+  nodes: AbstractionNode[];
+  anchors: CueAnchor[];
+} {
+  const persistedFacts = input.persistedFacts
+    .map((fact) => ({
+      ...fact,
+      memoryId: fact.memoryId.trim(),
+      content: safeHarmonicDisplayText(fact.content) ?? "",
+      insertedAt:
+        fact.insertedAt && Number.isFinite(Date.parse(fact.insertedAt))
+          ? new Date(fact.insertedAt).toISOString()
+          : input.recordedAt,
+      tags: sortedUnique(
+        fact.tags.flatMap((tag) => {
+          const safeTag = safeHarmonicDisplayText(tag);
+          return safeTag ? [safeTag] : [];
+        })
+      ),
+      entityRef: safeHarmonicDisplayText(fact.entityRef),
+      cueAnchors: normalizeCueAnchorInputs(fact.cueAnchors),
+    }))
+    .filter((fact) => fact.memoryId.length > 0 && fact.content.length > 0)
+    .sort(
+      (left, right) =>
+        compareDeterministicStrings(left.memoryId, right.memoryId) ||
+        compareDeterministicStrings(left.content, right.content)
+    );
+
+  if (persistedFacts.length === 0) return { nodes: [], anchors: [] };
+
+  const sourceMemoryIds = sortedUnique(persistedFacts.map((fact) => fact.memoryId));
+  const episodeNodeId = hashId("ep-", `${input.sessionKey}|${input.recordedAt}|${sourceMemoryIds.join("|")}`);
+  const episodeTitle = safeHarmonicDisplayText(input.episodeTitle) ?? persistedFacts[0]?.content ?? "Memory episode";
+  const episodeNode: AbstractionNode = {
+    schemaVersion: 1,
+    nodeId: episodeNodeId,
+    recordedAt: input.recordedAt,
+    sessionKey: input.sessionKey,
+    kind: "episode",
+    abstractionLevel: "micro",
+    title: truncate(episodeTitle, 80),
+    summary: truncate(
+      persistedFacts
+        .slice(0, 3)
+        .map((fact) => fact.content)
+        .join("; "),
+      400
+    ),
+    sourceMemoryIds,
+    entityRefs: sortedUnique(persistedFacts.flatMap((fact) => (fact.entityRef ? [fact.entityRef] : []))),
+    tags: sortedUnique(persistedFacts.flatMap((fact) => fact.tags)),
+    metadata: sourceMemoryInsertedAtMetadata(persistedFacts),
+  };
+
+  const mentionGroups = new Map<string, { names: string[]; types: string[]; facts: string[]; segment: string }>();
+  for (const mention of input.entityMentions) {
+    const name = safeHarmonicDisplayText(mention.name);
+    if (!name) continue;
+    const identity = normalizedHarmonicEntityIdentity(name);
+    const group = mentionGroups.get(identity) ?? {
+      names: [],
+      types: [],
+      facts: [],
+      segment: harmonicEntitySegment(name),
+    };
+    group.names.push(name);
+    group.types.push(mention.type.trim().toLowerCase());
+    group.facts.push(
+      ...(mention.facts ?? []).flatMap((fact) => {
+        const safeFact = safeHarmonicDisplayText(fact);
+        return safeFact ? [safeFact] : [];
+      })
+    );
+    mentionGroups.set(identity, group);
+  }
+  const groupsPerSegment = new Map<string, number>();
+  for (const group of mentionGroups.values()) {
+    groupsPerSegment.set(group.segment, (groupsPerSegment.get(group.segment) ?? 0) + 1);
+  }
+
+  const topicEntries = [...mentionGroups.entries()]
+    .sort(([left], [right]) => compareDeterministicStrings(left, right))
+    .flatMap(([identity, group]) => {
+      const matchingFacts = persistedFacts.filter((fact) => {
+        if (!fact.entityRef) return false;
+        return harmonicEntityReferenceMatches(
+          fact.entityRef,
+          sortedUnique(group.names)[0] ?? identity,
+          groupsPerSegment.get(group.segment) === 1
+        );
+      });
+      const nodeSegment = `${group.segment}-${hashId("", identity)}`;
+      const mentionSummary = sortedUnique(group.facts).join("; ");
+      const node: AbstractionNode = {
+        schemaVersion: 1,
+        nodeId: `topic-${nodeSegment}`,
+        recordedAt: input.recordedAt,
+        sessionKey: input.sessionKey,
+        kind: group.types.includes("project") ? "project" : "topic",
+        abstractionLevel: "meso",
+        title: sortedUnique(group.names)[0] ?? group.segment,
+        summary: truncate(
+          mentionSummary ||
+            matchingFacts
+              .slice(0, 3)
+              .map((fact) => fact.content)
+              .join("; ") ||
+            sortedUnique(group.names)[0] ||
+            group.segment,
+          400
+        ),
+        sourceMemoryIds: sortedUnique(matchingFacts.map((fact) => fact.memoryId)),
+        entityRefs: sortedUnique(group.names),
+        tags: sortedUnique(matchingFacts.flatMap((fact) => fact.tags)),
+        metadata: sourceMemoryInsertedAtMetadata(matchingFacts),
+      };
+      return [{ identity, segment: group.segment, node }];
+    });
+  const topicNodes = topicEntries.map((entry) => entry.node);
+  const topicNodeIdByIdentity = new Map(topicEntries.map((entry) => [entry.identity, entry.node.nodeId]));
+  const topicEntriesBySegment = new Map<string, typeof topicEntries>();
+  for (const entry of topicEntries) {
+    const entries = topicEntriesBySegment.get(entry.segment) ?? [];
+    entries.push(entry);
+    topicEntriesBySegment.set(entry.segment, entries);
+  }
+  const topicNodeIdForEntityRef = (entityRef: string): string | undefined => {
+    const exact = topicNodeIdByIdentity.get(normalizedHarmonicEntityIdentity(entityRef));
+    if (exact) return exact;
+    const segmentEntries = topicEntriesBySegment.get(harmonicEntitySegment(entityRef));
+    return segmentEntries?.length === 1 ? segmentEntries[0]?.node.nodeId : undefined;
+  };
+  const anchorsById = new Map<string, CueAnchor>();
+  for (const fact of persistedFacts) {
+    const deterministicAnchors: HarmonicCueAnchorInput[] = [];
+    if (fact.entityRef) {
+      deterministicAnchors.push({ type: "entity", value: fact.entityRef });
+    }
+    const date = validAtDate(fact.validAt);
+    if (date) deterministicAnchors.push({ type: "date", value: date });
+
+    for (const anchorInput of [...fact.cueAnchors, ...deterministicAnchors]) {
+      const anchorValue = safeHarmonicDisplayText(anchorInput.value);
+      if (anchorValue === undefined) continue;
+      const normalizedCue = normalizeRecallTokens(anchorValue).join(" ");
+      if (normalizedCue.length === 0) continue;
+      const anchorId = hashId("cue-", `${anchorInput.type}:${normalizedCue}`);
+      const topicNodeId = fact.entityRef ? topicNodeIdForEntityRef(fact.entityRef) : undefined;
+      const nodeRefs = sortedUnique(topicNodeId ? [episodeNodeId, topicNodeId] : [episodeNodeId]);
+      const existing = anchorsById.get(anchorId);
+      const mergedNodeRefs = sortedUnique([...(existing?.nodeRefs ?? []), ...nodeRefs]);
+      const sourceMemoryIdsByNodeRef = Object.fromEntries(
+        mergedNodeRefs.map((nodeRef) => [
+          nodeRef,
+          sortedUnique([
+            ...(existing?.sourceMemoryIdsByNodeRef?.[nodeRef] ?? []),
+            ...(nodeRefs.includes(nodeRef) ? [fact.memoryId] : []),
+          ]),
+        ])
+      );
+      anchorsById.set(anchorId, {
+        schemaVersion: 1,
+        anchorId,
+        anchorType: anchorInput.type,
+        anchorValue:
+          existing && compareDeterministicStrings(existing.anchorValue, anchorValue) < 0
+            ? existing.anchorValue
+            : anchorValue,
+        normalizedCue,
+        recordedAt: input.recordedAt,
+        sessionKey: input.sessionKey,
+        nodeRefs: mergedNodeRefs,
+        sourceMemoryIdsByNodeRef,
+        tags: sortedUnique([...(existing?.tags ?? []), ...fact.tags]),
+      });
+    }
+  }
+
+  return {
+    nodes: [episodeNode, ...topicNodes]
+      .map((node) => ({
+        ...node,
+        sourceMemoryIds: sortedUnique(node.sourceMemoryIds ?? []),
+        entityRefs: sortedUnique(node.entityRefs ?? []),
+        tags: sortedUnique(node.tags ?? []),
+      }))
+      .sort((left, right) => compareDeterministicStrings(left.nodeId, right.nodeId)),
+    anchors: [...anchorsById.values()]
+      .map((anchor) => ({
+        ...anchor,
+        nodeRefs: sortedUnique(anchor.nodeRefs),
+        tags: sortedUnique(anchor.tags ?? []),
+      }))
+      .sort((left, right) => compareDeterministicStrings(left.anchorId, right.anchorId)),
+  };
+}
+
+export async function persistHarmonicRecords(options: {
+  memoryDir: string;
+  abstractionNodeStoreDir?: string;
+  nodes: AbstractionNode[];
+  anchors: CueAnchor[];
+}): Promise<void> {
+  if (options.nodes.length > 0) {
+    await upsertAbstractionNodes({
+      memoryDir: options.memoryDir,
+      abstractionNodeStoreDir: options.abstractionNodeStoreDir,
+      nodes: options.nodes,
+    });
+  }
+  if (options.anchors.length > 0) {
+    await upsertCueAnchors({
+      memoryDir: options.memoryDir,
+      abstractionNodeStoreDir: options.abstractionNodeStoreDir,
+      anchors: options.anchors,
+    });
+  }
+}

package/src/harmonic-retrieval.ts

@@ -1,18 +1,122 @@
 import path from "node:path";
-import { listJsonFiles, readJsonFile } from "./json-store.js";
+import { listJsonFilesStrict, readJsonFile } from "./json-store.js";
 import { throwIfAborted } from "./abort-error.js";
-import {
-  resolveAbstractionNodeStoreDir,
-  validateAbstractionNode,
-  type AbstractionNode,
-} from "./abstraction-nodes.js";
-import {
-  resolveCueAnchorStoreDir,
-  validateCueAnchor,
-  type CueAnchor,
-  type CueAnchorType,
-} from "./cue-anchors.js";
+import { inferMemoryStatus, toMemoryPathRel } from "./memory-lifecycle-ledger-utils.js";
+ import {
+   HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY,
+   resolveAbstractionNodeStoreDir,
+   validateAbstractionNode,
+   type AbstractionNode,
+ } from "./abstraction-nodes.js";
+import { resolveCueAnchorStoreDir, validateCueAnchor, type CueAnchor, type CueAnchorType } from "./cue-anchors.js";
+import { compareDeterministicStrings } from "./deterministic-order.js";
 import { countRecallTokenOverlap, normalizeRecallTokens } from "./recall-tokenization.js";
+import { stripAttributesSuffix } from "./structured-attributes.js";
+import { isValidityExpiredNow } from "./temporal-validity.js";
+import type { MemoryFile } from "./types.js";
+
+type SourceMemoryMap = Map<string, MemoryFile>;
+
+async function readSourceMemories(options: {
+  memoryDir: string;
+  abortSignal?: AbortSignal;
+}): Promise<SourceMemoryMap> {
+  const sourceMemories: SourceMemoryMap = new Map();
+ try {
+ const { StorageManager } = await import("./storage.js");
+ const storage = new StorageManager(options.memoryDir);
+ const [hotMemories, coldMemories] = await Promise.all([
+ storage.readAllMemories({ abortSignal: options.abortSignal }),
+ storage.readAllColdMemories(),
+ ]);
+ for (const memory of [...hotMemories, ...coldMemories]) {
+      throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
+      sourceMemories.set(memory.frontmatter.id, memory);
+    }
+  } catch {
+    throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
+    // Source validation fails closed when the authorized memory directory is
+    // unreadable. Source-less nodes remain eligible for retrieval.
+    sourceMemories.clear();
+  }
+  return sourceMemories;
+}
+
+function projectSourceBackedNode(
+  node: AbstractionNode,
+  sourceMemories: SourceMemoryMap,
+  memoryDir: string,
+  temporalExpiredInInjection: boolean,
+  nowMs: number
+): AbstractionNode | null {
+  const sourceMemoryIds = node.sourceMemoryIds ?? [];
+  if (sourceMemoryIds.length === 0) return node;
+
+  const activeSourceMemoryIds = sourceMemoryIds.filter((memoryId) => {
+    const memory = sourceMemories.get(memoryId);
+    return (
+      memory !== undefined &&
+      inferMemoryStatus(memory.frontmatter, toMemoryPathRel(memoryDir, memory.path)) === "active" &&
+      (temporalExpiredInInjection || !isValidityExpiredNow(memory.frontmatter, nowMs))
+    );
+  });
+  if (activeSourceMemoryIds.length === 0) return null;
+
+  const activeMemories = activeSourceMemoryIds.flatMap((memoryId) => {
+    const memory = sourceMemories.get(memoryId);
+    return memory ? [memory] : [];
+  });
+  const activeContents = activeMemories.map((memory) =>
+    memory.frontmatter.structuredAttributes ? stripAttributesSuffix(memory.content) : memory.content
+  );
+  let metadata: Record<string, string> | undefined;
+  const insertedAtRaw = node.metadata?.[HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY];
+  if (insertedAtRaw) {
+    try {
+      const insertedAt = JSON.parse(insertedAtRaw) as Record<string, unknown>;
+      const activeInsertedAt = activeSourceMemoryIds.flatMap((memoryId) => {
+        const value = insertedAt[memoryId];
+        return typeof value === "string" ? [[memoryId, value] as const] : [];
+      });
+      if (activeInsertedAt.length > 0) {
+        metadata = {
+          [HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY]: JSON.stringify(Object.fromEntries(activeInsertedAt)),
+        };
+      }
+    } catch {
+      metadata = undefined;
+    }
+  }
+
+  return {
+    ...node,
+    sourceMemoryIds: activeSourceMemoryIds,
+    title: activeContents[0]?.slice(0, 80) ?? node.title,
+    summary: activeContents.slice(0, 3).join("; ").slice(0, 400),
+    tags: [...new Set(activeMemories.flatMap((memory) => memory.frontmatter.tags))].sort(compareDeterministicStrings),
+    entityRefs: [
+      ...new Set(
+        activeMemories.flatMap((memory) =>
+          typeof memory.frontmatter.entityRef === "string" ? [memory.frontmatter.entityRef] : []
+        )
+      ),
+    ].sort(compareDeterministicStrings),
+    metadata,
+  };
+}
+
+function anchorMatchesProjectedNode(
+  anchor: CueAnchor,
+  nodeRef: string,
+  node: AbstractionNode,
+  allowLegacyAttribution: boolean
+): boolean {
+  const activeSourceMemoryIds = node.sourceMemoryIds ?? [];
+  if (activeSourceMemoryIds.length === 0) return true;
+  if (!anchor.sourceMemoryIdsByNodeRef) return allowLegacyAttribution;
+  const anchorSourceMemoryIds = anchor.sourceMemoryIdsByNodeRef[nodeRef] ?? [];
+  return anchorSourceMemoryIds.some((sourceMemoryId) => activeSourceMemoryIds.includes(sourceMemoryId));
+}
 
 export interface HarmonicMatchedAnchor {
   anchorId: string;
@@ -74,7 +178,11 @@ function scoreNode(node: AbstractionNode, queryTokens: Set<string>): { score: nu
   return { score, matchedFields };
 }
 
-function scoreAnchor(anchor: CueAnchor, queryTokens: Set<string>): { score: number; matchedFields: string[] } {
+function scoreAnchor(
+  anchor: CueAnchor,
+  queryTokens: Set<string>,
+  eligibleNodeTags: readonly string[]
+): { score: number; matchedFields: string[] } {
   const matchedFields: string[] = [];
   let score = 0;
 
@@ -93,7 +201,7 @@ function scoreAnchor(anchor: CueAnchor, queryTokens: Set<string>): { score: numb
     matchedFields.push("anchorType");
   }
 
-  const tagMatches = countRecallTokenOverlap(queryTokens, anchor.tags?.join(" "));
+  const tagMatches = countRecallTokenOverlap(queryTokens, eligibleNodeTags.join(" "));
   if (tagMatches > 0) {
     score += tagMatches * 2;
     matchedFields.push("anchorTags");
@@ -107,7 +215,7 @@ async function readAbstractionNodes(options: {
   abstractionNodeStoreDir?: string;
 }): Promise<AbstractionNode[]> {
   const rootDir = resolveAbstractionNodeStoreDir(options.memoryDir, options.abstractionNodeStoreDir);
-  const files = await listJsonFiles(path.join(rootDir, "nodes"));
+  const files = await listJsonFilesStrict(path.join(rootDir, "nodes"), { allowMissingDirectory: true });
   const nodes: AbstractionNode[] = [];
   for (const filePath of files) {
     try {
@@ -125,7 +233,7 @@ async function readCueAnchors(options: {
 }): Promise<CueAnchor[]> {
   const abstractionRoot = resolveAbstractionNodeStoreDir(options.memoryDir, options.abstractionNodeStoreDir);
   const rootDir = resolveCueAnchorStoreDir(abstractionRoot);
-  const files = await listJsonFiles(rootDir);
+  const files = await listJsonFilesStrict(rootDir, { allowMissingDirectory: true });
   const anchors: CueAnchor[] = [];
   for (const filePath of files) {
     try {
@@ -145,15 +253,38 @@ export async function searchHarmonicRetrieval(options: {
   sessionKey?: string;
   anchorsEnabled: boolean;
   abortSignal?: AbortSignal;
+  temporalExpiredInInjection?: boolean;
 }): Promise<HarmonicRetrievalResult[]> {
   throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
   const queryTokens = new Set(normalizeRecallTokens(options.query, ["what", "which"]));
   if (queryTokens.size === 0 || options.maxResults <= 0) return [];
 
   const nodes = await readAbstractionNodes(options);
+  const sourceBackedNodes = nodes.filter((node) => (node.sourceMemoryIds?.length ?? 0) > 0);
+  const sourceMemories: SourceMemoryMap =
+    sourceBackedNodes.length > 0 ? await readSourceMemories(options) : new Map<string, MemoryFile>();
+  const legacyCompatibleNodeRefs = new Set<string>();
+  const nowMs = Date.now();
+  const eligibleNodes = nodes.flatMap((node) => {
+    const projected = projectSourceBackedNode(
+      node,
+      sourceMemories,
+      options.memoryDir,
+      options.temporalExpiredInInjection === true,
+      nowMs
+    );
+    if (
+      projected &&
+      (node.sourceMemoryIds?.length ?? 0) > 0 &&
+      projected.sourceMemoryIds?.length === node.sourceMemoryIds?.length
+    ) {
+      legacyCompatibleNodeRefs.add(node.nodeId);
+    }
+    return projected ? [projected] : [];
+  });
   const candidates = new Map<string, HarmonicCandidate>();
 
-  for (const node of nodes) {
+  for (const node of eligibleNodes) {
     throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
     const { score, matchedFields } = scoreNode(node, queryTokens);
     if (score <= 0) continue;
@@ -169,12 +300,21 @@ export async function searchHarmonicRetrieval(options: {
   if (options.anchorsEnabled) {
     throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
     const anchors = await readCueAnchors(options);
-    const nodeIndex = new Map(nodes.map((node) => [node.nodeId, node]));
+    const nodeIndex = new Map(eligibleNodes.map((node) => [node.nodeId, node]));
     for (const anchor of anchors) {
       throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
-      const { score, matchedFields } = scoreAnchor(anchor, queryTokens);
+ const eligibleNodeRefs = anchor.nodeRefs.filter((nodeRef) => {
+ const node = nodeIndex.get(nodeRef);
+ return (
+ node !== undefined &&
+ anchorMatchesProjectedNode(anchor, nodeRef, node, legacyCompatibleNodeRefs.has(nodeRef))
+ );
+ });
+ const eligibleNodeTags = new Set(eligibleNodeRefs.flatMap((nodeRef) => nodeIndex.get(nodeRef)?.tags ?? []));
+ const eligibleAnchorTags = anchor.tags?.filter((tag) => eligibleNodeTags.has(tag)) ?? [];
+      const { score, matchedFields } = scoreAnchor(anchor, queryTokens, eligibleAnchorTags);
       if (score <= 0) continue;
-      for (const nodeRef of anchor.nodeRefs) {
+      for (const nodeRef of eligibleNodeRefs) {
         const node = nodeIndex.get(nodeRef);
         if (!node) continue;
         const existing = candidates.get(nodeRef) ?? {
@@ -207,17 +347,18 @@ export async function searchHarmonicRetrieval(options: {
         nodeScore: candidate.nodeScore,
         anchorScore: candidate.anchorScore,
         matchedFields: [...candidate.matchedFields].sort(),
-        matchedAnchors: [...candidate.matchedAnchors.values()].sort((left, right) =>
-          left.anchorType.localeCompare(right.anchorType) || left.anchorValue.localeCompare(right.anchorValue)
+        matchedAnchors: [...candidate.matchedAnchors.values()].sort(
+          (left, right) =>
+            left.anchorType.localeCompare(right.anchorType) || left.anchorValue.localeCompare(right.anchorValue)
         ),
       };
     })
     .filter((result) => result.nodeScore > 0 || result.anchorScore > 0)
     .sort(
       (left, right) =>
-        right.score - left.score
-        || right.anchorScore - left.anchorScore
-        || right.node.recordedAt.localeCompare(left.node.recordedAt),
+        right.score - left.score ||
+        right.anchorScore - left.anchorScore ||
+        right.node.recordedAt.localeCompare(left.node.recordedAt)
     )
     .slice(0, options.maxResults);
 }

package/src/index.ts

@@ -508,7 +508,8 @@ export {
   type RemnicChatGptMemoryCard,
   type RemnicChatGptMemoryInspectorResult,
 } from "./mcp-memory-inspector-app.js";
-
+export * from "./coding/pre-action-gate.js";
+export * from "./causal-trajectory.js";
 // Coding-agent subsystem (issue #569)
 export {
   resolveGitContext,
@@ -1442,10 +1443,7 @@ export {
   type ForkLineage,
 } from "./transfer/capsule-fork.js";
 
-// ---------------------------------------------------------------------------
-// Coding-graph engine contract (#1551 PR1) — types owned by core,
-// implemented by @remnic/coding-graph (à-la-carte optional).
-// ---------------------------------------------------------------------------
+// Coding-graph engine contract (#1551 PR1), implemented by optional @remnic/coding-graph.
 
 export {
   CODING_GRAPH_ENGINE_VERSION,
@@ -1463,3 +1461,4 @@ export type {
   SymbolIR,
 } from "./coding/coding-graph-types.js";
 export type { ResolvedScopeProfilePlan } from "./namespaces/scope-profiles.js";
+export * from "./maintenance/atomic-file.js";