@remnic/core 9.62.0 → 9.62.1

package/src/cli.ts

@@ -12,6 +12,7 @@ import { resolveNamespaceCapabilities,
 import { ThreadingManager } from "./threading.js";
 import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
 import { utcDayRange } from "./transcript.js";
+import { padEndDisplay, truncateGraphemeSafe } from "./whitespace.js";
 import { runWearablesCliCommand } from "./wearables/cli.js";
 import { registerMeetingsCommands } from "./cli/meetings-commands.js";
 import { registerResearchStatusCommands } from "./cli/research-status-commands.js";
@@ -5672,7 +5673,7 @@ export function registerCli(
               console.log(`  raw excerpts (${r.rawExcerpts.length}):`);
               for (const ex of r.rawExcerpts) {
                 console.log(
-                  `    [turn ${ex.turnIndex}, ${ex.role}] ${ex.content.slice(0, 200)}`,
+                  `    [turn ${ex.turnIndex}, ${ex.role}] ${truncateGraphemeSafe(ex.content, 200)}`,
                 );
               }
             }
@@ -7614,7 +7615,7 @@ export function registerCli(
               console.log(`  ${r.path} (score: ${r.score.toFixed(3)})`);
               if (r.snippet) {
                 console.log(
-                  `    ${r.snippet.slice(0, 150).replace(/\n/g, " ")}`,
+                  `    ${truncateGraphemeSafe(r.snippet, 150).replace(/\n/g, " ")}`,
                 );
               }
               console.log();
@@ -7640,7 +7641,7 @@ export function registerCli(
             console.log(`\n=== Text Search Fallback: "${query}" (${matches.length} results) ===\n`);
             console.log(`QMD status: ${qmdStatus}\n`);
             for (const m of matches.slice(0, maxResults)) {
-              console.log(`  [${m.frontmatter.category}] ${m.content.slice(0, 120)}`);
+              console.log(`  [${m.frontmatter.category}] ${truncateGraphemeSafe(m.content, 120)}`);
             }
           }
         });
