@1agh/maude 1.0.9 → 1.2.0

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/file-ledger.ts

@@ -45,6 +45,28 @@ import { atomicWrite } from './atomic-write.ts';
 /** Debounce for persisting the ledger. Same figure as the doc journal. */
 export const LEDGER_FLUSH_MS = 1_000;
 
+/**
+ * Per-path failure backoff: base delay, ceiling, and the jitter that keeps a
+ * few hundred failing paths from re-arriving in lockstep.
+ *
+ * The ceiling is ten minutes rather than something larger because a path that
+ * is waiting is a path a person is waiting for. Ten minutes is long enough to
+ * stop being the hub's problem and short enough that a recovered hub converges
+ * without anyone restarting anything.
+ */
+export const BACKOFF_BASE_MS = 5_000;
+export const MAX_BACKOFF_MS = 10 * 60_000;
+
+/** Exponential with full jitter, clamped. Exported for the tests to reason
+ *  about the bounds rather than the draw. */
+export function backoffDelayMs(attempts: number, random: () => number = Math.random): number {
+  const n = Math.max(1, Math.min(32, Math.trunc(attempts)));
+  const ceiling = Math.min(MAX_BACKOFF_MS, BACKOFF_BASE_MS * 2 ** (n - 1));
+  // Full jitter: a uniform draw over the whole window, not a band around it.
+  // The band shape still lets a synchronised cohort stay synchronised.
+  return Math.max(BACKOFF_BASE_MS, Math.round(ceiling * (0.5 + 0.5 * random())));
+}
+
 /**
  * How recently a file must have been written for its stat cache to be
  * distrusted. Comfortably above any filesystem's timestamp granularity, and
@@ -65,6 +87,15 @@ export type DeliveryState =
   | 'conflict'
   /** We tried and could not — the reason says what to fix. */
   | 'stuck'
+  /**
+   * The workspace will NOT take this file, and no amount of waiting changes
+   * that — it is over the door's size ceiling, or the hourly allowance is
+   * spent. Distinct from `stuck` because the answer is different: `stuck` is
+   * retried, this is not, and a path that cannot succeed must stop costing a
+   * request slot on every pass (2026-09-03: a 465.8 MB video did exactly that,
+   * on every boot, forever).
+   */
+  | 'refused'
   /** Something references this asset and NO peer has ever offered it. */
   | 'referenced-but-unoffered'
   /** On this disk, and the hub has not acknowledged it. */
@@ -122,6 +153,33 @@ export interface LedgerRow {
   reason?: string;
   /** Where the conflict copy was parked, so the panel can point at it. */
   conflictCopy?: string;
+  /**
+   * WHY this row is blocked, as a value WE chose — never re-derived from the
+   * reason string.
+   *
+   * `reason` can embed a bounded snippet of a hub-supplied error body
+   * (`failureReason()`), so matching on its text means a hostile hub can steer
+   * how its own refusals are classified. The writer knows the class at the
+   * moment it refuses; recording it removes the guess.
+   */
+  blockedClass?: 'too-large' | 'quota' | 'unreachable' | 'refused';
+  /**
+   * PER-PATH FAILURE BACKOFF — consecutive failed attempts for this path.
+   *
+   * The plane had none, so every pass re-attempted the identical failing set at
+   * full rate: on 2026-09-03 a single sponsor logo went up 24 times in 10
+   * seconds, and 314 PUTs covered only 44 distinct paths. That is not a retry
+   * policy, it is the client helping a struggling hub struggle.
+   */
+  attempts?: number;
+  /**
+   * Earliest wall-clock this path may be attempted again.
+   *
+   * ON THE LEDGER, not in memory, for the same reason the deletion budget is:
+   * otherwise "restart the app" is the bypass, and a restart is the ordinary
+   * response to "sync seems stuck".
+   */
+  nextAttemptAt?: number;
   /**
    * The remote hash whose bytes we have ALREADY parked aside.
    *
@@ -227,6 +285,20 @@ export interface FileLedger {
   setState(rel: string, state: DeliveryState, extra?: Partial<LedgerRow>): void;
   forget(rel: string): void;
 
+  /**
+   * Is this path inside its backoff window right now?
+   *
+   * A path answering true must be skipped WITHOUT spending a request slot —
+   * charging it against `MAX_REQUESTS_PER_PASS` would let a few permanently
+   * failing paths starve every healthy one, which is the shape that made two
+   * alligators runs move zero files while sending 616 MB.
+   */
+  isBackedOff(rel: string, now: number): boolean;
+  /** Record one failed attempt and arm the next window. Returns the new delay. */
+  noteAttemptFailed(rel: string, now: number): number;
+  /** A path that worked: clear the counter and the window. */
+  noteAttemptOk(rel: string): void;
+
   /** The outbox: hashes this machine has in flight, for self-echo detection. */
   outboxAdd(hash: string): void;
   outboxDone(hash: string): void;
@@ -335,6 +407,21 @@ export function createFileLedger(opts: FileLedgerOptions): FileLedger {
         ...(typeof r.state === 'string' ? { state: r.state as DeliveryState } : {}),
         ...(typeof r.reason === 'string' ? { reason: r.reason.slice(0, 200) } : {}),
         ...(typeof r.conflictCopy === 'string' ? { conflictCopy: r.conflictCopy } : {}),
+        ...(r.blockedClass === 'too-large' ||
+        r.blockedClass === 'quota' ||
+        r.blockedClass === 'unreachable' ||
+        r.blockedClass === 'refused'
+          ? { blockedClass: r.blockedClass }
+          : {}),
+        // BACKOFF STATE IS PART OF THE ROW, so it has to be part of the
+        // allowlist. This is an allowlist, not a merge: a field missing from
+        // here is written to disk and silently dropped on the next load, which
+        // would make the backoff reset on every restart — the exact bypass
+        // persisting it was meant to close.
+        ...(Number.isFinite(r.attempts) && (r.attempts as number) >= 0
+          ? { attempts: Math.min(Math.trunc(r.attempts as number), 1_000) }
+          : {}),
+        ...(Number.isFinite(r.nextAttemptAt) ? { nextAttemptAt: r.nextAttemptAt } : {}),
       };
     }
     return out;
@@ -554,6 +641,36 @@ export function createFileLedger(opts: FileLedgerOptions): FileLedger {
       schedule();
     },
 
+    isBackedOff(rel, now) {
+      const next = data.rows[rel]?.nextAttemptAt;
+      if (!Number.isFinite(next)) return false;
+      // A window that ends absurdly far out is a corrupted or hostile row, not
+      // a backoff — treat it as expired rather than letting it park a path
+      // forever. The ledger is a local file, but a restore or a clock jump can
+      // still put nonsense in it.
+      if ((next as number) - now > MAX_BACKOFF_MS) return false;
+      return now < (next as number);
+    },
+
+    noteAttemptFailed(rel, now) {
+      const r = rowFor(rel);
+      const attempts = (Number.isFinite(r.attempts) ? (r.attempts as number) : 0) + 1;
+      r.attempts = attempts;
+      const delay = backoffDelayMs(attempts);
+      r.nextAttemptAt = now + delay;
+      schedule();
+      return delay;
+    },
+
+    noteAttemptOk(rel) {
+      const r = data.rows[rel];
+      if (!r) return;
+      if (r.attempts === undefined && r.nextAttemptAt === undefined) return;
+      r.attempts = undefined;
+      r.nextAttemptAt = undefined;
+      schedule();
+    },
+
     outboxAdd: (hash) => {
       outbox.add(hash);
     },