@co-engram/core 0.1.0 → 0.1.1

package/dist/merge/content.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Content body 段落级 3-way 合并
+ *
+ * 调 `git merge-file -p --diff3` 让 git 做机械合并。
+ * 干净合并 → 直接用;有 marker → fallback updatedAt 取赢家整段;
+ * updatedAt 一致 → 尝试 LLM 兜底(若提供 arbiter);失败 → escalate,
+ * 把带 marker 的输出原样返回(由 driver 写入 %A + exit 1)。
+ *
+ * @module @co-engram/core/merge
+ */
+import type { LlmArbiter } from "./llm-arbiter.js";
+export interface ContentMergeOutcome {
+    readonly merged: string;
+    readonly strategy: "git-3way-clean" | "updatedAt-fallback" | "llm-resolved" | "escalate";
+    readonly conflictMarkersPresent: boolean;
+    readonly winner: "ours" | "theirs" | null;
+}
+export declare function mergeContent(params: {
+    base: string;
+    ours: string;
+    theirs: string;
+    oursUpdatedAt: string;
+    theirsUpdatedAt: string;
+    markerSize?: number;
+}): ContentMergeOutcome;
+/**
+ * Async 版 content 合并,在 updatedAt collision 时追加 LLM 兜底(spec §5.6)。
+ *
+ * 注意:content 冲突对 LLM 是困难场景(段落级语义合并),所以仅当:
+ *   1. 提供 arbiter
+ *   2. updatedAt 完全一致(机械规则无解)
+ *
+ * 才调 LLM。LLM 必须返回 verdict=merge + mergedValue 才会被采用;
+ * verdict=ours/theirs 也接受,采用对应整段。
+ *
+ * 调用方约束:path 必须是 engram 相对路径(写 audit + prompt 用)。
+ */
+export declare function mergeContentAsync(params: {
+    base: string;
+    ours: string;
+    theirs: string;
+    oursUpdatedAt: string;
+    theirsUpdatedAt: string;
+    oursUpdatedBy?: string;
+    theirsUpdatedBy?: string;
+    markerSize?: number;
+    arbiter: LlmArbiter;
+    path: string;
+}): Promise<ContentMergeOutcome>;
+//# sourceMappingURL=content.d.ts.map

package/dist/merge/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/merge/content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EACb,gBAAgB,GAChB,oBAAoB,GACpB,cAAc,GACd,UAAU,CAAC;IACf,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;CAC3C;AAID,wBAAgB,YAAY,CAAC,MAAM,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,mBAAmB,CA0EtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAqD/B"}

package/dist/merge/content.js

