@co-engram/core 0.1.2 → 0.1.3

package/dist/storage/repository.d.ts

@@ -90,6 +90,18 @@ export declare class EngramRepository {
     private updateIndexEntry;
     /** 从 index 删除一条并写盘 */
     private deleteIndexEntry;
+    /**
+     * 清理索引中所有指向 relativePath 的孤儿 entry,返回清理数量。
+     *
+     * 触发场景:外部(用户 rm / git 操作 / 进程异常)删除 engram 文件后,
+     * engram-index.json 仍保留旧 ULID 的 entry。下一次 createEngram 写入
+     * 同 path 的新 ULID 会留下永不消失的孤儿,导致 listEngrams / viewer
+     * 显示"重影"(同一文件被两个 ULID 引用)。
+     *
+     * 同 path 出现多条 entry 本身就是不变量破坏 —— 此处发现即清。多数调用
+     * 不会命中,N=0 时是 O(|index|) 扫一次,可接受。
+     */
+    private purgeStaleIndexEntriesForPath;
     /**
      * 启动对 engram-index.json 的 fs.watch 监听。
      *
@@ -134,7 +146,13 @@ export declare class EngramRepository {
     createEngram(input: EngramCreateInput & {
         pathHint?: string;
     }): Engram;
-    /** 默认路径:{domainTags.join('/')/}{slug}.md */
+    /**
+     * 默认路径:{domainTags.join('/')/}{slug}.md
+     *
+     * private engram 自动落 `private/` 子目录(被 .gitignore 隔离出团队仓库)。
+     * 注意:本函数只用于「无 pathHint」场景;调用方传 pathHint 时直接尊重用户路径,
+     * 不会自动加 private 前缀(避免 `private/private/...` 双前缀)。
+     */
     private deriveDefaultPath;
     /**
      * 读取完整 Engram(单文件 + 统计)
@@ -154,8 +172,20 @@ export declare class EngramRepository {
     updateEngram(stableId: string, input: EngramUpdateInput): Engram;
     /** 重新组装路径:替换 basename 为 newSlug */
     private rebuildPath;
+    /**
+     * 调整路径的 visibility 前缀(不改动 basename):
+     * - `'private'` → 加 `private/` 前缀(若已含则幂等返回原值)
+     * - 其他(`'public'`/`'team'`/`'restricted'`) → 移除 `private/` 前缀(若不含则幂等返回)
+     *
+     * 用于 updateEngram 中 visibility 变更时的路径迁移。
+     * 注意:仅处理前缀,basename 由 rebuildPath 负责,两者正交可串联应用。
+     */
+    private rebuildPathForVisibility;
     /**
      * 删除 Engram + 级联删除触及的 synapses + 清理 index
+     *
+     * 走 `this.deleteSynapsesTouching` 方法版而非模块函数,以触发
+     * 邻居派生段( Obsidian wikilinks)的 cascade refresh。
      */
     deleteEngram(stableId: string): void;
     /**
@@ -205,6 +235,12 @@ export declare class EngramRepository {
     readSynapseByEndpoints(from: string, to: string, kind: SynapseKind): Synapse | undefined;
     /** 按 id 查 synapse */
     readSynapseById(synapseId: string): Synapse | undefined;
+    /**
+     * 触发 Obsidian 派生段重建(多条 engram 一次性刷新,去重)。
+     *
+     * 永不抛(regenerateObsidianLinks 内部已吞错)。调用方无需 try/catch。
+     */
+    private refreshObsidianLinks;
     /** 创建 synapse(idempotent) */
     createSynapse(input: SynapseCreateInput): Synapse;
     /**

package/dist/storage/repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/storage/repository.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/storage/repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAeH,OAAO,KAAK,EACV,MAAM,EACN,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,eAAe,EAGf,YAAY,EACZ,iBAAiB,EAGjB,gBAAgB,EAChB,kBAAkB,EAClB,OAAO,EACP,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAEV,gBAAgB,EAChB,YAAY,EAEZ,YAAY,EACb,MAAM,8BAA8B,CAAC;AAWtC,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAyBnE,OAAO,EAYL,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAM3B,oBAAoB;AACpB,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CAC9B;AA4DD;;;;GAIG;AACH,qBAAa,gBAAgB;IAwBf,OAAO,CAAC,QAAQ,CAAC,MAAM;IAvBnC,OAAO,CAAC,UAAU,CAA6B;IAC/C;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAqB;IAE5C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAyB;IAE7D;;;OAGG;IACH,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;gBAEP,MAAM,EAAE,gBAAgB;IAIrD,4BAA4B;IAC5B,IAAI,eAAe,IAAI,QAAQ,CAE9B;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAID;;;;;;;;;;OAUG;IACH,OAAO,CAAC,QAAQ;IA8BhB,sBAAsB;IACtB,YAAY,IAAI,cAAc;IAM9B;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAgBpB,uBAAuB;IACvB,OAAO,CAAC,gBAAgB;IAMxB,sBAAsB;IACtB,OAAO,CAAC,gBAAgB;IAMxB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,6BAA6B;IAcrC;;;;;;;;;;;;;OAaG;IACH,aAAa,IAAI,IAAI;IAqBrB,2BAA2B;IAC3B,YAAY,IAAI,IAAI;IAWpB,0DAA0D;IAC1D,OAAO,CAAC,oBAAoB;IAa5B;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAQjD,yBAAyB;IACzB,OAAO,CAAC,WAAW;IAgBnB,2BAA2B;IAC3B,OAAO,CAAC,YAAY;IAOpB;;;;;;;;OAQG;IACH,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;IAqFtE;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAWpC;;OAEG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IASjC;;;;;;OAMG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,MAAM;IAyIhE,mCAAmC;IACnC,OAAO,CAAC,WAAW;IAMnB;;;;;;;OAOG;IACH,OAAO,CAAC,wBAAwB;IAahC;;;;;OAKG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAWpC;;OAEG;IACH,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAa1D,+BAA+B;IAC/B,WAAW,IAAI,kBAAkB,EAAE;IAanC;;;;OAIG;IACH,wBAAwB,CACtB,QAAQ,EAAE,SAAS,kBAAkB,EAAE,GACtC,SAAS,MAAM,EAAE;IACpB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,MAAM,EAAE;IAgBvE;;;;OAIG;IACH,eAAe,IAAI,SAAS,gBAAgB,EAAE;IAI9C,uBAAuB;IACvB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAY7D,yCAAyC;IACzC,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAmBjD;;;;;OAKG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;QAAC,QAAQ,EAAE,OAAO,EAAE,CAAA;KAAE;IAI5E;;;;;OAKG;IACH,kBAAkB,IAAI,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAKjE,8BAA8B;IAC9B,sBAAsB,CACpB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,WAAW,GAChB,OAAO,GAAG,SAAS;IAItB,qBAAqB;IACrB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAIvD;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAS5B,6BAA6B;IAC7B,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO;IAwCjD;;;;;OAKG;IACH,aAAa,CACX,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,kBAAkB,GACxB,OAAO;IA0CV,mBAAmB;IACnB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAWtC,gCAAgC;IAChC,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAgBhD;;;;;;;OAOG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;IAuB7D;;;;OAIG;IACH,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAc9D;;;;OAIG;IACH,uBAAuB,CACrB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,sBAAsB,GAC3B,IAAI;IAoBP;;OAEG;IACH,sBAAsB,CACpB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,eAAe,EAAE,GACnC,IAAI;IAoBP;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IAiBtE;;;;;OAKG;IACH,kBAAkB,CAChB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE;QACL,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;KAC7B,GACA,IAAI;IAyBP;;;;;;OAMG;IACH,eAAe,CACb,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,YAAY,EACrB,SAAS,CAAC,EAAE,eAAe,GAC1B,IAAI;IASP;;;;OAIG;IACH,sBAAsB,CACpB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE;QAAE,MAAM,EAAE,gBAAgB,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GACtD,IAAI;IAQP;;OAEG;IACH,wBAAwB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAUtE;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAgCzB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,YAAY;IA8LhE;;;;;OAKG;IACH,YAAY,IAAI,YAAY;IAyC5B;;OAEG;IACH,OAAO,CAAC,cAAc;IAqFtB,OAAO,CAAC,gBAAgB;IAaxB,gCAAgC;IAChC,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAI1C;;;;;;;;;;OAUG;IACH,aAAa,CAAC,cAAc,EAAE,QAAQ,GAAG;QACvC,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,EAAE,CAAC;KAClB;CAkFF"}

package/dist/storage/repository.js

@@ -19,11 +19,14 @@ import { join, relative, sep } from "node:path";
 import { ulid } from "ulid";
 import { isStableEngramId } from "../types/repository-types.js";
 import { slugify, inferDomainTagsFromPath } from "../types/slugify.js";
+import { safeEmit } from "../prompt-signals/event-bus.js";
+import { safeJoinWithinRoot, isPathWithinRoot, } from "./path.js";
 import { computeContentHash, computeContentSize } from "./hash.js";
 import { DEFAULT_LANGUAGE } from "../i18n/index.js";
 import { readEngramFile, writeEngramFile, deleteEngramFile, renameEngramFile, parseEngramFile, detectEngramFileLanguage, } from "./engram-store.js";
 import { SYNAPSES_DIR, collectAllSynapses, upsertSynapse, readSynapseByEndpoints, readSynapseById, listSynapsesForEngram, deleteSynapsesTouching, synapseRelativePath, deleteSynapseFile, writeSynapseFile, parseSynapseFile, } from "./synapse-store.js";
 import { buildIndexEntryFromFrontmatter, engramIndexPath, readEngramIndex, rebuildEngramIndex, removeEngramIndexEntry, upsertEngramIndexEntry, writeEngramIndex, } from "./engram-index.js";
+import { regenerateObsidianLinks, checkObsidianView, } from "./obsidian-links.js";
 const DEFAULT_IMPORTANCE = 0.5;
 const DEFAULT_CONFIDENCE_BY_SOURCE = {
     firsthand: 0.85,
@@ -64,6 +67,21 @@ function deriveAutoSummary(content, title) {
         return cleaned;
     return cleaned.slice(0, 197) + "...";
 }
+/**
+ * Synapse visibility 继承规则:取两端 engram 的最严。
+ *
+ * 严格度排序:`private` > `restricted` > `team` > `public`。
+ * 任一端是 private,synapse 整条就按 private 处理(保守策略)。
+ */
+const VIS_STRICTNESS = {
+    public: 0,
+    team: 1,
+    restricted: 2,
+    private: 3,
+};
+function maxVisibility(a, b) {
+    return VIS_STRICTNESS[a] >= VIS_STRICTNESS[b] ? a : b;
+}
 /**
  * EngramRepository — per-edge synapse + ULID stable id + 单文件 engram
  *
@@ -180,6 +198,29 @@ export class EngramRepository {
         removeEngramIndexEntry(index, id);
         this.persistIndex(index);
     }
+    /**
+     * 清理索引中所有指向 relativePath 的孤儿 entry,返回清理数量。
+     *
+     * 触发场景:外部(用户 rm / git 操作 / 进程异常)删除 engram 文件后,
+     * engram-index.json 仍保留旧 ULID 的 entry。下一次 createEngram 写入
+     * 同 path 的新 ULID 会留下永不消失的孤儿,导致 listEngrams / viewer
+     * 显示"重影"(同一文件被两个 ULID 引用)。
+     *
+     * 同 path 出现多条 entry 本身就是不变量破坏 —— 此处发现即清。多数调用
+     * 不会命中,N=0 时是 O(|index|) 扫一次,可接受。
+     */
+    purgeStaleIndexEntriesForPath(relativePath) {
+        const index = this.getIndex();
+        const stale = [];
+        for (const [id, entry] of index.entries) {
+            if (entry.path === relativePath)
+                stale.push(id);
+        }
+        for (const id of stale) {
+            this.deleteIndexEntry(id);
+        }
+        return stale.length;
+    }
     // ─── Cross-process watcher ─────────────────────────────────────────────
     /**
      * 启动对 engram-index.json 的 fs.watch 监听。
@@ -262,17 +303,26 @@ export class EngramRepository {
     /** 解析 stableId → 相对路径 */
     resolvePath(stableId) {
         if (!isStableEngramId(stableId)) {
-            // 兼容:可能是相对路径,直接当 path 用
+            // 兼容:可能是相对路径,直接当 path 用。
+            // 但必须先校验路径在 root 内(防 `..` 逃逸,path traversal 防御)
+            if (!isPathWithinRoot(this.config.rootPath, stableId))
+                return undefined;
             if (this.existsAtPath(stableId))
                 return stableId;
             return undefined;
         }
         const entry = this.getIndex().entries.get(stableId);
+        // 防御:索引中的 path 也校验(理论上是 trusted,但 doctor 自愈后可能含异常)
+        if (entry?.path && !isPathWithinRoot(this.config.rootPath, entry.path)) {
+            return undefined;
+        }
         return entry?.path;
     }
     /** 检查相对路径是否存在 engram 文件 */
     existsAtPath(relativePath) {
-        return existsSync(join(this.config.rootPath, relativePath));
+        if (!isPathWithinRoot(this.config.rootPath, relativePath))
+            return false;
+        return existsSync(safeJoinWithinRoot(this.config.rootPath, relativePath));
     }
     // ─── Engram CRUD ───────────────────────────────────────────────────────
     /**
@@ -290,11 +340,18 @@ export class EngramRepository {
         const sourceType = input.sourceType ?? "firsthand";
         const contentHash = computeContentHash(input.content);
         const contentSize = computeContentSize(input.content);
+        // pathHint 优先;否则用 deriveDefaultPath(slugify title + raw domainTags + .md)
+        // safeJoinWithinRoot 拦截 `..` 逃逸与绝对路径(path traversal 防御)
         const relativePath = input.pathHint ?? this.deriveDefaultPath(input);
-        const absolutePath = join(this.config.rootPath, relativePath);
+        const absolutePath = safeJoinWithinRoot(this.config.rootPath, relativePath);
         if (existsSync(absolutePath)) {
             throw new Error(`Engram already exists at ${relativePath}`);
         }
+        // 自愈:外部 rm / git 操作可能让 engram-index.json 残留指向同 path
+        // 但磁盘已无文件的孤儿 entry。新 ULID 写入后会留下永不消失的"重影"
+        // (listEngrams / viewer 显示重复节点)。在写入前清理。engram_doctor
+        // 是手动巡检版本,此处是写入路径的自动防线。
+        this.purgeStaleIndexEntriesForPath(relativePath);
         const hasExplicitDomainTags = input.domainTags.length > 0;
         const frontmatter = {
             id: stableId,
@@ -344,14 +401,29 @@ export class EngramRepository {
             contentHash,
         });
         this.updateIndexEntry(entry);
+        // Task 3.4 Phase B:engram 创建后 emit,让 prompt-signals cache 失效并 debounced rebuild
+        safeEmit({
+            type: "engram_created",
+            engramId: stableId,
+            at: new Date().toISOString(),
+        });
         return this.readEngram(stableId);
     }
-    /** 默认路径:{domainTags.join('/')/}{slug}.md */
+    /**
+     * 默认路径:{domainTags.join('/')/}{slug}.md
+     *
+     * private engram 自动落 `private/` 子目录(被 .gitignore 隔离出团队仓库)。
+     * 注意:本函数只用于「无 pathHint」场景;调用方传 pathHint 时直接尊重用户路径,
+     * 不会自动加 private 前缀(避免 `private/private/...` 双前缀)。
+     */
     deriveDefaultPath(input) {
         const slug = slugify(input.title);
         const domains = input.domainTags.length > 0 ? input.domainTags : [];
         const parts = [...domains, `${slug}.md`];
-        return parts.join("/");
+        const basePath = parts.join("/");
+        return input.visibility === "private"
+            ? `private/${basePath}`
+            : basePath;
     }
     /**
      * 读取完整 Engram(单文件 + 统计)
@@ -361,7 +433,8 @@ export class EngramRepository {
         if (!relativePath) {
             throw new Error(`Engram not found: ${stableId}`);
         }
-        const absolutePath = join(this.config.rootPath, relativePath);
+        // resolvePath 已校验路径在 root 内,这里再防御一次
+        const absolutePath = safeJoinWithinRoot(this.config.rootPath, relativePath);
         const file = readEngramFile(absolutePath);
         return this.assembleEngram(file, relativePath);
     }
@@ -371,7 +444,8 @@ export class EngramRepository {
     exists(stableId) {
         const relativePath = this.resolvePath(stableId);
         return (relativePath !== undefined &&
-            existsSync(join(this.config.rootPath, relativePath)));
+            isPathWithinRoot(this.config.rootPath, relativePath) &&
+            existsSync(safeJoinWithinRoot(this.config.rootPath, relativePath)));
     }
     /**
      * 更新 Engram(content/frontmatter 双写)
@@ -454,9 +528,18 @@ export class EngramRepository {
         const newSlugUnlocked = oldFrontmatter.slug === undefined
             ? slugify(newTitle)
             : oldFrontmatter.slug;
-        const newPath = newSlugUnlocked !== oldSlug
-            ? this.rebuildPath(relativePath, newSlugUnlocked)
-            : relativePath;
+        // 处理 visibility 变化:public/team/restricted ↔ private → 路径前缀调整
+        // (private engram 落 `private/` 子目录,变更 visibility 时同步迁移路径)
+        const oldVisibility = oldFrontmatter.visibility ?? "public";
+        const visibilityChanged = newVisibility !== oldVisibility;
+        // slug + visibility 都可能触发 rename,正交串联应用
+        let newPath = relativePath;
+        if (newSlugUnlocked !== oldSlug) {
+            newPath = this.rebuildPath(newPath, newSlugUnlocked);
+        }
+        if (visibilityChanged) {
+            newPath = this.rebuildPathForVisibility(newPath, newVisibility);
+        }
         const newFile = {
             frontmatter: newFrontmatter,
             content: newContent,
@@ -464,10 +547,15 @@ export class EngramRepository {
         if (newPath !== relativePath) {
             const newAbsolutePath = join(this.config.rootPath, newPath);
             if (existsSync(newAbsolutePath)) {
-                throw new Error(`Slug rename conflict: ${newPath} already exists`);
+                // 原子性保证:目标已存在就报错,不动旧文件
+                throw new Error(`Rename conflict: ${newPath} already exists`);
             }
             writeEngramFile(newAbsolutePath, newFile, this.language);
             rmSync(absolutePath);
+            // 旧路径孤儿 index entry 清理(原 updateEngram 漏了这一步):
+            // rename 后旧 path 的反向 entry(path → stableId)若不清理,会留下
+            // 「磁盘无文件但 index 有记录」的孤儿,listEngrams / viewer 会显示重影。
+            this.purgeStaleIndexEntriesForPath(relativePath);
         }
         else {
             writeEngramFile(absolutePath, newFile, this.language);
@@ -488,8 +576,28 @@ export class EngramRepository {
         parts[parts.length - 1] = `${newSlug}.md`;
         return parts.join("/");
     }
+    /**
+     * 调整路径的 visibility 前缀(不改动 basename):
+     * - `'private'` → 加 `private/` 前缀(若已含则幂等返回原值)
+     * - 其他(`'public'`/`'team'`/`'restricted'`) → 移除 `private/` 前缀(若不含则幂等返回)
+     *
+     * 用于 updateEngram 中 visibility 变更时的路径迁移。
+     * 注意:仅处理前缀,basename 由 rebuildPath 负责,两者正交可串联应用。
+     */
+    rebuildPathForVisibility(path, visibility) {
+        const PRIVATE_PREFIX = "private/";
+        if (visibility === "private") {
+            return path.startsWith(PRIVATE_PREFIX) ? path : `${PRIVATE_PREFIX}${path}`;
+        }
+        return path.startsWith(PRIVATE_PREFIX)
+            ? path.slice(PRIVATE_PREFIX.length)
+            : path;
+    }
     /**
      * 删除 Engram + 级联删除触及的 synapses + 清理 index
+     *
+     * 走 `this.deleteSynapsesTouching` 方法版而非模块函数,以触发
+     * 邻居派生段( Obsidian wikilinks)的 cascade refresh。
      */
     deleteEngram(stableId) {
         const relativePath = this.resolvePath(stableId);
@@ -497,7 +605,7 @@ export class EngramRepository {
             return;
         const absolutePath = join(this.config.rootPath, relativePath);
         deleteEngramFile(absolutePath);
-        deleteSynapsesTouching(this.config.rootPath, stableId);
+        this.deleteSynapsesTouching(stableId);
         if (isStableEngramId(stableId)) {
             this.deleteIndexEntry(stableId);
         }
@@ -613,9 +721,40 @@ export class EngramRepository {
     readSynapseById(synapseId) {
         return readSynapseById(this.config.rootPath, synapseId);
     }
+    /**
+     * 触发 Obsidian 派生段重建(多条 engram 一次性刷新,去重)。
+     *
+     * 永不抛(regenerateObsidianLinks 内部已吞错)。调用方无需 try/catch。
+     */
+    refreshObsidianLinks(...ids) {
+        const seen = new Set();
+        for (const id of ids) {
+            if (!id || seen.has(id))
+                continue;
+            seen.add(id);
+            regenerateObsidianLinks(this.config.rootPath, id, this.language);
+        }
+    }
     /** 创建 synapse(idempotent) */
     createSynapse(input) {
-        return upsertSynapse(this.config.rootPath, {
+        // 继承最严 visibility:取 from/to 两端 engram 的 max(private > restricted > team > public)
+        // 端点查不到(已删/无效 id)时降级 'public',不阻塞 synapse 创建
+        let fromVis = "public";
+        let toVis = "public";
+        try {
+            fromVis = this.readEngram(input.from).visibility ?? "public";
+        }
+        catch {
+            // from engram 不存在或不可读,降级 public
+        }
+        try {
+            toVis = this.readEngram(input.to).visibility ?? "public";
+        }
+        catch {
+            // to engram 不存在或不可读,降级 public
+        }
+        const inheritedVisibility = maxVisibility(fromVis, toVis);
+        const result = upsertSynapse(this.config.rootPath, {
             from: input.from,
             to: input.to,
             kind: input.kind,
@@ -625,8 +764,17 @@ export class EngramRepository {
             createdBy: input.createdBy,
             sourceSemantic: input.sourceSemantic,
             targetSemantic: input.targetSemantic,
+            visibility: inheritedVisibility,
             language: this.language,
         });
+        this.refreshObsidianLinks(input.from, input.to);
+        // Task 3.4 Phase B:synapse 创建影响 graph 结构,触发 prompt-signals rebuild
+        safeEmit({
+            type: "synapse_created",
+            engramId: input.from,
+            at: new Date().toISOString(),
+        });
+        return result;
     }
     /**
      * 更新 synapse(走 upsert,合并 evidence)。
@@ -648,7 +796,7 @@ export class EngramRepository {
             const oldPath = join(this.config.rootPath, synapseRelativePath(target.id, target.kind));
             deleteSynapseFile(oldPath);
         }
-        return upsertSynapse(this.config.rootPath, {
+        const result = upsertSynapse(this.config.rootPath, {
             from: target.from,
             to: target.to,
             kind: nextKind,
@@ -659,8 +807,13 @@ export class EngramRepository {
             sourceSemantic: target.sourceSemantic,
             targetSemantic: target.targetSemantic,
             resolutionState: target.resolutionState,
+            // 保守策略:不因端点 visibility 提升而自动调整 synapse visibility,
+            // 保留原值。Phase 1.5 可加 recomputeSynapseVisibility(engramId)。
+            visibility: target.visibility ?? "public",
             language: this.language,
         });
+        this.refreshObsidianLinks(target.from, target.to);
+        return result;
     }
     /** 删除某条 synapse */
     deleteSynapse(synapseId) {
@@ -669,10 +822,26 @@ export class EngramRepository {
             return;
         const path = join(this.config.rootPath, synapseRelativePath(syn.id, syn.kind));
         deleteSynapseFile(path);
+        this.refreshObsidianLinks(syn.from, syn.to);
     }
     /** 级联删除触及 engram 的所有 synapse */
     deleteSynapsesTouching(engramId) {
-        return deleteSynapsesTouching(this.config.rootPath, engramId);
+        // 先抓所有邻居 endpoint — 删除后这些 synapse 就找不到了,
+        // 邻居 engram.md 的派生段还引用着 engramId,需要重建。
+        const touching = listSynapsesForEngram(this.config.rootPath, engramId);
+        const neighbors = new Set();
+        for (const s of touching.outgoing) {
+            if (s.to !== engramId)
+                neighbors.add(s.to);
+        }
+        for (const s of touching.incoming) {
+            if (s.from !== engramId)
+                neighbors.add(s.from);
+        }
+        const count = deleteSynapsesTouching(this.config.rootPath, engramId);
+        if (neighbors.size > 0)
+            this.refreshObsidianLinks(...neighbors);
+        return count;
     }
     /**
      * 添加 outgoing synapse。
@@ -683,7 +852,7 @@ export class EngramRepository {
      * @returns 实际落盘的 synapse(其 id 是计算值)
      */
     addOutgoingSynapse(fromId, synapse) {
-        return upsertSynapse(this.config.rootPath, {
+        const result = upsertSynapse(this.config.rootPath, {
             from: fromId,
             to: synapse.to,
             kind: synapse.kind,
@@ -701,6 +870,8 @@ export class EngramRepository {
             resolutionState: synapse.resolutionState,
             language: this.language,
         });
+        this.refreshObsidianLinks(fromId, synapse.to);
+        return result;
     }
     /**
      * 删除 outgoing synapse。
@@ -714,6 +885,7 @@ export class EngramRepository {
             return;
         const path = join(this.config.rootPath, synapseRelativePath(target.id, target.kind));
         deleteSynapseFile(path);
+        this.refreshObsidianLinks(target.from, target.to);
     }
     /**
      * 更新 synapse 的 resolutionState(contradicts 专用)。
@@ -822,6 +994,12 @@ export class EngramRepository {
      */
     updateVerificationStatus(id, status) {
         this.mutateFrontmatter(id, (fm) => ({ ...fm, verificationStatus: status }));
+        // Task 3.4 Phase B:验证状态变化影响 prompt 的 lowConfidenceTopics
+        safeEmit({
+            type: "engram_verified",
+            engramId: id,
+            at: new Date().toISOString(),
+        });
     }
     /**
      * 低层 frontmatter 修改:不触发 version++,不改 slug,不改 path。
@@ -876,6 +1054,11 @@ export class EngramRepository {
                 path: orphanPath,
                 message: `Markdown file without frontmatter: ${orphanPath} (either delete it or add frontmatter with a stable id)`,
                 autoFixed: false,
+                nextAction: {
+                    tool: "engram_create",
+                    argsHint: `{ title, content, kind, domainTags, createdBy }  // 直接读取这个 markdown 的内容作为 engram body`,
+                    explanation: "Markdown 文件没有 frontmatter,所以不在 engram 索引里。如果是新记忆,用 engram_create 注册(把现有正文粘到 content);如果是废弃草稿,直接 rm 即可。",
+                },
             });
             pendingManualReview.push(issues[issues.length - 1]);
         });
@@ -913,11 +1096,17 @@ export class EngramRepository {
                     // 标记相关 synapse dangling
                     const touching = listSynapsesForEngram(this.config.rootPath, oldId);
                     if (touching.outgoing.length + touching.incoming.length > 0) {
+                        const danglingCount = touching.outgoing.length + touching.incoming.length;
                         pendingManualReview.push({
                             kind: "dangling_synapse",
                             stableId: oldId,
-                            message: `Engram ${oldId} was deleted but ${touching.outgoing.length + touching.incoming.length} synapse(s) still reference it (clean up manually or restore the engram)`,
+                            message: `Engram ${oldId} was deleted but ${danglingCount} synapse(s) still reference it (clean up manually or restore the engram)`,
                             autoFixed: false,
+                            nextAction: {
+                                tool: "synapse_delete",
+                                argsHint: `{ id: "<synapseId>" }  // synapseId 在每个 synapse 的 yaml id 字段,逐条删`,
+                                explanation: `被删 engram 还有 ${danglingCount} 条 synapse 指向它,这些 synapse 现在是悬空的。去 synapses/ 目录找出涉及该 engram 的 synapse,用 synapse_delete 逐条清理;或者用 engram_create 重建该 engram(让 synapse 重新有目标)。`,
+                            },
                         });
                     }
                 }
@@ -988,6 +1177,35 @@ export class EngramRepository {
                 });
             }
         }
+        // 5. Obsidian 视图一致性(派生段 wikilinks)
+        // 对每条 engram:checkObsidianView 检测派生段与权威源(synapse yaml)不一致,
+        // 不一致 → regenerateObsidianLinks 重写派生段(wikilink target=文件名)。
+        for (const [id, entry] of freshIndex.entries) {
+            const absPath = join(this.config.rootPath, entry.path);
+            if (!existsSync(absPath))
+                continue;
+            let file;
+            try {
+                file = readEngramFile(absPath);
+            }
+            catch {
+                continue; // parse 错误由别处报告(或phan_markdown 路径)
+            }
+            const touching = listSynapsesForEngram(this.config.rootPath, id);
+            const status = checkObsidianView(file, touching, freshIndex);
+            if (!status.stale)
+                continue;
+            regenerateObsidianLinks(this.config.rootPath, id, this.language);
+            fixes.push({
+                kind: "obsidian_view_stale",
+                stableId: id,
+                path: entry.path,
+                message: `Obsidian derived wikilinks regenerated (target=filename, display=title·kind)`,
+                autoFixed: true,
+            });
+        }
+        // Task 3.4 Phase B:doctor 完成后 emit(doctor 可能 sweep/forget,engram 集合变化)
+        safeEmit({ type: "doctor_completed", at: new Date().toISOString() });
         return {
             startedAt,
             finishedAt: now(),