@co-engram/core 0.1.0 → 0.1.1

package/dist/merge/synapse-merger.js

@@ -0,0 +1,277 @@
+/**
+ * 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 { parseSynapseFile, serializeSynapseFile, } from "../storage/synapse-store.js";
+import { classifySynapseField } from "./synapse-rules.js";
+import { mergeSynapseImmutableField } from "./synapse-rules.js";
+import { mergeSynapseUpdatedAtField } from "./synapse-rules.js";
+import { mergeSynapseMaxUpdatedAt } from "./synapse-rules.js";
+import { ImmutableSynapseViolationError } from "./synapse-rules.js";
+import { mergeEvidence } from "./evidence-union.js";
+import { mergeResolutionState } from "./resolution-state.js";
+export function mergeSynapseFile(params) {
+    const { baseRaw, oursRaw, theirsRaw, preResolvedFields } = params;
+    const base = parseSynapseFile(baseRaw);
+    const ours = parseSynapseFile(oursRaw);
+    const theirs = parseSynapseFile(theirsRaw);
+    const escalatedFields = [];
+    let arbitratedWinner = null;
+    // Mutable copy
+    const merged = {};
+    // Collect all keys from all sides
+    const allKeys = new Set([
+        ...Object.keys(base),
+        ...Object.keys(ours),
+        ...Object.keys(theirs),
+    ]);
+    for (const key of allKeys) {
+        const klass = classifySynapseField(key);
+        const baseV = base[key];
+        const oursV = ours[key];
+        const theirsV = theirs[key];
+        // Layer B 注入:如果字段已在 preResolvedFields 中,直接采用,跳过 Layer A
+        if (preResolvedFields && key in preResolvedFields) {
+            merged[key] = preResolvedFields[key];
+            // 不更新 arbitratedWinner(preResolvedFields 来源是 LLM,不是 updatedAt)
+            continue;
+        }
+        switch (klass) {
+            case "immutable": {
+                try {
+                    merged[key] = mergeSynapseImmutableField({
+                        base: baseV,
+                        ours: oursV,
+                        theirs: theirsV,
+                        fieldName: key,
+                    });
+                }
+                catch (e) {
+                    if (e instanceof ImmutableSynapseViolationError) {
+                        escalatedFields.push(key);
+                        merged[key] = oursV; // provisional; will be overwritten by markers
+                    }
+                    else {
+                        throw e;
+                    }
+                }
+                break;
+            }
+            case "updatedAt_arbitration": {
+                const r = mergeSynapseUpdatedAtField({
+                    base: baseV,
+                    ours: oursV,
+                    theirs: theirsV,
+                    oursUpdatedAt: ours.updatedAt,
+                    theirsUpdatedAt: theirs.updatedAt,
+                });
+                if ("escalated" in r) {
+                    escalatedFields.push(key);
+                    merged[key] = oursV;
+                }
+                else {
+                    merged[key] = r.value;
+                    if (r.winner)
+                        arbitratedWinner = r.winner;
+                }
+                break;
+            }
+            case "max_updatedAt": {
+                merged[key] = mergeSynapseMaxUpdatedAt(ours.updatedAt, theirs.updatedAt);
+                break;
+            }
+            case "array_union": {
+                // Spec §6.1: only evidence is array_union.
+                merged[key] = mergeEvidence({
+                    base: baseV ?? [],
+                    ours: oursV ?? [],
+                    theirs: theirsV ?? [],
+                });
+                break;
+            }
+            case "state_machine": {
+                // resolutionState
+                const r = mergeResolutionState({
+                    base: baseV,
+                    ours: oursV,
+                    theirs: theirsV,
+                });
+                if (r.merged)
+                    merged[key] = r.merged;
+                if (r.strategy === "tie-keep-ours" ||
+                    r.strategy === "higher-phase" ||
+                    r.strategy === "higher-priority-status") {
+                    // Surfaced for downstream evidence append (loser rationale)
+                }
+                break;
+            }
+            case "recomputed": {
+                // retrievalWeight is recomputed downstream; keep base value as placeholder.
+                merged[key] = baseV ?? oursV;
+                break;
+            }
+            case "passthrough":
+            default: {
+                // Unknown fields: keep ours if both present
+                merged[key] = oursV ?? theirsV ?? baseV;
+                break;
+            }
+        }
+    }
+    if (escalatedFields.length > 0) {
+        const wrapped = `<<<<<<< ours\n${oursRaw}\n=======\n${theirsRaw}\n>>>>>>> theirs\n`;
+        return {
+            merged: ours, // provisional; caller should use mergedContent
+            mergedContent: wrapped,
+            escalated: true,
+            strategy: `synapse escalated: ${escalatedFields.join(", ")}`,
+            arbitratedWinner: null,
+        };
+    }
+    // Reconstruct Synapse from merged record.
+    const mergedSynapse = reconstructSynapse(merged);
+    const serialized = serializeSynapseFile(mergedSynapse, "en");
+    const strategyBits = [];
+    if (arbitratedWinner) {
+        strategyBits.push(`arbitrated(${arbitratedWinner})`);
+    }
+    strategyBits.push(`evidence[${mergedSynapse.evidence.length}]`, `updatedAt-max`);
+    return {
+        merged: mergedSynapse,
+        mergedContent: serialized,
+        escalated: false,
+        strategy: `synapse: ${strategyBits.join(" + ")}`,
+        arbitratedWinner,
+    };
+}
+/**
+ * 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 async function mergeSynapseFileAsync(params) {
+    // Step 1: Layer A (sync)
+    const layerA = mergeSynapseFile(params);
+    if (!layerA.escalated) {
+        return layerA;
+    }
+    // Parse escalated field names from strategy string ("synapse escalated: a, b")
+    const fieldsList = layerA.strategy.replace(/^synapse escalated:\s*/, "");
+    const escalatedFields = fieldsList
+        .split(", ")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    // Step 2: 仅对 updatedAt_arbitration 类型字段调 LLM
+    const base = parseSynapseFile(params.baseRaw);
+    const ours = parseSynapseFile(params.oursRaw);
+    const theirs = parseSynapseFile(params.theirsRaw);
+    const baseRec = base;
+    const oursRec = ours;
+    const theirsRec = theirs;
+    const preResolvedFields = {};
+    let resolvedCount = 0;
+    let llmAttempted = 0;
+    const stillEscalatedImmutable = [];
+    for (const fieldName of escalatedFields) {
+        const klass = classifySynapseField(fieldName);
+        if (klass !== "updatedAt_arbitration") {
+            // immutable / state_machine 等 — 不让 LLM 介入
+            stillEscalatedImmutable.push(fieldName);
+            continue;
+        }
+        llmAttempted++;
+        const llmInput = {
+            conflictType: "synapse_field",
+            path: params.path,
+            fieldName,
+            base: baseRec[fieldName],
+            ours: oursRec[fieldName],
+            theirs: theirsRec[fieldName],
+            meta: {
+                oursUpdatedAt: ours.updatedAt,
+                theirsUpdatedAt: theirs.updatedAt,
+                oursUpdatedBy: oursRec.createdBy ?? "unknown",
+                theirsUpdatedBy: theirsRec.createdBy ?? "unknown",
+            },
+        };
+        const result = await params.arbiter.arbitrate(llmInput);
+        if (result.verdict.kind === "resolved") {
+            const output = result.verdict.output;
+            if (output.verdict === "merge" && "mergedValue" in output) {
+                preResolvedFields[fieldName] = output.mergedValue;
+                resolvedCount++;
+            }
+            else if (output.verdict === "ours") {
+                preResolvedFields[fieldName] = oursRec[fieldName];
+                resolvedCount++;
+            }
+            else if (output.verdict === "theirs") {
+                preResolvedFields[fieldName] = theirsRec[fieldName];
+                resolvedCount++;
+            }
+            // verdict=escalate → 不填,该字段继续走 Layer A escalate
+        }
+    }
+    if (resolvedCount === 0) {
+        // LLM 一无所获 — 返回原 escalate 结果
+        return layerA;
+    }
+    // Step 3: 用 preResolvedFields 重跑合并
+    const merged2 = mergeSynapseFile({
+        ...params,
+        preResolvedFields,
+    });
+    // 注:如果仍有 immutable 字段 escalate,merged2.escalated 仍为 true
+    // 在 strategy 中标注 LLM 解决了多少
+    if (merged2.escalated) {
+        return merged2; // immutable 字段仍 escalate,strategy 不变
+    }
+    return {
+        ...merged2,
+        strategy: `${merged2.strategy} + llm:${resolvedCount}/${llmAttempted} resolved`,
+    };
+}
+function reconstructSynapse(record) {
+    // Ensure required fields are present (they are immutable so always exist).
+    return {
+        id: record.id,
+        from: record.from,
+        to: record.to,
+        kind: record.kind,
+        weight: typeof record.weight === "number" ? record.weight : 0.5,
+        direction: record.direction ?? "directional",
+        evidence: record.evidence ?? [],
+        createdBy: record.createdBy ?? "",
+        createdAt: record.createdAt ?? "",
+        updatedAt: record.updatedAt ?? "",
+        retrievalWeight: typeof record.retrievalWeight === "number"
+            ? record.retrievalWeight
+            : 0.5,
+        sourceSemantic: record.sourceSemantic,
+        targetSemantic: record.targetSemantic,
+        resolutionState: record.resolutionState,
+    };
+}
+//# sourceMappingURL=synapse-merger.js.map

