@1agh/maude 1.0.11 → 1.3.0

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);
       }
     }
@@ -168,7 +284,11 @@ export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
     const svg = map.get('svg');
     if (typeof svg === 'string' && svg) {
       if (withinCap(slug, 'annotations', svg, MAX_ANNOTATIONS_BYTES)) {
-        await api.saveAnnotations(file, svg);
+        // Projection must never re-enter onAnnotationsChanged: an old flush
+        // finishing after a new edit otherwise republishes the old SVG and
+        // rolls back every peer. The API checks freshness after async IO and
+        // before its atomic rename; a later doc update schedules a new flush.
+        await api.projectAnnotations(file, svg, () => map.get('svg') === svg);
       }
     }
   }

package/apps/studio/collab/registry.ts

@@ -8,17 +8,13 @@
 
 import type { Awareness } from 'y-protocols/awareness';
 
+import { ANNOTATION_WRITE_ID, validAnnotationWriteId } from '../annotations-sync.ts';
+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;
@@ -57,7 +53,7 @@ export interface Registry {
    * post-write SVG; the room replaces `Y.Map.svg` so collab peers see the
    * updated stroke set without waiting for a cold-open re-seed.
    */
-  syncRoomFromAnnotations(slug: string, svg: string): void;
+  syncRoomFromAnnotations(slug: string, svg: string, writeId?: string): void;
   /**
    * Phase 30 — project agent editing-presence onto a slug's room awareness so
    * it crosses the hub (the loopback `ai-activity` bus event does not). `null`
@@ -186,27 +182,29 @@ 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 {
+  function syncRoomFromAnnotations(slug: string, svg: string, writeId?: string): void {
     const room = rooms.get(slug);
     if (!room) return;
     const map = room.doc.getMap<string>(Y_TYPES.annotations);
-    if (map.get('svg') === svg) return; // no-op guard — same rationale as comments
+    // Identical disk notifications remain no-ops. A new UI operation may
+    // deliberately restore identical content while an author has pending work.
+    const id = validAnnotationWriteId(writeId) ? writeId : undefined;
+    if (map.get('svg') === svg && (!id || map.get(ANNOTATION_WRITE_ID) === id)) return;
     room.doc.transact(() => {
       map.set('svg', svg);
+      if (id) map.set(ANNOTATION_WRITE_ID, id);
+      else map.delete(ANNOTATION_WRITE_ID);
     }, 'inspector-write');
   }
 

package/apps/studio/collab/room.ts

@@ -77,6 +77,15 @@ export interface RoomCallbacks {
    * the seeded state.
    */
   seed(slug: string, doc: Y.Doc): Promise<void> | void;
+
+  /**
+   * Accepted revisions (DDR-241 §7): while true, this room's document is a
+   * replica of the project's accepted state — no browser connection may write
+   * a persistent lane into it (the hub would drop it and the replica would
+   * diverge). Comments and annotations go through the API as proposals.
+   * Awareness is unaffected. Optional; absent means false.
+   */
+  acceptedMode?: () => boolean;
 }
 
 export interface Room {
@@ -216,6 +225,8 @@ export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
    */
   function refusedLanes(conn: RoomConn, roots: ReadonlySet<string>): string[] {
     const refused: string[] = [];
+    // Accepted revisions: every persistent lane is the hub's to change.
+    if (callbacks.acceptedMode?.()) return [...roots];
     for (const r of roots) {
       if (conn.realm === 'canvas' && (isBodyLane(r) || r === '<unresolved>')) {
         refused.push(r);
@@ -255,7 +266,7 @@ export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
       gateRefusalCount += 1;
       discardMirror();
       console.warn(
-        `[collab/${slug}] origin gate REFUSED a ${conn.readOnly ? 'read-only' : 'canvas-realm'} ` +
+        `[collab/${slug}] origin gate REFUSED a ${callbacks.acceptedMode?.() ? 'accepted-replica' : conn.readOnly ? 'read-only' : 'canvas-realm'} ` +
           `sync frame (lanes: ${refused.join(', ') || 'unclassifiable'}). ` +
           (conn.readOnly
             ? 'A viewer-role socket may only write comments — role matrix, cloud collab lane.'
@@ -351,7 +362,7 @@ export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
   }
 
   function receive(conn: RoomConn, payload: Uint8Array): void {
-    if (conn.realm === 'canvas' || conn.readOnly === true) {
+    if (conn.realm === 'canvas' || conn.readOnly === true || callbacks.acceptedMode?.()) {
       receiveGated(conn, payload);
       return;
     }

package/apps/studio/context.ts

@@ -259,6 +259,65 @@ export interface Context {
     current?(): {
       cancelAssetSweep(): boolean;
       retireForMove?(fromSlug: string, toRel: string): Promise<boolean>;
+      /** Accepted-revisions mode (DDR-241) — see SyncRuntime.proposeLane. */
+      proposeLane?(
+        slug: string,
+        lane: 'comments' | 'annotations' | 'meta',
+        text: string,
+        opts?: { baseText?: string; writeId?: string }
+      ): Promise<{ status: 'accepted' | 'rejected'; code?: string }> | null;
+      /** Accepted-revisions mode (DDR-241) — see SyncRuntime.proposeFolder. */
+      proposeFolder?(
+        op:
+          | { op: 'dir.create'; path: string }
+          | { op: 'dir.delete'; path: string }
+          | { op: 'dir.move'; from: string; to: string }
+      ): Promise<{ status: 'accepted' | 'rejected'; code?: string; queued?: boolean }> | null;
+      acceptedMode?(): boolean;
+      acceptedHistory?(q: {
+        limit?: number;
+        before?: number | null;
+        path?: string | null;
+      }): Promise<unknown[] | null>;
+      acceptedVersion?(repoRel: string, revision: number): Promise<string | null>;
+      acceptedRestore?(
+        repoRel: string,
+        revision: number
+      ): Promise<{ status: 'accepted' | 'rejected'; code?: string; queued?: boolean } | null>;
+      acceptedUndo?(
+        actionId: string,
+        redo?: boolean
+      ): Promise<{
+        status: 'accepted' | 'rejected';
+        code?: string;
+        queued?: boolean;
+        actionId?: string;
+      } | null>;
+      acceptedActionForContent?(repoRel: string, content: string): string | null;
+      prepareOffline?(): Promise<{
+        complete: boolean;
+        pulled: number;
+        passes: number;
+        failed: number;
+      } | null>;
+      conflictVersions?(
+        repoRel: string
+      ): { slug: string; mine: string | null; theirs: string } | null;
+      resolveConflict?(
+        repoRel: string,
+        choice: 'mine' | 'theirs'
+      ): Promise<{ status: 'accepted' | 'rejected' | 'taken'; code?: string } | null>;
+      /** T16 — AI action boundaries (see sync/action-stage.ts). */
+      beginAiAction?(key: string, label: string): void;
+      endAiAction?(
+        key: string,
+        outcome: 'done' | 'failed'
+      ): Promise<{ status: 'accepted' | 'rejected'; code?: string } | null>;
+      resolveAiAction?(choice: 'publish' | 'discard'): Promise<{
+        status: 'accepted' | 'rejected' | 'discarded';
+        code?: string;
+        canvases?: number;
+      } | null>;
     } | null;
   };
 }

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))