@@ -0,0 +1,137 @@
+/**
+ * Content body 段落级 3-way 合并
+ *
+ * 调 `git merge-file -p --diff3` 让 git 做机械合并。
+ * 干净合并 → 直接用;有 marker → fallback updatedAt 取赢家整段;
+ * updatedAt 一致 → 尝试 LLM 兜底(若提供 arbiter);失败 → escalate,
+ * 把带 marker 的输出原样返回(由 driver 写入 %A + exit 1)。
+ *
+ * @module @co-engram/core/merge
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const CONFLICT_MARKER_RE = /^(<{7}|={7}|>{7})/m;
+export function mergeContent(params) {
+    const { base, ours, theirs, oursUpdatedAt, theirsUpdatedAt, markerSize = 7, } = params;
+    const dir = mkdtempSync(join(tmpdir(), "co-engram-merge-"));
+    const oursPath = join(dir, "ours.tmp");
+    const basePath = join(dir, "base.tmp");
+    const theirsPath = join(dir, "theirs.tmp");
+    try {
+        writeFileSync(oursPath, ours, "utf8");
+        writeFileSync(basePath, base, "utf8");
+        writeFileSync(theirsPath, theirs, "utf8");
+        const result = spawnSync("git", [
+            "merge-file",
+            "-p",
+            "--diff3",
+            `--marker-size=${markerSize}`,
+            oursPath,
+            basePath,
+            theirsPath,
+        ], { encoding: "utf8" });
+        // git merge-file: exit 0 = clean; exit >0 = conflict count; null = error
+        const stdout = result.stdout ?? "";
+        const hasMarkers = CONFLICT_MARKER_RE.test(stdout);
+        if (!hasMarkers && result.status === 0) {
+            return {
+                merged: stdout,
+                strategy: "git-3way-clean",
+                conflictMarkersPresent: false,
+                winner: null,
+            };
+        }
+        // Conflict — try updatedAt fallback
+        if (oursUpdatedAt > theirsUpdatedAt) {
+            return {
+                merged: ours,
+                strategy: "updatedAt-fallback",
+                conflictMarkersPresent: false,
+                winner: "ours",
+            };
+        }
+        if (theirsUpdatedAt > oursUpdatedAt) {
+            return {
+                merged: theirs,
+                strategy: "updatedAt-fallback",
+                conflictMarkersPresent: false,
+                winner: "theirs",
+            };
+        }
+        // updatedAt collision — escalate, pass through git's marked output
+        return {
+            merged: stdout,
+            strategy: "escalate",
+            conflictMarkersPresent: true,
+            winner: null,
+        };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/**
+ * Async 版 content 合并,在 updatedAt collision 时追加 LLM 兜底(spec §5.6)。
+ *
+ * 注意:content 冲突对 LLM 是困难场景(段落级语义合并),所以仅当:
+ *   1. 提供 arbiter
+ *   2. updatedAt 完全一致(机械规则无解)
+ *
+ * 才调 LLM。LLM 必须返回 verdict=merge + mergedValue 才会被采用;
+ * verdict=ours/theirs 也接受,采用对应整段。
+ *
+ * 调用方约束:path 必须是 engram 相对路径(写 audit + prompt 用)。
+ */
+export async function mergeContentAsync(params) {
+    const layerA = mergeContent(params);
+    if (layerA.strategy !== "escalate") {
+        return layerA;
+    }
+    // Layer B: LLM 兜底
+    const llmInput = {
+        conflictType: "engram_content",
+        path: params.path,
+        base: params.base,
+        ours: params.ours,
+        theirs: params.theirs,
+        meta: {
+            oursUpdatedAt: params.oursUpdatedAt,
+            theirsUpdatedAt: params.theirsUpdatedAt,
+            oursUpdatedBy: params.oursUpdatedBy ?? "unknown",
+            theirsUpdatedBy: params.theirsUpdatedBy ?? "unknown",
+        },
+    };
+    const result = await params.arbiter.arbitrate(llmInput);
+    if (result.verdict.kind === "resolved") {
+        const output = result.verdict.output;
+        if (output.verdict === "merge" && typeof output.mergedValue === "string") {
+            return {
+                merged: output.mergedValue,
+                strategy: "llm-resolved",
+                conflictMarkersPresent: false,
+                winner: null, // merge 综合,无单边 winner
+            };
+        }
+        if (output.verdict === "ours") {
+            return {
+                merged: params.ours,
+                strategy: "llm-resolved",
+                conflictMarkersPresent: false,
+                winner: "ours",
+            };
+        }
+        if (output.verdict === "theirs") {
+            return {
+                merged: params.theirs,
+                strategy: "llm-resolved",
+                conflictMarkersPresent: false,
+                winner: "theirs",
+            };
+        }
+        // verdict=escalate: fall through to layerA
+    }
+    return layerA;
+}
+//# sourceMappingURL=content.js.map

package/dist/merge/content.js.map

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

package/dist/merge/cross-file-coordinator.d.ts

