@tobq/boardclip 2.1.113 → 2.1.114

package/lib/clipboard-model.js

@@ -1,6 +1,9 @@
 'use strict';
 
 const crypto = require('crypto');
+// The ONE tag rule (flat, case-insensitive, comma input, retired nested names) lives in
+// the isomorphic search engine so the popup, the demo, MCP and this model share it.
+const Tags = require('../site/shared/clip-search');
 
 const DEFAULT_SETTINGS = {
   max_age_days: 7,
@@ -42,6 +45,7 @@ const DEFAULT_SETTINGS = {
   options_panel_height: 0,
   show_shortcut: '',
   quick_paste_shortcut: '',
+  new_note_shortcut: '',
   // Quick-paste (numpad slots + panel number keys) behaviour. Per-machine, not
   // synced — these are about how THIS machine drives the OS paste, not content.
   // 'clipboard' = the real paste API (set clipboard + Ctrl/Cmd+V + restore),
@@ -52,6 +56,19 @@ const DEFAULT_SETTINGS = {
   quick_paste_restore: true,          // restore the previous clipboard after a quick-paste
   quick_paste_restore_delay_ms: 400,  // floor delay before restore; adapts up under lag
   groups: [],
+  // Tags nested with '/' before the flat-tags cutover (14 Oct 2026), split once into their
+  // parts: [{ name, parts, at }]. Synced and permanent, so an old device, a stale cloud copy,
+  // an old backup or an agent still writing 'todo/forge' lands as todo + forge.
+  group_splits: [],
+  // Tags with a '/' in their name made on a flat-tags device, where the '/' is a plain
+  // character: [{ name, at }]. Synced and permanent. A device on its first flat start
+  // cannot tell such a name from an old nested one and retires it; this record overrules
+  // that split everywhere (groupSplitMap); a merge joins the parts back into the name
+  // (rejoinLiterals) and that device puts it back on its own clips (unsplitLiterals).
+  group_literals: [],
+  // When THIS device cut over to flat tags (ms). Per device, never synced: before it, every
+  // '/' in a tag name meant nesting; after it, a new name's '/' is a plain character.
+  groups_flattened_at: 0,
   sync_path: '',
   sync_custom_paths: [],
   sync_disabled_paths: [],
@@ -73,6 +90,9 @@ const DEFAULT_SETTINGS = {
   // AI Access (local MCP server). See lib/mcp-core.js and the MCP section in main.js.
   ai_access_enabled: false,
   groups_shared_with_ai: [],   // group names whose clips are exposed to AI (curation allowlist)
+  // Explicit share-switch flips, synced per tag: { [tagKey]: { shared, at } }; the newest flip
+  // wins on every device. A device's list keeps its own state for tags never flipped.
+  ai_share_stamps: {},
   ai_always_allow: [],         // MCP tool names the user chose to always allow (skip approval modal)
   ai_approval_timeout_sec: 60, // approval modal deny-by-default countdown
   mcp_secret: '',              // per-machine control-channel HMAC secret (not synced)
@@ -333,11 +353,14 @@ function tombstoneRecord(source, deletedAt) {
 //    stays deleted even when clock skew makes it look newer than the delete.
 // A genuinely newer copy - edited elsewhere (different rev) or re-added later
 // (newer clock) - survives.
-function tombstoneSuppresses(tombstone, item) {
+// rawRev: the copy's revision before its tags were normalised (a delete made by a build
+// that still held the nested names records the nested rev).
+function tombstoneSuppresses(tombstone, item, rawRev = '') {
   if (!tombstone || !item) return false;
   const clock = itemMutationClock(item);
   if (clock <= (Number(tombstone.deletedAt) || 0)) return true;
-  return !!tombstone.rev && clipRevision(item) === tombstone.rev && clock <= tombstone.revClock;
+  if (!tombstone.rev || clock > tombstone.revClock) return false;
+  return clipRevision(item) === tombstone.rev || (!!rawRev && rawRev === tombstone.rev);
 }
 
 function normalizeTombstones(list, now = Date.now()) {
@@ -353,18 +376,144 @@ function normalizeTombstones(list, now = Date.now()) {
   return [...byId.values()];
 }
 
+// Tag deletes, { name, deletedAt, restoredAt?, anyCase? }: the newest delete and the newest
+// re-create of one tag. A flat-tags build writes anyCase (the tag in any spelling). A record
+// without it was written by a build from before 14 Oct 2026, when 'Work' and 'work' were two
+// tags: it deletes that exact spelling only, so a live twin survives. A record stays while
+// its delete or its re-create is under 30 days old.
 function normalizeGroupTombstones(list, now = Date.now()) {
   const cutoff = now - TOMBSTONE_MAX_AGE_MS;
-  const byName = new Map();
+  const bySlot = new Map();
   for (const tombstone of Array.isArray(list) ? list : []) {
     if (!tombstone || !tombstone.name) continue;
-    const name = String(tombstone.name);
+    const name = Tags.cleanTagName(tombstone.name);
+    if (!name) continue;
+    const anyCase = tombstone.anyCase === true;
+    const slot = anyCase ? `k:${Tags.tagKey(name)}` : `x:${name}`;
     const deletedAt = Number(tombstone.deletedAt) || 0;
-    if (deletedAt < cutoff) continue;
-    const existing = byName.get(name);
-    if (!existing || deletedAt > existing.deletedAt) byName.set(name, { name, deletedAt });
+    const restoredAt = Number(tombstone.restoredAt) || 0;
+    const record = bySlot.get(slot) || (anyCase ? { name, deletedAt: 0, anyCase: true } : { name, deletedAt: 0 });
+    if (anyCase) record.name = Tags.preferredSpelling(record.name, name);
+    record.deletedAt = Math.max(record.deletedAt, deletedAt);
+    if (restoredAt > (record.restoredAt || 0)) record.restoredAt = restoredAt;
+    bySlot.set(slot, record);
+  }
+  return [...bySlot.values()].filter(t => Math.max(t.deletedAt, t.restoredAt || 0) >= cutoff);
+}
+
+// What the tag deletes do: a delete not re-created since takes the tag off every copy (a
+// re-create is how a deleted tag comes back, registerTags). After a re-create only a copy
+// whose tags were last changed at or before the delete loses it, so a stale pre-delete copy
+// cannot bring the old memberships back. key: tagKey -> state (flat-build records); exact:
+// spelling -> state (older builds' records, applied to a raw name before it is respelled).
+function groupTombstoneIndex(list) {
+  const key = new Map();
+  const exact = new Map();
+  for (const t of normalizeGroupTombstones(list)) {
+    const state = { deletedAt: t.deletedAt, recreated: (t.restoredAt || 0) > t.deletedAt };
+    if (t.anyCase) key.set(Tags.tagKey(t.name), state);
+    else exact.set(t.name, state);
+  }
+  return { key, exact, size: key.size + exact.size };
+}
+
+// Does this delete take a tag off a copy whose tags were last changed at `clock`? A name
+// list has no clock (Infinity): only deletes not re-created apply to it.
+function deleteStrips(state, clock = Infinity) {
+  return !!state && (!state.recreated || clock <= state.deletedAt);
+}
+
+// The AI tag (always shared with AI) is spelled exactly AI_TAG_NAME. Before 14 Oct 2026 a
+// tag spelled any other way ('ai', 'Ai') was a different, private tag: it keeps its clips
+// as "<its name> (old)" and never turns into the shared AI tag, from any copy on any
+// device. A flat build never writes such a spelling (tagInputNames gives AI_TAG_NAME).
+const AI_TAG_NAME = 'AI';
+const AI_TAG_KEY = AI_TAG_NAME.toLowerCase();
+function renameAiTwins(names) {
+  let out = null;
+  for (let i = 0; i < names.length; i++) {
+    const name = Tags.cleanTagName(names[i]);
+    if (name === AI_TAG_NAME || Tags.tagKey(name) !== AI_TAG_KEY) continue;
+    if (!out) out = names.slice();
+    out[i] = `${name} (old)`;
+  }
+  return out || names;
+}
+
+// A raw tag list (as a clip, a settings file or an older build holds it) before it is put
+// in stored form: exact-spelling deletes applied, AI twins renamed. The same array when
+// nothing changes.
+function rawTagNames(names, ctx, clock = Infinity) {
+  let list = Array.isArray(names) ? names : [];
+  const exact = ctx && ctx.tombstones && ctx.tombstones.exact;
+  if (exact && exact.size && list.length) {
+    const kept = list.filter(g => !deleteStrips(exact.get(Tags.cleanTagName(g)), clock));
+    if (kept.length !== list.length) list = kept;
+  }
+  return renameAiTwins(list);
+}
+
+// The retired nested names: tagKey(name) -> parts. Permanent; the earliest record of a
+// name wins so every device agrees. A part is never the AI tag: sharing a clip with AI is
+// the AI tag itself, never a sub-group of it ('AI/drafts' is drafts, private as it was).
+function normalizeGroupSplits(list) {
+  const byKey = new Map();
+  for (const record of Array.isArray(list) ? list : []) {
+    if (!record || !record.name) continue;
+    const name = String(record.name);
+    const key = Tags.tagKey(name);
+    if (!key) continue;
+    const parts = (Array.isArray(record.parts) ? record.parts : Tags.nestedNameParts(name)).map(Tags.cleanTagName)
+      .filter(part => part && Tags.tagKey(part) !== AI_TAG_KEY);
+    const at = Number(record.at) || 0;
+    const existing = byKey.get(key);
+    if (!existing || at < existing.at || (at === existing.at && name < existing.name)) byKey.set(key, { name, parts, at });
+  }
+  return [...byKey.values()].sort((a, b) => a.at - b.at || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+// '/' names made on a flat-tags device (plain '/'), one per tag, the earliest record.
+function normalizeGroupLiterals(list) {
+  const byKey = new Map();
+  for (const record of Array.isArray(list) ? list : []) {
+    const name = Tags.cleanTagName(record && typeof record === 'object' ? record.name : record);
+    const key = Tags.tagKey(name);
+    if (!key || !name.includes('/')) continue;
+    const at = Number(record && record.at) || 0;
+    const existing = byKey.get(key);
+    if (!existing || at < existing.at || (at === existing.at && name < existing.name)) byKey.set(key, { name, at });
   }
-  return [...byName.values()];
+  return [...byKey.values()].sort((a, b) => a.at - b.at || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+// tagKey(plain '/' name) -> { name, parts }: the parts a late cutover split it into (its
+// own record, else the name's segments).
+function literalPartsMap(settings = {}) {
+  const map = new Map();
+  const literals = normalizeGroupLiterals(settings.group_literals);
+  if (!literals.length) return map;
+  const recorded = new Map(normalizeGroupSplits(settings.group_splits).map(r => [Tags.tagKey(r.name), r.parts]));
+  for (const { name } of literals) {
+    const key = Tags.tagKey(name);
+    const parts = recorded.get(key) || Tags.nestedNameParts(name).filter(p => Tags.tagKey(p) !== AI_TAG_KEY);
+    if (parts.length) map.set(key, { name, parts });
+  }
+  return map;
+}
+
+// tagKey(retired name) -> parts, without the names a flat device made as plain '/' tags.
+function groupSplitMap(list, literals = []) {
+  const literal = new Set(normalizeGroupLiterals(literals).map(record => Tags.tagKey(record.name)));
+  const map = new Map();
+  for (const record of normalizeGroupSplits(list)) {
+    const key = Tags.tagKey(record.name);
+    if (!literal.has(key)) map.set(key, record.parts);
+  }
+  return map;
+}
+// The split map one device's settings give (what tagContext and the MCP rewrite use).
+function splitMapOf(settings = {}) {
+  return groupSplitMap(settings.group_splits, settings.group_literals);
 }
 
 function normalizeSupersedes(list, now = Date.now()) {
@@ -440,8 +589,60 @@ function tombstoneMap(list) {
   return new Map(normalizeTombstones(list).map(t => [t.id, t]));
 }
 
-function groupTombstoneNames(list) {
-  return new Set(normalizeGroupTombstones(list).map(t => t.name));
+// What every tag list is normalised against: the retired names, the stored spelling of
+// each tag, and the deleted tags. Built from settings plus any name lists in play (both
+// sides of a merge), so the spelling chosen is the same on every device.
+function tagContext(settings = {}, nameLists = []) {
+  const splits = splitMapOf(settings);
+  const tombstones = groupTombstoneIndex(settings.group_tombstones);
+  const ctx = { splits, tombstones, spellings: null, literals: literalPartsMap(settings) };
+  const lists = [settings.groups, ...nameLists].map(list => Tags.expandTagNames(rawTagNames(list, ctx), splits, null));
+  ctx.spellings = Tags.tagSpellings(lists);
+  return ctx;
+}
+
+// Every tag list held by a set of clips (for tagContext).
+function itemTagLists(...histories) {
+  const lists = [];
+  for (const history of histories) {
+    for (const item of Array.isArray(history) ? history : []) {
+      if (item && item.pin && Array.isArray(item.pin.groups) && item.pin.groups.length) lists.push(item.pin.groups);
+      else if (item && !('pin' in item) && item.group) lists.push([item.group]);
+    }
+  }
+  return lists;
+}
+
+// A list of tag names (no clock: settings.groups, typed input, new-note tags) in stored
+// form: retired names split, stored spellings, deleted tags dropped, one per tag.
+function normalizeTagList(names, ctx) {
+  return keepUndeletedGroups(Tags.expandTagNames(rawTagNames(names, ctx), ctx.splits, ctx.spellings), Infinity, ctx.tombstones);
+}
+
+// The tags typed or sent in one go (New group, a picker, an AI tool's group param):
+// an existing tag named in full is that tag (even with a comma in its name); else the
+// comma-separated names, a retired nested name as its parts, each in its stored
+// spelling. Never filtered by tombstones: typing a deleted tag's name re-creates it.
+function tagInputNames(input, settings = {}) {
+  const ctx = tagContext(settings);
+  return Tags.inputTagNames(input, settings.groups, ctx.splits, ctx.spellings)
+    .map(name => (Tags.sameTag(name, AI_TAG_NAME) ? AI_TAG_NAME : name));
+}
+
+// One clip's tags in stored form. PURE: returns the item itself when nothing changes and
+// otherwise a COPY with a new pin object (a merge receives the live history objects, and
+// an in-place change would hide from every change detector). Never moves a clock and never
+// removes the pin itself (an unpinned clip can be age-pruned).
+function normalizeItemTags(item, ctx) {
+  if (!item || !item.pin || !Array.isArray(item.pin.groups)) return item;
+  const pin = item.pin;
+  const clock = groupState(pin).updatedAt;
+  const groups = keepUndeletedGroups(Tags.expandTagNames(rawTagNames(pin.groups, ctx, clock), ctx.splits, ctx.spellings), clock, ctx.tombstones);
+  if (groups === pin.groups) return item;
+  const nextPin = { ...pin };
+  if (groups.length) nextPin.groups = groups;
+  else delete nextPin.groups;
+  return { ...item, pin: nextPin };
 }
 
 function timestamp(value) {
@@ -495,17 +696,38 @@ function numberState(pin, fallback = 0) {
   };
 }
 
-function cleanPin(pin, deletedGroups = new Set()) {
+// Stored-form names (already respelled): the any-case deletes. deletedGroups:
+// groupTombstoneIndex. The same array when nothing goes.
+function keepUndeletedGroups(groups, updatedAt, deletedGroups) {
+  if (!deletedGroups || !deletedGroups.key.size || !groups.length) return groups;
+  const kept = groups.filter(g => !deleteStrips(deletedGroups.key.get(Tags.tagKey(g)), updatedAt));
+  return kept.length === groups.length ? groups : kept;
+}
+
+function cleanPin(pin, deletedGroups = groupTombstoneIndex([])) {
   if (!pin) return null;
   const cleaned = { ...pin };
   if (typeof cleaned.number !== 'number') delete cleaned.number;
   if (Array.isArray(cleaned.groups)) {
-    cleaned.groups = cleaned.groups.filter(g => !deletedGroups.has(g));
+    cleaned.groups = keepUndeletedGroups(cleaned.groups, groupState(pin).updatedAt, deletedGroups);
     if (!cleaned.groups.length) delete cleaned.groups;
   }
   return cleaned;
 }
 
+// One entry per tag (case-insensitive), first spelling kept.
+function uniqueTags(groups) {
+  const seen = new Set();
+  const out = [];
+  for (const g of groups) {
+    const key = Tags.tagKey(g);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    out.push(g);
+  }
+  return out;
+}
+
 function mergeGroupState(localPin, remotePin, localUpdatedAt, remoteUpdatedAt, deletedGroups) {
   const local = groupState(localPin, localUpdatedAt);
   const remote = groupState(remotePin, remoteUpdatedAt);
@@ -526,7 +748,7 @@ function mergeGroupState(localPin, remotePin, localUpdatedAt, remoteUpdatedAt, d
     updatedAt = remote.updatedAt;
   }
 
-  groups = [...new Set(groups)].filter(g => !deletedGroups.has(g));
+  groups = keepUndeletedGroups(uniqueTags(groups), updatedAt, deletedGroups);
   return { known: local.known || remote.known, groups, updatedAt };
 }
 
@@ -548,7 +770,7 @@ function mergeNumberState(localPin, remotePin, localUpdatedAt, remoteUpdatedAt)
 
 function mergePins(localPin, remotePin, localUpdatedAt = 0, remoteUpdatedAt = 0, groupTombstones = []) {
   if (!localPin && !remotePin) return null;
-  const deletedGroups = groupTombstoneNames(groupTombstones);
+  const deletedGroups = groupTombstoneIndex(groupTombstones);
   const localPinUpdated = pinMetadataUpdatedAt(localPin, localUpdatedAt);
   const remotePinUpdated = pinMetadataUpdatedAt(remotePin, remoteUpdatedAt);
 
@@ -850,11 +1072,13 @@ function migrateLegacyNumpadSlots(history, oldSlots, options = {}) {
   return { changed, migrated, created, skipped };
 }
 
+// A new clip's tags (a new note, a fork, Keep both): callers pass them in stored form
+// (main's normalizeTagNames); deleted tags are dropped here as well.
 function groupsOnlyPin(groups, updatedAt, groupTombstones = []) {
-  const deleted = groupTombstoneNames(groupTombstones);
-  const cleanGroups = [...new Set((Array.isArray(groups) ? groups : [])
-    .map(group => String(group || '').trim())
-    .filter(group => group && !deleted.has(group)))];
+  const deleted = groupTombstoneIndex(groupTombstones);
+  const cleanGroups = keepUndeletedGroups(uniqueTags((Array.isArray(groups) ? groups : [])
+    .map(group => Tags.cleanTagName(group))
+    .filter(Boolean)), Infinity, deleted);
   if (!cleanGroups.length) return null;
   const ts = timestamp(updatedAt) || Date.now();
   return { groups: cleanGroups, updatedAt: ts, groupsUpdatedAt: ts };
@@ -1066,6 +1290,38 @@ function mergeHistories(local, remote, settings = {}, report = null) {
     ensureItemId(item);
     allKeys.add(itemKey(item));
   }
+  // Tags in stored form on both sides: a copy from an old build or a stale provider, a
+  // restored backup, a tag deleted on another device. By copy (these are the live history
+  // objects), and the raw rev kept so a delete recorded against the old form still matches.
+  const ctx = tagContext(settings, itemTagLists(local, remote));
+  const rawRevs = new Map();
+  const normaliseSide = (list, isLocal) => list.map(item => {
+    if (!item) return item;
+    const next = normalizeItemTags(item, ctx);
+    if (next !== item) {
+      rawRevs.set(next, clipRevision(item));
+      if (isLocal && report) report.push({ event: 'normalised', id: itemKey(item), split: groupsOf(item).some(g => ctx.splits.has(Tags.tagKey(g))) });
+    }
+    return next;
+  });
+  local = normaliseSide(local, true);
+  remote = normaliseSide(remote, false);
+  if (ctx.literals.size) {
+    const localAt = new Map();
+    local.forEach((item, i) => { if (item) localAt.set(itemKey(item), i); });
+    remote = remote.map(item => {
+      const i = item ? localAt.get(itemKey(item)) : undefined;
+      if (i === undefined) return item;
+      const [l, r] = rejoinLiterals(local[i], item, ctx.literals);
+      if (l !== local[i]) {
+        rawRevs.set(l, rawRevs.get(local[i]) || clipRevision(local[i]));
+        if (report) report.push({ event: 'normalised', id: itemKey(l), split: false });
+        local[i] = l;
+      }
+      if (r !== item) rawRevs.set(r, rawRevs.get(item) || clipRevision(item));
+      return r;
+    });
+  }
   const merged = new Map();
   const pendingStaleByTarget = new Map();
 
@@ -1093,7 +1349,7 @@ function mergeHistories(local, remote, settings = {}, report = null) {
       // mutation clock is at/older than the delete. A legitimately NEWER re-add
       // or edit of the same content-hash id beats the tombstone (no surprise
       // cross-device clobber); a stale pre-delete copy stays deleted.
-      if (tombstoneSuppresses(deleted.get(key), item)) return;
+      if (tombstoneSuppresses(deleted.get(key), item, rawRevs.get(item))) return;
     }
 
     if (targetKey && allKeys.has(targetKey)) {
@@ -1169,6 +1425,293 @@ function mergeHistories(local, remote, settings = {}, report = null) {
   return result;
 }
 
+function sameNames(a, b) {
+  const x = Array.isArray(a) ? a : [];
+  const y = Array.isArray(b) ? b : [];
+  return x.length === y.length && x.every((v, i) => v === y[i]);
+}
+
+// The flat-tags state of one device's files, PURE: the app runs it at load, the MCP helper
+// at every read (so it agrees with the app even mid-update), and tests and the live-data
+// replay call it directly. Items must already be through migrateItemPin.
+// Before this device's cutover (settings.groups_flattened_at unset) a '/' in a tag name
+// meant nesting, so each such name is retired into its parts (group_splits); after it, only
+// the retired names are split (a name another device made with a plain '/' never is:
+// group_literals). Then every tag list is put in stored form (normalizeTagList,
+// normalizeItemTags). At the cutover the AI share list follows the unanimous rule: a tag is
+// shared only if every name it came from was shared. The AI tag never comes from a split
+// or another spelling (normalizeGroupSplits, renameAiTwins), so no clip can become
+// AI-visible through it; a clip made visible through another shared tag unshares that tag.
+// Returns { history, settings (patch), changed, report, undo }. history holds the very
+// same objects for clips that did not change; undo lists each changed clip's old tags.
+function planTagState(history, settings = {}, options = {}) {
+  const now = Number(options.now) || Date.now();
+  const aiName = AI_TAG_NAME;
+  const aiKey = AI_TAG_KEY;
+  const items = Array.isArray(history) ? history : [];
+  const cutover = !(Number(settings.groups_flattened_at) > 0);
+  const oldShared = Array.isArray(settings.groups_shared_with_ai) ? settings.groups_shared_with_ai.map(String) : [];
+  const oldGroups = Array.isArray(settings.groups) ? settings.groups.map(String) : [];
+  const itemLists = itemTagLists(items);
+  let splits = normalizeGroupSplits(settings.group_splits);
+  const retired = [];
+  if (cutover) {
+    const known = new Set([...splits, ...normalizeGroupLiterals(settings.group_literals)].map(r => Tags.tagKey(r.name)));
+    for (const list of [oldGroups, ...itemLists, oldShared]) {
+      for (const raw of list) {
+        const name = String(raw == null ? '' : raw);
+        const key = Tags.tagKey(name);
+        if (!name.includes('/') || !key || known.has(key)) continue;
+        known.add(key);
+        retired.push({ name: Tags.cleanTagName(name), parts: Tags.nestedNameParts(name), at: now });
+      }
+    }
+    if (retired.length) splits = normalizeGroupSplits([...splits, ...retired]);
+  }
+  const ctx = tagContext({ ...settings, group_splits: splits }, [...itemLists, oldShared]);
+
+  const nextHistory = items.slice();
+  const undo = [];
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    const next = normalizeItemTags(item, ctx);
+    if (next === item) continue;
+    nextHistory[i] = next;
+    undo.push({ id: itemKey(item), groups: groupsOf(item).slice() });
+  }
+  const groups = normalizeTagList(oldGroups, ctx);
+
+  let shared;
+  const report = { cutover, retired: retired.map(r => r.name), clipsChanged: undo.length, unsharedToProtect: [] };
+  if (cutover) {
+    const oldSet = new Set(oldShared);
+    const sources = new Map();
+    for (const list of [oldGroups, ...itemLists, oldShared]) {
+      for (const raw of list) {
+        const name = String(raw == null ? '' : raw);
+        for (const part of Tags.expandTagNames(renameAiTwins([name]), ctx.splits, null)) {
+          const key = Tags.tagKey(part);
+          if (!key) continue;
+          if (!sources.has(key)) sources.set(key, new Set());
+          sources.get(key).add(name);
+        }
+      }
+    }
+    const unanimous = key => key === aiKey || [...(sources.get(key) || [])].every(name => oldSet.has(name));
+    shared = [];
+    const seen = new Set();
+    for (const raw of oldShared) {
+      for (const name of Tags.expandTagNames(renameAiTwins([raw]), ctx.splits, ctx.spellings)) {
+        const key = Tags.tagKey(name);
+        if (!key || seen.has(key)) continue;
+        seen.add(key);
+        if (unanimous(key)) shared.push(name);
+      }
+    }
+    // Nothing private may become visible: before = the old exact-name rule.
+    const wasVisible = item => groupsOf(item).some(g => g === aiName || oldSet.has(g));
+    let sharedKeys = new Set([aiKey, ...shared.map(Tags.tagKey)]);
+    const isVisible = item => groupsOf(item).some(g => sharedKeys.has(Tags.tagKey(g)));
+    for (let i = 0; i < nextHistory.length; i++) {
+      if (wasVisible(items[i]) || !isVisible(nextHistory[i])) continue;
+      for (const g of groupsOf(nextHistory[i])) {
+        const key = Tags.tagKey(g);
+        if (key !== aiKey && sharedKeys.has(key)) report.unsharedToProtect.push(g);
+      }
+      const drop = new Set(report.unsharedToProtect.map(Tags.tagKey));
+      shared = shared.filter(name => !drop.has(Tags.tagKey(name)));
+      sharedKeys = new Set([aiKey, ...shared.map(Tags.tagKey)]);
+    }
+    report.visibleBefore = items.filter(wasVisible).length;
+    report.visibleAfter = nextHistory.filter(isVisible).length;
+  } else {
+    // After the cutover a retired name has no meaning of its own: never share by it.
+    shared = Tags.expandTagNames(renameAiTwins(oldShared.filter(name => !ctx.splits.has(Tags.tagKey(name)))), null, ctx.spellings);
+  }
+
+  const patch = { groups, group_splits: splits, groups_shared_with_ai: shared };
+  if (cutover) {
+    patch.groups_flattened_at = now;
+    // Several tag chips now join with AND by default: forget a remembered group join once.
+    const joins = settings.facet_joins && typeof settings.facet_joins === 'object' ? settings.facet_joins : null;
+    if (joins && 'group' in joins) {
+      const next = { ...joins };
+      delete next.group;
+      patch.facet_joins = next;
+    }
+  }
+  report.groupsBefore = oldGroups.length;
+  report.groupsAfter = groups.length;
+  report.sharedBefore = oldShared.length;
+  report.sharedAfter = shared.length;
+  report.spellingsMerged = [...ctx.spellings.keys()].length;
+  const changed = cutover || undo.length > 0 || !sameNames(groups, oldGroups)
+    || !sameNames(shared, oldShared) || JSON.stringify(splits) !== JSON.stringify(settings.group_splits || []);
+  return { history: nextHistory, settings: patch, changed, report, undo };
+}
+
+// A device on its first flat start cannot tell a name made with a plain '/' on another
+// device ('AC/DC', recorded in group_literals) from an old nested one, so its cutover split
+// it, without moving a clock. So two copies of one clip with the SAME tags clock, one with
+// the name and the other with its parts instead, are one tag list seen two ways (a real
+// edit moves the clock): the parts go back into the name before the copies merge, on
+// whichever device meets them first. PURE: returns [a, b], each the same object when
+// unchanged, else a copy.
+function rejoinLiterals(a, b, literals) {
+  if (!a || !b || !a.pin || !b.pin || !literals || !literals.size) return [a, b];
+  if (groupState(a.pin).updatedAt !== groupState(b.pin).updatedAt) return [a, b];
+  const oa = groupsOf(a);
+  const ob = groupsOf(b);
+  let ga = oa;
+  let gb = ob;
+  const has = (list, name) => list.some(g => Tags.sameTag(g, name));
+  for (const { name, parts } of literals.values()) {
+    const inA = has(ga, name);
+    if (inA === has(gb, name)) continue;
+    const withName = inA ? ga : gb;
+    const withParts = inA ? gb : ga;
+    if (!parts.every(p => has(withParts, p))) continue;
+    const at = withParts.findIndex(g => parts.some(p => Tags.sameTag(g, p)));
+    const kept = withParts.filter(g => !parts.some(p => Tags.sameTag(g, p)) || has(withName, g));
+    const joined = [...kept.slice(0, at), name, ...kept.slice(at)];
+    if (inA) gb = joined; else ga = joined;
+  }
+  const withGroups = (item, groups) => ({ ...item, pin: { ...item.pin, groups } });
+  return [ga === oa ? a : withGroups(a, ga), gb === ob ? b : withGroups(b, gb)];
+}
+
+// The tag list after a late cutover split a plain '/' name: the parts it listed for it
+// ('AC', 'DC') leave the list once no clip holds them (the list is a union across devices,
+// so without this they would stay as empty tags everywhere). Only parts of a name some
+// device actually split (its split record exists). heldNames: every tag on the clips in
+// play. The same array when nothing goes.
+function pruneLiteralParts(groups, settings = {}, heldNames = []) {
+  const list = Array.isArray(groups) ? groups : [];
+  const literals = normalizeGroupLiterals(settings.group_literals);
+  if (!literals.length) return list;
+  const splitBy = new Map(normalizeGroupSplits(settings.group_splits).map(r => [Tags.tagKey(r.name), r.parts]));
+  const held = new Set((heldNames || []).map(Tags.tagKey));
+  const listed = new Set(list.map(Tags.tagKey));
+  const drop = new Set();
+  for (const { name } of literals) {
+    const parts = splitBy.get(Tags.tagKey(name));
+    if (!parts || !listed.has(Tags.tagKey(name))) continue;
+    for (const part of parts) if (!held.has(Tags.tagKey(part))) drop.add(Tags.tagKey(part));
+  }
+  if (!drop.size) return list;
+  const kept = list.filter(name => !drop.has(Tags.tagKey(name)));
+  return kept.length === list.length ? list : kept;
+}
+
+// The late device's own clips: once the record arrives, the name goes back on the clips its
+// cutover split, from that cutover's undo ledger ([{ id, groups }]: each changed clip's old
+// tags), only where a clip still holds exactly what the cutover gave it (rejoinLiterals
+// needs both copies to meet, and an unchanged copy is never sent again). PURE, never moves
+// a clock. Returns { history (the same array when nothing changes), ids }.
+function unsplitLiterals(history, ledger, settings = {}) {
+  const items = Array.isArray(history) ? history : [];
+  const literals = new Set(normalizeGroupLiterals(settings.group_literals).map(r => Tags.tagKey(r.name)));
+  const byId = new Map();
+  for (const entry of Array.isArray(ledger) ? ledger : []) {
+    if (!entry || !entry.id || !Array.isArray(entry.groups) || byId.has(String(entry.id))) continue;
+    if (entry.groups.some(g => literals.has(Tags.tagKey(g)))) byId.set(String(entry.id), entry.groups.map(String));
+  }
+  if (!byId.size) return { history: items, ids: [] };
+  const current = tagContext(settings, itemTagLists(items));
+  const atCutover = { ...current, splits: groupSplitMap(settings.group_splits) };
+  const flattenedAt = Number(settings.groups_flattened_at) || Infinity;
+  const keys = list => list.map(Tags.tagKey).sort().join('\n');
+  let next = null;
+  const ids = [];
+  items.forEach((item, i) => {
+    const old = item && item.pin ? byId.get(itemKey(item)) : null;
+    if (!old || groupState(item.pin).updatedAt > flattenedAt) return;
+    const held = keys(groupsOf(item));
+    if (held !== keys(normalizeTagList(old, atCutover))) return;
+    const groups = normalizeTagList(old, current);
+    if (keys(groups) === held) return;
+    const pin = { ...item.pin };
+    if (groups.length) pin.groups = groups;
+    else delete pin.groups;
+    if (!next) next = items.slice();
+    next[i] = { ...item, pin };
+    ids.push(itemKey(item));
+  });
+  return { history: next || items, ids };
+}
+
+// A split record that reaches a device after its own cutover (another device's late
+// cutover) turns a name held here as one tag into its parts. The cutover's share rule
+// covers it too: a part stays shared with AI only if the retired name was shared here.
+// Only unshares, never shares. Returns { shared (the same array when nothing changes),
+// unshared }.
+function shareListAfterNewSplits(shared, newSplits, heldNames) {
+  const list = Array.isArray(shared) ? shared : [];
+  const held = new Set((heldNames || []).map(Tags.tagKey));
+  const sharedKeys = new Set(list.map(Tags.tagKey));
+  const drop = new Set();
+  for (const record of newSplits || []) {
+    const key = Tags.tagKey(record && record.name);
+    if (!key || !held.has(key) || sharedKeys.has(key)) continue;
+    for (const part of record.parts || []) if (sharedKeys.has(Tags.tagKey(part))) drop.add(Tags.tagKey(part));
+  }
+  if (!drop.size) return { shared: list, unshared: [] };
+  return {
+    shared: list.filter(name => !drop.has(Tags.tagKey(name))),
+    unshared: list.filter(name => drop.has(Tags.tagKey(name))),
+  };
+}
+
+// AI share switches, synced per tag: { [tagKey]: { name, shared, at } }. The newest flip
+// wins; at the same instant unshared wins (never share by accident).
+function normalizeShareStamps(value) {
+  const out = {};
+  if (!value || typeof value !== 'object') return out;
+  for (const [rawKey, stamp] of Object.entries(value)) {
+    if (!stamp || typeof stamp !== 'object') continue;
+    const name = Tags.cleanTagName(stamp.name || rawKey);
+    const key = Tags.tagKey(name);
+    const at = Number(stamp.at) || 0;
+    if (!key || !at) continue;
+    const next = { name, shared: !!stamp.shared, at };
+    const existing = out[key];
+    if (!existing || at > existing.at || (at === existing.at && existing.shared && !next.shared)) out[key] = next;
+  }
+  return out;
+}
+
+function mergeShareStamps(local, remote) {
+  const a = normalizeShareStamps(local);
+  const b = normalizeShareStamps(remote);
+  const out = { ...a };
+  for (const [key, stamp] of Object.entries(b)) {
+    const existing = out[key];
+    if (!existing || stamp.at > existing.at || (stamp.at === existing.at && existing.shared && !stamp.shared)) out[key] = stamp;
+  }
+  return out;
+}
+
+// A share list with every stamped flip applied (spellings: tagKey -> stored name).
+function applyShareStamps(list, stamps, spellings = null) {
+  const current = Array.isArray(list) ? list : [];
+  const normalized = normalizeShareStamps(stamps);
+  const keys = Object.keys(normalized);
+  if (!keys.length) return current;
+  let next = current.filter(name => {
+    const stamp = normalized[Tags.tagKey(name)];
+    return !stamp || stamp.shared;
+  });
+  const present = new Set(next.map(Tags.tagKey));
+  for (const key of keys) {
+    const stamp = normalized[key];
+    if (stamp.shared && !present.has(key)) {
+      next.push((spellings && spellings.get(key)) || stamp.name);
+      present.add(key);
+    }
+  }
+  return sameNames(next, current) ? current : next;
+}
+
 function planHistoryPrune(history, settings = {}, options = {}) {
   const now = options.now != null ? Number(options.now) : Date.now() / 1000;
   const maxAgeDays = Number(settings.max_age_days);
@@ -1196,9 +1739,11 @@ function isDestructivePrune(history, plan, options = {}) {
   return count >= minItems && count / total >= fraction;
 }
 
-function mergeGroups(local, remote, groupTombstones = []) {
-  const deleted = groupTombstoneNames(groupTombstones);
-  return [...new Set([...(local || []), ...(remote || [])])].filter(g => !deleted.has(g));
+// settings.groups across a merge: one entry per tag in stored form (ctx: tagContext of
+// the merged settings), local order first. Without ctx: deleted tags dropped, one per tag.
+function mergeGroups(local, remote, groupTombstones = [], ctx = null) {
+  const all = [...(local || []), ...(remote || [])];
+  return normalizeTagList(all, ctx || tagContext({ group_tombstones: groupTombstones }, [all]));
 }
 
 module.exports = {
@@ -1235,7 +1780,6 @@ module.exports = {
   supersedeMap,
   tombstoneIds,
   tombstoneMap,
-  groupTombstoneNames,
   planHistoryPrune,
   isDestructivePrune,
   mergePins,
@@ -1244,6 +1788,27 @@ module.exports = {
   itemMutationClock,
   mergeHistories,
   mergeGroups,
+  uniqueTags,
+  groupTombstoneIndex,
+  deleteStrips,
+  normalizeGroupSplits,
+  normalizeGroupLiterals,
+  splitMapOf,
+  rejoinLiterals,
+  unsplitLiterals,
+  pruneLiteralParts,
+  shareListAfterNewSplits,
+  AI_TAG_NAME,
+  groupSplitMap,
+  tagContext,
+  itemTagLists,
+  normalizeTagList,
+  normalizeItemTags,
+  tagInputNames,
+  planTagState,
+  normalizeShareStamps,
+  mergeShareStamps,
+  applyShareStamps,
   dedupeNumpadSlots,
   migrateLegacyNumpadSlots,
   applyTextEdit,