@1agh/maude 1.4.5 → 1.5.0

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-membership.ts

@@ -199,6 +199,16 @@ export interface ClassifyOptions {
  * `node_modules`, directory segments start alphanumeric, the final segment
  * may start with `_`.
  */
+/**
+ * The annotations board (DDR-242: `<slug>.annotations.json`) and its legacy v1
+ * form (`<slug>.annotations.svg`). BOTH stay canvas-owned: the board is the doc
+ * lane's, and a stale legacy sidecar must never ride the file plane between
+ * machines (the boot migration quarantines it locally).
+ */
+function isAnnotationsSidecar(lowerName: string): boolean {
+  return lowerName.endsWith('.annotations.json') || lowerName.endsWith('.annotations.svg');
+}
+
 export function classifyProjectFile(rel: string, opts: ClassifyOptions = {}): FileClass {
   const parts = relShape(rel);
   if (parts === null) return 'never';
@@ -219,7 +229,7 @@ export function classifyProjectFile(rel: string, opts: ClassifyOptions = {}): Fi
     // The canvas body and its NAMED sidecars — Plane A's, by construction.
     if (lowerLast.endsWith('.tsx')) return 'canvas-owned';
     if (lowerLast.endsWith('.meta.json')) return 'canvas-owned';
-    if (lowerLast.endsWith('.annotations.svg')) return 'canvas-owned';
+    if (isAnnotationsSidecar(lowerLast)) return 'canvas-owned';
     if (lowerLast.endsWith('.css') && opts.hasFile) {
       const sibling = `${rel.slice(0, -'.css'.length)}.tsx`;
       if (opts.hasFile(sibling)) return 'canvas-owned';
@@ -238,7 +248,7 @@ export function classifyProjectFile(rel: string, opts: ClassifyOptions = {}): Fi
   // pushed over them at 10:50:33). The annotations lane's own stamped
   // newest-wins protection never saw it coming — it guards the DOC lane, and
   // this was the file plane acting alone. One owner: the canvas.
-  if (parts.length === 1 && lowerLast.endsWith('.annotations.svg')) return 'canvas-owned';
+  if (parts.length === 1 && isAnnotationsSidecar(lowerLast)) return 'canvas-owned';
 
   if (COMPANION_SIDECAR_SUFFIXES.some((s) => lowerLast.endsWith(s))) return 'companion-text';
 

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

@@ -640,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.
    *
@@ -1497,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,
@@ -1648,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.
@@ -1673,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,
@@ -2082,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;
         }
@@ -2321,7 +2397,7 @@ function holdOversized(out: FilePlaneResult, ledger: FileLedger, file: Oversized
 function referencedAssetNames(designRoot: string): Set<string> {
   const out = new Set<string>();
   const RE = /assets\/([A-Za-z0-9._-]+\.[A-Za-z0-9]+)/g;
-  const SCANNED = /\.(?:annotations\.svg|tsx|jsx|css|meta\.json)$/i;
+  const SCANNED = /\.(?:annotations\.(?:svg|json)|tsx|jsx|css|meta\.json)$/i;
   const walk = (dir: string, depth: number): void => {
     if (depth > MAX_WALK_DEPTH) return;
     let entries: Dirent[];

package/apps/studio/sync/index.ts

@@ -33,6 +33,8 @@ import { hostname } from 'node:os';
 import path from 'node:path';
 import type { Awareness } from 'y-protocols/awareness';
 import * as Y from 'yjs';
+import { migrateAnnotationsV2 } from '../annotations/migrate-boot.ts';
+import { REPLICA_TYPE, replicaBoardText } from '../annotations/replica.ts';
 import { renewHubCredential } from '../cloud/renew.ts';
 import { Y_TYPES } from '../collab/persistence.ts';
 import type { Context, LinkedHub } from '../context.ts';
@@ -53,6 +55,7 @@ import {
   stampCanvasPath,
   stampMovedTo,
 } from './codec.ts';
+import { commentLedgerFor } from './comment-ledger.ts';
 import {
   type ConnectionMonitor,
   createConnectionMonitor,
@@ -70,13 +73,14 @@ import { createFsReader, type FsReader } from './fs-mirror.ts';
 import { type HubDocRow, hubHolds, indexHubDocs } from './hub-listing.ts';
 import { getHubRecord } from './hubs-config.ts';
 import { loadJournal, type SyncJournal } from './journal.ts';
-import { hasLedger, hubCapabilities } from './journal-client.ts';
+import { hasAnnotationsV2, hasLedger, hubCapabilities } from './journal-client.ts';
 import { isLoopbackHost } from './loopback.ts';
 import { migrateFlatFallback } from './migrate-flat-fallback.ts';
 import { migrateSeed } from './migrate-seed.ts';
 import { ORIGINS } from './origins.ts';
 import { createDocProjection, type DocProjection } from './projection.ts';
 import {
+  acceptedListing,
   describeRemoteDiff,
   diffRemoteDocs,
   fetchRemoteListing,
@@ -520,6 +524,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. */
@@ -2061,12 +2073,10 @@ export function createSyncRuntime(
     // 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 ?? [] };
+    // of retired documents whose transport rows may still linger — and a
+    // legacy tombstone for a name the manifest lists live no longer buries it
+    // (see `acceptedListing`).
+    return { ...(listing ?? {}), ...acceptedListing(listing, manifest.docs) };
   }
 
   /**
@@ -2233,6 +2243,9 @@ export function createSyncRuntime(
         designRoot: ctx.paths.designRoot,
         designRel: ctx.paths.designRel,
       });
+      // DDR-242 — idempotent; also covers a runtime cycled after boot (a
+      // project linked from the cloud panel) whose tree gained a v1 board.
+      migrateAnnotationsV2({ designRoot: ctx.paths.designRoot });
     }
 
     const scan = opts.canvases ? { canvases: opts.canvases, tsxCount: 0 } : await scanCanvases(ctx);
@@ -2373,18 +2386,23 @@ export function createSyncRuntime(
       path.sep,
       { ...pathOpts, realpath: realpathOfDeepestExisting, pathFor: manifestPathFor }
     );
-    const pullNote = describeRemoteDiff(remoteDiff);
+    // Named as it will actually happen: a canvas the project deleted is listed
+    // for a tick after its tombstone and is not pulled, so it is not announced.
+    const pullNote = describeRemoteDiff({
+      ...remoteDiff,
+      hubOnly: remoteDiff.hubOnly.filter((d) => !tombstoned.has(slugFromDocName(d.name) ?? '')),
+    });
     if (pullNote) console.log(`[sync] ${pullNote}`);
     /** Descriptor paths for one slug at one body path. The sidecar rules live
      *  here, once: `.meta.json`/`.css` are SIBLINGS of the body, while
-     *  `.annotations.svg` is keyed by the flat slug at the design root — the
+     *  `.annotations.json` is keyed by the flat slug at the design root — the
      *  asymmetry `workspace-files.mjs` documents, and which moving the body
      *  must not quietly change. */
     const descriptorFor = (slug: string, bodyAbs: string): CanvasDescriptor => ({
       slug,
       html: bodyAbs,
       comments: path.join(ctx.paths.commentsDir, `${slug}.json`),
-      annotations: path.join(ctx.paths.designRoot, `${slug}.annotations.svg`),
+      annotations: path.join(ctx.paths.designRoot, `${slug}.annotations.json`),
       meta: bodyAbs.replace(/\.tsx$/i, '.meta.json'),
       css: bodyAbs.replace(/\.tsx$/i, '.css'),
     });
@@ -2722,6 +2740,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 ----
@@ -3123,6 +3146,7 @@ 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),
@@ -3142,6 +3166,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);
@@ -3755,6 +3780,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);
@@ -3868,21 +3901,23 @@ export function createSyncRuntime(
               const agentOrigin = agent.origin;
               const slug = canvas.slug;
               const provComments = provider.document.getArray(Y_TYPES.comments);
-              const provAnn = provider.document.getMap(Y_TYPES.annotations);
+              // DDR-242 — the annotations replica: relay the board, the room
+              // diffs it per element (writeReplica), so only changes cross.
+              const provAnn = provider.document.getMap(REPLICA_TYPE);
               const onComments = (_e: unknown, tx: { origin: unknown }) => {
                 if (tx.origin === agentOrigin) return;
                 reg.syncRoomFromComments?.(slug, provComments.toArray());
               };
               const onAnn = (_e: unknown, tx: { origin: unknown }) => {
                 if (tx.origin === agentOrigin) return;
-                const svg = provAnn.get('svg');
-                if (typeof svg === 'string') reg.syncRoomFromAnnotations?.(slug, svg);
+                const board = replicaBoardText(provider.document);
+                if (board !== null) reg.syncRoomFromAnnotations?.(slug, board);
               };
               provComments.observe(onComments);
-              provAnn.observe(onAnn);
+              provAnn.observeDeep(onAnn);
               noteDetach(statusDetaches, canvas.slug, () => {
                 provComments.unobserve(onComments);
-                provAnn.unobserve(onAnn);
+                provAnn.unobserveDeep(onAnn);
               });
             }
           },
@@ -4622,6 +4657,17 @@ export function createSyncRuntime(
       void hubCapabilities({ hubUrl: linkedHub.url, signal: fileEventsProbe.signal })
         .then((caps) => {
           if (stopped) return;
+          // DDR-242 — a hub that predates the annotations-v2 model still keeps
+          // boards as SVG: its workspace checkout and kernel would not carry
+          // this studio's `.annotations.json` edits. Say so loudly; the
+          // annotations themselves stay safe (a v1 hub never writes the v2
+          // replica, and this studio never reads its SVG as authoritative).
+          if (caps !== null && !hasAnnotationsV2(caps)) {
+            console.warn(
+              `[sync] ${linkedHub.url} does not advertise annotations-v2 — update the hub; ` +
+                'whiteboard edits will not reach its checkout until it is'
+            );
+          }
           if (!hasLedger(caps)) {
             // No journal on this hub ⇒ the legacy client carries the upward
             // lane, exactly as the pre-v2 desktop did (Open decision 4).
@@ -4936,6 +4982,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;
@@ -5318,7 +5377,7 @@ async function walk(
       slug,
       html: abs,
       comments: path.join(commentsDir, `${slug}.json`),
-      annotations: path.join(designRoot, `${slug}.annotations.svg`),
+      annotations: path.join(designRoot, `${slug}.annotations.json`),
       // The `.meta.json` sidecar sits next to the body: `Foo.tsx` → `Foo.meta.json`.
       meta: abs.replace(/\.(tsx|html)$/i, '.meta.json'),
       // The `.css` sibling: `Foo.tsx` → `Foo.css` (absent for inline-CSS canvases).

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

@@ -212,6 +212,11 @@ export async function hubCapabilities(opts: {
   }
 }
 
+/** Does this hub keep annotations as the v2 element model (DDR-242)? */
+export function hasAnnotationsV2(capabilities: string[] | null): boolean {
+  return Array.isArray(capabilities) && capabilities.includes('annotations-v2');
+}
+
 /** Does this hub carry the journal file plane? */
 export function hasLedger(capabilities: string[] | null): boolean {
   return Array.isArray(capabilities) && capabilities.includes('ledger');

package/apps/studio/sync/limits.ts

@@ -15,8 +15,13 @@
 export const MAX_HTML_BYTES = 4 * 1024 * 1024;
 /** `_comments/<slug>.json`, serialized. */
 export const MAX_COMMENTS_BYTES = 1 * 1024 * 1024;
-/** `<slug>.annotations.svg`. */
-export const MAX_ANNOTATIONS_BYTES = 1 * 1024 * 1024;
+/**
+ * `<slug>.annotations.json` (DDR-242). Must equal `MAX_BOARD_BYTES` in
+ * annotations/constants.ts — annotations-v2-replica.test.ts pins the pair.
+ * Raised from v1's 1 MB: the v1 cap bit at ~3.7k elements, and the v2 board is
+ * ~3× more compact, so 4 MB is ≈ 20k typical elements (the element-count cap).
+ */
+export const MAX_ANNOTATIONS_BYTES = 4 * 1024 * 1024;
 /** The shared subset of a canvas `.meta.json`. */
 export const MAX_META_BYTES = 1 * 1024 * 1024;
 /** The canvas's sibling stylesheet. */