@1agh/maude 1.0.11 → 1.2.0

package/apps/studio/client/styles/4-components.css

@@ -2157,3 +2157,29 @@
   color: var(--fg-3);
   overflow-wrap: anywhere;
 }
+
+/* Seed progress (feature-large-project-seed).
+   A bar rather than a number alone: a large project's seed is minutes to hours
+   of work, and "1 412" reads the same whether it is a quarter done or finished.
+   Track and fill use existing tokens — no new colours enter the system here. */
+.sp-progress-track {
+  height: 4px;
+  border-radius: 2px;
+  background: var(--bg-2);
+  overflow: hidden;
+  margin: 6px 0 4px;
+}
+.sp-progress-fill {
+  height: 100%;
+  background: var(--accent);
+  border-radius: 2px;
+  transition: width var(--dur-2, 240ms) ease;
+}
+@media (prefers-reduced-motion: reduce) {
+  .sp-progress-fill { transition-duration: 1ms; }
+}
+/* The falsifiable half (DDR-214) — present, quiet, never the headline. */
+.sp-raw-counters {
+  opacity: 0.6;
+  font-size: 0.9em;
+}

package/apps/studio/collab/persistence.ts

@@ -10,6 +10,7 @@ import type { Api } from '../api.ts';
 import type { Context } from '../context.ts';
 // From the LEAF, never from `sync/codec.ts` — codec imports `Y_TYPES` from this
 // file, so reaching for it here would close a cycle (see sync/limits.ts).
+import { commentKey } from '../sync/comment-identity.ts';
 import { MAX_ANNOTATIONS_BYTES, MAX_COMMENTS_BYTES, withinByteCap } from '../sync/limits.ts';
 import { ensureStateDir, type RoomCallbacks } from './room.ts';
 
@@ -82,15 +83,91 @@ export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
   const { ctx, api, fileForSlug } = deps;
   const stateDir = ensureStateDir(ctx.paths.designRoot);
 
