@co-engram/core 0.1.0 → 0.1.1

package/dist/merge/llm-arbiter.js

@@ -0,0 +1,177 @@
+/**
+ * LLM merge arbitrator (spec §5).
+ *
+ * 接受 LlmClient + confidence threshold,把 LlmMergeInput 翻译成一次 LLM 调用,
+ * 解析输出,应用置信度阈值,失败一律降级到 escalate(留 marker)。
+ *
+ * 不重试(spec §5.5):失败就降级,backup + audit 兜底。
+ *
+ * @module @co-engram/core/merge
+ */
+import { createHash } from "node:crypto";
+import { parseLlmMergeOutput, } from "./llm-contract.js";
+import { LLM_MERGE_SYSTEM_PROMPT, buildLlmMergeUserPrompt, } from "./llm-prompt.js";
+/**
+ * 默认置信度阈值(spec §5.5)。
+ *
+ * 低于此值的输出按 escalate 处理 —— 调用方应保留 marker,留给人工解决。
+ */
+export const DEFAULT_LLM_CONFIDENCE_THRESHOLD = 0.7;
+/**
+ * 默认超时(spec §5.5):15s,merge driver 必须 block 但不能拖死 git pull。
+ */
+export const DEFAULT_LLM_TIMEOUT_MS = 15_000;
+/**
+ * 默认 token 预算(spec §5.5):input < 1000, output < 200。
+ */
+export const DEFAULT_LLM_MAX_OUTPUT_TOKENS = 200;
+/**
+ * LLM 仲裁器 —— 把机械规则解决不了的冲突交给 LLM。
+ *
+ * 调用方:
+ * ```ts
+ * const arbiter = new LlmArbiter({ client, auditLog, providerName: 'anthropic' });
+ * const result = await arbiter.arbitrate(input);
+ * if (result.verdict.kind === 'resolved') {
+ *   applyMerge(result.verdict.output);
+ * } else {
+ *   writeConflictMarkers();
+ * }
+ * ```
+ */
+export class LlmArbiter {
+    client;
+    confidenceThreshold;
+    timeoutMs;
+    maxOutputTokens;
+    temperature;
+    auditLog;
+    providerName;
+    constructor(config) {
+        this.client = config.client;
+        this.confidenceThreshold =
+            config.confidenceThreshold ?? DEFAULT_LLM_CONFIDENCE_THRESHOLD;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_LLM_TIMEOUT_MS;
+        this.maxOutputTokens =
+            config.maxOutputTokens ?? DEFAULT_LLM_MAX_OUTPUT_TOKENS;
+        this.temperature = config.temperature ?? 0.1;
+        this.auditLog = config.auditLog;
+        this.providerName = config.providerName;
+    }
+    async arbitrate(input) {
+        const userPrompt = buildLlmMergeUserPrompt(input);
+        const fullPrompt = `${LLM_MERGE_SYSTEM_PROMPT}\n\n---\n\n${userPrompt}`;
+        const promptHash = hashPrompt(fullPrompt);
+        const start = Date.now();
+        let raw;
+        try {
+            raw = await this.client.complete(fullPrompt, {
+                maxTokens: this.maxOutputTokens,
+                temperature: this.temperature,
+                timeoutMs: this.timeoutMs,
+            });
+        }
+        catch (e) {
+            const latencyMs = Date.now() - start;
+            const msg = e instanceof Error ? e.message : String(e);
+            this.auditFailure(input, promptHash, latencyMs, undefined, msg);
+            return {
+                verdict: { kind: "escalated", reason: "llm_call_failed" },
+                latencyMs,
+                promptHash,
+            };
+        }
+        const latencyMs = Date.now() - start;
+        const parsed = parseLlmMergeOutput(raw);
+        if (!parsed.ok) {
+            this.auditFailure(input, promptHash, latencyMs, raw, `parse_failed: ${parsed.message}`);
+            return {
+                verdict: { kind: "escalated", reason: "parse_failed" },
+                latencyMs,
+                rawResponse: raw,
+                parseFailure: parsed,
+                promptHash,
+            };
+        }
+        const output = parsed.output;
+        // LLM 自己选择 escalate —— 尊重它的判断,但仍是 escalate 结果
+        if (output.verdict === "escalate") {
+            this.auditSuccess(input, promptHash, latencyMs, output, true);
+            return {
+                verdict: { kind: "escalated", reason: "verdict_escalate" },
+                latencyMs,
+                rawResponse: raw,
+                promptHash,
+            };
+        }
+        // 置信度阈值检查 —— 低于阈值不执行,降级到 marker
+        if (output.confidence < this.confidenceThreshold) {
+            this.auditSuccess(input, promptHash, latencyMs, output, true, true);
+            return {
+                verdict: { kind: "escalated", reason: "low_confidence" },
+                latencyMs,
+                rawResponse: raw,
+                promptHash,
+            };
+        }
+        this.auditSuccess(input, promptHash, latencyMs, output, false);
+        return {
+            verdict: { kind: "resolved", output },
+            latencyMs,
+            rawResponse: raw,
+            promptHash,
+        };
+    }
+    auditSuccess(input, promptHash, latencyMs, output, escalated, lowConfidence = false) {
+        if (!this.auditLog)
+            return;
+        this.auditLog.append({
+            actor: "system",
+            action: escalated
+                ? "merge_llm_arbitrated_escalated"
+                : "merge_llm_arbitrated",
+            metadata: {
+                path: input.path,
+                conflictType: input.conflictType,
+                fieldName: input.fieldName,
+                promptHash,
+                verdict: output.verdict,
+                confidence: output.confidence,
+                rationale: output.rationale,
+                latencyMs,
+                provider: this.providerName,
+                ...(lowConfidence ? { lowConfidence: true } : {}),
+                ...(escalated ? { escalated: true } : {}),
+            },
+        });
+    }
+    auditFailure(input, promptHash, latencyMs, rawResponse, errorMessage) {
+        if (!this.auditLog)
+            return;
+        this.auditLog.append({
+            actor: "system",
+            action: "merge_llm_arbitrated_failed",
+            metadata: {
+                path: input.path,
+                conflictType: input.conflictType,
+                fieldName: input.fieldName,
+                promptHash,
+                latencyMs,
+                provider: this.providerName,
+                error: errorMessage,
+                ...(rawResponse !== undefined
+                    ? { rawResponseLength: rawResponse.length }
+                    : {}),
+            },
+        });
+    }
+}
+/**
+ * 计算 prompt 短哈希(SHA256 前 12 hex 字符)。
+ *
+ * 用于 audit + 异常检测:若大量调用的 promptHash 突然变化,说明 prompt 漂移。
+ */
+function hashPrompt(prompt) {
+    return createHash("sha256").update(prompt).digest("hex").slice(0, 12);
+}
+//# sourceMappingURL=llm-arbiter.js.map