package/dist/merge/synapse-merger.js.map

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

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

@@ -0,0 +1,66 @@
+/**
+ * Synapse field classification and simple merge rules (spec §6.1).
+ *
+ * Field classes:
+ *   - immutable            : id/from/to/kind/createdBy/createdAt — identity
+ *   - updatedAt_arbitration: weight/direction/sourceSemantic/targetSemantic
+ *   - max_updatedAt        : updatedAt itself
+ *   - array_union          : evidence (handled in evidence-union.ts)
+ *   - recomputed           : retrievalWeight (system-derived)
+ *   - state_machine        : resolutionState (handled in resolution-state.ts)
+ *   - passthrough          : unknown fields — keep base if unchanged, else ours
+ *
+ * @module @co-engram/core/merge
+ */
+export type SynapseFieldClass = "immutable" | "updatedAt_arbitration" | "max_updatedAt" | "array_union" | "recomputed" | "state_machine" | "passthrough";
+export declare function classifySynapseField(fieldName: string): SynapseFieldClass;
+/** Thrown when an immutable synapse field is divergently edited by both sides. */
+export declare class ImmutableSynapseViolationError extends Error {
+    readonly fieldName: string;
+    readonly ours: unknown;
+    readonly theirs: unknown;
+    readonly base: unknown;
+    constructor(params: {
+        fieldName: string;
+        base: unknown;
+        ours: unknown;
+        theirs: unknown;
+    });
+}
+/**
+ * Merge an immutable synapse field.
+ *
+ * - base == ours == theirs → base
+ * - one side changed → that side's value
+ * - both sides changed to the same value → that value
+ * - both sides changed differently → throw ImmutableSynapseViolationError
+ */
+export declare function mergeSynapseImmutableField<T>(params: {
+    base: T;
+    ours: T;
+    theirs: T;
+    fieldName: string;
+}): T;
+/**
+ * Merge a field whose value is chosen by updatedAt arbitration.
+ *
+ * Returns:
+ *   - { value, winner } on clean arbitration (winner is 'ours' | 'theirs')
+ *   - { value, winner: null } when neither side changed
+ *   - { escalated: true } when updatedAt ties (caller should escalate)
+ */
+export declare function mergeSynapseUpdatedAtField<T>(params: {
+    base: T;
+    ours: T;
+    theirs: T;
+    oursUpdatedAt: string;
+    theirsUpdatedAt: string;
+}): {
+    value: T;
+    winner: "ours" | "theirs" | null;
+} | {
+    escalated: true;
+};
+/** max(ours, theirs) for ISO timestamps (lexicographic compare works for UTC). */
+export declare function mergeSynapseMaxUpdatedAt(oursUpdatedAt: string, theirsUpdatedAt: string): string;
+//# sourceMappingURL=synapse-rules.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"synapse-rules.d.ts","sourceRoot":"","sources":["../../src/merge/synapse-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,uBAAuB,GACvB,eAAe,GACf,aAAa,GACb,YAAY,GACZ,eAAe,GACf,aAAa,CAAC;AAkBlB,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,iBAAiB,CASzE;AAED,kFAAkF;AAClF,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,MAAM,EAAE;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,OAAO,CAAC;QACd,IAAI,EAAE,OAAO,CAAC;QACd,MAAM,EAAE,OAAO,CAAC;KACjB;CAUF;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,MAAM,EAAE;IACpD,IAAI,EAAE,CAAC,CAAC;IACR,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,EAAE,CAAC,CAAC;IACV,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,CAAC,CAWJ;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,MAAM,EAAE;IACpD,IAAI,EAAE,CAAC,CAAC;IACR,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,EAAE,CAAC,CAAC;IACV,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAYvE;AAED,kFAAkF;AAClF,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,GACtB,MAAM,CAER"}

