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 };
+}