@@ -0,0 +1,52 @@
+/**
+ * CrossFileCoordinator (spec §7) — post-merge 跨文件一致性 check。
+ *
+ * git merge driver 只看单文件冲突,**看不到跨文件状态**。当 engram 被
+ * refuted/forgotten 但另一方在其上加 synapse 时,driver 不知道 — 这类
+ * 不一致通过本模块在 post-merge hook / maintenance light stage 检测。
+ *
+ * 设计:
+ *   - 不重试 / 不阻塞(失败只 audit,等待下次 deep stage)
+ *   - 明确语义的 check 自动修复;需要语义判断的 check 调 LLM
+ *   - 报告 spec §7.4 统计影响
+ *
+ * @module @co-engram/core/merge
+ */
+import type { EngramRepository } from "../storage/repository.js";
+import type { AuditLog } from "../observability/audit-log.js";
+import type { LlmArbiter } from "./llm-arbiter.js";
+/** spec §7.3 不一致类型 */
+export type InconsistencyKind = "refuted_engram_has_active_synapse" | "supersedes_target_not_archived" | "contradicts_resolution_state_drift" | "disjoint_domain_tags";
+export interface Inconsistency {
+    readonly kind: InconsistencyKind;
+    readonly path?: string;
+    readonly engramId?: string;
+    readonly synapseId?: string;
+    readonly detail: string;
+    /** 是否被自动修复;false 表示需要 LLM/人工 */
+    readonly autoFixed: boolean;
+}
+export interface CrossFileConsistencyReport {
+    readonly startedAt: number;
+    readonly finishedAt: number;
+    readonly durationMs: number;
+    readonly inconsistencies: readonly Inconsistency[];
+    readonly autoFixedCount: number;
+    readonly llmEscalatedCount: number;
+}
+/**
+ * 跑一遍跨文件一致性 check(spec §7.3)。
+ *
+ * 不抛错(失败 → 写 inconsistency,继续)。
+ * 不阻塞调用方(post-merge hook 必须 fast-fail)。
+ */
+export declare function runCrossFileConsistency(params: {
+    repository: EngramRepository;
+    auditLog?: AuditLog;
+    /**
+     * 可选 LLM 仲裁器。提供时用于需要语义判断的 check(domainTags union
+     * vs 二选一 / contradicts resolutionState)。不提供 → 这两类只记录 inconsistency。
+     */
+    llmArbiter?: LlmArbiter;
+}): Promise<CrossFileConsistencyReport>;
+//# sourceMappingURL=cross-file-coordinator.d.ts.map

package/dist/merge/cross-file-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-file-coordinator.d.ts","sourceRoot":"","sources":["../../src/merge/cross-file-coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,sBAAsB;AACtB,MAAM,MAAM,iBAAiB,GACzB,mCAAmC,GACnC,gCAAgC,GAChC,oCAAoC,GACpC,sBAAsB,CAAC;AAE3B,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAQD;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAyDtC"}

package/dist/merge/cross-file-coordinator.js