package/dist/merge/llm-arbiter.js.map

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

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

@@ -0,0 +1,86 @@
+/**
+ * LLM merge arbitration contract (spec §5.2, §5.3).
+ *
+ * Pure types + JSON parsing — no LLM client coupling here.
+ * The LlmArbiter (P3.2) consumes these and drives the actual LLM call.
+ *
+ * @module @co-engram/core/merge
+ */
+/**
+ * 冲突类型 —— 决定 prompt 上下文与 LLM 介入的成本权衡。
+ *
+ * - engram_frontmatter:engram 的 YAML 字段冲突(title / domainTags 等)
+ * - engram_content:engram 正文段落冲突
+ * - synapse_field:synapse 的 YAML 字段冲突
+ * - synapse_evidence:synapse.evidence 数组合并冲突
+ * - resolution_state:synapse 的 resolutionState 合并冲突
+ * - updatedAt_collision:updatedAt 完全一致 + 内容分歧的边界场景
+ * - cross_file_inconsistency:跨文件一致性(P3.6 CrossFileCoordinator 触发)
+ */
+export type LlmMergeConflictType = "engram_frontmatter" | "engram_content" | "synapse_field" | "synapse_evidence" | "resolution_state" | "updatedAt_collision" | "cross_file_inconsistency";
+/**
+ * LLM 仲裁输入(spec §5.2)
+ *
+ * 调用方负责把 base/ours/theirs 序列化为 JSON-safe 值;LLM 只看结构化字段,
+ * 不直接接触原始 markdown / yaml 文本(降低 token、避免 prompt injection)。
+ */
+export interface LlmMergeInput {
+    readonly conflictType: LlmMergeConflictType;
+    readonly path: string;
+    readonly fieldName?: string;
+    readonly base: unknown;
+    readonly ours: unknown;
+    readonly theirs: unknown;
+    readonly meta: {
+        readonly oursUpdatedAt: string;
+        readonly theirsUpdatedAt: string;
+        readonly oursUpdatedBy: string;
+        readonly theirsUpdatedBy: string;
+    };
+}
+/**
+ * LLM 仲裁输出(spec §5.3)
+ *
+ * verdict 语义:
+ *   - "ours"     : 取 ours 原值
+ *   - "theirs"   : 取 theirs 原值
+ *   - "merge"    : 综合双方,mergedValue 必填
+ *   - "escalate" : 无法判定 / 低置信 / 语义不一致 → 留 marker
+ *
+ * confidence:[0,1] 区间,低于阈值(默认 0.7)时调用方按 escalate 处理。
+ */
+export interface LlmMergeOutput {
+    readonly verdict: "ours" | "theirs" | "merge" | "escalate";
+    readonly mergedValue?: unknown;
+    readonly rationale: string;
+    readonly confidence: number;
+}
+/**
+ * JSON 解析失败原因 —— 调用方据此决定 fallback 行为。
+ */
+export type LlmOutputParseErrorReason = "empty_response" | "invalid_json" | "missing_verdict" | "invalid_verdict" | "invalid_confidence" | "missing_rationale" | "missing_merged_value";
+export interface LlmOutputParseFailure {
+    readonly ok: false;
+    readonly reason: LlmOutputParseErrorReason;
+    readonly raw: string;
+    readonly message: string;
+}
+export interface LlmOutputParseSuccess {
+    readonly ok: true;
+    readonly output: LlmMergeOutput;
+}
+export type LlmOutputParseResult = LlmOutputParseSuccess | LlmOutputParseFailure;
+/**
+ * 解析 LLM 返回的原始字符串为 LlmMergeOutput。
+ *
+ * 验证规则:
+ *   1. 必须是合法 JSON(允许前后空白 / ```json 代码块包裹)
+ *   2. verdict ∈ {ours, theirs, merge, escalate}
+ *   3. confidence ∈ [0, 1]
+ *   4. rationale 必须是非空字符串
+ *   5. verdict='merge' 时 mergedValue 必填
+ *
+ * 任何不满足都返回 failure,调用方据此降级。
+ */
+export declare function parseLlmMergeOutput(raw: string): LlmOutputParseResult;
+//# sourceMappingURL=llm-contract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llm-contract.d.ts","sourceRoot":"","sources":["../../src/merge/llm-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAC5B,oBAAoB,GACpB,gBAAgB,GAChB,eAAe,GACf,kBAAkB,GAClB,kBAAkB,GAClB,qBAAqB,GACrB,0BAA0B,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;KAClC,CAAC;CACH;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,MAAM,yBAAyB,GACjC,gBAAgB,GAChB,cAAc,GACd,iBAAiB,GACjB,iBAAiB,GACjB,oBAAoB,GACpB,mBAAmB,GACnB,sBAAsB,CAAC;AAE3B,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,MAAM,oBAAoB,GAC5B,qBAAqB,GACrB,qBAAqB,CAAC;AAI1B;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CA+GrE"}

