@1agh/maude 1.4.4 → 1.4.6

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

@@ -0,0 +1,229 @@
+// Per-machine comment ledger — issue #133.
+//
+// Records, per canvas slug, the comment identities (`commentKey`) that were on
+// this machine's `_comments/<slug>.json` AND in the shared document at the last
+// point the two agreed. It answers the one question neither side can answer
+// alone after a restart: an id that is on disk but not in the document — is it
+// a comment still on its way TO the document (keep it), or one the document
+// DROPPED while this machine was away (a remote delete — let it go)?
+//
+//   - in the ledger → it was synced before, the document no longer has it: a
+//     delete. The projection may write the file without it, and a cold-start
+//     union must not put it back.
+//   - not in the ledger → never synced from here: still in flight (a mutation
+//     whose import has not landed, an external edit — how /design:edit resolves
+//     comments). Keep it; defer, exactly as before.
+//
+// Before this, the "ever carried" knowledge lived only in memory
+// (collab/persistence.ts), so it started empty on every launch. A desktop that
+// was closed while a comment was deleted on the web then read that id as "in
+// flight" forever and never wrote its comments file again (accepted mode: the
+// file froze), and the legacy cold-start union re-added it for everyone.
+//
+// Per hub, like the sync journal (DDR-102): the file carries the hub URL it was
+// recorded against, and relinking to a different hub wipes it — "synced
+// before" against one hub says nothing about another. Best-effort and never
+// throws: a missing or corrupt ledger reads as empty, which degrades to the old
+// behaviour (defer), the safe direction. Lives under `_state/`, which is
+// already per-machine runtime state (DDR-115 taxonomy), so no new path.
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { atomicWrite } from './atomic-write.ts';
+import { commentKey } from './comment-identity.ts';
+
+const LEDGER_FILE = 'comment-ledger.json';
+/**
+ * Written immediately, not debounced: a record follows a comments-file write
+ * (rare), and a peer quit right after syncing must not lose it — a debounced
+ * ledger lost exactly that record in the E2E relaunch run and left the file
+ * frozen. Order is file first, ledger second, so a crash between the two
+ * leaves ids the ledger does not know: deferred, the safe direction.
+ */
+const FLUSH_MS = 0;
+/** Same ceiling as collab/persistence.ts MAX_SEEN_COMMENT_IDS (DDR-054 §2d). */
+const MAX_IDS_PER_SLUG = 10_000;
+
+interface LedgerFileShape {
+  hubUrl: string | null;
+  updatedAt: number;
+  slugs: Record<string, string[]>;
+}
+
+/** A read-only view of the identities recorded for one canvas. */
+export interface SyncedSet {
+  readonly size: number;
+  /** Takes a raw `commentKey`; the ledger stores only its hash. */
+  has(key: string): boolean;
+}
+
+/**
+ * The stored form of a comment key. Hashed (security review F3): an id-less
+ * comment's key is its whole JSON body, which a peer controls — the ledger must
+ * not grow with comment bodies, only with how many there are.
+ */
+export function ledgerKey(key: string): string {
+  return createHash('sha256').update(key).digest('base64url').slice(0, 22);
+}
+
+export interface CommentLedger {
+  /** Identities last known synced for `slug` (empty when never recorded). */
+  get(slug: string): SyncedSet;
+  /** Has `slug` ever been recorded (under the current hub)? Distinguishes
+   *  "synced, and had no comments" from "no knowledge" (first launch after
+   *  upgrading, a fresh link) — only the first may act on a difference. */
+  known(slug: string): boolean;
+  /** Replace `slug`'s record with the identities of a list both sides now agree on. */
+  record(slug: string, keys: Iterable<string>): void;
+  /**
+   * Linked to a (different) hub → drop every record. The identity must name
+   * the document namespace, not just the URL: one hub serves several
+   * workspaces (and branches), and "synced before" in one says nothing about
+   * another (security review F1c). `null` = no hub.
+   */
+  invalidateIfHubChanged(identity: string | null): void;
+  /** Persist now. Best-effort. */
+  flush(): void;
+}
+
+export function commentLedgerPath(designRoot: string): string {
+  return path.join(designRoot, '_state', LEDGER_FILE);
+}
+
+export interface LoadCommentLedgerOptions {
+  /** Tests use 0 to persist synchronously. */
+  flushMs?: number;
+  writer?: (file: string, bytes: string) => void;
+}
+
+export function loadCommentLedger(
+  designRoot: string,
+  opts: LoadCommentLedgerOptions = {}
+): CommentLedger {
+  const file = commentLedgerPath(designRoot);
+  const flushMs = opts.flushMs ?? FLUSH_MS;
+  const writer = opts.writer ?? ((p: string, bytes: string) => void atomicWrite(p, bytes));
+
+  let hubUrl: string | null = null;
+  const slugs = new Map<string, Set<string>>();
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let dirty = false;
+
+  try {
+    if (existsSync(file)) {
+      const parsed = JSON.parse(readFileSync(file, 'utf8')) as Partial<LedgerFileShape>;
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        hubUrl = typeof parsed.hubUrl === 'string' ? parsed.hubUrl : null;
+        const raw = parsed.slugs;
+        if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+          for (const [slug, ids] of Object.entries(raw)) {
+            if (!Array.isArray(ids)) continue;
+            const keys = ids.filter((k): k is string => typeof k === 'string');
+            slugs.set(slug, new Set(keys.slice(-MAX_IDS_PER_SLUG)));
+          }
+        }
+      }
+    }
+  } catch {
+    /* corrupt → empty; every id then reads as "in flight", the old behaviour */
+  }
+
+  function persist(): void {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (!dirty) return;
+    dirty = false;
+    const payload: LedgerFileShape = {
+      hubUrl,
+      updatedAt: Date.now(),
+      slugs: Object.fromEntries([...slugs].map(([s, ids]) => [s, [...ids]])),
+    };
+    try {
+      writer(file, `${JSON.stringify(payload)}\n`);
+    } catch (err) {
+      console.warn(
+        '[sync/comment-ledger] persist failed:',
+        err instanceof Error ? err.message : err
+      );
+    }
+  }
+
+  function schedule(): void {
+    dirty = true;
+    if (flushMs === 0) {
+      persist();
+      return;
+    }
+    if (!timer) timer = setTimeout(persist, flushMs);
+  }
+
+  return {
+    get(slug) {
+      const set = slugs.get(slug);
+      return {
+        size: set?.size ?? 0,
+        has: (key: string) => !!set && set.has(ledgerKey(key)),
+      };
+    },
+    known(slug) {
+      return slugs.has(slug);
+    },
+    record(slug, keys) {
+      const next = new Set<string>();
+      for (const k of keys) {
+        next.add(ledgerKey(k));
+        if (next.size >= MAX_IDS_PER_SLUG) break;
+      }
+      const prev = slugs.get(slug);
+      if (prev && prev.size === next.size && [...next].every((k) => prev.has(k))) return;
+      slugs.set(slug, next);
+      schedule();
+    },
+    invalidateIfHubChanged(url) {
+      if (url === hubUrl) return;
+      hubUrl = url;
+      slugs.clear();
+      schedule();
+    },
+    flush: persist,
+  };
+}
+
+/**
+ * The local half of a cold-start comments union, minus the comments a peer
+ * deleted while this machine was away: those the ledger knows were synced from
+ * here and the document no longer holds. Everything else — comments never
+ * synced from here — still unions up, exactly as before. Shared by both
+ * cold-start paths (sync/agent.ts reconcile, sync/migrate-seed.ts), which must
+ * agree or one would resurrect what the other let go.
+ */
+export function withoutRemotelyDeleted(
+  local: unknown[],
+  docList: unknown[],
+  syncedBefore: Pick<SyncedSet, 'size' | 'has'> | undefined
+): unknown[] {
+  if (!syncedBefore || syncedBefore.size === 0) return local;
+  const inDoc = new Set(docList.map(commentKey));
+  return local.filter((c) => {
+    const k = commentKey(c);
+    return inDoc.has(k) || !syncedBefore.has(k);
+  });
+}
+
+// One ledger per design root per process: the room projection (collab/) and the
+// sync agent (sync/) must share it, or two writers would overwrite each other's
+// file and each would only know half of what was synced.
+const shared = new Map<string, CommentLedger>();
+
+export function commentLedgerFor(designRoot: string): CommentLedger {
+  let l = shared.get(designRoot);
+  if (!l) {
+    l = loadCommentLedger(designRoot);
+    shared.set(designRoot, l);
+  }
+  return l;
+}