package/dist/merge/synapse-rules.js

@@ -0,0 +1,112 @@
+/**
+ * Synapse field classification and simple merge rules (spec §6.1).
+ *
+ * Field classes:
+ *   - immutable            : id/from/to/kind/createdBy/createdAt — identity
+ *   - updatedAt_arbitration: weight/direction/sourceSemantic/targetSemantic
+ *   - max_updatedAt        : updatedAt itself
+ *   - array_union          : evidence (handled in evidence-union.ts)
+ *   - recomputed           : retrievalWeight (system-derived)
+ *   - state_machine        : resolutionState (handled in resolution-state.ts)
+ *   - passthrough          : unknown fields — keep base if unchanged, else ours
+ *
+ * @module @co-engram/core/merge
+ */
+const IMMUTABLE_SYNASPSE_FIELDS = new Set([
+    "id",
+    "from",
+    "to",
+    "kind",
+    "createdBy",
+    "createdAt",
+]);
+const UPDATED_AT_ARBITRATION_FIELDS = new Set([
+    "weight",
+    "direction",
+    "sourceSemantic",
+    "targetSemantic",
+]);
+export function classifySynapseField(fieldName) {
+    if (IMMUTABLE_SYNASPSE_FIELDS.has(fieldName))
+        return "immutable";
+    if (UPDATED_AT_ARBITRATION_FIELDS.has(fieldName))
+        return "updatedAt_arbitration";
+    if (fieldName === "updatedAt")
+        return "max_updatedAt";
+    if (fieldName === "evidence")
+        return "array_union";
+    if (fieldName === "retrievalWeight")
+        return "recomputed";
+    if (fieldName === "resolutionState")
+        return "state_machine";
+    return "passthrough";
+}
+/** Thrown when an immutable synapse field is divergently edited by both sides. */
+export class ImmutableSynapseViolationError extends Error {
+    fieldName;
+    ours;
+    theirs;
+    base;
+    constructor(params) {
+        super(`Immutable synapse field "${params.fieldName}" divergently edited: ours=${JSON.stringify(params.ours)} theirs=${JSON.stringify(params.theirs)} base=${JSON.stringify(params.base)}`);
+        this.name = "ImmutableSynapseViolationError";
+        this.fieldName = params.fieldName;
+        this.ours = params.ours;
+        this.theirs = params.theirs;
+        this.base = params.base;
+    }
+}
+/**
+ * Merge an immutable synapse field.
+ *
+ * - base == ours == theirs → base
+ * - one side changed → that side's value
+ * - both sides changed to the same value → that value
+ * - both sides changed differently → throw ImmutableSynapseViolationError
+ */
+export function mergeSynapseImmutableField(params) {
+    const { base, ours, theirs, fieldName } = params;
+    if (ours === theirs)
+        return ours;
+    if (base === ours)
+        return theirs;
+    if (base === theirs)
+        return ours;
+    throw new ImmutableSynapseViolationError({
+        fieldName,
+        base,
+        ours,
+        theirs,
+    });
+}
+/**
+ * Merge a field whose value is chosen by updatedAt arbitration.
+ *
+ * Returns:
+ *   - { value, winner } on clean arbitration (winner is 'ours' | 'theirs')
+ *   - { value, winner: null } when neither side changed
+ *   - { escalated: true } when updatedAt ties (caller should escalate)
+ */
+export function mergeSynapseUpdatedAtField(params) {
+    const { base, ours, theirs, oursUpdatedAt, theirsUpdatedAt } = params;
+    if (ours === theirs)
+        return { value: ours, winner: null };
+    if (base === ours && base === theirs)
+        return { value: base, winner: null };
+    // Only one side changed → take it without arbitration
+    if (base === ours)
+        return { value: theirs, winner: "theirs" };
+    if (base === theirs)
+        return { value: ours, winner: "ours" };
+    // Both sides changed differently → arbitrate by updatedAt
+    if (oursUpdatedAt === theirsUpdatedAt)
+        return { escalated: true };
+    return oursUpdatedAt > theirsUpdatedAt
+        ? { value: ours, winner: "ours" }
+        : { value: theirs, winner: "theirs" };
+}
+/** max(ours, theirs) for ISO timestamps (lexicographic compare works for UTC). */
+export function mergeSynapseMaxUpdatedAt(oursUpdatedAt, theirsUpdatedAt) {
+    return oursUpdatedAt >= theirsUpdatedAt ? oursUpdatedAt : theirsUpdatedAt;
+}
+//# sourceMappingURL=synapse-rules.js.map

