@co-engram/core 0.1.0

package/dist/storage/engram-index.js

@@ -0,0 +1,215 @@
+/**
+ * Engram Index — 派生缓存 {stableId → path/title/mtime/...}
+ *
+ * 设计见 docs/superpowers/specs/2026-06-22-per-edge-synapse-refactor-design.md。
+ *
+ * 文件位置:`.co-engram/engram-index.json`(gitignore)
+ * 用途:
+ *   - doctor 增量扫描(mtime 比对)
+ *   - repository 快速查 stableId → path
+ *   - graph 派生
+ *   - viewer 渲染
+ *
+ * @module @co-engram/core/storage
+ */
+import { readdirSync, readFileSync, statSync, writeFileSync, mkdirSync, existsSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { isStableEngramId } from "../types/repository-types.js";
+import { slugify, inferDomainTagsFromPath } from "../types/slugify.js";
+import { isEngramFile, parseEngramFile, } from "./engram-store.js";
+/** .co-engram/ 顶层缓存目录名 */
+export const CO_ENGRAM_CACHE_DIR = ".co-engram";
+/** engram-index.json 文件名 */
+export const ENGRAM_INDEX_FILENAME = "engram-index.json";
+/** 应被 index 扫描跳过的目录 */
+const SKIP_DIRECTORIES = new Set([
+    CO_ENGRAM_CACHE_DIR,
+    "node_modules",
+    ".git",
+    "synapses", // synapse 数据,不是 engram
+    "engrams", // 旧版三文件数据布局(content/meta/synapses),不扫
+]);
+/**
+ * 应被 index 扫描跳过的 markdown 文件名(大小写不敏感)。
+ * 这些是仓库级文档,不是 engram —— 例如 README 是 quickstart 教用户创建的文件。
+ * doctor 不会把它们报为 orphan_markdown。
+ */
+const SKIP_MARKDOWN_FILENAMES = new Set([
+    "readme.md",
+    "license.md",
+    "contributing.md",
+    "changelog.md",
+    "code_of_conduct.md",
+    "security.md",
+]);
+/** engram-index.json 完整路径 */
+export function engramIndexPath(dataRoot) {
+    return join(dataRoot, CO_ENGRAM_CACHE_DIR, ENGRAM_INDEX_FILENAME);
+}
+/** 创建空 index */
+export function createEmptyEngramIndex() {
+    return {
+        version: 1,
+        entries: new Map(),
+        lastRebuiltAt: new Date().toISOString(),
+    };
+}
+/**
+ * 从磁盘读取 index;不存在或损坏返回空 index。
+ */
+export function readEngramIndex(dataRoot) {
+    const path = engramIndexPath(dataRoot);
+    if (!existsSync(path))
+        return createEmptyEngramIndex();
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        const entries = new Map();
+        if (parsed.engrams && typeof parsed.engrams === "object") {
+            for (const [key, value] of Object.entries(parsed.engrams)) {
+                if (isStableEngramId(key) && value) {
+                    entries.set(key, value);
+                }
+            }
+        }
+        return {
+            version: 1,
+            entries,
+            lastRebuiltAt: parsed.lastRebuiltAt ?? new Date().toISOString(),
+        };
+    }
+    catch {
+        return createEmptyEngramIndex();
+    }
+}
+/**
+ * 落盘 index(gitignore,但结构稳定以便人类 debug)。
+ */
+export function writeEngramIndex(dataRoot, index) {
+    const path = engramIndexPath(dataRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    const engramsObj = {};
+    for (const [key, value] of index.entries) {
+        engramsObj[key] = value;
+    }
+    const data = {
+        version: 1,
+        engrams: engramsObj,
+        lastRebuiltAt: new Date().toISOString(),
+    };
+    writeFileSync(path, JSON.stringify(data, null, 2), "utf8");
+}
+/**
+ * 从单条 engram 文件构建 index entry。
+ *
+ * - slug:frontmatter 显式则锁定,否则从 title slugify
+ * - domainTags:frontmatter 显式则锁定,否则从路径推断
+ * - mtime / contentHash 必须由调用者传入
+ */
+export function buildIndexEntryFromFrontmatter(params) {
+    const { relativePath, frontmatter, mtime, contentHash } = params;
+    const hasExplicitSlug = typeof frontmatter.slug === "string" && frontmatter.slug.length > 0;
+    const slug = hasExplicitSlug ? frontmatter.slug : slugify(frontmatter.title);
+    const hasExplicitDomainTags = Array.isArray(frontmatter.domainTags) && frontmatter.domainTags.length > 0;
+    const domainTags = hasExplicitDomainTags
+        ? [...frontmatter.domainTags]
+        : inferDomainTagsFromPath(relativePath);
+    return {
+        id: frontmatter.id,
+        path: relativePath,
+        title: frontmatter.title,
+        slug,
+        slugLocked: hasExplicitSlug,
+        domainTags,
+        domainTagsLocked: hasExplicitDomainTags,
+        tags: Array.isArray(frontmatter.tags) ? [...frontmatter.tags] : [],
+        kind: frontmatter.kind,
+        verificationStatus: frontmatter.verificationStatus,
+        createdAt: frontmatter.createdAt,
+        updatedAt: frontmatter.updatedAt,
+        mtime,
+        contentHash,
+    };
+}
+/**
+ * 扫描 dataRoot 下所有 .md,构建 engram-index。
+ *
+ * 规则:
+ * - 跳过 SKIP_DIRECTORIES 中的目录(.co-engram, node_modules, .git, synapses)
+ * - 无 frontmatter 的 .md 跳过(由 doctor 报告为 orphan_markdown)
+ * - frontmatter 缺 id 的 .md 跳过(由 doctor 报告为 orphan_markdown)
+ */
+export function rebuildEngramIndex(dataRoot, onOrphan) {
+    const index = createEmptyEngramIndex();
+    function walk(currentDir, relativeDir) {
+        let entries;
+        try {
+            entries = readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (SKIP_DIRECTORIES.has(entry.name))
+                continue;
+            const absolutePath = join(currentDir, entry.name);
+            const relativePath = relativeDir.length === 0 ? entry.name : `${relativeDir}/${entry.name}`;
+            if (entry.isDirectory()) {
+                walk(absolutePath, relativePath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (!entry.name.endsWith(".md"))
+                continue;
+            if (SKIP_MARKDOWN_FILENAMES.has(entry.name.toLowerCase()))
+                continue;
+            try {
+                const raw = readFileSync(absolutePath, "utf8");
+                if (!isEngramFile(raw)) {
+                    onOrphan?.(relativePath);
+                    continue;
+                }
+                const parsed = parseEngramFile(raw);
+                const stat = statSync(absolutePath);
+                const entryRecord = buildIndexEntryFromFrontmatter({
+                    relativePath,
+                    frontmatter: parsed.frontmatter,
+                    mtime: stat.mtimeMs,
+                    contentHash: parsed.frontmatter.contentHash ?? "",
+                });
+                index.entries.set(entryRecord.id, entryRecord);
+            }
+            catch {
+                onOrphan?.(relativePath);
+            }
+        }
+    }
+    walk(dataRoot, "");
+    index.lastRebuiltAt = new Date().toISOString();
+    return index;
+}
+/**
+ * 增量更新:仅更新单条 engram 的 index entry。
+ */
+export function upsertEngramIndexEntry(index, entry) {
+    index.entries.set(entry.id, entry);
+    return index;
+}
+/**
+ * 从 index 中删除一条 engram。
+ */
+export function removeEngramIndexEntry(index, id) {
+    return index.entries.delete(id);
+}
+/**
+ * 按 path 查 stableId(用于 doctor 检测文件移动)。
+ */
+export function findEngramIdByPath(index, relativePath) {
+    for (const entry of index.entries.values()) {
+        if (entry.path === relativePath)
+            return entry.id;
+    }
+    return undefined;
+}
+//# sourceMappingURL=engram-index.js.map

package/dist/storage/engram-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engram-index.js","sourceRoot":"","sources":["../../src/storage/engram-index.ts"],"names":[],"mappings":"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"}

package/dist/storage/engram-store.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Engram 单文件存储(frontmatter + content)
+ *
+ * 设计要点:
+ * - 单文件:meta 字段进 frontmatter,content 跟在后面(英文)或前面(中文)
+ * - ULID 作为 stable id(永不变),与路径解耦
+ * - 文件可放在任意多层目录,slug 是文件名(可被 frontmatter 锁定)
+ *
+ * ## 双语双位置格式
+ *
+ * ### 英文模式(legacy,默认):
+ * ```
+ * ---
+ * id: 01JXKA9F8S7TQN8C9V2F3M4P5
+ * title: ...
+ * kind: observation
+ * ...
+ * ---
+ *
+ * <content>
+ * ```
+ *
+ * ### 中文模式(language='zh'):
+ * ```
+ * <content>
+ *
+ * <!-- co-engram-meta:zh -->
+ * ---
+ * 标识: 01JXKA9F8S7TQN8C9V2F3M4P5
+ * 标题: ...
+ * 类型: observation
+ * ...
+ * __语言: zh
+ * ---
+ * ```
+ *
+ * 中文模式的字段名按 `ENGRAM_FIELD_MAP.zh` 映射;`__语言: zh` 是保留标记,
+ * 解析时剥离,不进入运行时 `Engram` 对象。
+ *
+ * 解析器(`parseEngramFile`)自动检测两种格式并归一化为运行时英文 keys,
+ * 因此旧文件无需迁移即可读取。
+ *
+ * @module @co-engram/core/storage
+ */
+import type { EngramKind, EmotionalValence, EngramSourceType, EngramVisibility, VerificationStatus } from "../types/engram.js";
+import type { StableEngramId } from "../types/repository-types.js";
+import type { Language } from "../i18n/types.js";
+/** Frontmatter 字段 */
+export interface EngramFrontmatter {
+    /** Stable engram id (ULID) */
+    readonly id: StableEngramId;
+    readonly title: string;
+    /** 显式 slug(锁定);不存在则从 title slugify */
+    readonly slug?: string;
+    /** 显式 domainTags(锁定);不存在则从路径推断 */
+    readonly domainTags?: readonly string[];
+    readonly kind: EngramKind;
+    readonly kinds?: readonly EngramKind[];
+    readonly tags?: readonly string[];
+    readonly summary?: string;
+    readonly contentHash?: string;
+    readonly contentSize?: number;
+    readonly createdBy: string;
+    readonly createdAt: string;
+    readonly updatedBy: string;
+    readonly updatedAt: string;
+    readonly version: number;
+    readonly importance?: number;
+    readonly confidence?: number;
+    readonly emotionalValence?: EmotionalValence;
+    readonly sourceType?: EngramSourceType;
+    readonly evidenceCount?: number;
+    readonly retrievalCount?: number;
+    readonly effectiveRetrievals?: number;
+    readonly failedUses?: number;
+    readonly reinforcementScore?: number;
+    readonly decayHalfLifeDays?: number | null;
+    readonly lastRetrievedAt?: string;
+    readonly lastEffectiveAt?: string;
+    readonly lastRetrievalScore?: number;
+    /** 显式锁定的 freshness(优先于派生);仅当 lifecycle 工具强制切换时设置 */
+    readonly forcedFreshness?: "fresh" | "aging" | "stale" | "forgotten";
+    readonly status?: "draft" | "active" | "archived" | "forgotten";
+    readonly visibility?: EngramVisibility;
+    readonly verificationStatus?: VerificationStatus;
+    readonly encodingContext?: string;
+    readonly perspective?: string;
+    readonly contextTags?: readonly string[];
+    /** 其他扩展字段 */
+    readonly [key: string]: unknown;
+}
+/** Engram 单文件结构 */
+export interface EngramFile {
+    readonly frontmatter: EngramFrontmatter;
+    readonly content: string;
+}
+/**
+ * 序列化为 frontmatter + content 的 markdown。
+ *
+ * - `language='en'`(默认):顶部 frontmatter + 英文字段名(legacy 格式)
+ * - `language='zh'`:正文在前 + 底部 frontmatter + 中文字段名 + `__语言: zh` 标记
+ *
+ * 默认 `'en'` 保证未传 language 的现有调用零破坏。
+ */
+export declare function serializeEngramFile(file: EngramFile, language?: Language): string;
+/**
+ * 解析单文件,自动检测格式(顶部/底部、中文/英文)。
+ *
+ * 检测顺序:
+ * 1. 开头是 `---\n` → 顶部 frontmatter(英文 legacy 或未来中文顶部)
+ * 2. 否则若含 `<!-- co-engram-meta:` 标记 → 底部 frontmatter(中文)
+ * 3. 否则抛错
+ *
+ * 解析后:
+ * - 反向归一化磁盘 keys 为运行时英文 keys(自动检测中文 keys)
+ * - 剥离语言标记字段(`__lang` / `__语言`)
+ * - 验证 id/title 存在
+ *
+ * 解析失败抛 Error(不静默回退,人类错误由 doctor 报告)。
+ */
+export declare function parseEngramFile(raw: string): EngramFile;
+/** 读取 engram 文件 */
+export declare function readEngramFile(filePath: string): EngramFile;
+/** 写入 engram 文件(自动创建父目录);language 决定磁盘格式 */
+export declare function writeEngramFile(filePath: string, file: EngramFile, language?: Language): void;
+/** 删除 engram 文件 */
+export declare function deleteEngramFile(filePath: string): void;
+/** 原子重命名(用于 doctor 修复文件路径) */
+export declare function renameEngramFile(oldPath: string, newPath: string): void;
+/**
+ * 检查文件是否是 engram(顶部 `---` + 有效 frontmatter,或含底部 meta marker)。
+ *
+ * 用于 doctor 扫描时区分:
+ * - 单文件 frontmatter 的 engram
+ * - 普通 markdown(无 frontmatter,提示注册为 engram)
+ */
+export declare function isEngramFile(raw: string): boolean;
+/**
+ * 检测已序列化文件的磁盘 language(供迁移逻辑判断是否需重写)。
+ *
+ * 返回:
+ * - `'zh'` — 底部 frontmatter(中文模式)
+ * - `'en'` — 顶部 frontmatter 且无中文标记(英文模式)
+ * - `undefined` — 不是有效 engram 文件
+ */
+export declare function detectEngramFileLanguage(raw: string): Language | undefined;
+//# sourceMappingURL=engram-store.d.ts.map

package/dist/storage/engram-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engram-store.d.ts","sourceRoot":"","sources":["../../src/storage/engram-store.ts"],"names":[],"mappings":"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"}

package/dist/storage/engram-store.js

@@ -0,0 +1,221 @@
+/**
+ * Engram 单文件存储(frontmatter + content)
+ *
+ * 设计要点:
+ * - 单文件:meta 字段进 frontmatter,content 跟在后面(英文)或前面(中文)
+ * - ULID 作为 stable id(永不变),与路径解耦
+ * - 文件可放在任意多层目录,slug 是文件名(可被 frontmatter 锁定)
+ *
+ * ## 双语双位置格式
+ *
+ * ### 英文模式(legacy,默认):
+ * ```
+ * ---
+ * id: 01JXKA9F8S7TQN8C9V2F3M4P5
+ * title: ...
+ * kind: observation
+ * ...
+ * ---
+ *
+ * <content>
+ * ```
+ *
+ * ### 中文模式(language='zh'):
+ * ```
+ * <content>
+ *
+ * <!-- co-engram-meta:zh -->
+ * ---
+ * 标识: 01JXKA9F8S7TQN8C9V2F3M4P5
+ * 标题: ...
+ * 类型: observation
+ * ...
+ * __语言: zh
+ * ---
+ * ```
+ *
+ * 中文模式的字段名按 `ENGRAM_FIELD_MAP.zh` 映射;`__语言: zh` 是保留标记,
+ * 解析时剥离,不进入运行时 `Engram` 对象。
+ *
+ * 解析器(`parseEngramFile`)自动检测两种格式并归一化为运行时英文 keys,
+ * 因此旧文件无需迁移即可读取。
+ *
+ * @module @co-engram/core/storage
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync, renameSync, } from "node:fs";
+import { dirname } from "node:path";
+import { parse, stringify } from "yaml";
+import { DEFAULT_LANGUAGE } from "../i18n/index.js";
+import { ENGRAM_FIELD_MAP, ENGRAM_FIELD_REVERSE_MAP, delocalizeKeys, detectChineseKeys, localizeKeys, } from "../i18n/field-names.js";
+const FRONTMATTER_DELIMITER = "---";
+/**
+ * 底部 frontmatter 的开场 HTML 注释标记
+ *
+ * 形式:`<!-- co-engram-meta:<lang> -->`(`:zh` / `:en`)
+ * 解析时容忍缺失 lang 后缀(向后兼容),允许任何后缀值。
+ * 注释行让 markdown 渲染器忽略,人类阅读时不被干扰。
+ */
+const BOTTOM_META_MARKER_RE = /<!--[ \t]*co-engram-meta:?[a-z]*[ \t]*-->\s*\n/;
+/**
+ * 序列化为 frontmatter + content 的 markdown。
+ *
+ * - `language='en'`(默认):顶部 frontmatter + 英文字段名(legacy 格式)
+ * - `language='zh'`:正文在前 + 底部 frontmatter + 中文字段名 + `__语言: zh` 标记
+ *
+ * 默认 `'en'` 保证未传 language 的现有调用零破坏。
+ */
+export function serializeEngramFile(file, language = DEFAULT_LANGUAGE) {
+    const body = file.content.replace(/^\n+/, "").replace(/\n+$/, "");
+    if (language === "zh") {
+        const localized = localizeKeys(file.frontmatter, "zh", ENGRAM_FIELD_MAP, {
+            attachLangMarker: true,
+        });
+        const yamlStr = stringify(localized, { lineWidth: 0 });
+        const yamlTrimmed = yamlStr.endsWith("\n") ? yamlStr : yamlStr + "\n";
+        return `${body}\n\n<!-- co-engram-meta:zh -->\n${FRONTMATTER_DELIMITER}\n${yamlTrimmed}${FRONTMATTER_DELIMITER}\n`;
+    }
+    const yamlStr = stringify(file.frontmatter, { lineWidth: 0 });
+    const yamlTrimmed = yamlStr.endsWith("\n") ? yamlStr : yamlStr + "\n";
+    return `${FRONTMATTER_DELIMITER}\n${yamlTrimmed}${FRONTMATTER_DELIMITER}\n\n${body}\n`;
+}
+/**
+ * 解析单文件,自动检测格式(顶部/底部、中文/英文)。
+ *
+ * 检测顺序:
+ * 1. 开头是 `---\n` → 顶部 frontmatter(英文 legacy 或未来中文顶部)
+ * 2. 否则若含 `<!-- co-engram-meta:` 标记 → 底部 frontmatter(中文)
+ * 3. 否则抛错
+ *
+ * 解析后:
+ * - 反向归一化磁盘 keys 为运行时英文 keys(自动检测中文 keys)
+ * - 剥离语言标记字段(`__lang` / `__语言`)
+ * - 验证 id/title 存在
+ *
+ * 解析失败抛 Error(不静默回退,人类错误由 doctor 报告)。
+ */
+export function parseEngramFile(raw) {
+    // 检测格式:顶部 vs 底部
+    let yamlText;
+    let body;
+    if (raw.startsWith(FRONTMATTER_DELIMITER)) {
+        // 顶部 frontmatter(legacy en 或顶部的 zh)
+        const closeMarker = `\n${FRONTMATTER_DELIMITER}\n`;
+        const closeIndex = raw.indexOf(closeMarker, FRONTMATTER_DELIMITER.length);
+        if (closeIndex === -1) {
+            throw new Error("Invalid engram file: missing closing frontmatter delimiter");
+        }
+        const yamlStart = FRONTMATTER_DELIMITER.length + 1;
+        yamlText = raw.slice(yamlStart, closeIndex);
+        const bodyRaw = raw.slice(closeIndex + closeMarker.length);
+        body = bodyRaw.replace(/^\n+/, "").replace(/\n+$/, "");
+    }
+    else {
+        // 底部 frontmatter:查找 `<!-- co-engram-meta -->` 标记
+        const markerMatch = raw.match(BOTTOM_META_MARKER_RE);
+        if (!markerMatch || markerMatch.index === undefined) {
+            throw new Error("Invalid engram file: missing frontmatter (expected leading `---` or `<!-- co-engram-meta -->` marker)");
+        }
+        const yamlRegionStart = markerMatch.index + markerMatch[0].length;
+        const rest = raw.slice(yamlRegionStart);
+        if (!rest.startsWith(FRONTMATTER_DELIMITER)) {
+            throw new Error("Invalid engram file: bottom meta marker not followed by `---`");
+        }
+        const closeMarker = `\n${FRONTMATTER_DELIMITER}\n`;
+        const closeIndex = rest.indexOf(closeMarker, FRONTMATTER_DELIMITER.length);
+        if (closeIndex === -1) {
+            throw new Error("Invalid engram file: missing closing bottom frontmatter delimiter");
+        }
+        const yamlStart = FRONTMATTER_DELIMITER.length;
+        yamlText = rest.slice(yamlStart, closeIndex);
+        const bodyRaw = raw.slice(0, markerMatch.index);
+        body = bodyRaw.replace(/^\n+/, "").replace(/\n+$/, "");
+    }
+    const parsed = parse(yamlText);
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error("Invalid engram file: frontmatter is not an object");
+    }
+    const rawObj = parsed;
+    const { normalized } = delocalizeKeys(rawObj, ENGRAM_FIELD_REVERSE_MAP);
+    // 兜底:如果反向索引未识别出中文 keys(老版数据没有 __语言 标记),
+    // 检测 raw 顶层是否含中文 key 并尝试归一化。delocalizeKeys 已用反向索引覆盖,
+    // 这里只是确保未来添加新字段时不会丢失。
+    void detectChineseKeys; // 保留导入以便未来扩展(启发式检测目前由 delocalizeKeys 覆盖)
+    const frontmatter = normalized;
+    if (typeof frontmatter.id !== "string" || frontmatter.id.length === 0) {
+        throw new Error("Invalid engram file: frontmatter missing id");
+    }
+    if (typeof frontmatter.title !== "string") {
+        throw new Error("Invalid engram file: frontmatter missing title");
+    }
+    return { frontmatter, content: body };
+}
+/** 读取 engram 文件 */
+export function readEngramFile(filePath) {
+    const raw = readFileSync(filePath, "utf8");
+    return parseEngramFile(raw);
+}
+/** 写入 engram 文件(自动创建父目录);language 决定磁盘格式 */
+export function writeEngramFile(filePath, file, language = DEFAULT_LANGUAGE) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, serializeEngramFile(file, language), "utf8");
+}
+/** 删除 engram 文件 */
+export function deleteEngramFile(filePath) {
+    if (existsSync(filePath)) {
+        unlinkSync(filePath);
+    }
+}
+/** 原子重命名(用于 doctor 修复文件路径) */
+export function renameEngramFile(oldPath, newPath) {
+    mkdirSync(dirname(newPath), { recursive: true });
+    renameSync(oldPath, newPath);
+}
+/**
+ * 检查文件是否是 engram(顶部 `---` + 有效 frontmatter,或含底部 meta marker)。
+ *
+ * 用于 doctor 扫描时区分:
+ * - 单文件 frontmatter 的 engram
+ * - 普通 markdown(无 frontmatter,提示注册为 engram)
+ */
+export function isEngramFile(raw) {
+    // 快速路径:顶部 frontmatter
+    if (raw.startsWith(FRONTMATTER_DELIMITER)) {
+        try {
+            parseEngramFile(raw);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // 底部 frontmatter:必须含 marker
+    if (BOTTOM_META_MARKER_RE.test(raw)) {
+        try {
+            parseEngramFile(raw);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * 检测已序列化文件的磁盘 language(供迁移逻辑判断是否需重写)。
+ *
+ * 返回:
+ * - `'zh'` — 底部 frontmatter(中文模式)
+ * - `'en'` — 顶部 frontmatter 且无中文标记(英文模式)
+ * - `undefined` — 不是有效 engram 文件
+ */
+export function detectEngramFileLanguage(raw) {
+    if (!isEngramFile(raw))
+        return undefined;
+    // 底部 marker 表示 zh
+    if (BOTTOM_META_MARKER_RE.test(raw) &&
+        !raw.startsWith(FRONTMATTER_DELIMITER)) {
+        return "zh";
+    }
+    return "en";
+}
+//# sourceMappingURL=engram-store.js.map

package/dist/storage/engram-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engram-store.js","sourceRoot":"","sources":["../../src/storage/engram-store.ts"],"names":[],"mappings":"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"}

package/dist/storage/git-stage.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Git 暂存与提交消息生成（P0-C 规范化提交）
+ *
+ * 提供：
+ *   - stageChanges: 根据 engramIds 收集对应三文件路径
+ *   - generateCommitMessage: 分析暂存文件，生成规范化提交消息
+ *   - assessChangeRisk: 根据 synapse 类型评估变更风险
+ *
+ * @module @co-engram/core/storage
+ */
+import type { SynapseKind } from "../types/synapse.js";
+/** 提交消息信息 */
+export interface CommitInfo {
+    /** 完整提交消息 */
+    readonly message: string;
+    /** 变更类型 */
+    readonly kind: "create" | "update" | "delete" | "mixed";
+    /** 涉及的 engram 数量 */
+    readonly engramCount: number;
+}
+/** 风险等级 */
+export type ChangeRisk = "low" | "medium" | "high";
+/** 变更风险评估结果 */
+export interface ChangeRiskAssessment {
+    readonly risk: ChangeRisk;
+    readonly reasons: readonly string[];
+}
+/**
+ * 将 engramIds 转换为三文件路径列表
+ *
+ * @param engramIds - 相对路径形式的 engram ID 列表
+ * @returns 相对 rootPath 的文件路径数组（每个 engram 对应 3 个文件）
+ */
+export declare function stageChanges(engramIds: readonly string[]): string[];
+/**
+ * 生成规范化提交消息
+ *
+ * 形如：`co-engram: 新增[设备ADB调试方法]及3条连接(supersedes, depends_on)`
+ *
+ * P0 简化版：只基于文件路径数量生成消息，不解析实际内容。
+ * P1+ 版本会读 YAML 提取 title/kind/synapse kinds 生成更详细消息。
+ */
+export declare function generateCommitMessage(stagedFiles: readonly string[], options?: {
+    title?: string;
+    synapseKinds?: readonly SynapseKind[];
+}): CommitInfo;
+/**
+ * 评估变更风险
+ *
+ * 规则（来自设计文档 §八）：
+ *   低风险：新增 extends/similar_to/exemplifies/contextualizes/consolidates
+ *   中风险：新增 depends_on/causes/follows/derives_from/part_of
+ *   高风险：新增 contradicts/supersedes 或删除已有连接
+ */
+export declare function assessChangeRisk(synapseKinds: readonly SynapseKind[], hasDeletions: boolean): ChangeRiskAssessment;
+//# sourceMappingURL=git-stage.d.ts.map

package/dist/storage/git-stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-stage.d.ts","sourceRoot":"","sources":["../../src/storage/git-stage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,aAAa;AACb,MAAM,WAAW,UAAU;IACzB,aAAa;IACb,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,WAAW;IACX,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IACxD,oBAAoB;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,WAAW;AACX,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEnD,eAAe;AACf,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAiBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAOnE;AAgDD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,SAAS,WAAW,EAAE,CAAA;CAAE,GAClE,UAAU,CA4BZ;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,SAAS,WAAW,EAAE,EACpC,YAAY,EAAE,OAAO,GACpB,oBAAoB,CAmCtB"}