@@ -7783,12 +7784,12 @@ export function registerCli(
             for (const cluster of result.clusters) {
               console.log(`\n  Category: ${cluster.category} (${cluster.memories.length} memories, overlap=${cluster.overlapScore.toFixed(2)})`);
               for (const m of cluster.memories) {
-                const preview = m.content.length > 80 ? m.content.slice(0, 80) + "..." : m.content;
+                const preview = m.content.length > 80 ? `${truncateGraphemeSafe(m.content, 80)}...` : m.content;
                 console.log(`    - ${m.frontmatter.id}: ${preview}`);
               }
               if (cluster.canonicalContent) {
                 const preview = cluster.canonicalContent.length > 120
-                  ? cluster.canonicalContent.slice(0, 120) + "..."
+                  ? `${truncateGraphemeSafe(cluster.canonicalContent, 120)}...`
                   : cluster.canonicalContent;
                 console.log(`    → Canonical: ${preview}`);
               }
@@ -8018,7 +8019,7 @@ export function registerCli(
             const lastAccessed = m.frontmatter.lastAccessed
               ? new Date(m.frontmatter.lastAccessed).toLocaleDateString()
               : "unknown";
-            console.log(`  ${m.frontmatter.accessCount}x  [${m.frontmatter.category}] ${m.content.slice(0, 80)}`);
+            console.log(`  ${m.frontmatter.accessCount}x  [${m.frontmatter.category}] ${truncateGraphemeSafe(m.content, 80)}`);
             console.log(`       Last accessed: ${lastAccessed}  ID: ${m.frontmatter.id}`);
             console.log();
           }
@@ -8071,7 +8072,7 @@ export function registerCli(
           console.log("\n=== Importance Distribution ===\n");
           for (const [level, count] of Object.entries(levelCounts)) {
             const bar = "█".repeat(Math.min(count, 50));
-            console.log(`  ${level.padEnd(10)} ${count.toString().padStart(4)} ${bar}`);
+            console.log(`  ${padEndDisplay(level, 10)} ${count.toString().padStart(4)} ${bar}`);
           }
           console.log(`\n  Total scored: ${withImportance.length} / ${memories.length} memories\n`);
 
@@ -8104,7 +8105,7 @@ export function registerCli(
             console.log(
               `  ${imp.score.toFixed(2)} [${imp.level}] [${m.frontmatter.category}]`,
             );
-            console.log(`    ${m.content.slice(0, 100)}`);
+            console.log(`    ${truncateGraphemeSafe(m.content, 100)}`);
             if (imp.keywords.length > 0) {
               console.log(`    Keywords: ${imp.keywords.join(", ")}`);
             }
@@ -8131,7 +8132,7 @@ export function registerCli(
 
           for (const topic of topics.slice(0, top)) {
             const bar = "█".repeat(Math.min(Math.round(topic.score * 10), 30));
-            console.log(`  ${topic.term.padEnd(20)} ${topic.score.toFixed(3)} (${topic.count}x) ${bar}`);
+            console.log(`  ${padEndDisplay(topic.term, 20)} ${topic.score.toFixed(3)} (${topic.count}x) ${bar}`);
           }
         });
 
@@ -8163,7 +8164,7 @@ export function registerCli(
             console.log(`    Time range: ${summary.timeRangeStart.slice(0, 10)} to ${summary.timeRangeEnd.slice(0, 10)}`);
             console.log(`    Source memories: ${summary.sourceEpisodeIds.length}`);
             console.log(`    Key facts: ${summary.keyFacts.length}`);
-            console.log(`\n    Summary: ${summary.summaryText.slice(0, 200)}...`);
+            console.log(`\n    Summary: ${truncateGraphemeSafe(summary.summaryText, 200)}...`);
             console.log();
           }
         });
@@ -8255,13 +8256,13 @@ export function registerCli(
             const parent = memories.find((m) => m.frontmatter.id === parentId);
             console.log(`\n=== Chunks for ${parentId} ===\n`);
             if (parent) {
-              console.log(`Parent: ${parent.content.slice(0, 100)}...`);
+              console.log(`Parent: ${truncateGraphemeSafe(parent.content, 100)}...`);
               console.log();
             }
 
             for (const chunk of chunks) {
               console.log(
-                `  [${(chunk.frontmatter.chunkIndex ?? 0) + 1}/${chunk.frontmatter.chunkTotal}] ${chunk.content.slice(0, 80)}...`,
+                `  [${(chunk.frontmatter.chunkIndex ?? 0) + 1}/${chunk.frontmatter.chunkTotal}] ${truncateGraphemeSafe(chunk.content, 80)}...`,
               );
             }
             return;
@@ -9408,7 +9409,7 @@ function formatTranscript(entries: TranscriptEntry[]): string {
   return entries
     .map((e) => {
       const time = e.timestamp.slice(11, 16); // HH:MM
-      return `[${time}] ${e.role}: ${e.content.slice(0, 200)}${e.content.length > 200 ? "..." : ""}`;
+      return `[${time}] ${e.role}: ${truncateGraphemeSafe(e.content, 200)}${e.content.length > 200 ? "..." : ""}`;
     })
     .join("\n");
 }

package/src/entity-retrieval.ts

@@ -8,12 +8,9 @@ import { collectNativeKnowledgeChunks, type NativeKnowledgeChunk } from "./nativ
 import { compareEntityTimestamps, normalizeEntityName, type StorageManager } from "./storage.js";
 import { normalizeEntityText, resolveRequestedEntitySectionKeys } from "./entity-schema.js";
 import type { EntityStructuredSection, MemoryFile, PluginConfig, TranscriptEntry } from "./types.js";
+import { truncateGraphemeSafe } from "./whitespace.js";
 import { containsPhrase } from "./entity-retrieval-boundaries.js";
-import {
-  buildOriginStructuredSections,
-  sanitizeOriginatedFacts,
-  type EntityOriginStructuredSection,
-} from "./entity-origin-fields.js";
+import { buildOriginStructuredSections, sanitizeOriginatedFacts, type EntityOriginStructuredSection } from "./entity-origin-fields.js";
 import {
   checkEntityRecallAbort,
   entityRecallSectionAbsent,
@@ -106,7 +103,7 @@ function uniqueStrings(values: string[]): string[] {
 function compactLine(value: string, maxLength: number = 220): string {
   const normalized = value.replace(/\s+/g, " ").trim();
   if (normalized.length <= maxLength) return normalized;
-  return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+  return `${truncateGraphemeSafe(normalized, maxLength - 1).trimEnd()}…`;
 }
 function dedupeHintSnippetsByText(snippets: EntityHintSnippet[]): EntityHintSnippet[] {
   const deduped = new Map<string, EntityHintSnippet>();
@@ -1052,7 +1049,7 @@ function formatEntityHintSection(
 
   let result = lines.join("\n");
   if (result.length > maxChars) {
-    result = `${result.slice(0, Math.max(0, maxChars - 15)).trimEnd()}\n\n...(trimmed)\n`;
+    result = `${truncateGraphemeSafe(result, Math.max(0, maxChars - 15)).trimEnd()}\n\n...(trimmed)\n`;
   }
   return result.trim().length > 0 ? result.trimEnd() : null;
 }

package/src/harmonic-construction.test.ts

@@ -1,10 +1,11 @@
 import assert from "node:assert/strict";
 import { spawn } from "node:child_process";
-import { appendFile, mkdir, mkdtemp, open, readFile, rm, stat, unlink, utimes, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, mkdtemp, open, readdir, readFile, rm, stat, unlink, utimes, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 import {
+  HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY,
   getAbstractionNodeStoreStatus,
   upsertAbstractionNode,
   upsertAbstractionNodes,
@@ -26,12 +27,14 @@ import {
   deriveHarmonicRecords,
   normalizeCueAnchorInputs,
 } from "./harmonic-construction.js";
-import { searchHarmonicRetrieval } from "./harmonic-retrieval.js";
+import { searchHarmonicRetrieval, type HarmonicRetrievalResult } from "./harmonic-retrieval.js";
 import { readJsonFile, withJsonStoreMutationLock } from "./json-store.js";
 import {
   filterHarmonicEntityMentions,
   persistConstructedHarmonicRecords,
 } from "./orchestration/harmonic-construction-persist.js";
+import { compareDeterministicStrings } from "./deterministic-order.js";
+import { stripAttributesSuffix } from "./structured-attributes.js";
 import { Orchestrator } from "./orchestrator.js";
 import { ExtractedFactSchema, ExtractionResultSchema } from "./schemas.js";
 import type { ExtractionResult, MemoryFile } from "./types.js";
@@ -1259,6 +1262,188 @@ test("harmonic anchors stay scoped to projected active sources in a mixed episod
   }
 });
 
+async function persistRecencyFixture(memoryDir: string): Promise<{
+  storageDir: string;
+  persistedIds: string[];
+  contentById: Map<string, string>;
+}> {
+  const config = parseConfig({
+    openaiApiKey: "sk-test",
+    memoryDir,
+    workspaceDir: path.join(memoryDir, "workspace"),
+    qmdEnabled: false,
+    embeddingFallbackEnabled: false,
+    chunkingEnabled: false,
+    harmonicRetrievalEnabled: true,
+    abstractionAnchorsEnabled: false,
+  });
+  const orchestrator = new Orchestrator(config) as unknown as PersistenceHarness;
+  const storage = await orchestrator.getStorage("default");
+  await storage.ensureDirectories();
+  const contents = [
+    "Atlas fact zero of the oldest insertion pair.",
+    "Atlas fact one of the oldest insertion pair.",
+    "Atlas fact two at the middle insertion time.",
+    "Atlas fact three of the newest insertion pair.",
+    "Atlas fact four of the newest insertion pair.",
+  ];
+  const { persistedIds } = await orchestrator.persistExtraction(
+    {
+      facts: contents.map((content) => ({
+        category: "fact",
+        content,
+        confidence: 0.99,
+        tags: ["atlas"],
+        entityRef: "atlas-project",
+        cueAnchors: [],
+      })),
+      entities: [{ name: "atlas-project", type: "company", facts: [] }],
+      profileUpdates: [],
+      questions: [],
+      relationships: [],
+      episodeTitle: "Atlas insertion ordering",
+    },
+    storage,
+    null,
+    { sessionKey: "session:harmonic-recency" }
+  );
+  const expectedContents = new Set(contents);
+  const contentById = new Map<string, string>();
+  const factIds: string[] = [];
+  for (const persistedId of persistedIds) {
+    const memory = await storage.getMemoryById(persistedId);
+    if (!memory) continue;
+    const content = memory.frontmatter.structuredAttributes
+      ? stripAttributesSuffix(memory.content)
+      : memory.content;
+    if (!expectedContents.has(content)) continue;
+    factIds.push(persistedId);
+    contentById.set(persistedId, content);
+  }
+  assert.equal(factIds.length, 5, `expected the five fact memories, got ${persistedIds.length} persisted`);
+  return { storageDir: storage.dir, persistedIds: factIds, contentById };
+}
+
+async function rewriteTopicInsertedAt(
+  storageDir: string,
+  insertedAtById: Record<string, string> | null,
+  recordedAt?: string
+): Promise<void> {
+  const nodesDir = path.join(storageDir, "state", "abstraction-nodes", "nodes");
+  for (const dayEntry of await readdir(nodesDir, { withFileTypes: true })) {
+    if (!dayEntry.isDirectory()) continue;
+    for (const entryName of await readdir(path.join(nodesDir, dayEntry.name))) {
+      if (!entryName.endsWith(".json")) continue;
+      const filePath = path.join(nodesDir, dayEntry.name, entryName);
+      const node = JSON.parse(await readFile(filePath, "utf8")) as Record<string, unknown>;
+      if (node.kind !== "topic") continue;
+      const metadata = { ...(node.metadata as Record<string, string>) };
+      if (insertedAtById === null) {
+        delete metadata[HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY];
+      } else {
+        metadata[HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY] = JSON.stringify(insertedAtById);
+      }
+      await writeFile(
+        filePath,
+        `${JSON.stringify({ ...node, metadata, ...(recordedAt ? { recordedAt } : {}) }, null, 2)}\n`
+      );
+    }
+  }
+}
+
+async function findProjectedTopic(
+  storageDir: string
+): Promise<HarmonicRetrievalResult | undefined> {
+  const results = await searchHarmonicRetrieval({
+    memoryDir: storageDir,
+    query: "atlas",
+    maxResults: 5,
+    anchorsEnabled: false,
+  });
+  return results.find((result) => result.node.kind === "topic");
+}
+
+test("harmonic projection orders sources newest-first with deterministic tiebreak", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-harmonic-recency-"));
+  try {
+    const { storageDir, persistedIds, contentById } = await persistRecencyFixture(memoryDir);
+    const ascendingIds = [...persistedIds].sort(compareDeterministicStrings);
+    const [first, second, third, fourth, fifth] = ascendingIds.map((memoryId) => memoryId);
+    assert.ok(first && second && third && fourth && fifth);
+    const oldest = "2026-01-01T00:00:00.000Z";
+    const middle = "2026-02-01T00:00:00.000Z";
+    const newest = "2026-03-01T00:00:00.000Z";
+    const insertedAtByRank = [oldest, oldest, middle, newest, newest];
+    await rewriteTopicInsertedAt(
+      storageDir,
+      Object.fromEntries(ascendingIds.map((memoryId, index) => [memoryId, insertedAtByRank[index]]))
+    );
+
+    const topic = await findProjectedTopic(storageDir);
+    assert.ok(topic, "topic node must stay retrievable");
+    assert.deepEqual(topic.node.sourceMemoryIds, [fourth, fifth, third, first, second]);
+    assert.equal(topic.node.title, contentById.get(fourth));
+    assert.equal(
+      topic.node.summary,
+      [fourth, fifth, third].map((memoryId) => contentById.get(memoryId)).join("; ")
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("harmonic projection keeps ascending id order for equal or missing insertion timestamps", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-harmonic-recency-equal-"));
+  try {
+    const { storageDir, persistedIds, contentById } = await persistRecencyFixture(memoryDir);
+    const ascendingIds = [...persistedIds].sort(compareDeterministicStrings);
+    const [first, second, third, fourth, fifth] = ascendingIds.map((memoryId) => memoryId);
+    assert.ok(first && second && third && fourth && fifth);
+    const expectedSummary = [first, second, third]
+      .map((memoryId) => contentById.get(memoryId))
+      .join("; ");
+
+    await rewriteTopicInsertedAt(
+      storageDir,
+      Object.fromEntries(ascendingIds.map((memoryId) => [memoryId, "2026-01-01T00:00:00.000Z"]))
+    );
+    let topic = await findProjectedTopic(storageDir);
+    assert.ok(topic);
+    assert.deepEqual(topic.node.sourceMemoryIds, ascendingIds);
+    assert.equal(topic.node.title, contentById.get(first));
+    assert.equal(topic.node.summary, expectedSummary);
+
+    await rewriteTopicInsertedAt(storageDir, null);
+    topic = await findProjectedTopic(storageDir);
+    assert.ok(topic);
+    assert.deepEqual(topic.node.sourceMemoryIds, ascendingIds);
+    assert.equal(topic.node.title, contentById.get(first));
+    assert.equal(topic.node.summary, expectedSummary);
+
+    await rewriteTopicInsertedAt(
+      storageDir,
+      {
+        [first]: "not-a-timestamp",
+        [second]: "2026-01-01T00:00:00.000Z",
+        [third]: "2026-02-01T00:00:00.000Z",
+        [fourth]: "definitely not a date",
+        [fifth]: "2026-03-01T00:00:00.000Z",
+      },
+      "2026-06-01T00:00:00.000Z"
+    );
+    topic = await findProjectedTopic(storageDir);
+    assert.ok(topic);
+    assert.deepEqual(topic.node.sourceMemoryIds, [first, fourth, fifth, third, second]);
+    assert.equal(topic.node.title, contentById.get(first));
+    assert.equal(
+      topic.node.summary,
+      [first, fourth, fifth].map((memoryId) => contentById.get(memoryId)).join("; ")
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
 test("non-default namespace construction ignores the default store override", async () => {
   const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-harmonic-namespace-"));
   try {

package/src/harmonic-retrieval.ts

@@ -13,6 +13,7 @@ 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 { isRecord } from "./store-contract.js";
 import type { MemoryFile } from "./types.js";
 
 type SourceMemoryMap = Map<string, MemoryFile>;
@@ -42,6 +43,22 @@ async function readSourceMemories(options: {
   return sourceMemories;
 }
 
+function parseSourceMemoryInsertedAt(node: AbstractionNode): Map<string, string> {
+  const insertedAtById = new Map<string, string>();
+  const insertedAtRaw = node.metadata?.[HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY];
+  if (!insertedAtRaw) return insertedAtById;
+  try {
+    const parsed = JSON.parse(insertedAtRaw) as unknown;
+    if (!isRecord(parsed)) return insertedAtById;
+    for (const [memoryId, value] of Object.entries(parsed)) {
+      if (typeof value === "string") insertedAtById.set(memoryId, value);
+    }
+  } catch {
+    // Malformed insertion metadata leaves ordering on the recordedAt fallback.
+  }
+  return insertedAtById;
+}
+
 function projectSourceBackedNode(
   node: AbstractionNode,
   sourceMemories: SourceMemoryMap,
@@ -62,6 +79,19 @@ function projectSourceBackedNode(
   });
   if (activeSourceMemoryIds.length === 0) return null;
 
+ // Newest-first source order keeps the projected title and summary on the most
+ // recently inserted facts. Equal or missing timestamps fall back to ascending
+ // id order, which matches the stored sourceMemoryIds order.
+ const insertedAtById = parseSourceMemoryInsertedAt(node);
+ const insertedAtMs = (memoryId: string): number => {
+   const parsedMs = Date.parse(insertedAtById.get(memoryId) ?? "");
+   return Number.isFinite(parsedMs) ? parsedMs : Date.parse(node.recordedAt);
+ };
+ activeSourceMemoryIds.sort(
+   (left, right) =>
+     insertedAtMs(right) - insertedAtMs(left) || compareDeterministicStrings(left, right)
+ );
+
   const activeMemories = activeSourceMemoryIds.flatMap((memoryId) => {
     const memory = sourceMemories.get(memoryId);
     return memory ? [memory] : [];
@@ -69,40 +99,32 @@ function projectSourceBackedNode(
   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;
-    }
+ let metadata: Record<string, string> | undefined;
+ const activeInsertedAt = activeSourceMemoryIds.flatMap((memoryId) => {
+   const value = insertedAtById.get(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)),
+   };
   }
 
-  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,
-  };
+ 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(

package/src/index.ts

@@ -11,6 +11,8 @@
  *
  */
 
+export { collapseWhitespace, displayWidth, graphemeUnits, padEndDisplay, truncateCodePointSafe, truncateGraphemeSafe } from "./whitespace.js";
+
 // ---------------------------------------------------------------------------
 // Plugin entry resolution
 // ---------------------------------------------------------------------------
@@ -1446,10 +1448,7 @@ export {
 
 // Coding-graph engine contract (#1551 PR1), implemented by optional @remnic/coding-graph.
 
-export {
-  CODING_GRAPH_ENGINE_VERSION,
-  TIER_1_LANGUAGES,
-} from "./coding/coding-graph-types.js";
+export { CODING_GRAPH_ENGINE_VERSION, TIER_1_LANGUAGES } from "./coding/coding-graph-types.js";
 
 export type {
   CodingGraphEngine,

package/src/orchestration/recall-section-coordinator.ts

@@ -19,6 +19,7 @@
 
 import type { LastRecallBudgetSummary } from "../recall-state.js";
 import { estimateTokenCount } from "../token-estimate.js";
+import { graphemeUnits, truncateGraphemeSafe } from "../whitespace.js";
 import type { PluginConfig, RecallSectionConfig } from "../types.js";
 
 export interface RecallSectionAppendOptions {
@@ -145,7 +146,7 @@ export class RecallSectionCoordinator {
       finalContent =
         sectionId === "profile"
           ? this.truncateProfileToBoundary(finalContent, maxChars)
-          : `${finalContent.slice(0, maxChars)}\n\n...(trimmed)\n`;
+          : `${truncateGraphemeSafe(finalContent, maxChars)}\n\n...(trimmed)\n`;
     }
     if (finalContent.length === 0) return false;
     const existing = sectionBuckets.get(sectionId) ?? [];
@@ -174,11 +175,16 @@ export class RecallSectionCoordinator {
     const contentLimit = maxChars - suffix.length;
     if (contentLimit <= 0) {
       const boundary = content.lastIndexOf("\n", maxChars);
-      return content.slice(0, boundary > 0 ? boundary : maxChars).trimEnd();
+      const clipped = boundary > 0
+        ? content.slice(0, boundary)
+        : truncateGraphemeSafe(content, maxChars);
+      return clipped.trimEnd();
     }
     const boundary = content.lastIndexOf("\n", contentLimit);
-    const end = boundary > 0 ? boundary : contentLimit;
-    return `${content.slice(0, end).trimEnd()}${suffix}`;
+    const clipped = boundary > 0
+      ? content.slice(0, boundary)
+      : truncateGraphemeSafe(content, contentLimit);
+    return `${clipped.trimEnd()}${suffix}`;
   }
   truncateRecallSectionToBudget(
     content: string,
@@ -191,20 +197,20 @@ export class RecallSectionCoordinator {
       content.length <= maxChars
         ? content
         : maxChars <= suffix.length
-          ? content.slice(0, maxChars)
-          : `${content.slice(0, maxChars - suffix.length)}${suffix}`;
+          ? truncateGraphemeSafe(content, maxChars)
+          : `${truncateGraphemeSafe(content, maxChars - suffix.length)}${suffix}`;
     if (maxTokens === undefined || estimateTokenCount(charBounded) <= maxTokens) {
       return charBounded;
     }
     const markerFits =
       maxChars > suffix.length && estimateTokenCount(suffix) <= maxTokens;
-    const tokenSource = content.length > maxChars ? content.slice(0, maxChars) : content;
-    const codePoints = [...tokenSource];
+    const tokenSource = content.length > maxChars ? truncateGraphemeSafe(content, maxChars) : content;
+    const units = graphemeUnits(tokenSource);
     let low = 0;
-    let high = codePoints.length;
+    let high = units.length;
     while (low < high) {
       const mid = Math.ceil((low + high) / 2);
-      const prefix = codePoints.slice(0, mid).join("");
+      const prefix = units.slice(0, mid).join("");
       const candidate = markerFits ? `${prefix}${suffix}` : prefix;
       if (candidate.length <= maxChars && estimateTokenCount(candidate) <= maxTokens) {
         low = mid;
@@ -214,19 +220,19 @@ export class RecallSectionCoordinator {
     }
     if (markerFits && low === 0) {
       low = 0;
-      high = codePoints.length;
+      high = units.length;
       while (low < high) {
         const mid = Math.ceil((low + high) / 2);
-        const prefix = codePoints.slice(0, mid).join("");
+        const prefix = units.slice(0, mid).join("");
         if (prefix.length <= maxChars && estimateTokenCount(prefix) <= maxTokens) {
           low = mid;
         } else {
           high = mid - 1;
         }
       }
-      return codePoints.slice(0, low).join("");
+      return units.slice(0, low).join("");
     }
-    const prefix = codePoints.slice(0, low).join("");
+    const prefix = units.slice(0, low).join("");
     return markerFits ? `${prefix}${suffix}` : prefix;
   }