@@ -0,0 +1,222 @@
+/**
+ * CrossFileCoordinator (spec §7) — post-merge 跨文件一致性 check。
+ *
+ * git merge driver 只看单文件冲突,**看不到跨文件状态**。当 engram 被
+ * refuted/forgotten 但另一方在其上加 synapse 时,driver 不知道 — 这类
+ * 不一致通过本模块在 post-merge hook / maintenance light stage 检测。
+ *
+ * 设计:
+ *   - 不重试 / 不阻塞(失败只 audit,等待下次 deep stage)
+ *   - 明确语义的 check 自动修复;需要语义判断的 check 调 LLM
+ *   - 报告 spec §7.4 统计影响
+ *
+ * @module @co-engram/core/merge
+ */
+/** spec §7.3 中"refuted/forgotten"对应的 engram status 集合 */
+const INACTIVE_STATUSES = ["archived", "forgotten"];
+/** spec §7.3 中"应被 archived"的 verification status */
+const REFUTED_VERIFICATION = "refuted";
+/**
+ * 跑一遍跨文件一致性 check(spec §7.3)。
+ *
+ * 不抛错(失败 → 写 inconsistency,继续)。
+ * 不阻塞调用方(post-merge hook 必须 fast-fail)。
+ */
+export async function runCrossFileConsistency(params) {
+    const { repository, auditLog, llmArbiter } = params;
+    const startedAt = Date.now();
+    const inconsistencies = [];
+    // Check 1: refuted/forgotten engram 仍有 active outgoing synapse (spec §7.3 行 1)
+    inconsistencies.push(...checkRefutedEngramsHaveActiveSynapses(repository));
+    // Check 2: supersedes 关系破裂 (spec §7.3 行 2)
+    inconsistencies.push(...checkSupersedesTargets(repository));
+    // Check 3 + 4: 需要 LLM 介入的不一致(可选)
+    if (llmArbiter) {
+        inconsistencies.push(...(await checkContradictsDrift(repository, llmArbiter)));
+        inconsistencies.push(...(await checkDisjointDomainTags(repository, llmArbiter)));
+    }
+    else {
+        // 无 LLM — 仍扫描并 audit,但不尝试修复
+        inconsistencies.push(...scanContradictsDriftNoLlm(repository));
+        inconsistencies.push(...scanDisjointDomainTagsNoLlm(repository));
+    }
+    // 自动修复的 inconsistency 标 autoFixed=true(已在 check 内部完成)
+    // 写 audit log
+    if (auditLog) {
+        for (const inc of inconsistencies) {
+            auditLog.append({
+                actor: "system",
+                action: "merge_conflict_escalated",
+                metadata: {
+                    kind: inc.kind,
+                    path: inc.path,
+                    engramId: inc.engramId,
+                    synapseId: inc.synapseId,
+                    detail: inc.detail,
+                    autoFixed: inc.autoFixed,
+                    source: "cross-file-coordinator",
+                },
+            });
+        }
+    }
+    const finishedAt = Date.now();
+    const autoFixedCount = inconsistencies.filter((i) => i.autoFixed).length;
+    const llmEscalatedCount = inconsistencies.filter((i) => !i.autoFixed).length;
+    return {
+        startedAt,
+        finishedAt,
+        durationMs: finishedAt - startedAt,
+        inconsistencies,
+        autoFixedCount,
+        llmEscalatedCount,
+    };
+}
+// ============================================================
+// Check 1: refuted/forgotten engram 仍有 active outgoing synapse
+// ============================================================
+function checkRefutedEngramsHaveActiveSynapses(repository) {
+    const out = [];
+    for (const entry of repository.listEngrams()) {
+        let engram;
+        try {
+            engram = repository.readEngram(entry.id);
+        }
+        catch {
+            continue; // 索引过期 / 文件已被删
+        }
+        const isInactive = INACTIVE_STATUSES.includes(engram.status) ||
+            engram.verificationStatus === REFUTED_VERIFICATION;
+        if (!isInactive)
+            continue;
+        // 查该 engram 的 outgoing synapses
+        const { outgoing } = repository.readSynapses(engram.id);
+        if (outgoing.length === 0)
+            continue;
+        out.push({
+            kind: "refuted_engram_has_active_synapse",
+            engramId: engram.id,
+            detail: `engram status=${engram.status}/verificationStatus=${engram.verificationStatus ?? "unverified"} but has ${outgoing.length} outgoing synapse(s)`,
+            autoFixed: false,
+        });
+    }
+    return out;
+}
+// ============================================================
+// Check 2: supersedes 关系破裂 — A supersedes B,B 应 archived
+// ============================================================
+function checkSupersedesTargets(repository) {
+    const out = [];
+    // 遍历所有 engram,查 kind=supersedes 的 outgoing synapse
+    for (const entry of repository.listEngrams()) {
+        let engram;
+        try {
+            engram = repository.readEngram(entry.id);
+        }
+        catch {
+            continue;
+        }
+        const { outgoing } = repository.readSynapses(engram.id);
+        for (const syn of outgoing) {
+            if (syn.kind !== "supersedes")
+                continue;
+            let target;
+            try {
+                target = repository.readEngram(syn.to);
+            }
+            catch {
+                continue; // target 不存在 — dangling synapse,doctor 已处理
+            }
+            if (target.status === "archived")
+                continue;
+            // 自动修复:把 target.status 设为 archived(spec §7.3 行 2:明确语义)
+            try {
+                repository.updateLifecycle(target.id, "archived");
+                out.push({
+                    kind: "supersedes_target_not_archived",
+                    engramId: target.id,
+                    synapseId: syn.id,
+                    detail: `auto-archived ${target.id} (superseded by ${engram.id})`,
+                    autoFixed: true,
+                });
+            }
+            catch {
+                out.push({
+                    kind: "supersedes_target_not_archived",
+                    engramId: target.id,
+                    synapseId: syn.id,
+                    detail: `failed to auto-archive ${target.id}`,
+                    autoFixed: false,
+                });
+            }
+        }
+    }
+    return out;
+}
+// ============================================================
+// Check 3: contradicts synapse resolutionState drift (LLM-assisted)
+// ============================================================
+async function checkContradictsDrift(repository, _arbiter) {
+    // 完整 LLM 仲裁涉及大量 LLM 调用,Phase 3 先扫描 + 记录,实际修复留 P4
+    return scanContradictsDriftNoLlm(repository);
+}
+function scanContradictsDriftNoLlm(repository) {
+    const out = [];
+    for (const entry of repository.listEngrams()) {
+        let engram;
+        try {
+            engram = repository.readEngram(entry.id);
+        }
+        catch {
+            continue;
+        }
+        const { outgoing } = repository.readSynapses(engram.id);
+        for (const syn of outgoing) {
+            if (syn.kind !== "contradicts")
+                continue;
+            const rs = syn.resolutionState;
+            if (!rs)
+                continue;
+            // pending / auto_resolved 状态长期停留 → 可能 drift
+            if (rs.status === "pending" || rs.status === "auto_resolved") {
+                out.push({
+                    kind: "contradicts_resolution_state_drift",
+                    engramId: engram.id,
+                    synapseId: syn.id,
+                    detail: `contradicts synapse stuck in ${rs.status} phase ${rs.phase}`,
+                    autoFixed: false,
+                });
+            }
+        }
+    }
+    return out;
+}
+// ============================================================
+// Check 4: disjoint domainTags (LLM-assisted)
+// ============================================================
+async function checkDisjointDomainTags(repository, _arbiter) {
+    // 完整 LLM 仲裁涉及版本对比,Phase 3 先扫描空 tags / 单元素 tags 异常
+    return scanDisjointDomainTagsNoLlm(repository);
+}
+function scanDisjointDomainTagsNoLlm(repository) {
+    const out = [];
+    for (const entry of repository.listEngrams()) {
+        let engram;
+        try {
+            engram = repository.readEngram(entry.id);
+        }
+        catch {
+            continue;
+        }
+        const tags = engram.domainTags ?? [];
+        if (tags.length === 0) {
+            out.push({
+                kind: "disjoint_domain_tags",
+                engramId: engram.id,
+                detail: `engram has empty domainTags after merge`,
+                autoFixed: false,
+            });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=cross-file-coordinator.js.map

package/dist/merge/cross-file-coordinator.js.map

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

package/dist/merge/data-root.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Walk up from a file path to find the team memory data root.
+ *
+ * Data root = the directory containing the `.co-engram/` subdir.
+ *
+ * @module @co-engram/core/merge
+ */
+export declare function findDataRoot(startPath: string): string | null;
+//# sourceMappingURL=data-root.d.ts.map

package/dist/merge/data-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-root.d.ts","sourceRoot":"","sources":["../../src/merge/data-root.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA0B7D"}

package/dist/merge/data-root.js

@@ -0,0 +1,42 @@
+/**
+ * Walk up from a file path to find the team memory data root.
+ *
+ * Data root = the directory containing the `.co-engram/` subdir.
+ *
+ * @module @co-engram/core/merge
+ */
+import { existsSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+const MARKER_DIR = ".co-engram";
+export function findDataRoot(startPath) {
+    let current = startPath;
+    // If startPath is a file, begin from its directory
+    try {
+        const stat = statSync(current);
+        if (stat.isFile())
+            current = dirname(current);
+    }
+    catch {
+        // path may not exist yet (e.g. %A in some git versions); assume it's a file path
+        current = dirname(current);
+    }
+    current = resolve(current);
+    // Walk up
+    while (true) {
+        if (existsSync(join(current, MARKER_DIR))) {
+            try {
+                const stat = statSync(join(current, MARKER_DIR));
+                if (stat.isDirectory())
+                    return current;
+            }
+            catch {
+                // ignore stat errors
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return null; // filesystem root
+        current = parent;
+    }
+}
+//# sourceMappingURL=data-root.js.map

package/dist/merge/data-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-root.js","sourceRoot":"","sources":["../../src/merge/data-root.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,MAAM,UAAU,GAAG,YAAY,CAAC;AAEhC,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,IAAI,OAAO,GAAG,SAAS,CAAC;IACxB,mDAAmD;IACnD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC/B,IAAI,IAAI,CAAC,MAAM,EAAE;YAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,iFAAiF;QACjF,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B,UAAU;IACV,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC;YAC1C,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;gBACjD,IAAI,IAAI,CAAC,WAAW,EAAE;oBAAE,OAAO,OAAO,CAAC;YACzC,CAAC;YAAC,MAAM,CAAC;gBACP,qBAAqB;YACvB,CAAC;QACH,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,MAAM,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC,CAAC,kBAAkB;QACvD,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/merge/driver-llm.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Driver-side LLM client bootstrap (spec §5.1).
+ *
+ * 问题:host (claude-code-mcp / openclaw-plugin) 启动时已经构造了 LlmClient 实例,
+ * 但 git merge driver 是 git 直接 spawn 的独立进程,host 无法注入对象引用。
+ *
+ * 解决:host 把 LLM 配置(endpoint / apiKey / model)序列化到
+ * `~/.co-engram/llm-config.json`,driver 启动时读出来用 fetch 构造 HTTP client。
+ *
+ * 协议选 OpenAI-compatible(/chat/completions) —— 最通用:
+ *   - OpenAI / Azure / 通义 / 智谱 / DeepSeek / 月之暗面 / ollama 原生支持
+ *   - Anthropic 也有 OpenAI 兼容端点(https://api.anthropic.com/v1/openai/v1)
+ *
+ * @module @co-engram/core/merge
+ */
+import type { LlmClient } from "../observability/necessity-evaluator.js";
+/**
+ * LLM 配置(序列化形式)。
+ *
+ * host 启动时写入,driver 启动时读出。
+ * 字段命名与 host 端 NecessityLlmConfig 对齐,便于 host 直接序列化。
+ */
+export interface LlmClientConfig {
+    /** OpenAI-compatible chat completions endpoint(完整 URL) */
+    readonly endpoint: string;
+    /** API key(Bearer token) */
+    readonly apiKey: string;
+    /** 模型名(如 'glm-5.2' / 'claude-sonnet-4-6' / 'gpt-5.5') */
+    readonly model: string;
+    /** 额外 headers(可选) */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** 写入时间(ISO)——driver 用于 staleness 检查 */
+    readonly writtenAt: string;
+    /** 写入者( host 名,用于诊断) */
+    readonly writtenBy?: string;
+}
+/**
+ * 解析 config 文件路径。
+ *
+ * 优先级:
+ *   1. `$CO_ENGRAM_LLM_CONFIG`(绝对路径,测试用)
+ *   2. `$HOME/.co-engram/llm-config.json`(默认)
+ *   3. 退化:OS tmpdir(不推荐,仅当 HOME 缺失时)
+ */
+export declare function resolveLlmConfigPath(): string;
+/**
+ * 写 LLM 配置到磁盘(host 启动时调用)。
+ *
+ * 不抛错 —— 写失败只警告,host 不应因 LLM 配置写盘失败而崩溃。
+ */
+export declare function writeLlmClientConfig(config: Omit<LlmClientConfig, "writtenAt">): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * 读 LLM 配置(driver 启动时调用)。
+ *
+ * 不抛错 —— 读失败/文件缺失都返回 undefined,driver 退化为 no-LLM 模式。
+ */
+export declare function readLlmClientConfig(): LlmClientConfig | undefined;
+/**
+ * 删除 LLM 配置(uninstall 时调用)。
+ *
+ * 用于 host 完全卸载 merge driver 时清理敏感数据。
+ * 失败不抛错,只返回 status。
+ */
+export declare function clearLlmClientConfig(): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * 创建 OpenAI-compatible HTTP LlmClient(基于 fetch)。
+ *
+ * 任何抛错都让调用方(LlmArbiter)捕获并降级到 escalate。
+ */
+export declare function createHttpLlmClient(config: LlmClientConfig): LlmClient;
+/**
+ * Driver 启动时的便捷入口:读 config + 构造 client。
+ *
+ * 失败返回 null,driver 退化为 no-LLM 模式(机械规则解决不了的冲突 → marker)。
+ */
+export declare function createDriverLlmClient(): {
+    client: LlmClient;
+    config: LlmClientConfig;
+} | null;
+//# sourceMappingURL=driver-llm.d.ts.map

package/dist/merge/driver-llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-llm.d.ts","sourceRoot":"","sources":["../../src/merge/driver-llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAWH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qBAAqB;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wBAAwB;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAKD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAM7C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,GACzC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAgB3D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,eAAe,GAAG,SAAS,CAiBjE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAChC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAY/B;AAcD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAiDtE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI;IACvC,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,eAAe,CAAC;CACzB,GAAG,IAAI,CAQP"}