@remnic/core 9.3.753 → 9.3.755

package/dist/{chunk-34THARMH.js → chunk-XBM5DG4O.js}

@@ -1,12 +1,12 @@
+import {
+  WEARABLES_DIR_NAME,
+  isValidTranscriptDate
+} from "./chunk-M7XQSUBB.js";
 import {
   TombstoneStore,
   buildRetiredFactTombstoneInputs,
   collectRetiredMemoriesForRebuild
 } from "./chunk-L2B3EE7B.js";
-import {
-  WEARABLES_DIR_NAME,
-  isValidTranscriptDate
-} from "./chunk-M7XQSUBB.js";
 import {
   isErrnoCode
 } from "./chunk-5UZXUTVO.js";
@@ -28,6 +28,10 @@ import {
   SPECULATIVE_TTL_DAYS,
   confidenceTier
 } from "./chunk-JS2HKKOK.js";
+import {
+  normalizeProjectionPreview,
+  normalizeProjectionTags
+} from "./chunk-SCU65EZI.js";
 import {
   readProjectedGovernanceRecord,
   readProjectedMemoryBrowse,
@@ -45,10 +49,6 @@ import {
   sortMemoryLifecycleEvents,
   toMemoryPathRel
 } from "./chunk-RULE4VG5.js";
-import {
-  normalizeProjectionPreview,
-  normalizeProjectionTags
-} from "./chunk-SCU65EZI.js";
 import {
   rotateMarkdownFileToArchive
 } from "./chunk-DM2T26WE.js";
@@ -64,7 +64,7 @@ import {
 import {
   parseFaithfulnessField,
   serializeFaithfulnessFields
-} from "./chunk-YTU7WKYN.js";
+} from "./chunk-2OZ2JEUP.js";
 import {
   isConsolidationOperator,
   isValidDerivedFromEntry
@@ -112,10 +112,489 @@ import {
 } from "./chunk-VS2IYZRU.js";
 
 // src/storage.ts
-import { access, lstat, readdir, readFile, realpath, stat, writeFile, mkdir, unlink, appendFile, open } from "fs/promises";
-import { appendFileSync, createReadStream, mkdirSync, readFileSync, statSync } from "fs";
-import { createHash } from "crypto";
-import path from "path";
+import { access, lstat, readdir as readdir2, readFile, realpath, stat, writeFile, mkdir, unlink as unlink2, appendFile, open } from "fs/promises";
+import { appendFileSync, createReadStream, mkdirSync, readFileSync, statSync } from "fs";
+import { createHash } from "crypto";
+import path2 from "path";
+
+// src/storage/entity-store.ts
+import { readdir, unlink } from "fs/promises";
+import path from "path";
+var EntityStore = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  /** Normalize an entity name using this store's alias table. */
+  normalizeEntityName(raw, type) {
+    return normalizeEntityName(raw, type, this.deps.userAliases);
+  }
+  async writeEntity(name, type, facts, options = {}) {
+    await this.deps.ensureDirectories();
+    if (typeof name !== "string" || !name.trim() || typeof type !== "string" || !type.trim()) {
+      log.warn("writeEntity: invalid entity payload, skipping", {
+        nameType: typeof name,
+        typeType: typeof type
+      });
+      return "";
+    }
+    const safeFacts = Array.isArray(facts) ? [...new Set(
+      facts.filter((fact) => typeof fact === "string").map((fact) => fact.trim()).filter((fact) => fact.length > 0)
+    )] : [];
+    let normalized = this.deps.normalizeEntityName(name, type);
+    const match = await this.deps.findMatchingEntity(name, type);
+    if (match && match !== normalized) {
+      log.debug(`fuzzy match: "${normalized}" \u2192 existing "${match}"`);
+      normalized = match;
+    }
+    const filePath = path.join(this.deps.entitiesDir, `${normalized}.md`);
+    let entity = {
+      name,
+      type,
+      created: "",
+      updated: (/* @__PURE__ */ new Date()).toISOString(),
+      facts: [],
+      summary: void 0,
+      synthesis: void 0,
+      synthesisUpdatedAt: void 0,
+      synthesisVersion: void 0,
+      synthesisStructuredFactCount: void 0,
+      synthesisStructuredFactDigest: void 0,
+      timeline: [],
+      relationships: [],
+      activity: [],
+      aliases: []
+    };
+    try {
+      const existing = await this.deps.readStorageSecureFile(filePath);
+      entity = parseEntityFile(existing, this.deps.entitySchemas);
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
+      if (!isErrnoCode(err, "ENOENT")) throw err;
+    }
+    const timestamp = options.timestamp?.trim() || (/* @__PURE__ */ new Date()).toISOString();
+    const source = options.source?.trim() || void 0;
+    const sessionKey = options.sessionKey?.trim() || void 0;
+    const principal = options.principal?.trim() || void 0;
+    const structuredSectionMap = new Map(
+      (entity.structuredSections ?? []).map((section) => [section.key, {
+        ...section,
+        facts: [...section.facts]
+      }])
+    );
+    for (const section of options.structuredSections ?? []) {
+      const normalizedSection = normalizeEntityStructuredSection(type, section, this.deps.entitySchemas);
+      const normalizedFacts = normalizeStructuredSectionFacts(section.facts);
+      if (normalizedFacts.length === 0) continue;
+      const existingSection = structuredSectionMap.get(normalizedSection.key);
+      if (!existingSection) {
+        structuredSectionMap.set(normalizedSection.key, {
+          key: normalizedSection.key,
+          title: normalizedSection.title,
+          facts: normalizedFacts
+        });
+        continue;
+      }
+      existingSection.facts = normalizeStructuredSectionFacts([...existingSection.facts, ...normalizedFacts]);
+      if (!existingSection.title.trim() && normalizedSection.title.trim()) {
+        existingSection.title = normalizedSection.title;
+      }
+    }
+    for (const fact of safeFacts) {
+      const nextEntry = {
+        timestamp,
+        text: fact,
+        ...source ? { source } : {},
+        ...sessionKey ? { sessionKey } : {},
+        ...principal ? { principal } : {}
+      };
+      const alreadyPresent = entity.timeline.some(
+        (entry) => entry.timestamp === nextEntry.timestamp && entry.text === nextEntry.text && entry.source === nextEntry.source && entry.sessionKey === nextEntry.sessionKey && entry.principal === nextEntry.principal
+      );
+      if (alreadyPresent) continue;
+      entity.timeline.push(nextEntry);
+    }
+    entity.structuredSections = sortStructuredSectionsBySchema(
+      type,
+      Array.from(structuredSectionMap.values()).filter((section) => section.facts.length > 0),
+      this.deps.entitySchemas
+    );
+    entity.facts = compileEntityFacts(entity.timeline, entity.structuredSections);
+    entity.summary = entity.synthesis || entity.summary;
+    entity.name = name;
+    entity.type = type;
+    entity.created = entity.created || timestamp;
+    entity.updated = (/* @__PURE__ */ new Date()).toISOString();
+    await this.deps.snapshotBeforeWrite(filePath, "write");
+    await this.deps.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.deps.entitySchemas));
+    this.deps.invalidateKnowledgeIndexCache();
+    this.deps.bumpMemoryStatusVersion();
+    log.debug(`wrote entity ${normalized}`);
+    return normalized;
+  }
+  async readEntity(name) {
+    const filePath = this.deps.resolveEntityFilePath(name);
+    if (filePath === null) {
+      return "";
+    }
+    try {
+      return await this.deps.readStorageSecureFile(filePath);
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
+      if (!isErrnoCode(err, "ENOENT")) throw err;
+      return "";
+    }
+  }
+  /** Return sorted list of entity filenames (without .md extension) */
+  async listEntityNames() {
+    try {
+      const entries = await readdir(this.deps.entitiesDir);
+      return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", "")).sort();
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Set or rewrite the synthesis layer of an entity file.
+   */
+  async updateEntitySynthesis(name, synthesis, options = {}) {
+    const filePath = path.join(this.deps.entitiesDir, `${name}.md`);
+    let entity;
+    try {
+      const content = await this.deps.readStorageSecureFile(filePath);
+      entity = parseEntityFile(content, this.deps.entitySchemas);
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
+      if (!isErrnoCode(err, "ENOENT")) throw err;
+      log.debug(`updateEntitySynthesis: entity file ${name}.md not found`);
+      return;
+    }
+    const updatedAt = options.updatedAt?.trim() || entity.synthesisUpdatedAt?.trim() || void 0;
+    const entityUpdatedAt = options.entityUpdatedAt?.trim() || updatedAt || entity.updated || (/* @__PURE__ */ new Date()).toISOString();
+    const synthesisTimelineCount = Number.isInteger(options.synthesisTimelineCount) && (options.synthesisTimelineCount ?? 0) >= 0 ? options.synthesisTimelineCount : void 0;
+    const synthesisStructuredFactCount = Number.isInteger(options.synthesisStructuredFactCount) && (options.synthesisStructuredFactCount ?? 0) >= 0 ? options.synthesisStructuredFactCount : countEntityStructuredFacts(entity);
+    const synthesisStructuredFactDigest = options.synthesisStructuredFactDigest?.trim() || fingerprintEntityStructuredFacts(entity);
+    entity.synthesis = synthesis.trim();
+    entity.summary = entity.synthesis;
+    entity.synthesisUpdatedAt = updatedAt;
+    entity.synthesisTimelineCount = synthesisTimelineCount;
+    entity.synthesisStructuredFactCount = synthesisStructuredFactCount;
+    entity.synthesisStructuredFactDigest = synthesisStructuredFactDigest;
+    entity.synthesisVersion = Math.max(0, entity.synthesisVersion ?? 0) + (options.incrementVersion === false ? 0 : 1);
+    entity.updated = entityUpdatedAt;
+    await this.deps.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.deps.entitySchemas));
+    await this.deps.removeEntitySynthesisQueueEntries([
+      .../* @__PURE__ */ new Set([name, this.deps.normalizeEntityName(entity.name, entity.type)])
+    ]);
+    this.deps.invalidateKnowledgeIndexCache();
+    this.deps.bumpMemoryStatusVersion();
+  }
+  /**
+   * Read all entity files and return lightweight EntityFile objects.
+   * Parsing is fast (~50-100ms for ~1,800 files) since entity files are small.
+   */
+  async readAllEntityFiles() {
+    const currentVersion = this.deps.getMemoryStatusVersion();
+    const schemaCacheKey = buildEntitySchemaCacheKey(this.deps.entitySchemas);
+    const cacheKey = `${this.deps.getEntityCacheSecureStoreKey()}\0${schemaCacheKey}`;
+    const cached = getCachedEntities(this.deps.baseDir, currentVersion, cacheKey);
+    if (cached) return cached;
+    try {
+      const entries = await readdir(this.deps.entitiesDir);
+      const mdFiles = entries.filter((e) => e.endsWith(".md"));
+      if (mdFiles.length === 0) return [];
+      const BATCH_SIZE = 100;
+      const entities = [];
+      for (let i = 0; i < mdFiles.length; i += BATCH_SIZE) {
+        const batch = mdFiles.slice(i, i + BATCH_SIZE);
+        const results = await Promise.all(
+          batch.map(async (entry) => {
+            try {
+              return await this.deps.readStorageSecureFile(path.join(this.deps.entitiesDir, entry));
+            } catch (err) {
+              if (err instanceof SecureStoreLockedError) throw err;
+              if (!isErrnoCode(err, "ENOENT")) throw err;
+              return null;
+            }
+          })
+        );
+        for (const content of results) {
+          if (content !== null) entities.push(parseEntityFile(content, this.deps.entitySchemas));
+        }
+      }
+      setCachedEntities(this.deps.baseDir, entities, currentVersion, cacheKey);
+      return entities;
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError || !isErrnoCode(err, "ENOENT")) throw err;
+      return [];
+    }
+  }
+  /**
+   * Build the Knowledge Index: a compact markdown table of top-scored entities.
+   * Respects maxEntities and maxChars limits from config.
+   */
+  async buildKnowledgeIndex(config, overrides) {
+    const useDefaultLimits = overrides?.maxEntities === void 0 && overrides?.maxChars === void 0;
+    if (useDefaultLimits && this.deps.knowledgeIndexCache && Date.now() - this.deps.knowledgeIndexCache.builtAt < StorageManager.KNOWLEDGE_INDEX_CACHE_TTL_MS) {
+      return { result: this.deps.knowledgeIndexCache.result, cached: true };
+    }
+    const entities = await this.deps.readAllEntityFiles();
+    if (entities.length === 0) {
+      if (useDefaultLimits) this.deps.knowledgeIndexCache = { result: "", builtAt: Date.now() };
+      return { result: "", cached: false };
+    }
+    const now = /* @__PURE__ */ new Date();
+    const scored = entities.map((e) => ({
+      name: e.name,
+      type: e.type,
+      score: StorageManager.scoreEntity(e, now),
+      factCount: e.facts.length,
+      summary: e.synthesis ?? e.summary,
+      topRelationships: e.relationships.slice(0, 3).map((r) => r.target)
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    const maxEntities = typeof overrides?.maxEntities === "number" ? Math.max(0, Math.floor(overrides.maxEntities)) : config.knowledgeIndexMaxEntities;
+    const topN = scored.slice(0, maxEntities);
+    if (topN.length === 0) {
+      if (useDefaultLimits) this.deps.knowledgeIndexCache = { result: "", builtAt: Date.now() };
+      return { result: "", cached: false };
+    }
+    const header = "## Knowledge Index\n\n| Entity | Type | Summary | Connected to |\n|--------|------|---------|-------------|";
+    const rows = [];
+    let totalChars = header.length;
+    const maxChars = typeof overrides?.maxChars === "number" ? Math.max(0, Math.floor(overrides.maxChars)) : config.knowledgeIndexMaxChars;
+    for (const entity of topN) {
+      const summary = entity.summary || `${entity.factCount} facts`;
+      const connected = entity.topRelationships.length > 0 ? entity.topRelationships.join(", ") : "\u2014";
+      const row = `| ${entity.name} | ${entity.type} | ${summary} | ${connected} |`;
+      if (totalChars + row.length + 1 > maxChars) break;
+      rows.push(row);
+      totalChars += row.length + 1;
+    }
+    const result = rows.length === 0 ? "" : `${header}
+${rows.join("\n")}
+`;
+    if (useDefaultLimits) this.deps.knowledgeIndexCache = { result, builtAt: Date.now() };
+    return { result, cached: false };
+  }
+  /**
+   * Merge fragmented entity files that resolve to the same canonical name.
+   * Preserves relationships, activity, aliases, and summary from all fragments.
+   * Returns count of files merged.
+   */
+  async mergeFragmentedEntities() {
+    let merged = 0;
+    try {
+      const entries = await readdir(this.deps.entitiesDir);
+      const mdFiles = entries.filter((e) => e.endsWith(".md"));
+      const groups = /* @__PURE__ */ new Map();
+      for (const file of mdFiles) {
+        const baseName = file.replace(".md", "");
+        const dashIdx = baseName.indexOf("-");
+        if (dashIdx === -1) continue;
+        const type = baseName.slice(0, dashIdx);
+        const restOfName = baseName.slice(dashIdx + 1);
+        const canonical = this.deps.normalizeEntityName(restOfName, type);
+        if (!groups.has(canonical)) groups.set(canonical, []);
+        groups.get(canonical).push(file);
+      }
+      for (const [canonical, files] of groups) {
+        if (files.length <= 1) continue;
+        const mergedEntity = {
+          name: "",
+          type: "other",
+          created: "",
+          updated: "",
+          extraFrontmatterLines: [],
+          preSectionLines: [],
+          facts: [],
+          summary: void 0,
+          synthesis: void 0,
+          synthesisUpdatedAt: void 0,
+          synthesisTimelineCount: void 0,
+          synthesisStructuredFactCount: void 0,
+          synthesisStructuredFactDigest: void 0,
+          synthesisVersion: void 0,
+          timeline: [],
+          relationships: [],
+          activity: [],
+          aliases: [],
+          structuredSections: [],
+          extraSections: []
+        };
+        for (const file of files) {
+          const filePath = path.join(this.deps.entitiesDir, file);
+          try {
+            const content = await this.deps.readStorageSecureFile(filePath);
+            const parsed = parseEntityFile(content, this.deps.entitySchemas);
+            if (!mergedEntity.type || mergedEntity.type === "other") {
+              mergedEntity.type = parsed.type;
+            }
+            if (!mergedEntity.updated || compareEntityTimestamps(parsed.updated, mergedEntity.updated) > 0) {
+              mergedEntity.updated = parsed.updated;
+            }
+            const parsedCreated = parsed.created || parsed.updated;
+            const mergedCreated = mergedEntity.created?.trim() || "";
+            const parsedCreatedMs = parsedCreated ? Date.parse(parsedCreated) : Number.NaN;
+            const mergedCreatedMs = mergedCreated ? Date.parse(mergedCreated) : Number.NaN;
+            const parsedCreatedIsValid = Number.isFinite(parsedCreatedMs);
+            const mergedCreatedIsValid = Number.isFinite(mergedCreatedMs);
+            if (parsedCreated && (!mergedCreated || parsedCreatedIsValid && !mergedCreatedIsValid || parsedCreatedIsValid && mergedCreatedIsValid && parsedCreatedMs < mergedCreatedMs || !parsedCreatedIsValid && !mergedCreatedIsValid && compareEntityTimestamps(parsedCreated, mergedCreated) < 0)) {
+              mergedEntity.created = parsedCreated;
+            }
+            if (parsed.name.length > mergedEntity.name.length) {
+              mergedEntity.name = parsed.name;
+            }
+            const parsedSynthesisUpdatedAt = parsed.synthesisUpdatedAt?.trim() || void 0;
+            const mergedSynthesisUpdatedAt = mergedEntity.synthesisUpdatedAt?.trim() || void 0;
+            if (parsed.synthesis && (!mergedEntity.synthesis || !mergedSynthesisUpdatedAt && Boolean(parsedSynthesisUpdatedAt) || Boolean(mergedSynthesisUpdatedAt) && Boolean(parsedSynthesisUpdatedAt) && compareEntityTimestamps(parsedSynthesisUpdatedAt, mergedSynthesisUpdatedAt) > 0)) {
+              mergedEntity.synthesis = parsed.synthesis;
+              mergedEntity.summary = parsed.synthesis;
+              mergedEntity.synthesisUpdatedAt = parsedSynthesisUpdatedAt;
+              mergedEntity.synthesisTimelineCount = parsed.synthesisTimelineCount;
+              mergedEntity.synthesisStructuredFactCount = parsed.synthesisStructuredFactCount;
+              mergedEntity.synthesisStructuredFactDigest = parsed.synthesisStructuredFactDigest;
+              mergedEntity.synthesisVersion = parsed.synthesisVersion;
+            } else if (!mergedEntity.summary && parsed.summary) {
+              mergedEntity.summary = parsed.summary;
+              mergedEntity.synthesis = parsed.summary;
+              mergedEntity.synthesisUpdatedAt = parsedSynthesisUpdatedAt;
+              mergedEntity.synthesisTimelineCount = parsed.synthesisTimelineCount;
+              mergedEntity.synthesisStructuredFactCount = parsed.synthesisStructuredFactCount;
+              mergedEntity.synthesisStructuredFactDigest = parsed.synthesisStructuredFactDigest;
+              mergedEntity.synthesisVersion = parsed.synthesisVersion;
+            }
+            mergedEntity.timeline.push(...parsed.timeline);
+            mergedEntity.relationships.push(...parsed.relationships);
+            mergedEntity.activity.push(...parsed.activity);
+            mergedEntity.aliases.push(...parsed.aliases);
+            const mergedStructuredSectionMap = new Map(
+              (mergedEntity.structuredSections ?? []).map((section) => [section.key, {
+                ...section,
+                facts: [...section.facts]
+              }])
+            );
+            for (const section of parsed.structuredSections ?? []) {
+              const existingSection = mergedStructuredSectionMap.get(section.key);
+              if (!existingSection) {
+                mergedStructuredSectionMap.set(section.key, {
+                  key: section.key,
+                  title: section.title,
+                  facts: [...new Set(section.facts.map((fact) => fact.trim()).filter((fact) => fact.length > 0))]
+                });
+                continue;
+              }
+              const mergedFacts = new Set(existingSection.facts.map((fact) => fact.trim()));
+              for (const fact of section.facts) {
+                const trimmed = fact.trim();
+                if (!trimmed) continue;
+                mergedFacts.add(trimmed);
+              }
+              existingSection.facts = Array.from(mergedFacts);
+              if (!existingSection.title.trim() && section.title.trim()) {
+                existingSection.title = section.title;
+              }
+            }
+            mergedEntity.structuredSections = Array.from(mergedStructuredSectionMap.values());
+            mergedEntity.extraFrontmatterLines.push(...parsed.extraFrontmatterLines ?? []);
+            mergedEntity.preSectionLines.push(...parsed.preSectionLines ?? []);
+            mergedEntity.extraSections.push(...(parsed.extraSections ?? []).map((section) => ({
+              title: section.title,
+              lines: [...section.lines]
+            })));
+          } catch (err) {
+            if (err instanceof SecureStoreLockedError) throw err;
+            if (!isErrnoCode(err, "ENOENT")) throw err;
+          }
+        }
+        const timelineKeys = /* @__PURE__ */ new Set();
+        mergedEntity.timeline = mergedEntity.timeline.filter((entry) => {
+          const key = JSON.stringify([
+            entry.timestamp,
+            entry.source ?? "",
+            entry.sessionKey ?? "",
+            entry.principal ?? "",
+            entry.text
+          ]);
+          if (timelineKeys.has(key)) return false;
+          timelineKeys.add(key);
+          return true;
+        });
+        const relKeys = /* @__PURE__ */ new Set();
+        mergedEntity.relationships = mergedEntity.relationships.filter((r) => {
+          const key = `${r.target}::${r.label}`;
+          if (relKeys.has(key)) return false;
+          relKeys.add(key);
+          return true;
+        });
+        const actKeys = /* @__PURE__ */ new Set();
+        mergedEntity.activity = mergedEntity.activity.filter((a) => {
+          const key = `${a.date}::${a.note}`;
+          if (actKeys.has(key)) return false;
+          actKeys.add(key);
+          return true;
+        }).sort((a, b) => b.date.localeCompare(a.date));
+        mergedEntity.aliases = [...new Set(mergedEntity.aliases)];
+        mergedEntity.structuredSections = sortStructuredSectionsBySchema(
+          mergedEntity.type,
+          mergedEntity.structuredSections ?? [],
+          this.deps.entitySchemas
+        );
+        mergedEntity.facts = compileEntityFacts(mergedEntity.timeline, mergedEntity.structuredSections);
+        const extraSectionKeys = /* @__PURE__ */ new Set();
+        mergedEntity.extraSections = (mergedEntity.extraSections ?? []).filter((section) => {
+          const key = `${section.title}::${section.lines.join("\n")}`;
+          if (extraSectionKeys.has(key)) return false;
+          extraSectionKeys.add(key);
+          return true;
+        });
+        if (!mergedEntity.name) {
+          const dashIdx = canonical.indexOf("-");
+          mergedEntity.name = dashIdx !== -1 ? canonical.slice(dashIdx + 1) : canonical;
+        }
+        mergedEntity.created = mergedEntity.created || mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
+        mergedEntity.updated = mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
+        const canonicalPath = path.join(this.deps.entitiesDir, `${canonical}.md`);
+        await this.deps.writeStorageSecureFile(canonicalPath, serializeEntityFile(mergedEntity, this.deps.entitySchemas));
+        for (const file of files) {
+          const filePath = path.join(this.deps.entitiesDir, file);
+          if (filePath !== canonicalPath) {
+            try {
+              await unlink(filePath);
+              merged++;
+              log.debug(`merged entity ${file} \u2192 ${canonical}.md`);
+            } catch {
+            }
+          }
+        }
+      }
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError || !isErrnoCode(err, "ENOENT")) throw err;
+    }
+    return merged;
+  }
+};
+
+// src/orchestration/self-deps.ts
+function selfDeps(self) {
+  const source = self;
+  return new Proxy(/* @__PURE__ */ Object.create(null), {
+    get(_target, prop) {
+      const value = source[prop];
+      return typeof value === "function" ? value.bind(self) : value;
+    },
+    set(_target, prop, value) {
+      if (!(prop in source)) return false;
+      source[prop] = value;
+      return true;
+    },
+    has(_target, prop) {
+      return prop in source;
+    }
+  });
+}
+
+// src/storage.ts
 var ARTIFACT_SEARCH_STOPWORDS = /* @__PURE__ */ new Set([
   "a",
   "an",
@@ -720,17 +1199,17 @@ var KNOWN_ENTITY_FILENAME_PREFIXES = /* @__PURE__ */ new Set([
   "topic"
 ]);
 function inferEntityTypeFromFilename(pathRel) {
-  const basename = path.basename(pathRel, ".md").toLowerCase();
+  const basename = path2.basename(pathRel, ".md").toLowerCase();
   const separator = basename.indexOf("-");
   if (separator <= 0) return void 0;
   const candidate = basename.slice(0, separator);
   return KNOWN_ENTITY_FILENAME_PREFIXES.has(candidate) ? candidate : void 0;
 }
 function normalizeFrontmatterForPath(frontmatter, pathRel, content = "") {
-  const normalizedPath = pathRel.split(path.sep).join("/");
+  const normalizedPath = pathRel.split(path2.sep).join("/");
   let normalizedFrontmatter = frontmatter;
   if (normalizedPath === "entities" || normalizedPath.startsWith("entities/") || normalizedPath.includes("/entities/")) {
-    const basename = path.basename(pathRel, ".md");
+    const basename = path2.basename(pathRel, ".md");
     const inferredType = inferEntityTypeFromContent(content) || inferEntityTypeFromFilename(pathRel) || "entity";
     const existingTags = Array.isArray(frontmatter.tags) ? frontmatter.tags : [];
     normalizedFrontmatter = {
@@ -797,8 +1276,8 @@ var ContentHashIndex = class _ContentHashIndex {
   secureStoreKeyProvider;
   secureStoreWriteKeyProvider;
   memoryDir;
-  constructor(stateDir, secureStoreKeyProvider = () => null, secureStoreWriteKeyProvider = secureStoreKeyProvider, memoryDir = path.dirname(stateDir)) {
-    this.filePath = path.join(stateDir, "fact-hashes.txt");
+  constructor(stateDir, secureStoreKeyProvider = () => null, secureStoreWriteKeyProvider = secureStoreKeyProvider, memoryDir = path2.dirname(stateDir)) {
+    this.filePath = path2.join(stateDir, "fact-hashes.txt");
     this.secureStoreKeyProvider = secureStoreKeyProvider;
     this.secureStoreWriteKeyProvider = secureStoreWriteKeyProvider;
     this.memoryDir = memoryDir;
@@ -845,7 +1324,7 @@ var ContentHashIndex = class _ContentHashIndex {
   /** Persist index to disk if changed. */
   async save() {
     if (!this.dirty) return;
-    await mkdir(path.dirname(this.filePath), { recursive: true });
+    await mkdir(path2.dirname(this.filePath), { recursive: true });
     await writeMaybeEncryptedFile(
       this.filePath,
       [...this.hashes].join("\n") + "\n",
@@ -1708,9 +2187,10 @@ var StorageManager = class _StorageManager {
   baseDir;
   entitySchemas;
   knowledgeIndexCache = null;
+  artifactIndexCache = null;
+  /** Read by storage/entity-store.ts (decomposition), hence not `private`. */
   static KNOWLEDGE_INDEX_CACHE_TTL_MS = 6e5;
   // 10 minutes (entity mutations invalidate)
-  artifactIndexCache = null;
   static ARTIFACT_INDEX_CACHE_TTL_MS = 6e4;
   // 1 minute
   static artifactWriteVersionByDir = /* @__PURE__ */ new Map();
@@ -1905,7 +2385,7 @@ var StorageManager = class _StorageManager {
         void 0,
         this.baseDir
       );
-      const rel = path.relative(this.baseDir, filePath).split(path.sep).join("/");
+      const rel = path2.relative(this.baseDir, filePath).split(path2.sep).join("/");
       return `${rel}:${version.versionId}`;
     } catch (err) {
       log.warn(
@@ -1915,18 +2395,28 @@ var StorageManager = class _StorageManager {
     }
   }
   /** The root directory of this storage instance. */
+  /** EntityStore (storage.ts decomposition). Lazy; selfDeps live wiring. */
+  _entityStore;
+  get entityStore() {
+    if (!this._entityStore) {
+      this._entityStore = new EntityStore(
+        selfDeps(this)
+      );
+    }
+    return this._entityStore;
+  }
   get dir() {
     return this.baseDir;
   }
   identityFilePath(workspaceDir, namespace) {
     const rawNamespace = typeof namespace === "string" ? namespace.trim() : "";
-    if (!rawNamespace) return path.join(workspaceDir, "IDENTITY.md");
+    if (!rawNamespace) return path2.join(workspaceDir, "IDENTITY.md");
     const safeNamespace = rawNamespace.replace(/[^a-zA-Z0-9._-]/g, "-");
-    return path.join(workspaceDir, `IDENTITY.${safeNamespace}.md`);
+    return path2.join(workspaceDir, `IDENTITY.${safeNamespace}.md`);
   }
   versionFilePath(kind) {
     const fileName = kind === "memory-status" ? ".memory-status-version.log" : kind === "artifact-write" ? ".artifact-write-version.log" : ".cold-write-version.log";
-    return path.join(this.stateDir, fileName);
+    return path2.join(this.stateDir, fileName);
   }
   bumpSharedVersion(kind, fallbackMap) {
     const filePath = this.versionFilePath(kind);
@@ -1973,7 +2463,7 @@ var StorageManager = class _StorageManager {
   // memories.
   // -------------------------------------------------------------------------
   get wearablesDir() {
-    return path.join(this.baseDir, WEARABLES_DIR_NAME);
+    return path2.join(this.baseDir, WEARABLES_DIR_NAME);
   }
   /**
    * Resolve the on-disk path for a source/day transcript. Throws on
@@ -1991,7 +2481,7 @@ var StorageManager = class _StorageManager {
         `invalid wearable transcript date '${String(date)}' \u2014 expected YYYY-MM-DD`
       );
     }
-    return path.join(this.wearablesDir, sourceId, `${date}.md`);
+    return path2.join(this.wearablesDir, sourceId, `${date}.md`);
   }
   async writeWearableDayTranscript(sourceId, date, serialized) {
     const targetPath = this.wearableTranscriptPath(sourceId, date);
@@ -2018,7 +2508,7 @@ var StorageManager = class _StorageManager {
       sources = [sourceId];
     } else {
       try {
-        const entries = await readdir(this.wearablesDir, { withFileTypes: true });
+        const entries = await readdir2(this.wearablesDir, { withFileTypes: true });
         sources = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
       } catch (err) {
         if (err.code === "ENOENT") return [];
@@ -2029,7 +2519,7 @@ var StorageManager = class _StorageManager {
       if (!/^[a-z][a-z0-9-]{0,63}$/.test(source)) continue;
       let entries;
       try {
-        entries = await readdir(path.join(this.wearablesDir, source));
+        entries = await readdir2(path2.join(this.wearablesDir, source));
       } catch (err) {
         if (err.code === "ENOENT") continue;
         throw err;
@@ -2116,25 +2606,25 @@ var StorageManager = class _StorageManager {
     });
   }
   get factsDir() {
-    return path.join(this.baseDir, "facts");
+    return path2.join(this.baseDir, "facts");
   }
   get correctionsDir() {
-    return path.join(this.baseDir, "corrections");
+    return path2.join(this.baseDir, "corrections");
   }
   get proceduresDir() {
-    return path.join(this.baseDir, "procedures");
+    return path2.join(this.baseDir, "procedures");
   }
   get reasoningTracesDir() {
-    return path.join(this.baseDir, "reasoning-traces");
+    return path2.join(this.baseDir, "reasoning-traces");
   }
   get entitiesDir() {
-    return path.join(this.baseDir, "entities");
+    return path2.join(this.baseDir, "entities");
   }
   resolveEntityFilePath(name) {
     if (typeof name !== "string") return null;
-    const filePath = path.resolve(this.entitiesDir, `${name}.md`);
-    const relative = path.relative(this.entitiesDir, filePath);
-    if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) {
+    const filePath = path2.resolve(this.entitiesDir, `${name}.md`);
+    const relative = path2.relative(this.entitiesDir, filePath);
+    if (relative === "" || relative.startsWith("..") || path2.isAbsolute(relative)) {
       return null;
     }
     return filePath;
@@ -2149,10 +2639,10 @@ var StorageManager = class _StorageManager {
     return writeMaybeEncryptedFileFromChunks(filePath, chunks, this.resolveWriteKey(), {}, this.baseDir).then(() => this.notifyCatalogWrite());
   }
   assertManagedStoragePath(filePath, method) {
-    const resolved = path.resolve(filePath);
-    const base = path.resolve(this.baseDir);
-    const rel = path.relative(base, resolved);
-    if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+    const resolved = path2.resolve(filePath);
+    const base = path2.resolve(this.baseDir);
+    const rel = path2.relative(base, resolved);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${path2.sep}`) || path2.isAbsolute(rel)) {
       throw new Error(`${method}: file path escapes memory dir`);
     }
     return resolved;
@@ -2164,7 +2654,7 @@ var StorageManager = class _StorageManager {
   async digestOfflineSyncFile(filePath) {
     const target = this.assertManagedStoragePath(filePath, "storage.digestOfflineSyncFile");
     const st = await stat(target);
-    const relPath = path.relative(this.baseDir, target).split(path.sep).join("/");
+    const relPath = path2.relative(this.baseDir, target).split(path2.sep).join("/");
     const cache = await this.loadOfflineSyncDigestCache();
     const cached = cache.get(relPath);
     if (cached && cached.statBytes === st.size && cached.mtimeMs === st.mtimeMs && cached.ctimeMs === st.ctimeMs && !cached.encrypted) {
@@ -2225,7 +2715,7 @@ var StorageManager = class _StorageManager {
         const bytes = typeof record.bytes === "number" ? record.bytes : NaN;
         const sha256 = typeof record.sha256 === "string" ? record.sha256 : "";
         const encrypted = record.encrypted === true;
-        if (cachePath.length === 0 || cachePath === ".." || cachePath.startsWith("../") || path.isAbsolute(cachePath) || !Number.isFinite(statBytes) || !Number.isFinite(mtimeMs) || !Number.isFinite(ctimeMs) || !Number.isFinite(bytes) || !/^[a-f0-9]{64}$/i.test(sha256)) {
+        if (cachePath.length === 0 || cachePath === ".." || cachePath.startsWith("../") || path2.isAbsolute(cachePath) || !Number.isFinite(statBytes) || !Number.isFinite(mtimeMs) || !Number.isFinite(ctimeMs) || !Number.isFinite(bytes) || !/^[a-f0-9]{64}$/i.test(sha256)) {
           continue;
         }
         cache.set(cachePath, { statBytes, mtimeMs, ctimeMs, encrypted, sha256, bytes });
@@ -2267,7 +2757,7 @@ var StorageManager = class _StorageManager {
       const cache = this.offlineSyncDigestCache;
       if (!cache) return;
       const entries = [...cache.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([entryPath, entry]) => ({ path: entryPath, ...entry }));
-      await mkdir(path.dirname(this.offlineSyncDigestCachePath), { recursive: true });
+      await mkdir(path2.dirname(this.offlineSyncDigestCachePath), { recursive: true });
       await writeFile(
         this.offlineSyncDigestCachePath,
         `${JSON.stringify({ version: 1, entries })}
@@ -2306,7 +2796,7 @@ var StorageManager = class _StorageManager {
   }
   async deleteOfflineSyncFile(filePath) {
     const target = this.assertManagedStoragePath(filePath, "storage.deleteOfflineSyncFile");
-    await unlink(target).catch((error) => {
+    await unlink2(target).catch((error) => {
       if (isErrnoCode(error, "ENOENT")) return;
       throw error;
     });
@@ -2316,14 +2806,14 @@ var StorageManager = class _StorageManager {
     this.invalidateAllMemoriesCache();
     this.invalidateKnowledgeIndexCache();
     this.factHashIndexAuthoritative = false;
-    await unlink(this.factHashIndexReadyPath).catch((error) => {
+    await unlink2(this.factHashIndexReadyPath).catch((error) => {
       if (isErrnoCode(error, "ENOENT")) return;
       throw error;
     });
-    if (filePath.includes(`${path.sep}cold${path.sep}`)) {
+    if (filePath.includes(`${path2.sep}cold${path2.sep}`)) {
       this.invalidateColdMemoriesCache();
     }
-    if (filePath.includes(`${path.sep}artifacts${path.sep}`)) {
+    if (filePath.includes(`${path2.sep}artifacts${path2.sep}`)) {
       this.bumpArtifactWriteVersion();
     }
     this.bumpMemoryStatusVersion();
@@ -2351,7 +2841,7 @@ var StorageManager = class _StorageManager {
   }
   async appendStorageSecureFileUnlocked(filePath, content) {
     const writeKey = this.resolveWriteKey();
-    await mkdir(path.dirname(filePath), { recursive: true });
+    await mkdir(path2.dirname(filePath), { recursive: true });
     if (writeKey === null) {
       try {
         if (isEncryptedFile(await readFile(filePath))) {
@@ -2377,16 +2867,16 @@ var StorageManager = class _StorageManager {
     this.notifyCatalogWrite();
   }
   get stateDir() {
-    return path.join(this.baseDir, "state");
+    return path2.join(this.baseDir, "state");
   }
   get offlineSyncDigestCachePath() {
-    return path.join(this.baseDir, ".offline-sync", "digest-cache.v1.json");
+    return path2.join(this.baseDir, ".offline-sync", "digest-cache.v1.json");
   }
   get entitySynthesisQueuePath() {
-    return path.join(this.stateDir, "entity-synthesis-queue.json");
+    return path2.join(this.stateDir, "entity-synthesis-queue.json");
   }
   get factHashIndexReadyPath() {
-    return path.join(this.stateDir, "fact-hashes.ready");
+    return path2.join(this.stateDir, "fact-hashes.ready");
   }
   // ── Tombstone store access (issue #1579) ─────────────────────────────────
   /**
@@ -2396,7 +2886,7 @@ var StorageManager = class _StorageManager {
    * helpers are injected into the store).
    */
   get tombstonesPath() {
-    return path.join(this.stateDir, "tombstones.jsonl");
+    return path2.join(this.stateDir, "tombstones.jsonl");
   }
   /**
    * Configure the tombstone invariant for this storage instance. Installed
@@ -2595,7 +3085,7 @@ var StorageManager = class _StorageManager {
         );
       }
       await factHashIndex.save();
-      await mkdir(path.dirname(this.factHashIndexReadyPath), { recursive: true });
+      await mkdir(path2.dirname(this.factHashIndexReadyPath), { recursive: true });
       await writeFile(this.factHashIndexReadyPath, "v1\n", "utf-8");
       this.factHashIndexAuthoritative = true;
     })().finally(() => {
@@ -2604,55 +3094,55 @@ var StorageManager = class _StorageManager {
     await this.factHashIndexAuthoritativePromise;
   }
   get questionsDir() {
-    return path.join(this.baseDir, "questions");
+    return path2.join(this.baseDir, "questions");
   }
   get artifactsDir() {
-    return path.join(this.baseDir, "artifacts");
+    return path2.join(this.baseDir, "artifacts");
   }
   get identityDir() {
-    return path.join(this.baseDir, "identity");
+    return path2.join(this.baseDir, "identity");
   }
   get identityAnchorPath() {
-    return path.join(this.identityDir, "identity-anchor.md");
+    return path2.join(this.identityDir, "identity-anchor.md");
   }
   get identityIncidentsDir() {
-    return path.join(this.identityDir, "incidents");
+    return path2.join(this.identityDir, "incidents");
   }
   get identityAuditsWeeklyDir() {
-    return path.join(this.identityDir, "audits", "weekly");
+    return path2.join(this.identityDir, "audits", "weekly");
   }
   get identityAuditsMonthlyDir() {
-    return path.join(this.identityDir, "audits", "monthly");
+    return path2.join(this.identityDir, "audits", "monthly");
   }
   get identityImprovementLoopsPath() {
-    return path.join(this.identityDir, "improvement-loops.md");
+    return path2.join(this.identityDir, "improvement-loops.md");
   }
   get identityReflectionsPath() {
-    return path.join(this.identityDir, "reflections.md");
+    return path2.join(this.identityDir, "reflections.md");
   }
   get profilePath() {
-    return path.join(this.baseDir, "profile.md");
+    return path2.join(this.baseDir, "profile.md");
   }
   get memoryActionsPath() {
-    return path.join(this.stateDir, "memory-actions.jsonl");
+    return path2.join(this.stateDir, "memory-actions.jsonl");
   }
   get memoryLifecycleLedgerPath() {
-    return path.join(this.stateDir, "memory-lifecycle-ledger.jsonl");
+    return path2.join(this.stateDir, "memory-lifecycle-ledger.jsonl");
   }
   get compressionGuidelinesPath() {
-    return path.join(this.stateDir, "compression-guidelines.md");
+    return path2.join(this.stateDir, "compression-guidelines.md");
   }
   get compressionGuidelineDraftPath() {
-    return path.join(this.stateDir, "compression-guidelines.draft.md");
+    return path2.join(this.stateDir, "compression-guidelines.draft.md");
   }
   get compressionGuidelineStatePath() {
-    return path.join(this.stateDir, "compression-guideline-state.json");
+    return path2.join(this.stateDir, "compression-guideline-state.json");
   }
   get compressionGuidelineDraftStatePath() {
-    return path.join(this.stateDir, "compression-guideline-draft-state.json");
+    return path2.join(this.stateDir, "compression-guideline-draft-state.json");
   }
   get behaviorSignalsPath() {
-    return path.join(this.stateDir, "behavior-signals.jsonl");
+    return path2.join(this.stateDir, "behavior-signals.jsonl");
   }
   /**
    * Buffer surprise telemetry ledger (issue #563 PR 3).
@@ -2665,7 +3155,7 @@ var StorageManager = class _StorageManager {
    * governance sweeps can treat it uniformly.
    */
   get bufferSurpriseLedgerPath() {
-    return path.join(this.stateDir, "buffer-surprise-ledger.jsonl");
+    return path2.join(this.stateDir, "buffer-surprise-ledger.jsonl");
   }
   /**
    * Entity alias table loaded from THIS store's config/aliases.json.
@@ -2675,9 +3165,11 @@ var StorageManager = class _StorageManager {
    * store loaded last rewrite every other store's canonical entity ids.
    */
   userAliases = {};
-  /** Normalize an entity name using this store's alias table. */
   normalizeEntityName(raw, type) {
-    return normalizeEntityName(raw, type, this.userAliases);
+    return this.entityStore.normalizeEntityName(
+      raw,
+      type
+    );
   }
   /**
    * Read-only view of this store's user alias table, for call sites that
@@ -2697,7 +3189,7 @@ var StorageManager = class _StorageManager {
     this.loadAliasesSync();
   }
   loadAliasesSync() {
-    const aliasPath = path.join(this.baseDir, "config", "aliases.json");
+    const aliasPath = path2.join(this.baseDir, "config", "aliases.json");
     this.userAliases = {};
     try {
       const raw = readFileSync(aliasPath, "utf-8");
@@ -2722,9 +3214,9 @@ var StorageManager = class _StorageManager {
   }
   async ensureDirectories() {
     const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-    await mkdir(path.join(this.factsDir, today), { recursive: true });
-    await mkdir(path.join(this.proceduresDir, today), { recursive: true });
-    await mkdir(path.join(this.reasoningTracesDir, today), { recursive: true });
+    await mkdir(path2.join(this.factsDir, today), { recursive: true });
+    await mkdir(path2.join(this.proceduresDir, today), { recursive: true });
+    await mkdir(path2.join(this.reasoningTracesDir, today), { recursive: true });
     await mkdir(this.correctionsDir, { recursive: true });
     await mkdir(this.entitiesDir, { recursive: true });
     await mkdir(this.stateDir, { recursive: true });
@@ -2734,7 +3226,7 @@ var StorageManager = class _StorageManager {
     await mkdir(this.identityIncidentsDir, { recursive: true });
     await mkdir(this.identityAuditsWeeklyDir, { recursive: true });
     await mkdir(this.identityAuditsMonthlyDir, { recursive: true });
-    await mkdir(path.join(this.baseDir, "config"), { recursive: true });
+    await mkdir(path2.join(this.baseDir, "config"), { recursive: true });
   }
   /**
    * Resolve the on-disk write path for a memory of the given category, creating
@@ -2751,11 +3243,11 @@ var StorageManager = class _StorageManager {
   async resolveCategoryWritePath(category, id, today) {
     if (category === "correction") {
       await mkdir(this.correctionsDir, { recursive: true });
-      return path.join(this.correctionsDir, `${id}.md`);
+      return path2.join(this.correctionsDir, `${id}.md`);
     }
-    const datedDir = path.join(getCategoryDir(this.baseDir, category), today);
+    const datedDir = path2.join(getCategoryDir(this.baseDir, category), today);
     await mkdir(datedDir, { recursive: true });
-    return path.join(datedDir, `${id}.md`);
+    return path2.join(datedDir, `${id}.md`);
   }
   async writeMemory(category, content, options = {}) {
     await this.ensureDirectories();
@@ -3005,7 +3497,7 @@ ${sanitized.text}
     await this.ensureDirectories();
     const now = /* @__PURE__ */ new Date();
     const day = now.toISOString().slice(0, 10);
-    const dir = path.join(this.artifactsDir, day);
+    const dir = path2.join(this.artifactsDir, day);
     await mkdir(dir, { recursive: true });
     const id = `artifact-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
     const fm = {
@@ -3029,7 +3521,7 @@ ${sanitized.text}
       log.warn(`artifact content rejected for ${id}; violations=${sanitized.violations.join(", ")}`);
       return "";
     }
-    const filePath = path.join(dir, `${id}.md`);
+    const filePath = path2.join(dir, `${id}.md`);
     await this.writeStorageSecureFile(filePath, `${serializeFrontmatter(fm)}
 
 ${sanitized.text}
@@ -3055,9 +3547,9 @@ ${sanitized.text}
       const artifacts = [];
       const readDir = async (dir) => {
         try {
-          const entries = await readdir(dir, { withFileTypes: true });
+          const entries = await readdir2(dir, { withFileTypes: true });
           for (const entry of entries) {
-            const fullPath = path.join(dir, entry.name);
+            const fullPath = path2.join(dir, entry.name);
             if (entry.isDirectory()) {
               await readDir(fullPath);
               continue;
@@ -3106,107 +3598,12 @@ ${sanitized.text}
     return hits.slice(0, maxResults).map((h) => h.memory);
   }
   async writeEntity(name, type, facts, options = {}) {
-    await this.ensureDirectories();
-    if (typeof name !== "string" || !name.trim() || typeof type !== "string" || !type.trim()) {
-      log.warn("writeEntity: invalid entity payload, skipping", {
-        nameType: typeof name,
-        typeType: typeof type
-      });
-      return "";
-    }
-    const safeFacts = Array.isArray(facts) ? [...new Set(
-      facts.filter((fact) => typeof fact === "string").map((fact) => fact.trim()).filter((fact) => fact.length > 0)
-    )] : [];
-    let normalized = this.normalizeEntityName(name, type);
-    const match = await this.findMatchingEntity(name, type);
-    if (match && match !== normalized) {
-      log.debug(`fuzzy match: "${normalized}" \u2192 existing "${match}"`);
-      normalized = match;
-    }
-    const filePath = path.join(this.entitiesDir, `${normalized}.md`);
-    let entity = {
+    return this.entityStore.writeEntity(
       name,
       type,
-      created: "",
-      updated: (/* @__PURE__ */ new Date()).toISOString(),
-      facts: [],
-      summary: void 0,
-      synthesis: void 0,
-      synthesisUpdatedAt: void 0,
-      synthesisVersion: void 0,
-      synthesisStructuredFactCount: void 0,
-      synthesisStructuredFactDigest: void 0,
-      timeline: [],
-      relationships: [],
-      activity: [],
-      aliases: []
-    };
-    try {
-      const existing = await this.readStorageSecureFile(filePath);
-      entity = parseEntityFile(existing, this.entitySchemas);
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      if (!isErrnoCode(err, "ENOENT")) throw err;
-    }
-    const timestamp = options.timestamp?.trim() || (/* @__PURE__ */ new Date()).toISOString();
-    const source = options.source?.trim() || void 0;
-    const sessionKey = options.sessionKey?.trim() || void 0;
-    const principal = options.principal?.trim() || void 0;
-    const structuredSectionMap = new Map(
-      (entity.structuredSections ?? []).map((section) => [section.key, {
-        ...section,
-        facts: [...section.facts]
-      }])
-    );
-    for (const section of options.structuredSections ?? []) {
-      const normalizedSection = normalizeEntityStructuredSection(type, section, this.entitySchemas);
-      const normalizedFacts = normalizeStructuredSectionFacts(section.facts);
-      if (normalizedFacts.length === 0) continue;
-      const existingSection = structuredSectionMap.get(normalizedSection.key);
-      if (!existingSection) {
-        structuredSectionMap.set(normalizedSection.key, {
-          key: normalizedSection.key,
-          title: normalizedSection.title,
-          facts: normalizedFacts
-        });
-        continue;
-      }
-      existingSection.facts = normalizeStructuredSectionFacts([...existingSection.facts, ...normalizedFacts]);
-      if (!existingSection.title.trim() && normalizedSection.title.trim()) {
-        existingSection.title = normalizedSection.title;
-      }
-    }
-    for (const fact of safeFacts) {
-      const nextEntry = {
-        timestamp,
-        text: fact,
-        ...source ? { source } : {},
-        ...sessionKey ? { sessionKey } : {},
-        ...principal ? { principal } : {}
-      };
-      const alreadyPresent = entity.timeline.some(
-        (entry) => entry.timestamp === nextEntry.timestamp && entry.text === nextEntry.text && entry.source === nextEntry.source && entry.sessionKey === nextEntry.sessionKey && entry.principal === nextEntry.principal
-      );
-      if (alreadyPresent) continue;
-      entity.timeline.push(nextEntry);
-    }
-    entity.structuredSections = sortStructuredSectionsBySchema(
-      type,
-      Array.from(structuredSectionMap.values()).filter((section) => section.facts.length > 0),
-      this.entitySchemas
+      facts,
+      options
     );
-    entity.facts = compileEntityFacts(entity.timeline, entity.structuredSections);
-    entity.summary = entity.synthesis || entity.summary;
-    entity.name = name;
-    entity.type = type;
-    entity.created = entity.created || timestamp;
-    entity.updated = (/* @__PURE__ */ new Date()).toISOString();
-    await this.snapshotBeforeWrite(filePath, "write");
-    await this.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.entitySchemas));
-    this.invalidateKnowledgeIndexCache();
-    this.bumpMemoryStatusVersion();
-    log.debug(`wrote entity ${normalized}`);
-    return normalized;
   }
   async readProfile() {
     try {
@@ -3364,7 +3761,7 @@ ${sanitized.text}
    * per-process in-memory cache safe across process boundaries.
    */
   invalidateColdMemoriesCache() {
-    const coldRoot = path.join(this.baseDir, "cold");
+    const coldRoot = path2.join(this.baseDir, "cold");
     _StorageManager.coldMemoriesCache.delete(coldRoot);
     this.bumpColdWriteVersion();
     invalidateAllForDir(this.baseDir);
@@ -3400,14 +3797,14 @@ ${sanitized.text}
         const dirStat = await lstat(dir);
         if (dirStat.isSymbolicLink() || !dirStat.isDirectory()) return;
         assertPathInsideRoot(memoryRootReal, await realpath(dir), dir);
-        entries = await readdir(dir, { withFileTypes: true });
+        entries = await readdir2(dir, { withFileTypes: true });
       } catch {
         return;
       }
       const subdirs = [];
       for (const entry of entries) {
         if (entry.isSymbolicLink()) continue;
-        const fullPath = path.join(dir, entry.name);
+        const fullPath = path2.join(dir, entry.name);
         if (entry.isDirectory()) {
           subdirs.push(fullPath);
         } else if (entry.name.endsWith(".md")) {
@@ -3423,7 +3820,7 @@ ${sanitized.text}
       }
     };
     for (const dir of RECALL_FALLBACK_DIRS) {
-      await collectPaths(path.join(this.baseDir, dir));
+      await collectPaths(path2.join(this.baseDir, dir));
     }
     return filePaths;
   }
@@ -3492,7 +3889,7 @@ ${sanitized.text}
     const correctionPaths = [];
     const factPaths = [];
     for (const filePath of filePaths) {
-      if (filePath === this.correctionsDir || filePath.startsWith(`${this.correctionsDir}${path.sep}`)) {
+      if (filePath === this.correctionsDir || filePath.startsWith(`${this.correctionsDir}${path2.sep}`)) {
         correctionPaths.push(filePath);
       } else {
         factPaths.push(filePath);
@@ -3610,10 +4007,10 @@ ${sanitized.text}
     const filePaths = [];
     const collectPaths = async (dir) => {
       try {
-        const entries = await readdir(dir, { withFileTypes: true });
+        const entries = await readdir2(dir, { withFileTypes: true });
         const subdirs = [];
         for (const entry of entries) {
-          const fullPath = path.join(dir, entry.name);
+          const fullPath = path2.join(dir, entry.name);
           if (entry.isDirectory()) {
             subdirs.push(fullPath);
           } else if (entry.name.endsWith(".md")) {
@@ -3640,9 +4037,9 @@ ${sanitized.text}
     const root = this.archiveDir;
     const readDir = async (dir) => {
       try {
-        const entries = await readdir(dir, { withFileTypes: true });
+        const entries = await readdir2(dir, { withFileTypes: true });
         for (const entry of entries) {
-          const fullPath = path.join(dir, entry.name);
+          const fullPath = path2.join(dir, entry.name);
           if (entry.isDirectory()) {
             await readDir(fullPath);
           } else if (entry.name.endsWith(".md")) {
@@ -3687,11 +4084,11 @@ ${sanitized.text}
           content: parsed.content
         };
       }
-      const normalizedPath = filePath.split(path.sep).join("/");
+      const normalizedPath = filePath.split(path2.sep).join("/");
       if (normalizedPath.includes("/entities/") && filePath.endsWith(".md")) {
         const entity = parseEntityFile(raw, this.entitySchemas);
         if (!entity.name) return null;
-        const nameWithoutExt = path.basename(filePath, ".md");
+        const nameWithoutExt = path2.basename(filePath, ".md");
         const fileMtime = entity.updated || await stat(filePath).then((s) => s.mtime.toISOString()).catch(() => (/* @__PURE__ */ new Date(0)).toISOString());
         return {
           path: filePath,
@@ -3715,7 +4112,7 @@ ${sanitized.text}
     }
   }
   resolveTierRootDir(tier) {
-    return tier === "cold" ? path.join(this.baseDir, "cold") : this.baseDir;
+    return tier === "cold" ? path2.join(this.baseDir, "cold") : this.baseDir;
   }
   resolveMemoryDateDir(memory) {
     const preferred = memory.frontmatter.created || memory.frontmatter.updated;
@@ -3730,13 +4127,13 @@ ${sanitized.text}
   buildTierMemoryPath(memory, tier) {
     const root = this.resolveTierRootDir(tier);
     if (this.isArtifactMemory(memory)) {
-      return path.join(root, "artifacts", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
+      return path2.join(root, "artifacts", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
     }
     if (memory.frontmatter.category === "correction") {
-      return path.join(root, "corrections", `${memory.frontmatter.id}.md`);
+      return path2.join(root, "corrections", `${memory.frontmatter.id}.md`);
     }
     const dir = categoryDirName(memory.frontmatter.category);
-    return path.join(root, dir, this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
+    return path2.join(root, dir, this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
   }
   async writeMemoryFileAtomic(targetPath, memory) {
     const fileContent = `${serializeFrontmatter(memory.frontmatter)}
@@ -3749,11 +4146,11 @@ ${memory.content}
   }
   async moveMemoryToPath(memory, targetPath) {
     await this.writeMemoryFileAtomic(targetPath, memory);
-    const sourcePath = path.resolve(memory.path);
-    const destPath = path.resolve(targetPath);
+    const sourcePath = path2.resolve(memory.path);
+    const destPath = path2.resolve(targetPath);
     if (sourcePath !== destPath) {
       try {
-        await unlink(memory.path);
+        await unlink2(memory.path);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (!message.includes("ENOENT")) {
@@ -3765,15 +4162,15 @@ ${memory.content}
   }
   async migrateMemoryToTier(memory, targetTier) {
     const targetPath = this.buildTierMemoryPath(memory, targetTier);
-    const sourcePath = path.resolve(memory.path);
-    const destPath = path.resolve(targetPath);
+    const sourcePath = path2.resolve(memory.path);
+    const destPath = path2.resolve(targetPath);
     if (sourcePath === destPath) {
       return { changed: false, targetPath };
     }
     const existing = await this.readMemoryByPath(targetPath);
     if (existing?.frontmatter.id === memory.frontmatter.id) {
       try {
-        await unlink(memory.path);
+        await unlink2(memory.path);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (!message.includes("ENOENT")) {
@@ -3792,7 +4189,7 @@ ${memory.content}
     return { changed: true, targetPath };
   }
   get archiveDir() {
-    return path.join(this.baseDir, "archive");
+    return path2.join(this.baseDir, "archive");
   }
   /**
    * Archive a memory by moving it from facts/ to archive/YYYY-MM-DD/.
@@ -3803,7 +4200,7 @@ ${memory.content}
     try {
       const now = lifecycle?.at ?? /* @__PURE__ */ new Date();
       const today = now.toISOString().slice(0, 10);
-      const destDir = path.join(this.archiveDir, today);
+      const destDir = path2.join(this.archiveDir, today);
       await mkdir(destDir, { recursive: true });
       const updatedFm = {
         ...memory.frontmatter,
@@ -3815,9 +4212,9 @@ ${memory.content}
 
 ${memory.content}
 `;
-      const destPath = path.join(destDir, path.basename(memory.path));
+      const destPath = path2.join(destDir, path2.basename(memory.path));
       await this.writeStorageSecureFile(destPath, fileContent);
-      await unlink(memory.path);
+      await unlink2(memory.path);
       this.invalidateAllMemoriesCache();
       await this.appendGeneratedMemoryLifecycleEventFailOpen(
         "storage.archiveMemory",
@@ -3844,33 +4241,19 @@ ${memory.content}
   }
   async readEntities() {
     try {
-      const entries = await readdir(this.entitiesDir);
+      const entries = await readdir2(this.entitiesDir);
       return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", ""));
     } catch {
       return [];
     }
   }
   async readEntity(name) {
-    const filePath = this.resolveEntityFilePath(name);
-    if (filePath === null) {
-      return "";
-    }
-    try {
-      return await this.readStorageSecureFile(filePath);
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      if (!isErrnoCode(err, "ENOENT")) throw err;
-      return "";
-    }
+    return this.entityStore.readEntity(
+      name
+    );
   }
-  /** Return sorted list of entity filenames (without .md extension) */
   async listEntityNames() {
-    try {
-      const entries = await readdir(this.entitiesDir);
-      return entries.filter((e) => e.endsWith(".md")).map((e) => e.replace(".md", "")).sort();
-    } catch {
-      return [];
-    }
+    return this.entityStore.listEntityNames();
   }
   /**
    * Find an existing entity that fuzzy-matches the proposed name.
@@ -3912,7 +4295,7 @@ ${memory.content}
     const memory = memories.find((m) => m.frontmatter.id === id);
     if (!memory) return false;
     try {
-      await unlink(memory.path);
+      await unlink2(memory.path);
       this.invalidateAllMemoriesCache();
       this.bumpMemoryStatusVersion();
       log.debug(`invalidated memory ${id}`);
@@ -3977,7 +4360,7 @@ ${memory.content}
 `;
     await this.writeStorageSecureFile(memory.path, fileContent);
     this.invalidateAllMemoriesCache();
-    if (memory.path.includes(`${path.sep}cold${path.sep}`)) {
+    if (memory.path.includes(`${path2.sep}cold${path2.sep}`)) {
       this.invalidateColdMemoriesCache();
     }
     try {
@@ -4035,7 +4418,7 @@ ${memory.content}
       const expiresAt = new Date(m.frontmatter.expiresAt).getTime();
       if (expiresAt < now) {
         try {
-          await unlink(m.path);
+          await unlink2(m.path);
           deleted.push(m);
           log.debug(`cleaned expired memory ${m.frontmatter.id} (TTL expired)`);
         } catch {
@@ -4049,7 +4432,7 @@ ${memory.content}
     return deleted;
   }
   async loadBuffer() {
-    const bufferPath = path.join(this.stateDir, "buffer.json");
+    const bufferPath = path2.join(this.stateDir, "buffer.json");
     try {
       const raw = await this.readStorageSecureFile(bufferPath);
       return JSON.parse(raw);
@@ -4061,11 +4444,11 @@ ${memory.content}
   }
   async saveBuffer(state) {
     await this.ensureDirectories();
-    const bufferPath = path.join(this.stateDir, "buffer.json");
+    const bufferPath = path2.join(this.stateDir, "buffer.json");
     await this.writeStorageSecureFile(bufferPath, JSON.stringify(state, null, 2));
   }
   async loadMeta() {
-    const metaPath = path.join(this.stateDir, "meta.json");
+    const metaPath = path2.join(this.stateDir, "meta.json");
     try {
       const raw = await this.readStorageSecureFile(metaPath);
       const parsed = JSON.parse(raw);
@@ -4099,7 +4482,7 @@ ${memory.content}
   }
   async saveMeta(state) {
     await this.ensureDirectories();
-    const metaPath = path.join(this.stateDir, "meta.json");
+    const metaPath = path2.join(this.stateDir, "meta.json");
     await this.writeStorageSecureFile(metaPath, JSON.stringify(state, null, 2));
   }
   async appendMemoryActionEvents(events) {
@@ -4269,7 +4652,7 @@ ${memory.content}
   async appendReextractJobs(events) {
     if (events.length === 0) return 0;
     await this.ensureDirectories();
-    const filePath = path.join(this.stateDir, "reextract-jobs.jsonl");
+    const filePath = path2.join(this.stateDir, "reextract-jobs.jsonl");
     const lines = events.map((event) => JSON.stringify(event)).join("\n") + "\n";
     try {
       await this.appendStorageSecureFile(filePath, lines);
@@ -4282,7 +4665,7 @@ ${memory.content}
   }
   async readReextractJobs(limit = 200) {
     const safeLimit = Number.isFinite(limit) ? Math.max(1, Math.min(1e3, Math.floor(limit))) : 200;
-    const filePath = path.join(this.stateDir, "reextract-jobs.jsonl");
+    const filePath = path2.join(this.stateDir, "reextract-jobs.jsonl");
     try {
       const raw = await this.readStorageSecureFile(filePath);
       const lines = raw.split("\n").filter((line) => line.trim().length > 0);
@@ -4463,8 +4846,8 @@ ${memory.content}
       activationState: "active"
     });
     await Promise.all([
-      unlink(this.compressionGuidelineDraftPath).catch(() => void 0),
-      unlink(this.compressionGuidelineDraftStatePath).catch(() => void 0)
+      unlink2(this.compressionGuidelineDraftPath).catch(() => void 0),
+      unlink2(this.compressionGuidelineDraftStatePath).catch(() => void 0)
     ]);
     return true;
   }
@@ -4536,7 +4919,7 @@ ${memory.content}
     const date = nowIso.slice(0, 10);
     const id = this.generateId("incident");
     const incident = createContinuityIncidentRecord(id, input, nowIso);
-    const filePath = path.join(this.identityIncidentsDir, `${date}-${id}.md`);
+    const filePath = path2.join(this.identityIncidentsDir, `${date}-${id}.md`);
     await this.writeStorageSecureFile(filePath, serializeContinuityIncident(incident));
     return { ...incident, filePath };
   }
@@ -4549,7 +4932,7 @@ ${memory.content}
       const incidents = [];
       for (const file of candidates) {
         if (incidents.length >= cappedLimit) break;
-        const filePath = path.join(this.identityIncidentsDir, file);
+        const filePath = path2.join(this.identityIncidentsDir, file);
         try {
           const raw = await this.readStorageSecureFile(filePath);
           const parsed = parseContinuityIncident(raw);
@@ -4580,7 +4963,7 @@ ${memory.content}
     await this.ensureDirectories();
     const safeKey = this.sanitizeIdentityAuditKey(key);
     const dir = period === "weekly" ? this.identityAuditsWeeklyDir : this.identityAuditsMonthlyDir;
-    const filePath = path.join(dir, `${safeKey}.md`);
+    const filePath = path2.join(dir, `${safeKey}.md`);
     await this.writeStorageSecureFile(filePath, content);
     return filePath;
   }
@@ -4588,7 +4971,7 @@ ${memory.content}
     try {
       const safeKey = this.sanitizeIdentityAuditKey(key);
       const dir = period === "weekly" ? this.identityAuditsWeeklyDir : this.identityAuditsMonthlyDir;
-      return await this.readStorageSecureFile(path.join(dir, `${safeKey}.md`));
+      return await this.readStorageSecureFile(path2.join(dir, `${safeKey}.md`));
     } catch (err) {
       if (err instanceof Error && err.message === "Invalid identity audit key") return null;
       if (!isErrnoCode(err, "ENOENT")) throw err;
@@ -4635,7 +5018,7 @@ ${memory.content}
     return `${prefix}-${ts}-${rand}`;
   }
   async readContinuityIncidentFileNames() {
-    const files = await readdir(this.identityIncidentsDir);
+    const files = await readdir2(this.identityIncidentsDir);
     return files.filter((file) => file.endsWith(".md")).sort().reverse();
   }
   async readContinuityIncidentFile(filePath) {
@@ -4652,12 +5035,12 @@ ${memory.content}
     const fileNames = await this.readContinuityIncidentFileNames();
     const directMatch = fileNames.find((name) => name.endsWith(`-${id}.md`));
     if (directMatch) {
-      const directPath = path.join(this.identityIncidentsDir, directMatch);
+      const directPath = path2.join(this.identityIncidentsDir, directMatch);
       const parsed = await this.readContinuityIncidentFile(directPath);
       if (parsed?.id === id) return directPath;
     }
     for (const fileName of fileNames) {
-      const filePath = path.join(this.identityIncidentsDir, fileName);
+      const filePath = path2.join(this.identityIncidentsDir, fileName);
       const parsed = await this.readContinuityIncidentFile(filePath);
       if (parsed?.id === id) return filePath;
     }
@@ -4687,7 +5070,7 @@ ${question}
 
 **Context:** ${context}
 `;
-    const filePath = path.join(this.questionsDir, `${id}.md`);
+    const filePath = path2.join(this.questionsDir, `${id}.md`);
     await this.writeStorageSecureFile(filePath, content);
     log.debug(`wrote question ${id} to ${filePath}`);
     this.invalidateQuestionsCache();
@@ -4707,11 +5090,11 @@ ${question}
       }
     }
     try {
-      const files = await readdir(this.questionsDir);
+      const files = await readdir2(this.questionsDir);
       const questions = [];
       for (const file of files) {
         if (!file.endsWith(".md")) continue;
-        const filePath = path.join(this.questionsDir, file);
+        const filePath = path2.join(this.questionsDir, file);
         const raw = await readMaybeEncryptedFile(filePath, this._secureStoreKey, this.baseDir);
         const parsed = this.parseQuestionFile(raw, filePath);
         if (parsed) {
@@ -4734,7 +5117,7 @@ ${question}
     if (!match) return null;
     const frontmatterStr = match[1];
     const body = match[2].trim();
-    const id = this.extractFrontmatterValue(frontmatterStr, "id") ?? path.basename(filePath, ".md");
+    const id = this.extractFrontmatterValue(frontmatterStr, "id") ?? path2.basename(filePath, ".md");
     const created = this.extractFrontmatterValue(frontmatterStr, "created") ?? "";
     const priority = parseFloat(
       this.extractFrontmatterValue(frontmatterStr, "priority") ?? "0.5"
@@ -4796,11 +5179,11 @@ ${question}
     } catch {
     }
     const hygiene = opts?.hygiene;
-    const rotateEnabled = hygiene?.enabled === true && hygiene.rotateEnabled === true && Array.isArray(hygiene.rotatePaths) && hygiene.rotatePaths.includes(path.basename(identityPath));
+    const rotateEnabled = hygiene?.enabled === true && hygiene.rotateEnabled === true && Array.isArray(hygiene.rotatePaths) && hygiene.rotatePaths.includes(path2.basename(identityPath));
     if (rotateEnabled) {
       const maxBytes = hygiene.rotateMaxBytes;
       if (existing.length > maxBytes) {
-        const archiveDir = path.join(workspaceDir, hygiene.archiveDir);
+        const archiveDir = path2.join(workspaceDir, hygiene.archiveDir);
         const { newContent } = await rotateMarkdownFileToArchive({
           filePath: identityPath,
           archiveDir,
@@ -4894,7 +5277,7 @@ ${reflection}
    * Deduplicates by target+label.
    */
   async addEntityRelationship(name, rel) {
-    const filePath = path.join(this.entitiesDir, `${name}.md`);
+    const filePath = path2.join(this.entitiesDir, `${name}.md`);
     let entity;
     try {
       const content = await this.readStorageSecureFile(filePath);
@@ -4919,7 +5302,7 @@ ${reflection}
    * Prepends to the beginning, prunes oldest entries beyond maxEntries.
    */
   async addEntityActivity(name, entry, maxEntries) {
-    const filePath = path.join(this.entitiesDir, `${name}.md`);
+    const filePath = path2.join(this.entitiesDir, `${name}.md`);
     let entity;
     try {
       const content = await this.readStorageSecureFile(filePath);
@@ -4942,7 +5325,7 @@ ${reflection}
    * Add an alias to an entity file. Deduplicates.
    */
   async addEntityAlias(name, alias) {
-    const filePath = path.join(this.entitiesDir, `${name}.md`);
+    const filePath = path2.join(this.entitiesDir, `${name}.md`);
     let entity;
     try {
       const content = await this.readStorageSecureFile(filePath);
@@ -4959,40 +5342,12 @@ ${reflection}
     await this.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.entitySchemas));
     this.invalidateKnowledgeIndexCache();
   }
-  /**
-   * Set or rewrite the synthesis layer of an entity file.
-   */
   async updateEntitySynthesis(name, synthesis, options = {}) {
-    const filePath = path.join(this.entitiesDir, `${name}.md`);
-    let entity;
-    try {
-      const content = await this.readStorageSecureFile(filePath);
-      entity = parseEntityFile(content, this.entitySchemas);
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      if (!isErrnoCode(err, "ENOENT")) throw err;
-      log.debug(`updateEntitySynthesis: entity file ${name}.md not found`);
-      return;
-    }
-    const updatedAt = options.updatedAt?.trim() || entity.synthesisUpdatedAt?.trim() || void 0;
-    const entityUpdatedAt = options.entityUpdatedAt?.trim() || updatedAt || entity.updated || (/* @__PURE__ */ new Date()).toISOString();
-    const synthesisTimelineCount = Number.isInteger(options.synthesisTimelineCount) && (options.synthesisTimelineCount ?? 0) >= 0 ? options.synthesisTimelineCount : void 0;
-    const synthesisStructuredFactCount = Number.isInteger(options.synthesisStructuredFactCount) && (options.synthesisStructuredFactCount ?? 0) >= 0 ? options.synthesisStructuredFactCount : countEntityStructuredFacts(entity);
-    const synthesisStructuredFactDigest = options.synthesisStructuredFactDigest?.trim() || fingerprintEntityStructuredFacts(entity);
-    entity.synthesis = synthesis.trim();
-    entity.summary = entity.synthesis;
-    entity.synthesisUpdatedAt = updatedAt;
-    entity.synthesisTimelineCount = synthesisTimelineCount;
-    entity.synthesisStructuredFactCount = synthesisStructuredFactCount;
-    entity.synthesisStructuredFactDigest = synthesisStructuredFactDigest;
-    entity.synthesisVersion = Math.max(0, entity.synthesisVersion ?? 0) + (options.incrementVersion === false ? 0 : 1);
-    entity.updated = entityUpdatedAt;
-    await this.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.entitySchemas));
-    await this.removeEntitySynthesisQueueEntries([
-      .../* @__PURE__ */ new Set([name, this.normalizeEntityName(entity.name, entity.type)])
-    ]);
-    this.invalidateKnowledgeIndexCache();
-    this.bumpMemoryStatusVersion();
+    return this.entityStore.updateEntitySynthesis(
+      name,
+      synthesis,
+      options
+    );
   }
   /**
    * Backward-compatible alias for legacy callers/tests.
@@ -5001,7 +5356,7 @@ ${reflection}
     const updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     let synthesisTimelineCount;
     try {
-      const filePath = path.join(this.entitiesDir, `${name}.md`);
+      const filePath = path2.join(this.entitiesDir, `${name}.md`);
       const content = await this.readStorageSecureFile(filePath);
       synthesisTimelineCount = parseEntityFile(content, this.entitySchemas).timeline.length;
     } catch (err) {
@@ -5084,7 +5439,7 @@ ${reflection}
       if (!raw) continue;
       const serialized = serializeEntityFile(parseEntityFile(raw, this.entitySchemas), this.entitySchemas);
       if (raw.trimEnd() === serialized.trimEnd()) continue;
-      await this.writeStorageSecureFile(path.join(this.entitiesDir, `${entityName}.md`), serialized);
+      await this.writeStorageSecureFile(path2.join(this.entitiesDir, `${entityName}.md`), serialized);
       migrated += 1;
     }
     if (migrated > 0) {
@@ -5099,45 +5454,8 @@ ${reflection}
   // ---------------------------------------------------------------------------
   // Scoring + Knowledge Index (Knowledge Graph v7.0)
   // ---------------------------------------------------------------------------
-  /**
-   * Read all entity files and return lightweight EntityFile objects.
-   * Parsing is fast (~50-100ms for ~1,800 files) since entity files are small.
-   */
   async readAllEntityFiles() {
-    const currentVersion = this.getMemoryStatusVersion();
-    const schemaCacheKey = buildEntitySchemaCacheKey(this.entitySchemas);
-    const cacheKey = `${this.getEntityCacheSecureStoreKey()}\0${schemaCacheKey}`;
-    const cached = getCachedEntities(this.baseDir, currentVersion, cacheKey);
-    if (cached) return cached;
-    try {
-      const entries = await readdir(this.entitiesDir);
-      const mdFiles = entries.filter((e) => e.endsWith(".md"));
-      if (mdFiles.length === 0) return [];
-      const BATCH_SIZE = 100;
-      const entities = [];
-      for (let i = 0; i < mdFiles.length; i += BATCH_SIZE) {
-        const batch = mdFiles.slice(i, i + BATCH_SIZE);
-        const results = await Promise.all(
-          batch.map(async (entry) => {
-            try {
-              return await this.readStorageSecureFile(path.join(this.entitiesDir, entry));
-            } catch (err) {
-              if (err instanceof SecureStoreLockedError) throw err;
-              if (!isErrnoCode(err, "ENOENT")) throw err;
-              return null;
-            }
-          })
-        );
-        for (const content of results) {
-          if (content !== null) entities.push(parseEntityFile(content, this.entitySchemas));
-        }
-      }
-      setCachedEntities(this.baseDir, entities, currentVersion, cacheKey);
-      return entities;
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError || !isErrnoCode(err, "ENOENT")) throw err;
-      return [];
-    }
+    return this.entityStore.readAllEntityFiles();
   }
   /**
    * Score an entity based on recency, frequency, activity, type priority,
@@ -5163,53 +5481,11 @@ ${reflection}
     const relDensity = Math.min(entity.relationships.length / 8, 1);
     return recency * 0.4 + frequency * 0.25 + activityScore * 0.15 + typePriority * 0.1 + relDensity * 0.1;
   }
-  /**
-   * Build the Knowledge Index: a compact markdown table of top-scored entities.
-   * Respects maxEntities and maxChars limits from config.
-   */
   async buildKnowledgeIndex(config, overrides) {
-    const useDefaultLimits = overrides?.maxEntities === void 0 && overrides?.maxChars === void 0;
-    if (useDefaultLimits && this.knowledgeIndexCache && Date.now() - this.knowledgeIndexCache.builtAt < _StorageManager.KNOWLEDGE_INDEX_CACHE_TTL_MS) {
-      return { result: this.knowledgeIndexCache.result, cached: true };
-    }
-    const entities = await this.readAllEntityFiles();
-    if (entities.length === 0) {
-      if (useDefaultLimits) this.knowledgeIndexCache = { result: "", builtAt: Date.now() };
-      return { result: "", cached: false };
-    }
-    const now = /* @__PURE__ */ new Date();
-    const scored = entities.map((e) => ({
-      name: e.name,
-      type: e.type,
-      score: _StorageManager.scoreEntity(e, now),
-      factCount: e.facts.length,
-      summary: e.synthesis ?? e.summary,
-      topRelationships: e.relationships.slice(0, 3).map((r) => r.target)
-    }));
-    scored.sort((a, b) => b.score - a.score);
-    const maxEntities = typeof overrides?.maxEntities === "number" ? Math.max(0, Math.floor(overrides.maxEntities)) : config.knowledgeIndexMaxEntities;
-    const topN = scored.slice(0, maxEntities);
-    if (topN.length === 0) {
-      if (useDefaultLimits) this.knowledgeIndexCache = { result: "", builtAt: Date.now() };
-      return { result: "", cached: false };
-    }
-    const header = "## Knowledge Index\n\n| Entity | Type | Summary | Connected to |\n|--------|------|---------|-------------|";
-    const rows = [];
-    let totalChars = header.length;
-    const maxChars = typeof overrides?.maxChars === "number" ? Math.max(0, Math.floor(overrides.maxChars)) : config.knowledgeIndexMaxChars;
-    for (const entity of topN) {
-      const summary = entity.summary || `${entity.factCount} facts`;
-      const connected = entity.topRelationships.length > 0 ? entity.topRelationships.join(", ") : "\u2014";
-      const row = `| ${entity.name} | ${entity.type} | ${summary} | ${connected} |`;
-      if (totalChars + row.length + 1 > maxChars) break;
-      rows.push(row);
-      totalChars += row.length + 1;
-    }
-    const result = rows.length === 0 ? "" : `${header}
-${rows.join("\n")}
-`;
-    if (useDefaultLimits) this.knowledgeIndexCache = { result, builtAt: Date.now() };
-    return { result, cached: false };
+    return this.entityStore.buildKnowledgeIndex(
+      config,
+      overrides
+    );
   }
   /** Invalidate the Knowledge Index cache (call after entity mutations). */
   invalidateKnowledgeIndexCache() {
@@ -5220,201 +5496,8 @@ ${rows.join("\n")}
   // ---------------------------------------------------------------------------
   /** Max lines for profile.md before LLM consolidation triggers */
   static PROFILE_MAX_LINES = 300;
-  /**
-   * Merge fragmented entity files that resolve to the same canonical name.
-   * Preserves relationships, activity, aliases, and summary from all fragments.
-   * Returns count of files merged.
-   */
   async mergeFragmentedEntities() {
-    let merged = 0;
-    try {
-      const entries = await readdir(this.entitiesDir);
-      const mdFiles = entries.filter((e) => e.endsWith(".md"));
-      const groups = /* @__PURE__ */ new Map();
-      for (const file of mdFiles) {
-        const baseName = file.replace(".md", "");
-        const dashIdx = baseName.indexOf("-");
-        if (dashIdx === -1) continue;
-        const type = baseName.slice(0, dashIdx);
-        const restOfName = baseName.slice(dashIdx + 1);
-        const canonical = this.normalizeEntityName(restOfName, type);
-        if (!groups.has(canonical)) groups.set(canonical, []);
-        groups.get(canonical).push(file);
-      }
-      for (const [canonical, files] of groups) {
-        if (files.length <= 1) continue;
-        const mergedEntity = {
-          name: "",
-          type: "other",
-          created: "",
-          updated: "",
-          extraFrontmatterLines: [],
-          preSectionLines: [],
-          facts: [],
-          summary: void 0,
-          synthesis: void 0,
-          synthesisUpdatedAt: void 0,
-          synthesisTimelineCount: void 0,
-          synthesisStructuredFactCount: void 0,
-          synthesisStructuredFactDigest: void 0,
-          synthesisVersion: void 0,
-          timeline: [],
-          relationships: [],
-          activity: [],
-          aliases: [],
-          structuredSections: [],
-          extraSections: []
-        };
-        for (const file of files) {
-          const filePath = path.join(this.entitiesDir, file);
-          try {
-            const content = await this.readStorageSecureFile(filePath);
-            const parsed = parseEntityFile(content, this.entitySchemas);
-            if (!mergedEntity.type || mergedEntity.type === "other") {
-              mergedEntity.type = parsed.type;
-            }
-            if (!mergedEntity.updated || compareEntityTimestamps(parsed.updated, mergedEntity.updated) > 0) {
-              mergedEntity.updated = parsed.updated;
-            }
-            const parsedCreated = parsed.created || parsed.updated;
-            const mergedCreated = mergedEntity.created?.trim() || "";
-            const parsedCreatedMs = parsedCreated ? Date.parse(parsedCreated) : Number.NaN;
-            const mergedCreatedMs = mergedCreated ? Date.parse(mergedCreated) : Number.NaN;
-            const parsedCreatedIsValid = Number.isFinite(parsedCreatedMs);
-            const mergedCreatedIsValid = Number.isFinite(mergedCreatedMs);
-            if (parsedCreated && (!mergedCreated || parsedCreatedIsValid && !mergedCreatedIsValid || parsedCreatedIsValid && mergedCreatedIsValid && parsedCreatedMs < mergedCreatedMs || !parsedCreatedIsValid && !mergedCreatedIsValid && compareEntityTimestamps(parsedCreated, mergedCreated) < 0)) {
-              mergedEntity.created = parsedCreated;
-            }
-            if (parsed.name.length > mergedEntity.name.length) {
-              mergedEntity.name = parsed.name;
-            }
-            const parsedSynthesisUpdatedAt = parsed.synthesisUpdatedAt?.trim() || void 0;
-            const mergedSynthesisUpdatedAt = mergedEntity.synthesisUpdatedAt?.trim() || void 0;
-            if (parsed.synthesis && (!mergedEntity.synthesis || !mergedSynthesisUpdatedAt && Boolean(parsedSynthesisUpdatedAt) || Boolean(mergedSynthesisUpdatedAt) && Boolean(parsedSynthesisUpdatedAt) && compareEntityTimestamps(parsedSynthesisUpdatedAt, mergedSynthesisUpdatedAt) > 0)) {
-              mergedEntity.synthesis = parsed.synthesis;
-              mergedEntity.summary = parsed.synthesis;
-              mergedEntity.synthesisUpdatedAt = parsedSynthesisUpdatedAt;
-              mergedEntity.synthesisTimelineCount = parsed.synthesisTimelineCount;
-              mergedEntity.synthesisStructuredFactCount = parsed.synthesisStructuredFactCount;
-              mergedEntity.synthesisStructuredFactDigest = parsed.synthesisStructuredFactDigest;
-              mergedEntity.synthesisVersion = parsed.synthesisVersion;
-            } else if (!mergedEntity.summary && parsed.summary) {
-              mergedEntity.summary = parsed.summary;
-              mergedEntity.synthesis = parsed.summary;
-              mergedEntity.synthesisUpdatedAt = parsedSynthesisUpdatedAt;
-              mergedEntity.synthesisTimelineCount = parsed.synthesisTimelineCount;
-              mergedEntity.synthesisStructuredFactCount = parsed.synthesisStructuredFactCount;
-              mergedEntity.synthesisStructuredFactDigest = parsed.synthesisStructuredFactDigest;
-              mergedEntity.synthesisVersion = parsed.synthesisVersion;
-            }
-            mergedEntity.timeline.push(...parsed.timeline);
-            mergedEntity.relationships.push(...parsed.relationships);
-            mergedEntity.activity.push(...parsed.activity);
-            mergedEntity.aliases.push(...parsed.aliases);
-            const mergedStructuredSectionMap = new Map(
-              (mergedEntity.structuredSections ?? []).map((section) => [section.key, {
-                ...section,
-                facts: [...section.facts]
-              }])
-            );
-            for (const section of parsed.structuredSections ?? []) {
-              const existingSection = mergedStructuredSectionMap.get(section.key);
-              if (!existingSection) {
-                mergedStructuredSectionMap.set(section.key, {
-                  key: section.key,
-                  title: section.title,
-                  facts: [...new Set(section.facts.map((fact) => fact.trim()).filter((fact) => fact.length > 0))]
-                });
-                continue;
-              }
-              const mergedFacts = new Set(existingSection.facts.map((fact) => fact.trim()));
-              for (const fact of section.facts) {
-                const trimmed = fact.trim();
-                if (!trimmed) continue;
-                mergedFacts.add(trimmed);
-              }
-              existingSection.facts = Array.from(mergedFacts);
-              if (!existingSection.title.trim() && section.title.trim()) {
-                existingSection.title = section.title;
-              }
-            }
-            mergedEntity.structuredSections = Array.from(mergedStructuredSectionMap.values());
-            mergedEntity.extraFrontmatterLines.push(...parsed.extraFrontmatterLines ?? []);
-            mergedEntity.preSectionLines.push(...parsed.preSectionLines ?? []);
-            mergedEntity.extraSections.push(...(parsed.extraSections ?? []).map((section) => ({
-              title: section.title,
-              lines: [...section.lines]
-            })));
-          } catch (err) {
-            if (err instanceof SecureStoreLockedError) throw err;
-            if (!isErrnoCode(err, "ENOENT")) throw err;
-          }
-        }
-        const timelineKeys = /* @__PURE__ */ new Set();
-        mergedEntity.timeline = mergedEntity.timeline.filter((entry) => {
-          const key = JSON.stringify([
-            entry.timestamp,
-            entry.source ?? "",
-            entry.sessionKey ?? "",
-            entry.principal ?? "",
-            entry.text
-          ]);
-          if (timelineKeys.has(key)) return false;
-          timelineKeys.add(key);
-          return true;
-        });
-        const relKeys = /* @__PURE__ */ new Set();
-        mergedEntity.relationships = mergedEntity.relationships.filter((r) => {
-          const key = `${r.target}::${r.label}`;
-          if (relKeys.has(key)) return false;
-          relKeys.add(key);
-          return true;
-        });
-        const actKeys = /* @__PURE__ */ new Set();
-        mergedEntity.activity = mergedEntity.activity.filter((a) => {
-          const key = `${a.date}::${a.note}`;
-          if (actKeys.has(key)) return false;
-          actKeys.add(key);
-          return true;
-        }).sort((a, b) => b.date.localeCompare(a.date));
-        mergedEntity.aliases = [...new Set(mergedEntity.aliases)];
-        mergedEntity.structuredSections = sortStructuredSectionsBySchema(
-          mergedEntity.type,
-          mergedEntity.structuredSections ?? [],
-          this.entitySchemas
-        );
-        mergedEntity.facts = compileEntityFacts(mergedEntity.timeline, mergedEntity.structuredSections);
-        const extraSectionKeys = /* @__PURE__ */ new Set();
-        mergedEntity.extraSections = (mergedEntity.extraSections ?? []).filter((section) => {
-          const key = `${section.title}::${section.lines.join("\n")}`;
-          if (extraSectionKeys.has(key)) return false;
-          extraSectionKeys.add(key);
-          return true;
-        });
-        if (!mergedEntity.name) {
-          const dashIdx = canonical.indexOf("-");
-          mergedEntity.name = dashIdx !== -1 ? canonical.slice(dashIdx + 1) : canonical;
-        }
-        mergedEntity.created = mergedEntity.created || mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
-        mergedEntity.updated = mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
-        const canonicalPath = path.join(this.entitiesDir, `${canonical}.md`);
-        await this.writeStorageSecureFile(canonicalPath, serializeEntityFile(mergedEntity, this.entitySchemas));
-        for (const file of files) {
-          const filePath = path.join(this.entitiesDir, file);
-          if (filePath !== canonicalPath) {
-            try {
-              await unlink(filePath);
-              merged++;
-              log.debug(`merged entity ${file} \u2192 ${canonical}.md`);
-            } catch {
-            }
-          }
-        }
-      }
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError || !isErrnoCode(err, "ENOENT")) throw err;
-    }
-    return merged;
+    return this.entityStore.mergeFragmentedEntities();
   }
   async cleanExpiredCommitments(decayDays) {
     const memories = await this.readAllMemories();
@@ -5429,7 +5512,7 @@ ${rows.join("\n")}
       const updatedAt = new Date(m.frontmatter.updated).getTime();
       if (updatedAt < cutoff) {
         try {
-          await unlink(m.path);
+          await unlink2(m.path);
           deleted.push(m);
           log.debug(`cleaned expired commitment ${m.frontmatter.id}`);
         } catch {
@@ -5499,7 +5582,7 @@ ${memory.content}
     const filePaths = await this.collectActiveMemoryPaths();
     const foundIds = /* @__PURE__ */ new Set();
     for (const filePath of filePaths) {
-      const basename = path.basename(filePath, ".md");
+      const basename = path2.basename(filePath, ".md");
       if (wantedIds.has(basename)) {
         foundIds.add(basename);
         if (foundIds.size === wantedIds.size) break;
@@ -5689,14 +5772,14 @@ Reason: ${reason}`, {
   // Memory Summarization (Phase 4A)
   // ---------------------------------------------------------------------------
   get summariesDir() {
-    return path.join(this.baseDir, "summaries");
+    return path2.join(this.baseDir, "summaries");
   }
   /**
    * Write a memory summary.
    */
   async writeSummary(summary) {
     await mkdir(this.summariesDir, { recursive: true });
-    const filePath = path.join(this.summariesDir, `${summary.id}.json`);
+    const filePath = path2.join(this.summariesDir, `${summary.id}.json`);
     await this.writeStorageSecureFile(filePath, JSON.stringify(summary, null, 2));
     log.debug(`wrote summary ${summary.id}`);
   }
@@ -5705,11 +5788,11 @@ Reason: ${reason}`, {
    */
   async readSummaries() {
     try {
-      const files = await readdir(this.summariesDir);
+      const files = await readdir2(this.summariesDir);
       const summaries = [];
       for (const file of files) {
         if (!file.endsWith(".json")) continue;
-        const filePath = path.join(this.summariesDir, file);
+        const filePath = path2.join(this.summariesDir, file);
         const raw = await this.readStorageSecureFile(filePath);
         summaries.push(JSON.parse(raw));
       }
@@ -5770,7 +5853,7 @@ ${memory.content}
    * Save topic scores to meta.json.
    */
   async saveTopics(topics) {
-    const metaPath = path.join(this.stateDir, "topics.json");
+    const metaPath = path2.join(this.stateDir, "topics.json");
     await mkdir(this.stateDir, { recursive: true });
     await this.writeStorageSecureFile(metaPath, JSON.stringify({ topics, updatedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2));
     log.debug(`saved ${topics.length} topic scores`);
@@ -5779,7 +5862,7 @@ ${memory.content}
    * Load topic scores from meta.json.
    */
   async loadTopics() {
-    const metaPath = path.join(this.stateDir, "topics.json");
+    const metaPath = path2.join(this.stateDir, "topics.json");
     try {
       const raw = await this.readStorageSecureFile(metaPath);
       return JSON.parse(raw);
@@ -5857,14 +5940,19 @@ ${memory.content}
 };
 
 export {
+  selfDeps,
   normalizeEntityName,
   ContentHashIndex,
   normalizeAttributePairs,
+  normalizeStructuredSectionFacts,
+  compileEntityFacts,
   compareEntityTimestamps,
+  countEntityStructuredFacts,
   fingerprintEntityStructuredFacts,
   isEntitySynthesisStale,
   parseEntityFile,
   serializeEntityFile,
+  buildEntitySchemaCacheKey,
   StorageManager
 };
-//# sourceMappingURL=chunk-34THARMH.js.map
+//# sourceMappingURL=chunk-XBM5DG4O.js.map