package/dist/merge/synapse-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"synapse-rules.js","sourceRoot":"","sources":["../../src/merge/synapse-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAWH,MAAM,yBAAyB,GAAG,IAAI,GAAG,CAAC;IACxC,IAAI;IACJ,MAAM;IACN,IAAI;IACJ,MAAM;IACN,WAAW;IACX,WAAW;CACZ,CAAC,CAAC;AAEH,MAAM,6BAA6B,GAAG,IAAI,GAAG,CAAC;IAC5C,QAAQ;IACR,WAAW;IACX,gBAAgB;IAChB,gBAAgB;CACjB,CAAC,CAAC;AAEH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,IAAI,yBAAyB,CAAC,GAAG,CAAC,SAAS,CAAC;QAAE,OAAO,WAAW,CAAC;IACjE,IAAI,6BAA6B,CAAC,GAAG,CAAC,SAAS,CAAC;QAC9C,OAAO,uBAAuB,CAAC;IACjC,IAAI,SAAS,KAAK,WAAW;QAAE,OAAO,eAAe,CAAC;IACtD,IAAI,SAAS,KAAK,UAAU;QAAE,OAAO,aAAa,CAAC;IACnD,IAAI,SAAS,KAAK,iBAAiB;QAAE,OAAO,YAAY,CAAC;IACzD,IAAI,SAAS,KAAK,iBAAiB;QAAE,OAAO,eAAe,CAAC;IAC5D,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,kFAAkF;AAClF,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IAC9C,SAAS,CAAS;IAClB,IAAI,CAAU;IACd,MAAM,CAAU;IAChB,IAAI,CAAU;IAEvB,YAAY,MAKX;QACC,KAAK,CACH,4BAA4B,MAAM,CAAC,SAAS,8BAA8B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CACpL,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;QAC7C,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAI,MAK7C;IACC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IACjD,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IACjC,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACjC,MAAM,IAAI,8BAA8B,CAAC;QACvC,SAAS;QACT,IAAI;QACJ,IAAI;QACJ,MAAM;KACP,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAI,MAM7C;IACC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,eAAe,EAAE,GAAG,MAAM,CAAC;IACtE,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC1D,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC3E,sDAAsD;IACtD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC9D,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC5D,0DAA0D;IAC1D,IAAI,aAAa,KAAK,eAAe;QAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAClE,OAAO,aAAa,GAAG,eAAe;QACpC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE;QACjC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC1C,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,wBAAwB,CACtC,aAAqB,EACrB,eAAuB;IAEvB,OAAO,aAAa,IAAI,eAAe,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,CAAC;AAC5E,CAAC"}

package/dist/merge/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Driver bundle version (single source of truth).
+ *
+ * Bumped on any change to driver behavior. Onboard uses this to decide
+ * whether to overwrite ~/.co-engram/merge-driver.js.
+ *
+ * @module @co-engram/core/merge
+ */
+export declare const DRIVER_BUNDLE_VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/merge/version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,qBAAqB,UAAU,CAAC"}

package/dist/merge/version.js

@@ -0,0 +1,10 @@
+/**
+ * Driver bundle version (single source of truth).
+ *
+ * Bumped on any change to driver behavior. Onboard uses this to decide
+ * whether to overwrite ~/.co-engram/merge-driver.js.
+ *
+ * @module @co-engram/core/merge
+ */
+export const DRIVER_BUNDLE_VERSION = "0.1.0";
+//# sourceMappingURL=version.js.map

package/dist/merge/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/merge/version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC"}