@remnic/core 9.26.0 → 9.28.0

package/src/storage/entity-store.ts

@@ -13,6 +13,7 @@
 import { readdir, unlink } from "node:fs/promises";
 import path from "node:path";
 import { normalizeEntityStructuredSection, sortStructuredSectionsBySchema } from "../entity-schema.js";
+import { withEntityCanonicalMutationLock } from "./entity-canonical-id-migration.js";
 import { log } from "../logger.js";
 import { getCachedEntities, setCachedEntities } from "../memory-cache.js";
 import type { VersionTrigger } from "../page-versioning.js";
@@ -78,6 +79,24 @@ export class EntityStore {
     } = {},
   ): Promise<string> {
     await this.deps.ensureDirectories();
+    return withEntityCanonicalMutationLock(
+      path.join(this.deps.baseDir, "state"),
+      () => this.writeEntityUnlocked(name, type, facts, options),
+    );
+  }
+
+  private async writeEntityUnlocked(
+    name: string,
+    type: string,
+    facts: string[],
+    options: {
+      timestamp?: string;
+      source?: string;
+      sessionKey?: string;
+      principal?: string;
+      structuredSections?: EntityStructuredSection[];
+    } = {},
+  ): Promise<string> {
     if (typeof name !== "string" || !name.trim() || typeof type !== "string" || !type.trim()) {
       log.warn("writeEntity: invalid entity payload, skipping", {
         nameType: typeof name,
@@ -238,6 +257,24 @@ export class EntityStore {
       updatedAt?: string;
       incrementVersion?: boolean;
     } = {},
+  ): Promise<void> {
+    return withEntityCanonicalMutationLock(
+      path.join(this.deps.baseDir, "state"),
+      () => this.updateEntitySynthesisUnlocked(name, synthesis, options),
+    );
+  }
+
+  private async updateEntitySynthesisUnlocked(
+    name: string,
+    synthesis: string,
+    options: {
+      entityUpdatedAt?: string;
+      synthesisStructuredFactCount?: number;
+      synthesisStructuredFactDigest?: string;
+      synthesisTimelineCount?: number;
+      updatedAt?: string;
+      incrementVersion?: boolean;
+    } = {},
   ): Promise<void> {
     const filePath = path.join(this.deps.entitiesDir, `${name}.md`);
     let entity: EntityFile;
@@ -407,6 +444,13 @@ export class EntityStore {
    * Returns count of files merged.
    */
   async mergeFragmentedEntities(): Promise<number> {
+    return withEntityCanonicalMutationLock(
+      path.join(this.deps.baseDir, "state"),
+      () => this.mergeFragmentedEntitiesUnlocked(),
+    );
+  }
+
+  private async mergeFragmentedEntitiesUnlocked(): Promise<number> {
     let merged = 0;
     try {
       const entries = await readdir(this.deps.entitiesDir);

package/src/storage/memory-frontmatter-metadata.ts

@@ -0,0 +1,17 @@
+export type RawFrontmatterOwner = object;
+
+const rawFrontmatterByMemory = new WeakMap<RawFrontmatterOwner, string>();
+
+export function extractRawFrontmatter(raw: string): string | null {
+  return raw.match(/^---\n([\s\S]*?)\n---\n?/)?.[1] ?? null;
+}
+
+export function rememberRawFrontmatter<T extends RawFrontmatterOwner>(owner: T, raw: string): T {
+  const frontmatter = extractRawFrontmatter(raw);
+  if (frontmatter !== null) rawFrontmatterByMemory.set(owner, frontmatter);
+  return owner;
+}
+
+export function readRawFrontmatter(owner: RawFrontmatterOwner): string | undefined {
+  return rawFrontmatterByMemory.get(owner);
+}

package/src/storage/memory-migration-serialization.ts

@@ -0,0 +1,37 @@
+import type { MemoryFile, MemoryFrontmatter } from "../types.js";
+import { readRawFrontmatter } from "./memory-frontmatter-metadata.js";
+
+export type MemoryEntityRefSerializer = (memory: MemoryFile, entityRef: string) => string;
+
+export function serializeMemoryWithEntityRef(
+  memory: MemoryFile,
+  entityRef: string,
+  fallback: MemoryEntityRefSerializer,
+): string {
+  const rawFrontmatter = readRawFrontmatter(memory);
+  if (rawFrontmatter === undefined) return fallback(memory, entityRef);
+  const lines = rawFrontmatter.split("\n");
+  let entityRefLine = -1;
+  for (let index = 0; index < lines.length; index += 1) {
+    if (/^\s*entityRef\s*:/.test(lines[index] ?? "")) entityRefLine = index;
+  }
+  if (entityRefLine >= 0) {
+    const indent = lines[entityRefLine]!.match(/^\s*/)?.[0] ?? "";
+    lines[entityRefLine] = `${indent}entityRef: ${entityRef}`;
+  } else {
+    lines.push(`entityRef: ${entityRef}`);
+  }
+  return `---\n${lines.join("\n")}\n---\n\n${memory.content}\n`;
+}
+
+export function createMemoryEntityRefSerializer(
+  serializeFrontmatter: (frontmatter: MemoryFrontmatter) => string,
+): MemoryEntityRefSerializer {
+  return (memory, entityRef) =>
+    serializeMemoryWithEntityRef(
+      memory,
+      entityRef,
+      (fallbackMemory, fallbackEntityRef) =>
+        `${serializeFrontmatter({ ...fallbackMemory.frontmatter, entityRef: fallbackEntityRef })}\n\n${fallbackMemory.content}\n`,
+    );
+}

package/src/storage/memory-read-store.ts

@@ -26,6 +26,7 @@ import {
   parseFrontmatter,
   StorageManager,
 } from "../storage.js";
+import { rememberRawFrontmatter } from "./memory-frontmatter-metadata.js";
 
 export interface MemoryReadStoreDeps {
   /** Live class object of the host instance — shared static caches (see storage.ts storageManagerClass). */
@@ -495,7 +496,7 @@ export class MemoryReadStore {
       // but SecureStoreLockedError must propagate — see re-throw below.
       const parsed = parseFrontmatter(raw);
       if (parsed) {
-        return {
+        return rememberRawFrontmatter({
           path: filePath,
           frontmatter: normalizeFrontmatterForPath(
             parsed.frontmatter,
@@ -503,7 +504,7 @@ export class MemoryReadStore {
             parsed.content,
           ),
           content: parsed.content,
-        };
+        }, raw);
       }
 
       // Entity files use a `# Name` + `**Type:** ...` markdown format rather than