@co-engram/core 0.1.0 → 0.1.1

package/dist/merge/post-merge-hook.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Post-merge git hook installer + runner (spec §7.5).
+ *
+ * Git 在 `git pull` / `git merge` 完成后会触发 `.git/hooks/post-merge`。
+ * 我们利用它跑一次跨文件一致性 check,捕捉 merge driver 看不到的
+ * 跨文件状态不一致(spec §7.3)。
+ *
+ * 设计要点:
+ *   1. installer 写一个**幂等**的 shell 脚本,不依赖具体路径
+ *   2. 脚本调用 `node <co-engram-cli>` 跑 runCrossFileConsistency
+ *   3. 失败/缺失不影响 git 操作(exit 0);不一致通过 audit log + stderr 提示
+ *   4. CLI 找不到时静默跳过(zero-friction:不影响普通 git pull)
+ *
+ * @module @co-engram/core/merge
+ */
+/** Marker 让我们识别已安装的 hook(避免覆盖用户自定义 hook)。 */
+export declare const HOOK_MARKER = "# co-engram-post-merge-hook";
+/** Hook 在仓库中的相对路径(相对于 repoRoot)。 */
+export declare const HOOK_RELATIVE_PATH = ".git/hooks/post-merge";
+export interface InstallPostMergeHookResult {
+    /** Hook 写入的绝对路径。 */
+    readonly hookPath: string;
+    /** True = 本次新建;False = 已存在且被覆盖(用户上次手改过或重装)。 */
+    readonly overwritten: boolean;
+}
+/**
+ * 在 repoRoot 中安装 `.git/hooks/post-merge` 钩子。
+ *
+ * 行为:
+ *   - .git/hooks 目录不存在 → 创建
+ *   - hook 不存在 → 写入
+ *   - hook 存在且包含 HOOK_MARKER → 覆盖(平滑升级)
+ *   - hook 存在但不含 HOOK_MARKER → **不覆盖**,把新内容写到 `.post-merge.co-engram`,
+ *     并提示用户手动合并(保护用户的自定义 hook)
+ */
+export declare function installPostMergeHook(params: {
+    repoRoot: string;
+}): InstallPostMergeHookResult;
+/**
+ * 卸载 post-merge hook(仅当我们安装的)。
+ *
+ * 如果 hook 不含 HOOK_MARKER,不操作(用户自定义)。
+ */
+export declare function uninstallPostMergeHook(params: {
+    repoRoot: string;
+}): {
+    removed: boolean;
+};
+export interface PostMergeHookStatus {
+    readonly installed: boolean;
+    /** True = 主 hook 是我们的;False = 主 hook 是用户的,但有 sidecar。 */
+    readonly atPrimaryPath: boolean;
+    readonly hookPath: string;
+}
+/** 检查 post-merge hook 是否已安装。 */
+export declare function getPostMergeHookStatus(params: {
+    repoRoot: string;
+}): PostMergeHookStatus;
+export interface PostMergeRunResult {
+    readonly dataRoot: string | null;
+    readonly inconsistencies: number;
+    readonly autoFixed: number;
+    readonly escalated: number;
+    readonly durationMs: number;
+    /** 数据根未找到 / repository 构建失败等错误。 */
+    readonly error?: string;
+}
+/**
+ * Post-merge runner:发现数据根 → 构建 repository → 跑 cross-file check。
+ *
+ * 设计为 CLI 友好:失败不抛(写 error 字段),返回值有结构化结果。
+ * 调用方(CLI)负责把它格式化成 stdout/stderr 文本。
+ */
+export declare function runPostMergeCheck(params: {
+    cwd: string;
+}): Promise<PostMergeRunResult>;
+//# sourceMappingURL=post-merge-hook.d.ts.map

package/dist/merge/post-merge-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-merge-hook.d.ts","sourceRoot":"","sources":["../../src/merge/post-merge-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAaH,6CAA6C;AAC7C,eAAO,MAAM,WAAW,gCAAgC,CAAC;AAEzD,oCAAoC;AACpC,eAAO,MAAM,kBAAkB,0BAA0B,CAAC;AAmC1D,MAAM,WAAW,0BAA0B;IACzC,oBAAoB;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,0BAA0B,CAoB7B;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG;IACpE,OAAO,EAAE,OAAO,CAAC;CAClB,CAYA;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,gCAAgC;AAChC,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,mBAAmB,CActB;AAMD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE;IAC9C,GAAG,EAAE,MAAM,CAAC;CACb,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAkE9B"}

package/dist/merge/post-merge-hook.js