-  // Per-slug latch: have we ever projected a NON-empty comments array for this
-  // canvas? We write an empty `[]` to disk only AFTER content has been seen — a
-  // genuine delete-all — never from a doc that was never populated (cold start
-  // before seed/migrate completes), which would clobber a non-empty local file.
-  // This closes the receiving-peer gap where a delete-all on one peer left
-  // stragglers on the other: the old `arr.length > 0` guard skipped the write
-  // when the array emptied, so the deletion never reached the peer's JSON file
-  // (the file the sidebar reads), even though the Y.Doc had converged (DDR-064).
-  const seenComments = new Set<string>();
+  // Per-slug: every comment identity this doc has EVER carried (issue #111).
+  //
+  // This subsumes the old `seenComments` latch — "have we ever projected a
+  // NON-empty array for this canvas", which gated the delete-all write so a
+  // never-populated doc could not clobber a non-empty local file with `[]`
+  // (DDR-064's receiving-peer gap). Same question, better evidence.
+  //
+  // It also answers the question the projection could not ask at all before,
+  // and the one this issue is about: is the doc AHEAD of the file (a real
+  // change, write it) or BEHIND it (a write the doc has not caught up with —
+  // writing would erase it)?
+  //
+  // Identity settles it without a wire-format change. An id on disk that the
+  // doc has held and dropped is a genuine delete and must materialize. An id on
+  // disk the doc has NEVER held is something the doc has not seen yet, and
+  // dropping it is silent data loss — the reporter's "add a second comment and
+  // it disappears after a few seconds". `Room.flush()` fires on ANY doc update
+  // and every hub update re-arms it, so on a linked project a flush lands in
+  // that window constantly; on a local one it essentially never does, which is
+  // exactly the scoping the reporter gave ("connected to a custom hub").
+  const docSeenComments = new Map<string, Set<string>>();
+
+  /**
+   * Ceiling on identities remembered per canvas — DDR-054 §2d applied to a set
+   * rather than a byte length.
+   *
+   * The doc is populated by the hub, so what lands in this set is peer-supplied
+   * and the set only ever grows: without a bound, a hostile hub streaming
+   * distinct comment ids is unbounded memory on every linked peer. Eviction is
+   * oldest-first (JS sets keep insertion order), and it degrades in the SAFE
+   * direction — an evicted id reads as "never seen", so the projection defers
+   * the write instead of deleting. The cost is that a delete of a very old
+   * comment on a canvas that has carried more than this many distinct comments
+   * may not materialize, which is a far better failure than losing one.
+   */
+  const MAX_SEEN_COMMENT_IDS = 10_000;
+
+  /**
+   * Docs already wired to their slug's identity set.
+   *
+   * WEAK on purpose: a room dropped when its last browser leaves destroys its
+   * doc, and a strong reference here would keep every doc of every canvas the
+   * user ever opened alive for the process's lifetime. The observer closes over
+   * the SET, not the other way round, so nothing else pins the doc either.
+   */
+  const observedCommentDocs = new WeakSet<Y.Doc>();
+
+  /**
+   * The identity set for `slug`, observing `doc` so it records an id the moment
+   * it ENTERS the array.
+   *
+   * Sampling at flush time alone is not enough, and the gap is a real delete
+   * bug rather than a theoretical one: an id that arrives and is deleted again
+   * between two flushes (a local add, then a remote delete inside the same
+   * 800 ms debounce — every doc update re-arms the timer, so this is the common
+   * shape, not a rare one) would never be recorded, the guard below would read
+   * the surviving disk copy as "never seen", and the delete could never
+   * materialize. The observer only ever ADDS, which is what makes it a record
+   * of what the doc has held rather than of what it holds.
+   *
+   * The set is per SLUG and the wiring is per DOC: a slug's room can be rebuilt
+   * on a fresh doc, and the ids carry over because this peer did see them.
+   */
+  function commentIdsSeenBy(slug: string, doc: Y.Doc): Set<string> {
+    let ids = docSeenComments.get(slug);
+    if (!ids) {
+      ids = new Set<string>();
+      docSeenComments.set(slug, ids);
+    }
+    if (observedCommentDocs.has(doc)) return ids;
+    observedCommentDocs.add(doc);
+
+    const seen = ids;
+    const arr = doc.getArray<unknown>(Y_TYPES.comments);
+    const absorb = () => {
+      for (const c of arr.toArray()) seen.add(commentKey(c));
+      for (const stale of seen) {
+        if (seen.size <= MAX_SEEN_COMMENT_IDS) break;
+        seen.delete(stale); // oldest first — insertion order
+      }
+    };
+    absorb();
+    arr.observe(absorb);
+    return ids;
+  }
 
   function ydocBinPath(slug: string): string {
     return path.join(stateDir, `${slug}.ydoc.bin`);
@@ -108,6 +185,13 @@ export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
   }
 
   async function seed(slug: string, doc: Y.Doc): Promise<void> {
+    // Start recording comment identities at ROOM MOUNT, before anything can
+    // gate out (issue #111). `persistJson` would otherwise be the first thing
+    // to observe this doc, which is one flush too late: an id added and deleted
+    // before that flush would never be recorded, and its delete could never
+    // materialize. This is the earliest callback that sees the doc.
+    commentIdsSeenBy(slug, doc);
+
     // Phase 9.2 (DDR-064) — under sharedDoc the migrate-seed + hub provider own
     // initial population for a pinned slug; a local file-seed here would push
     // fresh Y.Array items that DUPLICATE the hub's canonical items on merge
@@ -136,7 +220,22 @@ export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
     doc.transact(() => {
       if (comments.length > 0) {
         const arr = doc.getArray<unknown>(Y_TYPES.comments);
-        arr.push(comments);
+        // Push only what the array does not already hold (issue #112). This was
+        // an unconditional `arr.push(comments)`, which concatenates whenever the
+        // doc is NOT empty at seed time — the DDR-064 Risk 1 window that
+        // `shouldSeed`/`isPinned` closes only when the pin already exists, i.e.
+        // not when a room is mounted a beat before the hub provider attaches.
+        // The identity rule is `commentKey`, shared with the codec's diff and
+        // the cold-start union; the leaf import is deliberate — this file owns
+        // `Y_TYPES`, so it can never import `sync/codec.ts` back (see above).
+        const present = new Set(arr.toArray().map(commentKey));
+        const missing = comments.filter((c) => {
+          const k = commentKey(c);
+          if (present.has(k)) return false;
+          present.add(k);
+          return true;
+        });
+        if (missing.length > 0) arr.push(missing);
       }
       if (svg && typeof svg === 'string') {
         const map = doc.getMap<string>(Y_TYPES.annotations);
@@ -151,14 +250,31 @@ export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
 
     // Comments — Y.Array projection back to JSON. Write whenever the doc holds
     // comments, OR when it just emptied after previously holding some (so a
-    // delete-all materializes on EVERY peer's disk, not just the originator's).
-    // The seenComments latch keeps a never-populated doc (cold start) from
-    // clobbering a non-empty local file with [].
+    // delete-all materializes on EVERY peer's disk, not just the originator's),
+    // and never from a doc that was never populated at all (cold start before
+    // seed/migrate completes), which would clobber a non-empty local file.
+    //
+    // `everSeen` is that latch as well as the freshness oracle below — one
+    // notion of "this doc has held comments" instead of two that can disagree.
+    // It replaces a per-slug flag sampled HERE, which could not see a comment
+    // that arrived and was deleted again between two flushes: the flag stayed
+    // unset, so the delete-all read as "never populated" and never reached
+    // disk. Both readings need the same fact, and only the observer has it.
     const arr = doc.getArray(Y_TYPES.comments);
     const list = arr.toArray() as Parameters<Api['saveCommentsForFile']>[1];
-    if (list.length > 0) seenComments.add(slug);
-    if (list.length > 0 || seenComments.has(slug)) {
-      if (withinCap(slug, 'comments', JSON.stringify(list), MAX_COMMENTS_BYTES)) {
+    const everSeen = commentIdsSeenBy(slug, doc);
+    if (list.length > 0 || everSeen.size > 0) {
+      // Issue #111 — refuse to project a doc that is BEHIND the file. An id on
+      // disk this doc has never carried is a write still in flight towards it
+      // (a mutation whose file→doc import has not landed, an external edit to
+      // `_comments/<slug>.json`); overwriting it deletes a real comment with no
+      // error and no recovery. Deferring is safe and self-clearing: whatever
+      // brings that id into the doc is itself a doc update, which re-arms the
+      // flush, and the next pass writes the merged state. A delete still
+      // materializes — its id IS in `everSeen`, so the write proceeds.
+      const onDisk = await api.loadCommentsForFile(file);
+      const behind = onDisk.some((c) => !everSeen.has(commentKey(c)));
+      if (!behind && withinCap(slug, 'comments', JSON.stringify(list), MAX_COMMENTS_BYTES)) {
         await api.saveCommentsForFile(file, list);
       }
     }

package/apps/studio/collab/registry.ts

@@ -8,17 +8,12 @@
 
 import type { Awareness } from 'y-protocols/awareness';
 
+import { applyCommentsToDoc } from '../sync/codec.ts';
 import { bridgeAwareness } from './awareness-bridge.ts';
 import { Y_TYPES } from './persistence.ts';
 import type { Room, RoomCallbacks } from './room.ts';
 import { createRoom } from './room.ts';
 
-/** Structural equality via canonical JSON — used by the syncRoomFrom* no-op
- *  guards. Comment lists are small; stringify is cheap + dependency-free. */
-function jsonEqual(a: unknown, b: unknown): boolean {
-  return JSON.stringify(a) === JSON.stringify(b);
-}
-
 export interface Registry {
   /** Get-or-create. Reuses an existing room for the same slug. */
   get(slug: string): Room;
@@ -186,18 +181,15 @@ export function createRegistry(callbacks: RoomCallbacks): Registry {
   function syncRoomFromComments(slug: string, comments: readonly unknown[]): void {
     const room = rooms.get(slug);
     if (!room) return;
-    const arr = room.doc.getArray<unknown>(Y_TYPES.comments);
-    // No-op guard (load-bearing): skip when the room already holds this exact
-    // list. The wholesale delete+push always emits a doc update, which schedules
-    // a persist → file write → fs event → re-seed … so without this equality
-    // short-circuit, re-seeding the live room from a disk change (sync-agent or
-    // design:edit write — see createCollab's fs hook) would spin an 800ms
-    // persist storm. Equality breaks the loop after a single convergence.
-    if (jsonEqual(arr.toArray(), comments)) return;
-    room.doc.transact(() => {
-      if (arr.length > 0) arr.delete(0, arr.length);
-      if (comments.length > 0) arr.push(comments as unknown[]);
-    }, 'inspector-write');
+    // Through the codec's identity-keyed diff, NOT a local delete-all + push
+    // (issue #112). This bridge fires after EVERY comment mutation, so it was
+    // one of the three writers that could collide with an in-flight hub update
+    // and leave the array holding both runs. The codec keeps the no-op guard
+    // this function used to carry inline — an unchanged list emits no
+    // transaction, so re-seeding the live room from a disk change (sync-agent
+    // or design:edit write — see createCollab's fs hook) still can't spin the
+    // 800 ms persist storm the old equality short-circuit existed to prevent.
+    applyCommentsToDoc(room.doc, comments as unknown[], 'inspector-write');
   }
 
   function syncRoomFromAnnotations(slug: string, svg: string): void {

package/apps/studio/debug-bundle.ts

@@ -120,6 +120,13 @@ export function scrub(text: string, opts: ScrubOptions = {}): string {
 export interface DebugBundle {
   app: { maudeVersion: string; platform: string; arch: string };
   context: { projectName: string | null; activeCanvas: string | null };
+  /** Server process memory at report time (#119). A runaway-memory report used
+   *  to arrive as a number the user eyeballed in Activity Monitor, with nothing
+   *  in the bundle to confirm or refute it — and the log ring was silent
+   *  because the heap watch was measuring the wrong counter. `rss` is the same
+   *  number the user sees, so a future report of this class carries its own
+   *  evidence. Bytes; process-level, never per-request. */
+  process: { rssBytes: number; heapUsedBytes: number; uptimeSeconds: number };
   logs: { serverLogTail: string };
 }
 
@@ -137,6 +144,7 @@ export function buildDebugBundle(args: {
   tailLines?: number;
 }): DebugBundle {
   const scrubOpts: ScrubOptions = { repoRoot: args.repoRoot };
+  const memory = process.memoryUsage();
   return {
     app: {
       maudeVersion: args.maudeVersion,
@@ -147,6 +155,11 @@ export function buildDebugBundle(args: {
       projectName: args.projectName,
       activeCanvas: args.activeCanvas ? scrub(args.activeCanvas, scrubOpts) : null,
     },
+    process: {
+      rssBytes: memory.rss,
+      heapUsedBytes: memory.heapUsed,
+      uptimeSeconds: Math.round(process.uptime()),
+    },
     logs: {
       serverLogTail: logRingLines(args.tailLines ?? 200)
         .map((l) => scrub(l, scrubOpts))