package/apps/studio/sync/file-plane.ts

@@ -61,6 +61,7 @@ import {
   statSync,
   writeFileSync,
 } from 'node:fs';
+import { open as openAsync } from 'node:fs/promises';
 import path from 'node:path';
 
 import { conflictCopyName, decideFile, type FileState } from './decide-file.ts';
@@ -112,6 +113,28 @@ export function sha256File(abs: string): string {
   return hash.digest('hex');
 }
 
+/**
+ * The same digest, yielding to the event loop between chunks. A received video
+ * is verified on the path every canvas sync shares: hashing 513 MiB in one
+ * synchronous run held a teammate's edit back ~5 s on a receiving peer
+ * (F3 S14, 2026-09-23).
+ */
+export async function sha256FileAsync(abs: string): Promise<string> {
+  const hash = createHash('sha256');
+  const buf = Buffer.allocUnsafe(1024 * 1024);
+  const fh = await openAsync(abs, 'r');
+  try {
+    for (;;) {
+      const { bytesRead } = await fh.read(buf, 0, buf.length, null);
+      if (bytesRead <= 0) break;
+      hash.update(bytesRead === buf.length ? buf : buf.subarray(0, bytesRead));
+    }
+  } finally {
+    await fh.close();
+  }
+  return hash.digest('hex');
+}
+
 /**
  * What the door accepts, until it tells us otherwise.
  *
@@ -617,6 +640,21 @@ export function createFilePlane(opts: FilePlaneOptions): FilePlane {
   let reanchorsInARow = 0;
   let reanchorHeldSince = 0;
 
+  /**
+   * A conflict row is waiting on a remote only a FULL read can tell it.
+   *
+   * A push answered `conflict` defers to "the next pass, against what the hub
+   * holds now" — but for a path the hub then leaves alone, a cursor read says
+   * nothing, the remembered remote stays unknown, and the row sat in
+   * `conflict` for good: Resync restarted the plane and read the same silence
+   * (rca issue-file-ledger-orphaned-rows). So a conflict owes one full read.
+   * Seeded from the ledger, which is what makes Resync (a restart) pay it.
+   * Capped at one per `REANCHOR_HOLD_RECOVERY_MS`, like the re-anchor storm,
+   * so a hub answering `conflict` to every push cannot farm full reads.
+   */
+  let fullReadOwed = Object.values(ledger.rows()).some((r) => r.state === 'conflict');
+  let lastOwedFullReadAt = Number.NEGATIVE_INFINITY;
+
   /**
    * When the plane may talk to the hub again. Issue #109.
    *
@@ -901,7 +939,7 @@ export function createFilePlane(opts: FilePlaneOptions): FilePlane {
       }
       let got: string;
       try {
-        got = sha256File(staged);
+        got = await sha256FileAsync(staged);
       } catch {
         return { ok: false, reason: 'could not read the downloaded file back' };
       }
@@ -1474,7 +1512,14 @@ export function createFilePlane(opts: FilePlaneOptions): FilePlane {
     requestsThisPass = 0;
 
     // ── 1. The hub's side ────────────────────────────────────────────────
-    const startedFrom = ledger.cursor();
+    const payOwedRead = fullReadOwed && now() - lastOwedFullReadAt >= REANCHOR_HOLD_RECOVERY_MS;
+    if (payOwedRead) {
+      fullReadOwed = false;
+      lastOwedFullReadAt = now();
+    }
+    // An owed read is a compaction read in the SAME epoch: the ancestors still
+    // describe this log, so nothing is degraded — it only refreshes remotes.
+    const startedFrom = payOwedRead ? 0 : ledger.cursor();
     let fullRead = startedFrom === 0;
     let page = await fetchJournal({
       hubUrl: opts.hubUrl,
@@ -1625,6 +1670,45 @@ export function createFilePlane(opts: FilePlaneOptions): FilePlane {
         ledger.forget(rel);
         continue;
       }
+      // NOT OURS ON EITHER SIDE ANY MORE — forget it, do not keep refusing it.
+      //
+      // A path can leave the file plane while the ledger still tracks it: a
+      // `.css` written before its `.tsx` becomes the canvas's sidecar, or the
+      // canvas groups change. The local scan stops offering it, the hub stops
+      // listing it, and the row stayed behind forever — re-stamped `stuck` by
+      // the admission drop against a remembered remote, or frozen in
+      // `conflict` with nothing left to decide — counted as "waiting" in the
+      // panel (rca issue-file-ledger-orphaned-rows). Only when this page did
+      // not offer it: a path the hub is actively naming still goes through
+      // admission, which reports the refusal.
+      if (!here && !row && kept) {
+        const cls = classifyProjectFile(rel, {
+          canvasGroups: opts.canvasGroups,
+          hasFile: (r) => local.has(r) || existsSync(path.join(designRoot, r)),
+        });
+        if (!isFilePlaneClass(cls)) {
+          ledger.forget(rel);
+          continue;
+        }
+      }
+      // A DELETE IS A TRANSFER TOO. The code-module gate below only sees a
+      // non-null remote, so a tombstone walked past it: an ancestor this peer
+      // recorded (by push, or by agreement) was all `tombstone-agreed` needed
+      // to quarantine a code module on the word of a hub that may not move
+      // one. Refuse it here, reported, with the file and its row untouched.
+      if (row?.deleted && here && !opts.allowCodeModules) {
+        const cls = classifyProjectFile(rel, {
+          canvasGroups: opts.canvasGroups,
+          hasFile: (r) => local.has(r) || existsSync(path.join(designRoot, r)),
+        });
+        if (cls === 'code-module') {
+          out.dropped.push({
+            rel,
+            reason: 'code modules are removed only by an owner-vouched or loopback hub',
+          });
+          continue;
+        }
+      }
       // What the hub holds: this page when it spoke about the path, otherwise
       // what we last learned. `undefined` (never learned) reads as null only
       // after a full read has had the chance to say so.
@@ -1650,6 +1734,20 @@ export function createFilePlane(opts: FilePlaneOptions): FilePlane {
           continue;
         }
         if (cls === 'code-module' && !opts.allowCodeModules) {
+          // AGREEMENT IS NOT A TRANSFER. The gate refuses to move a code
+          // module from an unvouched hub (DDR-054); identical bytes on both
+          // sides move nothing, and reporting them as refused left a
+          // converged file permanently "stuck".
+          if (here && here.hash === remoteHash) {
+            void ledger.adoptAfter(rel, here.hash, () => {}, {
+              ...(row ? { remoteSeq: row.seq } : {}),
+              size: here.size,
+              mtimeMs: here.mtimeMs,
+              state: 'on-hub',
+            });
+            out.synced += 1;
+            continue;
+          }
           drop(
             out,
             rel,
@@ -2059,6 +2157,7 @@ export function createFilePlane(opts: FilePlaneOptions): FilePlane {
           ledger.setState(rel, 'conflict', {
             reason: 'the hub changed this file while the upload was in flight',
           });
+          fullReadOwed = true;
           out.conflicts.push({ rel, copy: null });
           return true;
         }

package/apps/studio/sync/index.ts

@@ -53,6 +53,7 @@ import {
   stampCanvasPath,
   stampMovedTo,
 } from './codec.ts';
+import { commentLedgerFor } from './comment-ledger.ts';
 import {
   type ConnectionMonitor,
   createConnectionMonitor,
@@ -119,6 +120,14 @@ export interface SyncProvider {
    * Optional: a provider without it is treated as writable.
    */
   isWritable?(): boolean;