@@ -0,0 +1,211 @@
+/**
+ * Post-merge git hook installer + runner (spec §7.5).
+ *
+ * Git 在 `git pull` / `git merge` 完成后会触发 `.git/hooks/post-merge`。
+ * 我们利用它跑一次跨文件一致性 check,捕捉 merge driver 看不到的
+ * 跨文件状态不一致(spec §7.3)。
+ *
+ * 设计要点:
+ *   1. installer 写一个**幂等**的 shell 脚本,不依赖具体路径
+ *   2. 脚本调用 `node <co-engram-cli>` 跑 runCrossFileConsistency
+ *   3. 失败/缺失不影响 git 操作(exit 0);不一致通过 audit log + stderr 提示
+ *   4. CLI 找不到时静默跳过(zero-friction:不影响普通 git pull)
+ *
+ * @module @co-engram/core/merge
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { findDataRoot } from "./data-root.js";
+import { runCrossFileConsistency } from "./cross-file-coordinator.js";
+import { EngramRepository } from "../storage/repository.js";
+import { AuditLog } from "../observability/audit-log.js";
+import { createDriverLlmClient } from "./driver-llm.js";
+import { LlmArbiter } from "./llm-arbiter.js";
+/** Marker 让我们识别已安装的 hook(避免覆盖用户自定义 hook)。 */
+export const HOOK_MARKER = "# co-engram-post-merge-hook";
+/** Hook 在仓库中的相对路径(相对于 repoRoot)。 */
+export const HOOK_RELATIVE_PATH = ".git/hooks/post-merge";
+/**
+ * 模板 shell 脚本。
+ *
+ * 策略:
+ *   1. 找到 co-engram CLI(尝试 PATH 中的 `co-engram`,然后 `npx co-engram`)
+ *   2. 跑 `co-engram post-merge --cwd <cwd>`
+ *   3. 任何错误都 exit 0(绝不阻塞 git)
+ *
+ * 注:模板里用 `${CO_ENGRAM_CLI}` 占位,installer 写入时替换。
+ */
+const HOOK_TEMPLATE = `#!/bin/sh
+${HOOK_MARKER}
+# Auto-installed by @co-engram/core. Runs cross-file consistency check.
+# Safe to remove. Will NOT be re-installed unless you run install again.
+
+# 找 co-engram CLI:PATH 优先,fallback 到 npx
+CO_ENGRAM_CLI=""
+if command -v co-engram >/dev/null 2>&1; then
+  CO_ENGRAM_CLI="co-engram"
+elif command -v npx >/dev/null 2>&1; then
+  CO_ENGRAM_CLI="npx --no-install co-engram"
+fi
+
+# CLI 不可用 → 静默退出(不阻塞 git,不刷屏)
+if [ -z "$CO_ENGRAM_CLI" ]; then
+  exit 0
+fi
+
+# 跑 post-merge check(任何错误都吞掉,只 stderr 提示)
+"$CO_ENGRAM_CLI" post-merge --cwd "$(pwd)" 2>&1 | sed 's/^/[co-engram] /' >&2 || true
+exit 0
+`;
+/**
+ * 在 repoRoot 中安装 `.git/hooks/post-merge` 钩子。
+ *
+ * 行为:
+ *   - .git/hooks 目录不存在 → 创建
+ *   - hook 不存在 → 写入
+ *   - hook 存在且包含 HOOK_MARKER → 覆盖(平滑升级)
+ *   - hook 存在但不含 HOOK_MARKER → **不覆盖**,把新内容写到 `.post-merge.co-engram`,
+ *     并提示用户手动合并(保护用户的自定义 hook)
+ */
+export function installPostMergeHook(params) {
+    const { repoRoot } = params;
+    const hookPath = join(repoRoot, HOOK_RELATIVE_PATH);
+    const hookDir = dirname(hookPath);
+    if (!existsSync(hookDir)) {
+        mkdirSync(hookDir, { recursive: true });
+    }
+    const existing = existsSync(hookPath) ? readFileSync(hookPath, "utf8") : null;
+    if (existing !== null && !existing.includes(HOOK_MARKER)) {
+        // 用户已有自定义 hook — 旁挂一份,不动原 hook
+        const sidecarPath = join(hookDir, "post-merge.co-engram");
+        writeFileSync(sidecarPath, HOOK_TEMPLATE, { mode: 0o755 });
+        return { hookPath: sidecarPath, overwritten: false };
+    }
+    writeFileSync(hookPath, HOOK_TEMPLATE, { mode: 0o755 });
+    return { hookPath, overwritten: existing !== null };
+}
+/**
+ * 卸载 post-merge hook(仅当我们安装的)。
+ *
+ * 如果 hook 不含 HOOK_MARKER,不操作(用户自定义)。
+ */
+export function uninstallPostMergeHook(params) {
+    const { repoRoot } = params;
+    const hookPath = join(repoRoot, HOOK_RELATIVE_PATH);
+    if (!existsSync(hookPath))
+        return { removed: false };
+    const content = readFileSync(hookPath, "utf8");
+    if (!content.includes(HOOK_MARKER))
+        return { removed: false };
+    try {
+        execSync(`rm -f ${JSON.stringify(hookPath)}`);
+        return { removed: true };
+    }
+    catch {
+        return { removed: false };
+    }
+}
+/** 检查 post-merge hook 是否已安装。 */
+export function getPostMergeHookStatus(params) {
+    const { repoRoot } = params;
+    const hookPath = join(repoRoot, HOOK_RELATIVE_PATH);
+    if (existsSync(hookPath)) {
+        const content = readFileSync(hookPath, "utf8");
+        if (content.includes(HOOK_MARKER)) {
+            return { installed: true, atPrimaryPath: true, hookPath };
+        }
+    }
+    const sidecar = join(dirname(hookPath), "post-merge.co-engram");
+    if (existsSync(sidecar)) {
+        return { installed: true, atPrimaryPath: false, hookPath: sidecar };
+    }
+    return { installed: false, atPrimaryPath: false, hookPath };
+}
+/**
+ * Post-merge runner:发现数据根 → 构建 repository → 跑 cross-file check。
+ *
+ * 设计为 CLI 友好:失败不抛(写 error 字段),返回值有结构化结果。
+ * 调用方(CLI)负责把它格式化成 stdout/stderr 文本。
+ */
+export async function runPostMergeCheck(params) {
+    const { cwd } = params;
+    const dataRoot = findDataRoot(resolve(cwd));
+    if (!dataRoot) {
+        return {
+            dataRoot: null,
+            inconsistencies: 0,
+            autoFixed: 0,
+            escalated: 0,
+            durationMs: 0,
+        };
+    }
+    const startedAt = Date.now();
+    let repo;
+    try {
+        repo = new EngramRepository({
+            rootPath: dataRoot,
+            language: detectLanguage(dataRoot),
+        });
+    }
+    catch (e) {
+        return {
+            dataRoot,
+            inconsistencies: 0,
+            autoFixed: 0,
+            escalated: 0,
+            durationMs: Date.now() - startedAt,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+    const auditLog = new AuditLog(dataRoot);
+    // 复用 driver 的 LLM bootstrap(可选)
+    const llmBootstrap = createDriverLlmClient();
+    const llmArbiter = llmBootstrap
+        ? new LlmArbiter({
+            client: llmBootstrap.client,
+            auditLog,
+            providerName: llmBootstrap.config.model,
+        })
+        : undefined;
+    try {
+        const report = await runCrossFileConsistency({
+            repository: repo,
+            auditLog,
+            llmArbiter,
+        });
+        return {
+            dataRoot,
+            inconsistencies: report.inconsistencies.length,
+            autoFixed: report.autoFixedCount,
+            escalated: report.llmEscalatedCount,
+            durationMs: Date.now() - startedAt,
+        };
+    }
+    catch (e) {
+        return {
+            dataRoot,
+            inconsistencies: 0,
+            autoFixed: 0,
+            escalated: 0,
+            durationMs: Date.now() - startedAt,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+}
+/**
+ * 从数据根探测语言。读 `.co-engram/config.json`,失败默认 'en'。
+ */
+function detectLanguage(dataRoot) {
+    try {
+        const configPath = join(dataRoot, ".co-engram", "config.json");
+        if (!existsSync(configPath))
+            return "en";
+        const config = JSON.parse(readFileSync(configPath, "utf8"));
+        return config.language ?? "en";
+    }
+    catch {
+        return "en";
+    }
+}
+//# sourceMappingURL=post-merge-hook.js.map

package/dist/merge/post-merge-hook.js.map

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

package/dist/merge/resolution-state.d.ts

@@ -0,0 +1,41 @@
+/**
+ * resolutionState state-machine merge (spec §6.3).
+ *
+ * Contradicts synapse three-phase lifecycle:
+ *   pending → auto_resolved / escalated → contested → resolved
+ *
+ * Merge rules:
+ *   1. ours == theirs → use either
+ *   2. one side absent → use the one present
+ *   3. phases differ → higher phase wins (closer to resolution)
+ *   4. phases equal → higher priority status wins
+ *      priority = { resolved: 4, escalated: 3, auto_resolved: 2, contested: 2, pending: 1 }
+ *   5. on override: append loser's rationale as evidence for the winner
+ *
+ * @module @co-engram/core/merge
+ */
+import type { SynapseResolutionState, SynapseResolutionStatus } from "../types/synapse.js";
+export declare const RESOLUTION_STATUS_PRIORITY: Record<SynapseResolutionStatus, number>;
+export type ResolutionMergeStrategy = "all-absent" | "one-side-absent" | "same-status" | "higher-phase" | "higher-priority-status" | "tie-keep-ours";
+export interface LoserRationale {
+    readonly fromStatus: SynapseResolutionStatus;
+    readonly fromPhase: 1 | 2 | 3;
+    readonly rationale: string;
+}
+export interface ResolutionMergeResult {
+    readonly merged: SynapseResolutionState | undefined;
+    readonly strategy: ResolutionMergeStrategy;
+    /** Loser's rationale, surfaced so caller can append it as evidence. */
+    readonly loserRationale: LoserRationale | null;
+}
+/**
+ * Merge three resolutionState values per spec §6.3 state machine.
+ *
+ * `base`, `ours`, `theirs` may all be undefined (synapse may not have one).
+ */
+export declare function mergeResolutionState(params: {
+    base?: SynapseResolutionState;
+    ours?: SynapseResolutionState;
+    theirs?: SynapseResolutionState;
+}): ResolutionMergeResult;
+//# sourceMappingURL=resolution-state.d.ts.map

package/dist/merge/resolution-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution-state.d.ts","sourceRoot":"","sources":["../../src/merge/resolution-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAC7C,uBAAuB,EACvB,MAAM,CAOP,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAC/B,YAAY,GACZ,iBAAiB,GACjB,aAAa,GACb,cAAc,GACd,wBAAwB,GACxB,eAAe,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,uBAAuB,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAC3C,uEAAuE;IACvE,QAAQ,CAAC,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;CAChD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,IAAI,CAAC,EAAE,sBAAsB,CAAC;IAC9B,IAAI,CAAC,EAAE,sBAAsB,CAAC;IAC9B,MAAM,CAAC,EAAE,sBAAsB,CAAC;CACjC,GAAG,qBAAqB,CAsExB"}

package/dist/merge/resolution-state.js

@@ -0,0 +1,100 @@
+/**
+ * resolutionState state-machine merge (spec §6.3).
+ *
+ * Contradicts synapse three-phase lifecycle:
+ *   pending → auto_resolved / escalated → contested → resolved
+ *
+ * Merge rules:
+ *   1. ours == theirs → use either
+ *   2. one side absent → use the one present
+ *   3. phases differ → higher phase wins (closer to resolution)
+ *   4. phases equal → higher priority status wins
+ *      priority = { resolved: 4, escalated: 3, auto_resolved: 2, contested: 2, pending: 1 }
+ *   5. on override: append loser's rationale as evidence for the winner
+ *
+ * @module @co-engram/core/merge
+ */
+export const RESOLUTION_STATUS_PRIORITY = {
+    pending: 1,
+    auto_resolved: 2,
+    contested: 2,
+    escalated: 3,
+    resolved: 4,
+};
+/**
+ * Merge three resolutionState values per spec §6.3 state machine.
+ *
+ * `base`, `ours`, `theirs` may all be undefined (synapse may not have one).
+ */
+export function mergeResolutionState(params) {
+    const { base, ours, theirs } = params;
+    if (!ours && !theirs) {
+        return {
+            merged: base,
+            strategy: "all-absent",
+            loserRationale: null,
+        };
+    }
+    if (ours && !theirs) {
+        return { merged: ours, strategy: "one-side-absent", loserRationale: null };
+    }
+    if (theirs && !ours) {
+        return {
+            merged: theirs,
+            strategy: "one-side-absent",
+            loserRationale: null,
+        };
+    }
+    // Both sides present — guaranteed by guards above
+    const oursState = ours;
+    const theirsState = theirs;
+    if (oursState.status === theirsState.status &&
+        oursState.phase === theirsState.phase) {
+        return {
+            merged: oursState,
+            strategy: "same-status",
+            loserRationale: null,
+        };
+    }
+    // Phases differ → higher phase wins
+    if (oursState.phase !== theirsState.phase) {
+        const oursWins = oursState.phase > theirsState.phase;
+        const winner = oursWins ? oursState : theirsState;
+        const loser = oursWins ? theirsState : oursState;
+        return {
+            merged: winner,
+            strategy: "higher-phase",
+            loserRationale: extractLoserRationale(loser),
+        };
+    }
+    // Same phase → higher priority status wins
+    const oursPriority = RESOLUTION_STATUS_PRIORITY[oursState.status];
+    const theirsPriority = RESOLUTION_STATUS_PRIORITY[theirsState.status];
+    if (oursPriority !== theirsPriority) {
+        const oursWins = oursPriority > theirsPriority;
+        const winner = oursWins ? oursState : theirsState;
+        const loser = oursWins ? theirsState : oursState;
+        return {
+            merged: winner,
+            strategy: "higher-priority-status",
+            loserRationale: extractLoserRationale(loser),
+        };
+    }
+    // Same phase + same priority (e.g. both 'contested' phase 3) → tie.
+    // Deterministically keep ours; caller may escalate if they detect the tie.
+    return {
+        merged: oursState,
+        strategy: "tie-keep-ours",
+        loserRationale: extractLoserRationale(theirsState),
+    };
+}
+function extractLoserRationale(loser) {
+    if (!loser.rationale || loser.rationale.trim() === "")
+        return null;
+    return {
+        fromStatus: loser.status,
+        fromPhase: loser.phase,
+        rationale: loser.rationale,
+    };
+}
+//# sourceMappingURL=resolution-state.js.map

package/dist/merge/resolution-state.js.map

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

package/dist/merge/synapse-merger.d.ts

@@ -0,0 +1,63 @@
+/**
+ * SynapseMerger — orchestrator for synapse file 3-way merge (spec §6).
+ *
+ * Composes:
+ *   - synapse-rules: immutable / updatedAt_arbitration / max_updatedAt
+ *   - evidence-union: array_union
+ *   - resolution-state: state_machine
+ *   - passthrough: unknown fields kept from ours
+ *
+ * Identity fields (id/from/to/kind/createdBy/createdAt) — divergent edits
+ * escalate per spec §6.4 "kind 改变 → driver 不介入". Note that since
+ * kind is part of the file path (`synapses/{kind}/syn-{id}.yaml`), kind
+ * changes show up as rename/add in git itself, not as content conflict.
+ *
+ * `mergeSynapseFile` 是 sync 版本,只走 Layer A(机械规则)。
+ * `mergeSynapseFileAsync` 在 updatedAt_arbitration 字段 escalate 时追加
+ * Layer B(LLM)兜底;immutable 字段保持 escalate(spec §6.4)。
+ *
+ * @module @co-engram-core/merge
+ */
+import type { Synapse } from "../types/synapse.js";
+import type { LlmArbiter } from "./llm-arbiter.js";
+export interface SynapseMergeResult {
+    /** Parsed merged synapse (only valid when escalated=false). */
+    readonly merged: Synapse;
+    /** Serialized merged YAML (with frontmatter delimiters). */
+    readonly mergedContent: string;
+    /** True when conflict could not be auto-resolved; markers in mergedContent. */
+    readonly escalated: boolean;
+    /** Human-readable summary of the strategy used. */
+    readonly strategy: string;
+    /** Winner side for updatedAt arbitrated fields, when applicable. */
+    readonly arbitratedWinner: "ours" | "theirs" | null;
+}
+export declare function mergeSynapseFile(params: {
+    baseRaw: string;
+    oursRaw: string;
+    theirsRaw: string;
+    /**
+     * 预解析的字段解决方案(用于 async 版注入 LLM 结果)。
+     * sync 调用方不传;key=字段名,value=替代 escalate 的最终值。
+     */
+    preResolvedFields?: Record<string, unknown>;
+}): SynapseMergeResult;
+/**
+ * Async 版 synapse 合并,在 Layer A escalate 后追加 Layer B(LLM)兜底。
+ *
+ * 触发条件(spec §5.7):
+ *   - updatedAt_arbitration 字段(weight/direction/sourceSemantic/targetSemantic)
+ *     双方都改 + updatedAt 一致 → LLM 决定
+ *
+ * 不触发:
+ *   - immutable 字段 escalate(spec §6.4: identity 字段冲突必须人工)
+ *   - Layer A 已解决
+ */
+export declare function mergeSynapseFileAsync(params: {
+    baseRaw: string;
+    oursRaw: string;
+    theirsRaw: string;
+    arbiter: LlmArbiter;
+    path: string;
+}): Promise<SynapseMergeResult>;
+//# sourceMappingURL=synapse-merger.d.ts.map

package/dist/merge/synapse-merger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synapse-merger.d.ts","sourceRoot":"","sources":["../../src/merge/synapse-merger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAaH,OAAO,KAAK,EAAE,OAAO,EAAmB,MAAM,qBAAqB,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;CACrD;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C,GAAG,kBAAkB,CAyJrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAyF9B"}