package/dist/merge/llm-contract.js

@@ -0,0 +1,134 @@
+/**
+ * LLM merge arbitration contract (spec §5.2, §5.3).
+ *
+ * Pure types + JSON parsing — no LLM client coupling here.
+ * The LlmArbiter (P3.2) consumes these and drives the actual LLM call.
+ *
+ * @module @co-engram/core/merge
+ */
+const VALID_VERDICTS = new Set(["ours", "theirs", "merge", "escalate"]);
+/**
+ * 解析 LLM 返回的原始字符串为 LlmMergeOutput。
+ *
+ * 验证规则:
+ *   1. 必须是合法 JSON(允许前后空白 / ```json 代码块包裹)
+ *   2. verdict ∈ {ours, theirs, merge, escalate}
+ *   3. confidence ∈ [0, 1]
+ *   4. rationale 必须是非空字符串
+ *   5. verdict='merge' 时 mergedValue 必填
+ *
+ * 任何不满足都返回 failure,调用方据此降级。
+ */
+export function parseLlmMergeOutput(raw) {
+    const trimmed = stripCodeFence(raw).trim();
+    if (trimmed.length === 0) {
+        return {
+            ok: false,
+            reason: "empty_response",
+            raw,
+            message: "LLM returned empty response",
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            reason: "invalid_json",
+            raw,
+            message: `JSON parse failed: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return {
+            ok: false,
+            reason: "invalid_json",
+            raw,
+            message: "LLM output is not a JSON object",
+        };
+    }
+    const obj = parsed;
+    if (!("verdict" in obj)) {
+        return {
+            ok: false,
+            reason: "missing_verdict",
+            raw,
+            message: "Missing 'verdict' field",
+        };
+    }
+    const verdict = obj.verdict;
+    if (typeof verdict !== "string" || !VALID_VERDICTS.has(verdict)) {
+        return {
+            ok: false,
+            reason: "invalid_verdict",
+            raw,
+            message: `Invalid verdict: ${JSON.stringify(verdict)}`,
+        };
+    }
+    if (!("confidence" in obj)) {
+        return {
+            ok: false,
+            reason: "invalid_confidence",
+            raw,
+            message: "Missing 'confidence' field",
+        };
+    }
+    const confidence = obj.confidence;
+    if (typeof confidence !== "number" ||
+        !Number.isFinite(confidence) ||
+        confidence < 0 ||
+        confidence > 1) {
+        return {
+            ok: false,
+            reason: "invalid_confidence",
+            raw,
+            message: `Invalid confidence (must be number in [0,1]): ${JSON.stringify(confidence)}`,
+        };
+    }
+    if (!("rationale" in obj) || typeof obj.rationale !== "string") {
+        return {
+            ok: false,
+            reason: "missing_rationale",
+            raw,
+            message: "Missing or non-string 'rationale'",
+        };
+    }
+    const rationale = obj.rationale.trim();
+    if (rationale.length === 0) {
+        return {
+            ok: false,
+            reason: "missing_rationale",
+            raw,
+            message: "Empty 'rationale'",
+        };
+    }
+    if (verdict === "merge" && !("mergedValue" in obj)) {
+        return {
+            ok: false,
+            reason: "missing_merged_value",
+            raw,
+            message: "verdict='merge' requires 'mergedValue'",
+        };
+    }
+    return {
+        ok: true,
+        output: {
+            verdict: verdict,
+            confidence,
+            rationale,
+            ...("mergedValue" in obj ? { mergedValue: obj.mergedValue } : {}),
+        },
+    };
+}
+/**
+ * 剥离 markdown 代码块包裹(```json ... ``` 或 ``` ... ```)。
+ *
+ * LLM 经常无视"只返回 JSON"指令,这里做防御性剥离。
+ */
+function stripCodeFence(text) {
+    const match = text.match(/```(?:json)?\s*\n([\s\S]*?)\n```/);
+    return match && match[1] ? match[1] : text;
+}
+//# sourceMappingURL=llm-contract.js.map

package/dist/merge/llm-contract.js.map

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

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

@@ -0,0 +1,25 @@
+/**
+ * LLM merge arbitration prompt template (spec §5.4).
+ *
+ * 模板输入:LlmMergeInput
+ * 模板输出:string —— 直接传给 LlmClient.complete()
+ *
+ * 设计:
+ *   - 系统提示稳定(可缓存);变量塞进 user 段以便 prompt cache 复用前缀
+ *   - 输出格式严格 JSON,parser (parseLlmMergeOutput) 会剥离 ```json 包裹
+ *   - 中性英文,避免 host i18n 干扰 verdict
+ *
+ * @module @co-engram/core/merge
+ */
+import type { LlmMergeInput } from "./llm-contract.js";
+/**
+ * 系统提示稳定,适合 prompt cache。LlmClient 调用方应作为 system prompt 传入。
+ */
+export declare const LLM_MERGE_SYSTEM_PROMPT = "You are a merge arbitrator for co-engram team memory files.\n\nYour job: given BASE / OURS / THEIRS snapshots of a single field or content block,\ndecide how to resolve the conflict and return strict JSON.\n\nVerdict semantics:\n- \"ours\"     \u2014 take OURS as-is\n- \"theirs\"   \u2014 take THEIRS as-is\n- \"merge\"    \u2014 synthesize; provide mergedValue (must include both sides' intent)\n- \"escalate\" \u2014 cannot decide confidently (low confidence or semantic incoherence)\n\nRules:\n- Preserve both sides' intent when possible (prefer \"merge\" over picking a side).\n- \"escalate\" if low confidence or the two sides are semantically incompatible.\n- Never invent facts not present in either side.\n- Never include markdown / code fences / prose outside the JSON object.\n\nReturn exactly this JSON shape (no other text):\n{\n  \"verdict\": \"ours\" | \"theirs\" | \"merge\" | \"escalate\",\n  \"mergedValue\": <any> // required only when verdict === \"merge\"\n  \"rationale\": \"<one short sentence>\",\n  \"confidence\": 0.0\n}";
+/**
+ * 构造 LLM 调用的 user prompt。
+ *
+ * 与 system prompt 分离,让 prompt cache 能复用 system 部分(spec §5.5)。
+ */
+export declare function buildLlmMergeUserPrompt(input: LlmMergeInput): string;
+//# sourceMappingURL=llm-prompt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llm-prompt.d.ts","sourceRoot":"","sources":["../../src/merge/llm-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,uBAAuB,2hCAuBlC,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAUpE"}

package/dist/merge/llm-prompt.js

@@ -0,0 +1,73 @@
+/**
+ * LLM merge arbitration prompt template (spec §5.4).
+ *
+ * 模板输入:LlmMergeInput
+ * 模板输出:string —— 直接传给 LlmClient.complete()
+ *
+ * 设计:
+ *   - 系统提示稳定(可缓存);变量塞进 user 段以便 prompt cache 复用前缀
+ *   - 输出格式严格 JSON,parser (parseLlmMergeOutput) 会剥离 ```json 包裹
+ *   - 中性英文,避免 host i18n 干扰 verdict
+ *
+ * @module @co-engram/core/merge
+ */
+/**
+ * 系统提示稳定,适合 prompt cache。LlmClient 调用方应作为 system prompt 传入。
+ */
+export const LLM_MERGE_SYSTEM_PROMPT = `You are a merge arbitrator for co-engram team memory files.
+
+Your job: given BASE / OURS / THEIRS snapshots of a single field or content block,
+decide how to resolve the conflict and return strict JSON.
+
+Verdict semantics:
+- "ours"     — take OURS as-is
+- "theirs"   — take THEIRS as-is
+- "merge"    — synthesize; provide mergedValue (must include both sides' intent)
+- "escalate" — cannot decide confidently (low confidence or semantic incoherence)
+
+Rules:
+- Preserve both sides' intent when possible (prefer "merge" over picking a side).
+- "escalate" if low confidence or the two sides are semantically incompatible.
+- Never invent facts not present in either side.
+- Never include markdown / code fences / prose outside the JSON object.
+
+Return exactly this JSON shape (no other text):
+{
+  "verdict": "ours" | "theirs" | "merge" | "escalate",
+  "mergedValue": <any> // required only when verdict === "merge"
+  "rationale": "<one short sentence>",
+  "confidence": 0.0
+}`;
+/**
+ * 构造 LLM 调用的 user prompt。
+ *
+ * 与 system prompt 分离,让 prompt cache 能复用 system 部分(spec §5.5)。
+ */
+export function buildLlmMergeUserPrompt(input) {
+    const fieldNameLine = input.fieldName ? `Field: ${input.fieldName}\n` : "";
+    return `Conflict type: ${input.conflictType}
+${fieldNameLine}Path: ${input.path}
+
+BASE (common ancestor): ${safeStringify(input.base)}
+OURS (${input.meta.oursUpdatedBy} at ${input.meta.oursUpdatedAt}): ${safeStringify(input.ours)}
+THEIRS (${input.meta.theirsUpdatedBy} at ${input.meta.theirsUpdatedAt}): ${safeStringify(input.theirs)}
+
+Decide and return JSON.`;
+}
+/**
+ * 安全序列化:避免 undefined / BigInt / 循环引用导致 JSON.stringify 抛错。
+ * 字符串值直接返回(让 prompt 更短、更可读)。
+ */
+function safeStringify(value) {
+    if (typeof value === "string")
+        return value;
+    if (value === undefined)
+        return "<undefined>";
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=llm-prompt.js.map

package/dist/merge/llm-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-prompt.js","sourceRoot":"","sources":["../../src/merge/llm-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;EAuBrC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAoB;IAC1D,MAAM,aAAa,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3E,OAAO,kBAAkB,KAAK,CAAC,YAAY;EAC3C,aAAa,SAAS,KAAK,CAAC,IAAI;;0BAER,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC;QAC3C,KAAK,CAAC,IAAI,CAAC,aAAa,OAAO,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC;UACpF,KAAK,CAAC,IAAI,CAAC,eAAe,OAAO,KAAK,CAAC,IAAI,CAAC,eAAe,MAAM,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC;;wBAE9E,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,aAAa,CAAC;IAC9C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/merge/merge-engram.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Engram 文件合并入口
+ *
+ * 组装 frontmatter 合并 + content 合并 + 收尾(contentHash / contentSize 重算,
+ * updatedAt 取 max, version 取 max+1, updatedBy='merge-driver')。
+ * 失败模式:任一方解析失败 → throw;frontmatter/content escalate → 用 git marker
+ * 形式包装输给 driver 写 %A + exit 1。
+ *
+ * @module @co-engram/core/merge
+ */
+import type { AuditLog } from "../observability/audit-log.js";
+import type { LlmArbiter } from "./llm-arbiter.js";
+export interface EngramMergeResult {
+    readonly mergedContent: string;
+    readonly strategy: string;
+    readonly winner: "ours" | "theirs" | null;
+    readonly escalated: boolean;
+    readonly backupPath?: string;
+}
+export declare function mergeEngramFile(params: {
+    baseRaw: string;
+    oursRaw: string;
+    theirsRaw: string;
+    relPath: string;
+    dataRoot?: string;
+    auditLog?: AuditLog;
+    /**
+     * 可选 LLM 仲裁器。提供时,frontmatter 在 Layer A escalate 后会调 LLM 兜底。
+     * 不提供时,仅走 Layer A(机械规则)—— 行为与 Phase 1 sync 版完全一致。
+     */
+    llmArbiter?: LlmArbiter;
+}): Promise<EngramMergeResult>;
+//# sourceMappingURL=merge-engram.d.ts.map

package/dist/merge/merge-engram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-engram.d.ts","sourceRoot":"","sources":["../../src/merge/merge-engram.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAeD,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA6J7B"}