+  /**
+   * The hub's own word on this connection's write right, carried by a save-mode
+   * notice (`maude.mode` with `writable`). It outranks the scope the handshake
+   * returned: a connection admitted read-only while the project took proposals
+   * is writable again the moment the project returns to legacy — the hub fences
+   * per message, not per handshake — and nothing re-authenticates it.
+   */
+  noteWritable?(writable: boolean): void;
   /** The hub authenticated this connection (again) — scope may have changed. */
   onAuthenticated?(cb: (scope: string) => void): () => void;
   /** Out-of-band messages from the hub on this document's socket. */
@@ -512,6 +521,14 @@ export interface SyncRuntime {
   ): Promise<{ status: 'accepted' | 'rejected'; code?: string; queued?: boolean }> | null;
   /** True while the linked project is in accepted-revisions mode. */
   acceptedMode?(): boolean;
+  /**
+   * Issue #133 — may the comment ledger record `slug`'s current comments as
+   * synced? Only when the hub is known to hold them: accepted mode (the doc IS
+   * the accepted replica), or a synced provider with nothing unacknowledged. A
+   * comment added offline and not yet delivered must never read as "synced",
+   * or the next cold start would take it for a remote delete.
+   */
+  commentsConfirmedOnHub?(slug: string): boolean;
   /** Tripwire count: local writes that reached an accepted replica. */
   acceptedWriteViolations?(): number;
   /** Accepted revisions: the project's logical history (T27). Null when legacy. */
