@1agh/maude 1.0.11 → 1.3.0

package/apps/studio/sync/codec.ts

@@ -1,3 +1,4 @@
+import { ANNOTATION_WRITE_ID } from '../annotations-sync.ts';
 // Y.Doc ↔ disk codecs for the bidirectional file sync agent (Phase 9 Task 4).
 //
 // The agent shuttles three classes of files between disk and the Y.Doc the
@@ -22,10 +23,11 @@
 // in the unchanged regions.
 
 import { hostname } from 'node:os';
-
+import { diffChars } from 'diff';
 import type * as Y from 'yjs';
 
 import { Y_TYPES } from '../collab/persistence.ts';
+import { commentKey, dedupeCommentsById } from './comment-identity.ts';
 import {
   MAX_ANNOTATIONS_BYTES,
   MAX_COMMENTS_BYTES,
@@ -96,20 +98,27 @@ export function htmlFromDoc(doc: Y.Doc): string {
 }
 
 /**
- * Apply `next` to the Y.Text inside `doc`. Uses a minimal common-prefix /
- * common-suffix replace so peers see a small op rather than a full replace.
+ * Apply `next` as bounded text hunks, preserving unchanged interior CRDT
+ * anchors as well as the common prefix/suffix (#121).
+ *
+ * THIS SHAPE IS A CONVERGENCE PROPERTY, NOT AN OPTIMIZATION (issue #114).
+ * Collapsing a concurrency-duplicated lane — `X + X` back to `X` — comes out of
+ * this diff as a PURE DELETE of the trailing run: no insert at all. Two peers
+ * that independently decide to collapse therefore delete the SAME CRDT items,
+ * and deletes are idempotent, so they converge.
+ *
+ * A wholesale `delete(0, len)` + `insert(0, next)` does not have that property.
+ * Both peers' inserts are new items at the same position, and Yjs keeps both —
+ * so the "repair" re-creates exactly the duplication it was meant to undo. The
+ * css lane was written that way, which is why it was the lane that never came
+ * out of a multi-peer cold start clean (measured: 0 of 43 lanes). Any lane whose
+ * duplication is repairable MUST go through here.
  *
  * Pass `origin` as the transaction origin so a downstream observer can
  * distinguish self-originated updates from peer/remote ones.
  */
-export function applyHtmlToDoc(doc: Y.Doc, next: string, origin?: unknown): boolean {
-  if (byteLengthUtf8(next) > MAX_HTML_BYTES) {
-    console.warn(
-      `[sync/codec] refusing HTML apply > ${MAX_HTML_BYTES} bytes (got ${byteLengthUtf8(next)}). DDR-054 §2d.`
-    );
-    return false;
-  }
-  const yText = doc.getText(Y_SYNC_TYPES.html);
+function applyTextLane(doc: Y.Doc, lane: string, next: string, origin?: unknown): boolean {
+  const yText = doc.getText(lane);
   const current = yText.toString();
   if (current === next) return false;
 
@@ -129,17 +138,55 @@ export function applyHtmlToDoc(doc: Y.Doc, next: string, origin?: unknown): bool
     suffix++;
   }
 
+  // Y.Text offsets are UTF-16; never leave half a surrogate outside a hunk.
+  if (prefix > 0 && /[\uD800-\uDBFF]/.test(current[prefix - 1] ?? '')) prefix--;
+  if (suffix > 0 && /[\uDC00-\uDFFF]/.test(current[current.length - suffix] ?? '')) suffix--;
   const deleteLen = current.length - prefix - suffix;
   const insertStr = next.slice(prefix, next.length - suffix);
 
+  // Keep pure inserts/deletes (especially repeat collapse) as one operation.
+  // For replacements preserve interior anchors: one prefix/suffix splice can
+  // move a concurrent insertion inside an unrelated JSX attribute (#121).
+  const changes =
+    deleteLen > 0 && insertStr.length > 0
+      ? diffChars(current.slice(prefix, current.length - suffix), insertStr, {
+          maxEditLength: 4096,
+          timeout: 50,
+        })
+      : null;
+  if (changes === undefined) throw new Error('Source diff exceeds the safe merge budget');
   doc.transact(() => {
-    if (deleteLen > 0) yText.delete(prefix, deleteLen);
-    if (insertStr.length > 0) yText.insert(prefix, insertStr);
+    if (changes) {
+      let offset = prefix;
+      for (const change of changes) {
+        if (change.removed) yText.delete(offset, change.value.length);
+        else {
+          if (change.added) yText.insert(offset, change.value);
+          offset += change.value.length;
+        }
+      }
+    } else {
+      if (deleteLen > 0) yText.delete(prefix, deleteLen);
+      if (insertStr.length > 0) yText.insert(prefix, insertStr);
+    }
   }, origin);
 
   return true;
 }
 
+/**
+ * Apply `next` to the canvas body Y.Text inside `doc`. See `applyTextLane`.
+ */
+export function applyHtmlToDoc(doc: Y.Doc, next: string, origin?: unknown): boolean {
+  if (byteLengthUtf8(next) > MAX_HTML_BYTES) {
+    console.warn(
+      `[sync/codec] refusing HTML apply > ${MAX_HTML_BYTES} bytes (got ${byteLengthUtf8(next)}). DDR-054 §2d.`
+    );
+    return false;
+  }
+  return applyTextLane(doc, Y_SYNC_TYPES.html, next, origin);
+}
+
 /* ---------------------------------------------------------------- comments */
 
 /**
@@ -153,14 +200,41 @@ export function commentsFromDoc(doc: Y.Doc): CommentsSnapshot {
   return arr.toArray();
 }
 
+/**
+ * Apply `next` to the comments Y.Array as a MINIMAL, IDENTITY-KEYED DIFF.
+ *
+ * THIS SHAPE IS A CONVERGENCE PROPERTY, NOT AN OPTIMIZATION (issue #112) —
+ * the same law `applyTextLane` states for the text lanes, which this lane was
+ * missing. It used to be `delete(0, len)` + `push(next)`, and under concurrency
+ * that is not a replace at all: two peers delete the SAME items (idempotent)
+ * but insert two runs at the same position, and Yjs keeps both. The array
+ * becomes `list + list`, `persistJson` writes that to `_comments/<slug>.json`,
+ * the file re-imports clean, and the duplication IS the new truth. Every
+ * reconciliation round doubled it — 1 → 2 → 4 → 8, the count the #112 reporter
+ * saw — and the cold-start union repair, published through the same wholesale
+ * write, re-created the duplication it had just undone. Verbatim the css lesson
+ * from issue #114, one lane later.
+ *
+ * The diff gives the lane the property the text lanes got:
+ *
+ *   - Collapsing a duplicated array is a PURE DELETE of items every peer holds,
+ *     and concurrent deletes of the same items are idempotent — so two peers
+ *     repairing at once converge instead of re-doubling.
+ *   - Dedupe happens on EVERY apply, not only at cold start, so an array that
+ *     doubled anyway (an older peer still on the wholesale write, a genuine
+ *     concurrent edit of one entry) collapses at the next apply rather than
+ *     compounding. Duplication became self-healing instead of exponential.
+ *   - Untouched comments keep their CRDT items, so a peer replacing one entry
+ *     no longer rewrites the whole list under everyone else's feet.
+ *
+ * Ordering follows the doc for surviving entries, with genuinely new ones
+ * appended. Reordering is deliberately NOT synced: it would be a delete+insert
+ * per moved entry — churn with the one shape this fix exists to avoid — and
+ * comment order carries no meaning (pins are placed by selector, the sidebar
+ * sorts by `created`).
+ */
 export function applyCommentsToDoc(doc: Y.Doc, next: CommentsSnapshot, origin?: unknown): boolean {
-  const arr = doc.getArray(Y_TYPES.comments);
-  // Comments are LWW on the JSON file (the snapshot is the source of truth);
-  // collapse Y.Array to the new state. For v1.1 we just replace wholesale —
-  // structural comment-level merge is deferred along with structured HTML.
-  // Check whether anything actually changed to avoid no-op transactions
-  // (transactions still fire `update` events, which would re-enter the loop).
-  const before = JSON.stringify(arr.toArray());
+  const arr = doc.getArray<unknown>(Y_TYPES.comments);
   const after = JSON.stringify(next);
   if (byteLengthUtf8(after) > MAX_COMMENTS_BYTES) {
     console.warn(
@@ -168,11 +242,51 @@ export function applyCommentsToDoc(doc: Y.Doc, next: CommentsSnapshot, origin?:
     );
     return false;
   }
-  if (before === after) return false;
+
+  // Desired state, keyed by comment identity. `next` can itself arrive
+  // duplicated (a file written before this fix, a list pushed by an older
+  // peer), so it is deduped on the way in — first occurrence wins, matching
+  // `unionCommentsById` and `dedupeCommentsById`.
+  const desired = new Map<string, unknown>();
+  for (const c of next) {
+    const k = commentKey(c);
+    if (!desired.has(k)) desired.set(k, c);
+  }
+
+  // Classify every item currently in the array: keep it, replace it in place,
+  // or delete it. Duplicates of an identity we already kept are deletes — that
+  // is what makes EVERY apply a repair, not just the cold-start union.
+  const current = arr.toArray();
+  const deletes: number[] = [];
+  const replaces: { index: number; value: unknown }[] = [];
+  const kept = new Set<string>();
+  for (let i = 0; i < current.length; i++) {
+    const k = commentKey(current[i]);
+    if (!desired.has(k) || kept.has(k)) {
+      deletes.push(i);
+      continue;
+    }
+    kept.add(k);
+    const want = desired.get(k);
+    if (JSON.stringify(current[i]) !== JSON.stringify(want))
+      replaces.push({ index: i, value: want });
+  }
+  const appends: unknown[] = [];
+  for (const [k, v] of desired) if (!kept.has(k)) appends.push(v);
+
+  // No-op guard. Transactions fire `update` events even when they change
+  // nothing, and an update re-enters the file→doc→file loop.
+  if (deletes.length === 0 && replaces.length === 0 && appends.length === 0) return false;
 
   doc.transact(() => {
-    if (arr.length > 0) arr.delete(0, arr.length);
-    if (next.length > 0) arr.push(next);
+    // Replaces first, while the indices computed above are still valid.
+    for (const r of replaces) {
+      arr.delete(r.index, 1);
+      arr.insert(r.index, [r.value]);
+    }
+    // Then deletes, descending, so each index stays valid as we go.
+    for (let i = deletes.length - 1; i >= 0; i--) arr.delete(deletes[i]!, 1);
+    if (appends.length > 0) arr.push(appends);
   }, origin);
   return true;
 }
@@ -218,6 +332,8 @@ export function applyAnnotationsToDoc(doc: Y.Doc, next: string | null, origin?:
   if (currentStr === next) return false;
 
   doc.transact(() => {
+    // A filesystem import is a new operation, never the previous UI author's echo.
+    map.delete(ANNOTATION_WRITE_ID);
     if (next === null || next === '') {
       map.delete('svg');
     } else {
@@ -301,6 +417,45 @@ function parsesAsObject(s: string): boolean {
 }
 
 /** The synced shared-meta JSON string held in the doc, or null when unset. */
+/**
+ * The canonical LANE value for a file's text — what the accepted-revisions
+ * kernel stores and what `readLaneFromDoc` returns once it is accepted
+ * (DDR-241). `null` when the file text cannot be a value of that lane.
+ */
+export function laneValueFromFile(
+  lane: 'html' | 'css' | 'meta' | 'annotations' | 'comments',
+  text: string
+): string | null {
+  if (lane === 'html' || lane === 'css' || lane === 'annotations') return text;
+  let parsed: unknown;
+  try {
+    parsed = parseJsonSafe(text);
+  } catch {
+    return null;
+  }
+  if (lane === 'meta') {
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    return sharedMetaCanonical(parsed as Record<string, unknown>);
+  }
+  if (!Array.isArray(parsed)) return null;
+  const list = dedupeCommentsById(parsed);
+  return list.length ? JSON.stringify(list) : '';
+}
+
+/** A lane's value as the accepted replica holds it (same canonical form). */
+export function readLaneFromDoc(
+  doc: Y.Doc,
+  lane: 'html' | 'css' | 'meta' | 'annotations' | 'comments'
+): string {
+  if (lane === 'html' || lane === 'css' || lane === 'meta') return doc.getText(lane).toString();
+  if (lane === 'annotations') {
+    const svg = doc.getMap<unknown>(Y_TYPES.annotations).get('svg');
+    return typeof svg === 'string' ? svg : '';
+  }
+  const list = doc.getArray<unknown>(Y_TYPES.comments).toArray();
+  return list.length ? JSON.stringify(list) : '';
+}
+
 export function metaFromDoc(doc: Y.Doc): string | null {
   return normalizeSharedMeta(doc.getText(Y_SYNC_TYPES.meta).toString());
 }
@@ -618,10 +773,19 @@ export function cssFromDoc(doc: Y.Doc): string | null {
 }
 
 /**
- * Apply the canvas's `.css` to the doc as opaque Y.Text (wholesale replace).
- * CSS round-trips byte-identically (we write exactly the doc string back), so a
- * wholesale delete+insert can't churn; the equality short-circuit keeps it quiet
- * when unchanged. Returns false on over-cap / no change.
+ * Apply the canvas's `.css` to the doc as opaque Y.Text.
+ *
+ * Goes through `applyTextLane` — the same prefix/suffix diff the body uses —
+ * and that is load-bearing, not tidiness (issue #114). This was a wholesale
+ * `delete(0, len)` + `insert(0, next)`, whose comment argued it "can't churn"
+ * because css round-trips byte-identically. True for a SINGLE writer, and the
+ * reason the lane looked fine in every single-peer test. Under concurrency it
+ * is the bug: two peers each replacing the lane keep both inserts, so the css
+ * doubled on a concurrent cold seed AND doubled again every time a peer tried
+ * to repair it. Measured in the field at 3×, 4× and 5×, while the body lane —
+ * same collision, diffing codec — never exceeded 3× and mostly self-healed.
+ *
+ * Returns false on over-cap / no change.
  */
 export function applyCssToDoc(doc: Y.Doc, next: string, origin?: unknown): boolean {
   if (byteLengthUtf8(next) > MAX_CSS_BYTES) {
@@ -630,11 +794,5 @@ export function applyCssToDoc(doc: Y.Doc, next: string, origin?: unknown): boole
     );
     return false;
   }
-  const t = doc.getText(Y_SYNC_TYPES.css);
-  if (t.toString() === next) return false;
-  doc.transact(() => {
-    if (t.length > 0) t.delete(0, t.length);
-    t.insert(0, next);
-  }, origin);
-  return true;
+  return applyTextLane(doc, Y_SYNC_TYPES.css, next, origin);
 }

package/apps/studio/sync/cold-start-apply.ts

@@ -39,6 +39,13 @@
 
 import type { ColdStartAction, ColdStartDecision } from './cold-start.ts';
 
+/** Why a cold-start snapshot was taken.
+ *
+ *  Deliberately NOT extended for the duplication collapse (issue #114). A
+ *  collapse only ever fires on an exact integer repeat, so the discarded copies
+ *  hold nothing the retained one doesn't — and `pruneSnapshots` evicts
+ *  oldest-first per slug, so a valueless snapshot on a hub-triggerable path is
+ *  an eviction lever against the copies that carry real bytes. */
 export type ColdStartSnapshotReason = 'pre-sync-local' | 'pre-sync-hub';
 
 export interface ColdStartConflictInfo {

package/apps/studio/sync/cold-start.ts

@@ -19,6 +19,7 @@
 // unavailable) or equal → hub wins, exactly the v1.1 default — but now both
 // sides are snapshotted first, so even a wrong pick costs one /design:rollback.
 
+import { commentKey } from './comment-identity.ts';
 import { hashBytes } from './echo-guard.ts';
 
 export type ColdStartAction =
@@ -75,13 +76,6 @@ export function isExactRepeat(docBody: string, localBody: string): boolean {
   return docBody === localBody.repeat(n);
 }
 
-function commentId(c: unknown): string | null {
-  if (c && typeof c === 'object' && typeof (c as { id?: unknown }).id === 'string') {
-    return (c as { id: string }).id;
-  }
-  return null;
-}
-
 /**
  * Union-merge two comment snapshots by stable `id` (DDR-102): doc order first,
  * local-only entries appended. Comments carry stable ids, so union loses
@@ -90,22 +84,30 @@ function commentId(c: unknown): string | null {
  * cold-start paths (agent reconcile + migrate-seed).
  */
 export function unionCommentsById(docList: unknown[], localList: unknown[]): unknown[] {
-  const out = [...docList];
-  const seenIds = new Set<string>();
-  const seenJson = new Set<string>();
-  for (const c of docList) {
-    const id = commentId(c);
-    if (id !== null) seenIds.add(id);
-    else seenJson.add(JSON.stringify(c));
-  }
-  for (const c of localList) {
-    const id = commentId(c);
-    const dup = id !== null ? seenIds.has(id) : seenJson.has(JSON.stringify(c));
-    if (dup) continue;
+  const out: unknown[] = [];
+  const seen = new Set<string>();
+  // THE DOC IS DEDUPED AGAINST ITSELF, not just against local (issue #114/#112).
+  // `out` used to be seeded as `[...docList]`, which made this union a filter on
+  // the LOCAL side only — so a doc whose comments array had already been
+  // concurrency-doubled (`applyCommentsToDoc` is delete-all + push: two peers
+  // replacing at once keep both pushes) carried every copy forward, and the
+  // merged result was re-published as the new truth. That is the amplifier
+  // behind "the comment self duplicated like 8 times": 2 → 4 → 8, one doubling
+  // per concurrent round, with nothing in the loop able to shrink it again.
+  // Deduping the doc half turns the same pass into the repair.
+  // `commentKey` is the SHARED identity rule (comment-identity.ts) — the same
+  // one `applyCommentsToDoc`'s diff and the room seed use. It has to be shared:
+  // if the union's notion of "same comment" ever drifted from the codec's, one
+  // layer's repair would be the other's duplicate.
+  const admit = (c: unknown): void => {
+    const k = commentKey(c);
+    if (seen.has(k)) return;
+    seen.add(k);
     out.push(c);
-    if (id !== null) seenIds.add(id);
-    else seenJson.add(JSON.stringify(c));
-  }
+  };
+  // Doc order first (same-id entries keep the doc's version), local-only appended.
+  for (const c of docList) admit(c);
+  for (const c of localList) admit(c);
   return out;
 }
 
@@ -292,3 +294,97 @@ export function decideAnnotationsColdStart(
     reason: `diverged — no per-lane stamp on one side, following the body winner (${bodyWinner})`,
   };
 }
+
+/* ------------------------------------------------------- css (per-lane) */
+
+export interface CssColdStartInput {
+  /** Local sibling `.css` content, or null when the file doesn't exist. */
+  local: string | null;
+  /** The css currently held by the doc (`null` when the lane is unset/empty). */
+  doc: string | null;
+  /** Journal entry's `cssHash` for this slug, or null when never checkpointed. */
+  journalHash: string | null;
+  /** Hash fn — passed in so this table stays as dependency-free as the rest. */
+  hash: (s: string) => string;
+  /** How the body lane resolved; the tie-break for a genuine divergence. */
+  bodyWinner: 'local' | 'hub';
+}
+
+export interface CssColdStartDecision {
+  winner: 'local' | 'hub' | 'none';
+  /** True when local won because the doc held local repeated N≥2 times. */
+  recoveredDuplication?: boolean;
+  reason: string;
+}
+
+/**
+ * Per-lane cold-start resolution for the canvas's sibling `.css` (issue #114).
+ *
+ * WHY THIS TABLE EXISTS. Every other Plane-A lane had one — `decideColdStart`
+ * for the body, `decideAnnotationsColdStart` for annotations, `repairSharedMeta`
+ * for meta — and css had none: it simply followed the body winner and re-applied
+ * the whole file whenever the two sides disagreed. That left it the only lane
+ * with no duplication guard at all, and `applyCssToDoc` is a delete-all+insert,
+ * so two peers seeding one empty document concurrently kept BOTH inserts and the
+ * lane became `CSS × N` (Yjs merges concurrent inserts at the same position by
+ * keeping both — not a corruption, the CRDT doing its job). Worse, the "repair"
+ * was itself another full insert, so every subsequent disagreement could double
+ * it again. Measured on the reporting machine's 84 persisted docs: the body lane
+ * was clean 21 times out of 84, the css lane ZERO times out of 43, and css
+ * carried strictly more copies than its own document's body in 43 of 43.
+ * Per-lane vigilance is what failed; a table per lane is the shape that holds.
+ *
+ * The rows mirror `decideColdStart`'s, in the same order and for the same
+ * reasons — crucially the `recover-seed-dup` row, checked BEFORE the journal
+ * fast-forward so a doubled lane is collapsed rather than read as "the hub moved
+ * ahead". Like the body's, it repairs only what it can PROVE: an exact integer
+ * repeat of the bytes on disk. A doc carrying genuinely new css is never an
+ * exact repeat, so this cannot clobber an edit.
+ */
+export function decideCssColdStart(input: CssColdStartInput): CssColdStartDecision {
+  const { local, doc, journalHash, hash, bodyWinner } = input;
+  const localEmpty = local === null || local === '';
+  const docEmpty = doc === null || doc === '';
+
+  if (localEmpty && docEmpty) return { winner: 'none', reason: 'both sides empty' };
+  if (localEmpty) return { winner: 'hub', reason: 'no local css — materializing the hub lane' };
+  if (docEmpty) {
+    // The body lane's DDR-064 guard, applied here: an empty css lane means the
+    // hub holds no css for this canvas YET, never "this canvas has no css".
+    // Without this row a local `.css` next to a hub-winning body never travelled
+    // at all — it sat on one disk and no peer ever saw it.
+    return { winner: 'local', reason: 'hub css lane empty — seeding local css up (DDR-064 guard)' };
+  }
+  if (doc === local) return { winner: 'none', reason: 'local and hub css identical' };
+
+  // Concurrent cold-seed collision, css edition — see the header. Collapsing is
+  // re-applying local: `applyCssToDoc` replaces the lane wholesale, so the
+  // repeated copies go and one stays.
+  if (isExactRepeat(doc, local)) {
+    return {
+      winner: 'local',
+      recoveredDuplication: true,
+      reason:
+        'hub css is local repeated — concurrent cold-seed duplication; collapsing to one copy',
+    };
+  }
+
+  // The journal checkpoint the css lane has been WRITING since DDR-102 and never
+  // reading. Same meaning as the body's: every local byte was already reconciled
+  // through this machine, so the hub is simply ahead.
+  if (journalHash !== null && journalHash === hash(local)) {
+    return {
+      winner: 'hub',
+      reason: 'local css matches the last-synced journal hash — hub is ahead, fast-forwarding',
+    };
+  }
+
+  // Genuine divergence. The css is visually coupled to the body, so it follows
+  // the body's resolution rather than inventing a second, possibly disagreeing
+  // winner for the same canvas — the pre-existing behaviour, now reached only
+  // when the rows above have ruled out the cases they can decide on their own.
+  return {
+    winner: bodyWinner,
+    reason: `css diverged — following the body winner (${bodyWinner})`,
+  };
+}

package/apps/studio/sync/comment-identity.ts

@@ -0,0 +1,68 @@
+// Comment identity — the one definition of "these two entries are the same
+// comment", shared by every layer that touches the comments lane (issue #112).
+//
+// A LEAF module, exactly like `limits.ts`: it imports NOTHING. That is
+// load-bearing, not tidiness. `collab/persistence.ts` owns `Y_TYPES` and
+// `sync/codec.ts` imports it from there, so persistence can never import the
+// codec back (its own comment says so) — yet the room seed needs the same
+// identity rule the codec's diff uses. A dependency-free leaf is the only
+// place both sides can reach.
+//
+// WHY IDENTITY IS A SHARED CONCERN. Comments travel over the hub as a Y.Array,
+// and the lane's whole failure mode is the same logical comment appearing as
+// several distinct CRDT items (issue #112: 1 → 2 → 4 → 8). Every layer that
+// writes the lane has to agree on which entries are "the same one", or one
+// layer's repair is another layer's duplicate.
+
+/**
+ * Stable identity for one comment entry.
+ *
+ * `id` is the real key — it is minted once by `commentsAdd` and survives every
+ * round-trip through disk, the Y.Array and the hub. Entries WITHOUT a string
+ * `id` (hand-edited files, pre-Phase-6 rows, junk pushed by an untrusted peer)
+ * fall back to JSON identity, which is deliberately conservative: it dedupes
+ * only byte-identical entries and never merges two rows that might differ.
+ *
+ * The `id:` / `json:` prefixes keep the two spaces from colliding — a comment
+ * whose id is literally the JSON of another entry can't shadow it.
+ */
+export function commentKey(c: unknown): string {
+  if (c && typeof c === 'object' && typeof (c as { id?: unknown }).id === 'string') {
+    return `id:${(c as { id: string }).id}`;
+  }
+  return `json:${JSON.stringify(c)}`;
+}
+
+/**
+ * Collapse a comment list to one entry per identity, keeping the FIRST
+ * occurrence.
+ *
+ * First-wins is the same rule `unionCommentsById` uses ("doc order first"), and
+ * the two must agree: `commentsAddReply` mutates the first match, so the copy
+ * the dedupe keeps has to be the copy the mutations edit.
+ *
+ * Returns the input array itself when there is nothing to drop, so callers can
+ * cheaply test `deduped !== list` to know whether a write is worth making.
+ */
+export function dedupeCommentsById<T>(list: readonly T[]): T[] {
+  const seen = new Set<string>();
+  const out: T[] = [];
+  for (const c of list) {
+    const k = commentKey(c);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(c);
+  }
+  return out;
+}
+
+/** True when `list` carries the same comment identity more than once. */
+export function hasDuplicateComments(list: readonly unknown[]): boolean {
+  const seen = new Set<string>();
+  for (const c of list) {
+    const k = commentKey(c);
+    if (seen.has(k)) return true;
+    seen.add(k);
+  }
+  return false;
+}

package/apps/studio/sync/connection-state.ts

@@ -310,7 +310,21 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
     const wasOffline = state === 'offline' || state === 'offline-long';
     clearAllTimers();
     state = 'online';
-    lastSyncAt = now();
+    // NOT `lastSyncAt = now()`.
+    //
+    // A SOCKET TRANSITION IS NOT A SYNC. This line used to stamp the
+    // last-synced clock from the WS coming back — an event that, by itself,
+    // has moved no document and settled no handshake. The field's own contract
+    // one screen up already says otherwise ("updated on REAL sync activity
+    // (noteSyncActivity), not just on offline→online transitions"); the code
+    // simply did not honour it.
+    //
+    // It was not a cosmetic drift. Live on the reported project (issue #118):
+    // `state:"online", docs:{synced:0,pending:85}` with `lastSyncAt` refreshed
+    // to the exact millisecond of that transition — so the one number a reader
+    // could have used to notice that nothing had synced in 15 minutes was
+    // being refreshed BY the failure. `noteSyncActivity` is the only honest
+    // source, and it is now the only one.
     offlineSince = null;
     queuedOps = 0;
     if (wasOffline) {

package/apps/studio/sync/ctl-provider.ts

@@ -95,6 +95,8 @@ export interface CtlProviderOptions {
   token: string;
   /** Fired with the hub's head on every well-formed poke. */
   onPoke: (head: number) => void;
+  /** Optional fast document-list invalidation; older consumers use onPoke. */
+  onDocuments?: () => void;
   documentName?: string;
   log?: Pick<Console, 'log' | 'warn' | 'error'>;
   /** Injected in tests; production builds one from `@hocuspocus/provider`. */
@@ -155,9 +157,19 @@ export function createCtlProvider(opts: CtlProviderOptions): CtlProvider {
 
   const wire = (p: CtlProviderLike): void => {
     p.on('status', (data: { status?: string }) => {
-      if (typeof data?.status === 'string') status = data.status;
+      if (typeof data?.status !== 'string') return;
+      const reconnect = data.status === 'connected' && status !== 'connected';
+      status = data.status;
+      if (reconnect && !stopped) {
+        try {
+          opts.onDocuments?.();
+        } catch (error) {
+          log.error?.(`[sync/ctl] discovery handler threw: ${(error as Error).message}`);
+        }
+      }
     });
     p.on('stateless', (data: { payload: string }) => {
+      if (stopped) return;
       const poke = parsePoke(data?.payload);
       if (poke === null) {
         malformed += 1;
@@ -172,7 +184,8 @@ export function createCtlProvider(opts: CtlProviderOptions): CtlProvider {
       }
       received += 1;
       try {
-        opts.onPoke(poke.head);
+        if (poke.documents && opts.onDocuments) opts.onDocuments();
+        else opts.onPoke(poke.head);
       } catch (err) {
         log.error?.(`[sync/ctl] poke handler threw: ${(err as Error).message}`);
       }