feat: mergeArtifacts — deterministic union-by-id with surfaced conflicts (F5 SLICE-3, INV-17, #14)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/mergeArtifacts.ts

@@ -0,0 +1,138 @@
+/**
+ * mergeArtifacts — the contract's merge semantics (INV-17) as a pure, vscode-
+ * free reference implementation (contract §6). 2-way union-by-id; every
+ * same-id divergence is resolved by the documented deterministic rules AND
+ * surfaced in `conflicts` — never silently guessed (INV-1's spirit at the
+ * artifact level). Refuses differing majors (INV-16: a rung never merges what
+ * it can't fully read). Not wired into any UI — rungs and humans invoke it; a
+ * .gitattributes merge driver is a later convenience (spec §1.7).
+ */
+import type { Artifact, Message, Thread } from "./model";
+
+export interface MergeResult {
+  merged: Artifact;
+  /** ids (or root keys) whose divergence was rule-resolved — surfaced, never silent. */
+  conflicts: string[];
+}
+
+type Rec = Record<string, unknown>;
+
+/** Order-insensitive canonical form: all object keys sorted, no whitespace (contract §6). */
+function stableStringify(v: unknown): string {
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(",")}]`;
+  if (v !== null && typeof v === "object") {
+    const rec = v as Rec;
+    return `{${Object.keys(rec)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${stableStringify(rec[k])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(v);
+}
+
+const same = (a: unknown, b: unknown): boolean => stableStringify(a) === stableStringify(b);
+
+/** Deterministic, symmetric tie-break: the lexicographically larger canonical form wins. */
+function lexLarger<T>(a: T, b: T): T {
+  return stableStringify(a) >= stableStringify(b) ? a : b;
+}
+
+/**
+ * Union two record arrays by id: one-side-only records pass through, identical
+ * records dedupe, same-id divergence is handed to `resolveDivergent` (which
+ * owns both picking the winner and reporting the conflict). Ours-order first,
+ * theirs-only appended in theirs-order.
+ */
+function unionById<T extends { id: string }>(ours: T[], theirs: T[], resolveDivergent: (o: T, t: T) => T): T[] {
+  const theirsById = new Map(theirs.map((t) => [t.id, t]));
+  const ourIds = new Set(ours.map((o) => o.id));
+  const out: T[] = [];
+  for (const o of ours) {
+    const t = theirsById.get(o.id);
+    out.push(t === undefined || same(o, t) ? o : resolveDivergent(o, t));
+  }
+  for (const t of theirs) if (!ourIds.has(t.id)) out.push(t);
+  return out;
+}
+
+/**
+ * Same-id threads: the shell (every field but `messages`) and the messages
+ * merge independently (contract §6). Divergent shells tie-break and report the
+ * thread id; messages union by id ordered by (createdAt, id), per-message
+ * divergence tie-breaks and reports the message id. The forge reply-append
+ * case merges cleanly by construction (fresh uuids, disjoint additions).
+ */
+function mergeThread(o: Thread, t: Thread, conflicts: string[]): Thread {
+  const { messages: oMsgs, ...oShell } = o;
+  const { messages: tMsgs, ...tShell } = t;
+  let shell = oShell;
+  if (!same(oShell, tShell)) {
+    conflicts.push(o.id);
+    shell = lexLarger(oShell, tShell);
+  }
+  const messages: Message[] = unionById(oMsgs, tMsgs, (a, b) => {
+    conflicts.push(a.id);
+    return lexLarger(a, b);
+  }).sort((a, b) =>
+    a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0,
+  );
+  return { ...shell, messages } as Thread;
+}
+
+export function mergeArtifacts(ours: Artifact, theirs: Artifact): MergeResult {
+  if (ours.schemaVersion !== theirs.schemaVersion) {
+    throw new Error(
+      `cannot merge differing schemaVersion majors: ${ours.schemaVersion} vs ${theirs.schemaVersion} (INV-16)`,
+    );
+  }
+  const conflicts: string[] = [];
+
+  // anchors: union by key; divergent same key → tie-break, reported.
+  const anchors: Artifact["anchors"] = { ...theirs.anchors, ...ours.anchors };
+  for (const k of Object.keys(ours.anchors)) {
+    const t = theirs.anchors[k];
+    if (t !== undefined && !same(ours.anchors[k], t)) {
+      conflicts.push(k);
+      anchors[k] = lexLarger(ours.anchors[k], t);
+    }
+  }
+
+  const threads = unionById(ours.threads, theirs.threads, (o, t) => mergeThread(o, t, conflicts));
+
+  const attributions = unionById(ours.attributions, theirs.attributions, (o, t) => {
+    conflicts.push(o.id);
+    // newer updatedAt wins; equal updatedAt falls through to the tie-break.
+    if (o.updatedAt !== t.updatedAt) return o.updatedAt > t.updatedAt ? o : t;
+    return lexLarger(o, t);
+  });
+
+  const proposals = unionById(ours.proposals, theirs.proposals, (o, t) => {
+    conflicts.push(o.id);
+    return lexLarger(o, t);
+  });
+
+  // root: known sections merged above; document must agree; unknown root keys
+  // union with the same tie-break + report (contract §6).
+  const KNOWN_ROOT = new Set(["schemaVersion", "document", "anchors", "threads", "attributions", "proposals"]);
+  let document = ours.document;
+  if (!same(ours.document, theirs.document)) {
+    conflicts.push("document");
+    document = lexLarger(ours.document, theirs.document);
+  }
+  const merged = { schemaVersion: ours.schemaVersion, document, anchors, threads, attributions, proposals } as Artifact &
+    Rec;
+  const oRec = ours as unknown as Rec;
+  const tRec = theirs as unknown as Rec;
+  for (const k of [...new Set([...Object.keys(oRec), ...Object.keys(tRec)])].sort()) {
+    if (KNOWN_ROOT.has(k)) continue;
+    const inO = k in oRec;
+    const inT = k in tRec;
+    if (inO && inT && !same(oRec[k], tRec[k])) {
+      conflicts.push(k);
+      merged[k] = lexLarger(oRec[k], tRec[k]);
+    } else {
+      merged[k] = inO ? oRec[k] : tRec[k];
+    }
+  }
+  return { merged, conflicts };
+}

test/mergeArtifacts.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect } from "vitest";
+import { emptyArtifact, type Artifact } from "../src/model";
+import { mergeArtifacts } from "../src/mergeArtifacts";
+import { expectValidSidecar } from "./helpers/validateSidecar";
+
+const FP = { text: "alpha", before: "", after: "", lineHint: 0 };
+
+function base(): Artifact {
+  const a = emptyArtifact("docs/x.md");
+  a.anchors["a_1"] = { fingerprint: FP };
+  a.threads.push({
+    id: "t_1",
+    anchorId: "a_1",
+    status: "open",
+    messages: [{ id: "m_1", author: { kind: "human", id: "ben" }, body: "hi", createdAt: "2026-06-10T00:00:00.000Z" }],
+  });
+  return a;
+}
+const clone = (a: Artifact): Artifact => JSON.parse(JSON.stringify(a));
+
+describe("mergeArtifacts (F5 SLICE-3, INV-17)", () => {
+  it("reply-append vs disjoint edit unions cleanly, no conflicts (the forge case)", () => {
+    const ours = base();
+    ours.attributions.push({
+      id: "at_1",
+      anchorId: "a_1",
+      author: { kind: "human", id: "ben" },
+      createdAt: "2026-06-10T01:00:00.000Z",
+      updatedAt: "2026-06-10T01:00:00.000Z",
+    });
+    const theirs = base();
+    theirs.threads[0].messages.push({
+      id: "m_2",
+      author: { kind: "human", id: "forge", email: "forge@example.org" },
+      body: "reply",
+      createdAt: "2026-06-10T02:00:00.000Z",
+    });
+    const { merged, conflicts } = mergeArtifacts(ours, theirs);
+    expect(conflicts).toEqual([]);
+    expect(merged.threads[0].messages.map((m) => m.id)).toEqual(["m_1", "m_2"]);
+    expect(merged.attributions.map((a) => a.id)).toEqual(["at_1"]);
+    expectValidSidecar(merged);
+  });
+
+  it("both sides append to the same thread: messages interleave by createdAt, no conflicts", () => {
+    const ours = base();
+    ours.threads[0].messages.push({ id: "m_b", author: { kind: "human", id: "ben" }, body: "B", createdAt: "2026-06-10T03:00:00.000Z" });
+    const theirs = base();
+    theirs.threads[0].messages.push({ id: "m_a", author: { kind: "human", id: "forge" }, body: "A", createdAt: "2026-06-10T02:00:00.000Z" });
+    const { merged, conflicts } = mergeArtifacts(ours, theirs);
+    expect(conflicts).toEqual([]);
+    expect(merged.threads[0].messages.map((m) => m.id)).toEqual(["m_1", "m_a", "m_b"]);
+  });
+
+  it("same attribution id divergent: newer updatedAt wins and the id is reported", () => {
+    const rec = {
+      id: "at_1",
+      anchorId: "a_1",
+      author: { kind: "human", id: "ben" } as const,
+      createdAt: "2026-06-10T00:00:00.000Z",
+      updatedAt: "2026-06-10T00:00:00.000Z",
+    };
+    const ours = base();
+    ours.attributions.push({ ...rec, updatedAt: "2026-06-10T05:00:00.000Z" });
+    const theirs = base();
+    theirs.attributions.push({ ...rec, updatedAt: "2026-06-10T04:00:00.000Z", turnId: "turn-x" });
+    const { merged, conflicts } = mergeArtifacts(ours, theirs);
+    expect(conflicts).toEqual(["at_1"]);
+    expect(merged.attributions[0].updatedAt).toBe("2026-06-10T05:00:00.000Z");
+    expect(merged.attributions[0].turnId).toBeUndefined();
+  });
+
+  it("divergent same-id proposals: deterministic tie-break, id reported, symmetric result", () => {
+    const p = {
+      id: "p_1",
+      anchorId: "a_1",
+      replacement: "AAA",
+      author: { kind: "human", id: "ben" } as const,
+      createdAt: "2026-06-10T00:00:00.000Z",
+    };
+    const ours = base();
+    ours.proposals.push({ ...p });
+    const theirs = base();
+    theirs.proposals.push({ ...p, replacement: "ZZZ" });
+    const r1 = mergeArtifacts(ours, theirs);
+    const r2 = mergeArtifacts(theirs, ours);
+    expect(r1.conflicts).toEqual(["p_1"]);
+    expect(r1.merged.proposals[0].replacement).toBe("ZZZ");
+    expect(r2.merged.proposals[0].replacement).toBe("ZZZ");
+  });
+
+  it("thread status divergence resolves deterministically and reports the thread id", () => {
+    const ours = base();
+    const theirs = clone(ours);
+    theirs.threads[0].status = "resolved";
+    const { merged, conflicts } = mergeArtifacts(ours, theirs);
+    expect(merged.threads[0].status).toBe("resolved");
+    expect(conflicts).toEqual(["t_1"]);
+  });
+
+  it("divergent same-id messages tie-break symmetrically and report the message id", () => {
+    const ours = base();
+    const theirs = clone(ours);
+    theirs.threads[0].messages[0].body = "hi (edited)";
+    const r1 = mergeArtifacts(ours, theirs);
+    const r2 = mergeArtifacts(theirs, ours);
+    expect(r1.conflicts).toEqual(["m_1"]);
+    expect(r2.conflicts).toEqual(["m_1"]);
+    // deterministic + symmetric: both directions pick the same winner
+    expect(r1.merged.threads[0].messages[0].body).toBe(r2.merged.threads[0].messages[0].body);
+  });
+
+  it("anchors union by key; divergent same key reported", () => {
+    const ours = base();
+    const theirs = base();
+    theirs.anchors["a_2"] = { fingerprint: { ...FP, text: "beta" } };
+    const clean = mergeArtifacts(ours, theirs);
+    expect(Object.keys(clean.merged.anchors).sort()).toEqual(["a_1", "a_2"]);
+    expect(clean.conflicts).toEqual([]);
+    const theirs2 = clone(ours);
+    theirs2.anchors["a_1"] = { fingerprint: { ...FP, lineHint: 9 } };
+    const dirty = mergeArtifacts(ours, theirs2);
+    expect(dirty.conflicts).toEqual(["a_1"]);
+  });
+
+  it("unknown fields ride with the winning record and root unknowns union", () => {
+    const ours = base() as Artifact & Record<string, unknown>;
+    ours.futureSection = [1];
+    const theirs = base() as Artifact & Record<string, unknown>;
+    theirs.otherFuture = "x";
+    const { merged, conflicts } = mergeArtifacts(ours, theirs);
+    expect((merged as unknown as Record<string, unknown>).futureSection).toEqual([1]);
+    expect((merged as unknown as Record<string, unknown>).otherFuture).toBe("x");
+    expect(conflicts).toEqual([]);
+  });
+
+  it("throws on differing majors (INV-16)", () => {
+    const ours = base();
+    const theirs = { ...base(), schemaVersion: 2 };
+    expect(() => mergeArtifacts(ours, theirs)).toThrow(/schemaVersion/);
+  });
+});