@@ -915,6 +932,8 @@ export function createSyncRuntime(
   // change is a proposal through the durable outbox, and the documents change
   // when the project publishes the accepted revision. Shared-doc only: the
   // two-doc agent path has no proposal lane and stays legacy.
+  /** Resolves once a previous run's outbox is drained: doc → own accepted html. */
+  let outboxDrained: Promise<Map<string, string>> = Promise.resolve(new Map());
   const acceptedLink: AcceptedLink | null = useSharedDoc
     ? createAcceptedLink({
         hubUrl: linkedHub.url,
@@ -925,7 +944,16 @@ export function createSyncRuntime(
         retryMs: opts.transactionRetryMs,
         onStats: (stats) => statusStore?.updateAccepted?.(stats),
         onStage: (summary) => statusStore?.updateAiAction?.(summary),
-        onBootstrap: (b) => noteProjectConfig(b.projectConfig),
+        onBootstrap: (b) => {
+          noteProjectConfig(b.projectConfig);
+          // F3 S17 — a save made as the socket died is held (the connection
+          // was not writable). After the reconnect the handshake re-admits the
+          // socket read-only BEFORE this peer learns the project now takes
+          // proposals, so its retry found the write still blocked and nothing
+          // retried again: the save stayed on disk, and the status said
+          // synced, until a restart. Knowing the mode, hand it back now.
+          if (b.mode === 'transactions') for (const p of projections.values()) p.retryDeferred();
+        },
       })
     : null;
   /**
@@ -2038,16 +2066,15 @@ export function createSyncRuntime(
   ): Awaited<ReturnType<typeof fetchRemoteListing>> {
     const manifest = acceptedOn() ? acceptedLink?.manifest : null;
     if (!manifest) return listing;
-    // A document the project RETIRED (moved away) is not a canvas to fetch,
-    // even while its storage row lingers — its successor is in the manifest.
-    const retired = new Set(manifest.docs.filter((d) => d.retired).map((d) => d.doc));
-    const documents = (listing?.documents ?? []).filter((d) => !retired.has(d.name));
-    const names = new Set(documents.map((d) => d.name));
-    for (const d of manifest.docs) {
-      if (d.retired || names.has(d.doc)) continue;
-      documents.push({ name: d.doc, bytes: 1 });
-      names.add(d.doc);
-    }
+    // An open Yjs room is not necessarily an accepted canvas. Its author can
+    // connect before doc.create commits; pulling that empty room would lock
+    // the receiver onto a lossy slug-derived path before the real path arrives.
+    // The accepted manifest alone names live canvases, including successors
+    // of retired documents whose transport rows may still linger.
+    const bytesByName = new Map((listing?.documents ?? []).map((d) => [d.name, d.bytes]));
+    const documents = manifest.docs
+      .filter((d) => !d.retired)
+      .map((d) => ({ name: d.doc, bytes: bytesByName.get(d.doc) ?? 1 }));
     return { ...(listing ?? { tombstones: [] }), documents, tombstones: listing?.tombstones ?? [] };
   }
 
@@ -2248,10 +2275,29 @@ export function createSyncRuntime(
         );
         // Work a previous run left unanswered goes first, in creation order —
         // before any cold start can propose something built on top of it.
-        void acceptedLink.client.drainOutbox().then((results) => {
-          if (results.length)
-            console.log(`[sync/tx] resent ${results.length} unanswered change(s).`);
-        });
+        // What each canvas's disk was last saved as, when that save was one of
+        // these: the base its cold start judges the disk against.
+        const own = new Map<string, string>();
+        outboxDrained = acceptedLink.client
+          .drainOutbox((result, operations) => {
+            for (const o of operations) {
+              const html =
+                o.op === 'lane.replace' && o.lane === 'html'
+                  ? o.content
+                  : o.op === 'doc.create'
+                    ? (o.lanes as Record<string, unknown> | undefined)?.html
+                    : undefined;
+              if (typeof o.doc !== 'string' || typeof html !== 'string') continue;
+              if (result.status === 'accepted') own.set(o.doc, html);
+              else own.delete(o.doc);
+            }
+          })
+          .then((results) => {
+            if (results.length)
+              console.log(`[sync/tx] resent ${results.length} unanswered change(s).`);
+            return own;
+          })
+          .catch(() => own);
         applyProjectDirs(acceptedLink.manifest?.dirs ?? []);
         proposeLocalFolders();
       }
@@ -2585,6 +2631,21 @@ export function createSyncRuntime(
       if (acceptedOn() && p?.op) projectionForRel(p.rel)?.noteSourceOp(p.op);
     });
     activityUnsubs.push(unsubSourceOp);
+    // Only the trusted API emits this after its write has finished. External
+    // fs events retain the quiet window; both paths use the same projection,
+    // proposal, validation and echo/deduplication rules.
+    const unsubSourceWritten = ctx.bus.on('source-written', (payload: unknown) => {
+      const p = payload as { rel?: unknown; content?: unknown } | null;
+      if (!acceptedOn() || typeof p?.content !== 'string') return;
+      const proj = projectionForRel(p.rel);
+      if (!proj) return;
+      proj.applyFromFs({
+        path: path.join(ctx.paths.designRoot, p.rel as string),
+        bytes: new TextEncoder().encode(p.content),
+        hash: hashBytes(p.content),
+      });
+    });
+    activityUnsubs.push(unsubSourceWritten);
     const unsubUnsuppress = ctx.bus.on('activity:unsuppress', (rel: unknown) => {
       projectionForRel(rel)?.cancelLocalWrite();
     });
@@ -2670,6 +2731,11 @@ export function createSyncRuntime(
     // in `_history/<slug>/` via history.ts so /design:rollback recovers them.
     journal = loadJournal(ctx.paths.designRoot);
     journal.invalidateIfHubChanged(linkedHub.url);
+    // Issue #133 — same per-hub rule for the comment ledger: "synced before"
+    // against one hub says nothing about another.
+    commentLedgerFor(ctx.paths.designRoot).invalidateIfHubChanged(
+      `${linkedHub.url} ${docNameFor('_')}`
+    );
     const history = createHistory(ctx);
 
     // ---- DDR-102 helpers: auth aggregation, re-probe, settle bookkeeping ----
@@ -3058,6 +3124,10 @@ export function createSyncRuntime(
           inProject = acceptedLink.manifest?.docs.some((d) => d.doc === docName && !d.retired);
         }
         const rel = path.relative(ctx.paths.designRoot, canvas.html).split(path.sep).join('/');
+        // A save a previous run left unanswered is answered first: a disk
+        // edited after it was edited ON it (F3 S14 on the cloud cell — judged
+        // against the older base, the save conflicted with itself).
+        const ownAccepted = (await outboxDrained).get(docName) ?? null;
         await acceptedColdStart({
           slug: canvas.slug,
           doc: provider.document,
@@ -3067,6 +3137,9 @@ export function createSyncRuntime(
           projection,
           historyDir: path.join(ctx.paths.historyDir, canvas.slug),
           journal: journal ?? undefined,
+          commentLedger: commentLedgerFor(ctx.paths.designRoot),
+          ownAccepted,
+          wasAccepted: (content) => acceptedLink.client.holdsValue(content),
           createDoc: (lanes) => acceptedLink.createDoc(canvas.slug, rel, lanes),
         });
         projection.reconcile();
@@ -3084,6 +3157,7 @@ export function createSyncRuntime(
           paths: canvasPaths,
           historyDir: path.join(ctx.paths.historyDir, canvas.slug),
           journal: journal ?? undefined,
+          commentLedger: commentLedgerFor(ctx.paths.designRoot),
           snapshot: async (content, reason) => {
             try {
               const snap = await history.writeSnapshot(relBody, content, reason);
@@ -3697,6 +3771,14 @@ export function createSyncRuntime(
                 echoGuard,
                 adopt: adoptOnce,
                 journal: journal ?? undefined,
+                commentLedger: commentLedgerFor(ctx.paths.designRoot),
+                commentsConfirmed: () => {
+                  const p = provider as unknown as {
+                    synced?: boolean;
+                    hasUnsyncedChanges?: boolean;
+                  };
+                  return p.synced === true && p.hasUnsyncedChanges === false;
+                },
                 snapshot: async (content, reason) => {
                   try {
                     const snap = await history.writeSnapshot(relBody, content, reason);
@@ -3733,6 +3815,8 @@ export function createSyncRuntime(
                   }
                   if (msg?.type !== 'maude.mode') return;
                   if (msg.mode === 'transactions' || msg.mode === 'legacy') {
+                    const writable = (msg as { writable?: unknown }).writable;
+                    if (typeof writable === 'boolean') provider.noteWritable?.(writable);
                     acceptedLink.noteMode(msg.mode);
                     void refreshAcceptedMode();
                   }
@@ -4876,6 +4960,19 @@ export function createSyncRuntime(
     },
     proposeFolder,
     acceptedMode: acceptedOn,
+    commentsConfirmedOnHub: (slug) => {
+      // The canvas must be live on the hub right now: a provider that has
+      // synced. In accepted mode its doc is the accepted replica (local writes
+      // are refused), but only once THIS canvas's projection exists — before
+      // that, a comment falls back to the local room and is not on the hub
+      // (security review F1b). In legacy mode nothing may be unacknowledged.
+      const p = providers.get(slug) as unknown as
+        | { synced?: boolean; hasUnsyncedChanges?: boolean }
+        | undefined;
+      if (!p || p.synced !== true) return false;
+      if (acceptedOn()) return projections.has(slug);
+      return p.hasUnsyncedChanges === false;
+    },
     acceptedWriteViolations: () => acceptedWriteViolations,
     acceptedHistory: async (q) => {
       if (!acceptedOn() || !acceptedLink) return null;
@@ -5740,11 +5837,17 @@ export function createDefaultProviderFactory(
     socket.on('status', resetSyncedOnDrop);
 
     let authedThisConnection = false;
+    /** A save-mode notice's verdict on THIS connection; a new handshake supersedes it. */
+    let modeWritable: boolean | null = null;
     provider.on('authenticated', () => {
       authedThisConnection = true;
+      modeWritable = null;
     });
     const forgetAuthOnDrop = (evt: { status?: string }) => {
-      if (evt?.status !== 'connected') authedThisConnection = false;
+      if (evt?.status !== 'connected') {
+        authedThisConnection = false;
+        modeWritable = null;
+      }
     };
     socket.on('status', forgetAuthOnDrop);
     return {
@@ -5757,7 +5860,11 @@ export function createDefaultProviderFactory(
       // over from before a drop says nothing about the hub now: a project
       // switched to accepted revisions while this peer was away re-admits it
       // read-only, and anything written in between would be dropped there.
-      isWritable: () => authedThisConnection && provider.authorizedScope === 'read-write',
+      isWritable: () =>
+        authedThisConnection && (modeWritable ?? provider.authorizedScope === 'read-write'),
+      noteWritable(writable: boolean) {
+        if (authedThisConnection) modeWritable = writable;
+      },
       onAuthenticated(cb: (scope: string) => void): () => void {
         const handler = (evt: { scope?: string }) => cb(String(evt?.scope ?? ''));
         provider.on('authenticated', handler);

package/apps/studio/sync/journal-client.ts

@@ -17,6 +17,8 @@
 // it as "no changes" is exactly the shape that lets a stale peer believe it is
 // current, which is the failure DDR-214's ordering amendment exists to prevent.
 
+import { isProjectFileShape } from './file-membership.ts';
+
 /** How long to wait for a journal page. Same figure as the manifest fetch. */
 const JOURNAL_TIMEOUT_MS = 6000;
 
@@ -58,8 +60,12 @@ export interface JournalPage {
   overflowed?: true;
 }
 
-/** A designRoot-relative path shape a peer will turn into a real file. */
-const ENTRY_PATH_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,255}$/;
+// A designRoot-relative path a peer will turn into a real file: the SAME shape
+// rule the hub's file door admits (`isProjectFileShape`). A private, narrower
+// regex here dropped every journalled path with a space in it — `ui/Studio
+// Docs.registry.json` was accepted from its author, journalled, and then
+// silently discarded by every other peer, with no ledger row and no refusal
+// shown (F3 S14, 2026-09-23).
 
 function parseEntry(raw: unknown): JournalEntry | null {
   if (!raw || typeof raw !== 'object') return null;
@@ -67,7 +73,7 @@ function parseEntry(raw: unknown): JournalEntry | null {
   const seq = e.seq;
   const p = e.path;
   if (typeof seq !== 'number' || !Number.isInteger(seq) || seq <= 0) return null;
-  if (typeof p !== 'string' || !ENTRY_PATH_RE.test(p) || p.split('/').includes('..')) return null;
+  if (typeof p !== 'string' || !isProjectFileShape(p)) return null;
   const sha = typeof e.sha256 === 'string' && /^[0-9a-f]{64}$/.test(e.sha256) ? e.sha256 : null;
   return {
     seq,