@1agh/maude 0.60.3 → 0.60.5

package/apps/studio/sync/asset-pull.ts

@@ -0,0 +1,210 @@
+// Cell→desktop asset pull — the downward half of the asset lane.
+//
+// THE BUG THIS EXISTS TO END. `asset-push.ts` is, in its own words, a
+// "Desktop→cell asset push", and the cell never runs it at all (the
+// `cellPairing` guard on `scheduleAssetSweep`). That is correct as designed —
+// the desktop is the peer that HAS the bytes — but nothing was ever built for
+// the other direction, so an image dropped onto a canvas IN THE BROWSER had its
+// bytes stranded on the cell forever.
+//
+// The text lanes hid how total that was. `<slug>.annotations.svg` syncs, so the
+// image stroke arrives on the desktop with its position, its size and its alt
+// text intact, and renders as a broken-image glyph: a canvas that is visibly
+// there and permanently empty. Confirmed on alligators — `assets/c0fa9c7f.png`
+// referenced by a synced annotation, absent from every local disk.
+//
+// WHAT IT WANTS IS DERIVED LOCALLY, NOT DICTATED. The hub is untrusted to peers
+// (DDR-054), so this never asks "what should I download" — it reads the files
+// this peer ALREADY HOLDS, collects the `assets/…` references in them, and asks
+// only for the ones missing from its own disk. A hostile hub cannot use this to
+// place a file nobody referenced.
+//
+// AND THE REFERENCES THEMSELVES ARE UNTRUSTED. An annotation can have arrived
+// from the hub, so a name found inside one is hub-controlled input. Every
+// candidate is re-validated against `ASSET_NAME_RE` before it becomes a path:
+// one segment, no scheme, no traversal, allowlisted extension — the same shape
+// `ASSET_IMAGE_HREF_RE` enforces on the way in.
+//
+// MISSING-ONLY AND IDEMPOTENT, so a whole machine costs one directory scan and
+// no requests, and a failed pull is retried for free on the next pass.
+
+import {
+  type Dirent,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import path from 'node:path';
+
+/** How long to wait for one asset. Generous — these are photographs and clips. */
+const GET_TIMEOUT_MS = 120_000;
+
+/** Refuse an implausible body outright rather than streaming it to disk. */
+const MAX_PULL_BYTES = 512 * 1024 * 1024;
+
+/**
+ * How many assets one pass will fetch.
+ *
+ * The same reasoning as the pull lane's `MAX_PULLS_PER_POLL`: every accepted
+ * name becomes a real file in the design root, and this runs on a schedule for
+ * the life of the process. A cap makes one answer unable to land thousands, and
+ * the remainder is simply picked up by the next pass.
+ */
+const MAX_PULLS_PER_PASS = 200;
+
+/**
+ * A content-addressed asset name: ONE segment, no traversal, known extension.
+ *
+ * Deliberately the same shape as the annotation sanitizer's
+ * `ASSET_IMAGE_HREF_RE`, widened to the media + font types the push lane already
+ * carries. Anchored, so `assets/../../etc/passwd` and `assets/x.png?../` are
+ * both refused before a path is built from them.
+ */
+const ASSET_NAME_RE =
+  /^[A-Za-z0-9._-]+\.(?:png|jpe?g|webp|gif|avif|svg|mp4|webm|mov|m4v|mp3|wav|m4a|aac|ogg|woff2?|ttf|otf)$/i;
+
+/** Every `assets/<name>` reference in a blob of text. */
+const REFERENCE_RE = /assets\/([A-Za-z0-9._-]+\.[A-Za-z0-9]+)/g;
+
+/** Files worth reading for references — the canvas and its sidecars. */
+const SCANNED_EXT = /\.(?:annotations\.svg|tsx|jsx|css|meta\.json)$/i;
+
+/** Runtime directories that never hold a live reference (DDR-115). */
+const SKIPPED_DIRS = new Set(['_trash', '_history', '_untrusted', '_smoke', 'node_modules']);
+
+export interface AssetPullResult {
+  pulled: string[];
+  /** Referenced, missing, and the hub could not supply it. */
+  failed: { name: string; reason: string }[];
+  /** Referenced and already on disk — the steady state. */
+  present: number;
+}
+
+/**
+ * Collect every `assets/<name>` this project references, validated.
+ *
+ * Reads the canvas bodies and their sidecars. A reference that does not survive
+ * `ASSET_NAME_RE` is dropped silently: it is either not an asset or not a name
+ * this peer will ever turn into a path.
+ */
+export function referencedAssets(designRoot: string): string[] {
+  const out = new Set<string>();
+  const walk = (dir: string, depth: number): void => {
+    if (depth > 8) return;
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        // `assets/` itself is the destination, not a source of references.
+        if (SKIPPED_DIRS.has(entry.name) || entry.name === 'assets') continue;
+        walk(abs, depth + 1);
+        continue;
+      }
+      if (!SCANNED_EXT.test(entry.name)) continue;
+      let text: string;
+      try {
+        text = readFileSync(abs, 'utf8');
+      } catch {
+        continue;
+      }
+      for (const match of text.matchAll(REFERENCE_RE)) {
+        const name = match[1];
+        if (name && ASSET_NAME_RE.test(name)) out.add(name);
+      }
+    }
+  };
+  walk(designRoot, 0);
+  return [...out].sort();
+}
+
+/**
+ * Fetch the referenced assets this machine does not have.
+ *
+ * Sequential on purpose, exactly like `pushAssets`: these run to videos, and
+ * saturating a link the sync is also using would starve the handshakes. Never
+ * throws — a failure is a line in `failed` and a free retry next pass.
+ */
+export async function pullAssets(opts: {
+  designRoot: string;
+  hubUrl: string;
+  /** Read at call time — silent renewal swaps the credential in place. */
+  token: () => string;
+  fetchImpl?: typeof fetch;
+  log?: Pick<Console, 'log' | 'warn'>;
+}): Promise<AssetPullResult> {
+  const { designRoot, hubUrl } = opts;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const log = opts.log ?? console;
+  const base = hubUrl.replace(/\/+$/, '');
+  const assetsDir = path.join(designRoot, 'assets');
+  const out: AssetPullResult = { pulled: [], failed: [], present: 0 };
+
+  const wanted: string[] = [];
+  for (const name of referencedAssets(designRoot)) {
+    if (existsSync(path.join(assetsDir, name))) out.present += 1;
+    else wanted.push(name);
+  }
+  if (wanted.length === 0) return out;
+
+  // A peer that has never held an asset has no `assets/` yet — the first pull
+  // is exactly when that is true.
+  try {
+    mkdirSync(assetsDir, { recursive: true });
+  } catch (err) {
+    log.warn(`[sync/assets] cannot create ${assetsDir}: ${(err as Error).message}`);
+    return out;
+  }
+
+  const batch = wanted.slice(0, MAX_PULLS_PER_PASS);
+  if (batch.length < wanted.length) {
+    // Named loudly, for the same reason the pull lane names its cap: a silent
+    // truncation reads as "sync is broken" with no cause.
+    log.warn(
+      `[sync/assets] ${wanted.length} referenced assets are missing here; taking ${batch.length} this pass.`
+    );
+  }
+
+  for (const name of batch) {
+    try {
+      const res = await fetchImpl(`${base}/assets/${encodeURIComponent(name)}`, {
+        headers: { authorization: `Bearer ${opts.token()}` },
+        signal: AbortSignal.timeout(GET_TIMEOUT_MS),
+      });
+      if (!res.ok) {
+        // A 404 is ordinary: the other peer has not pushed it yet. It costs a
+        // line here and is retried next pass, when it may well be there.
+        out.failed.push({ name, reason: `HTTP ${res.status}` });
+        continue;
+      }
+      const body = new Uint8Array(await res.arrayBuffer());
+      if (body.byteLength === 0 || body.byteLength > MAX_PULL_BYTES) {
+        out.failed.push({ name, reason: `implausible size (${body.byteLength} B)` });
+        continue;
+      }
+      // Write beside the target and rename, so a reader (the dev server serving
+      // this very path) never sees a half-written image.
+      const finalAbs = path.join(assetsDir, name);
+      const tmpAbs = `${finalAbs}.part`;
+      writeFileSync(tmpAbs, body);
+      renameSync(tmpAbs, finalAbs);
+      out.pulled.push(name);
+    } catch (err) {
+      out.failed.push({ name, reason: (err as Error).message });
+    }
+  }
+
+  if (out.pulled.length > 0) {
+    log.log(
+      `[sync/assets] pulled ${out.pulled.length} asset(s) down from the project (${out.failed.length} still missing).`
+    );
+  }
+  return out;
+}

package/apps/studio/sync/asset-push.ts

@@ -1,66 +1,42 @@
-// Desktop→cell asset push — DDR-217 + the 2026-08-11 addendum (fix 6 of the
-// 2026-08-10 sync RCA, completed).
+// Desktop→cell file push — DDR-217, the 2026-08-11 addendum, and the
+// feature-sync-file-plane widening (binding decision
+// maude/sync-two-plane-manifest-architecture).
 //
 // The sync lanes are text-only (`html`/`css`/`meta`/`syncMeta`), so a
-// desktop-linked project's binary assets never reached the cell — the grey
-// boxes. The desktop is the one peer that HAS the bytes and already holds an
-// authenticated channel to the hub, so it pushes them. There are TWO asset
-// classes, served two different ways, so they push to two different routes:
+// desktop-linked project's other files never reached the cell — first seen as
+// grey boxes (binary assets), then as a whole design system that never
+// arrived (the 103-file RCA). The desktop is the one peer that HAS the bytes
+// and already holds an authenticated channel to the hub, so it pushes them.
+//
+// MEMBERSHIP IS THE CLASSIFIER'S (`file-membership.ts`) — the same positive
+// enumeration the downward plane and the hub's own admission use: inert
+// media, companion text (`brand.css`, `README.md`), and code modules
+// (`_brand-css.ts`), with `canvas-owned` (the CRDT lanes') and `never`
+// (config, runtime state, everything unclassified) excluded. The old
+// assets-dir walk + binary-extension pair lived here; it is subsumed, not
+// joined, by the classifier.
+//
+// TWO ROUTES REMAIN, split by PATH (`routeFor`):
 //
 //   1. TOP-LEVEL content-addressed uploads (`<designRoot>/assets/<sha8>.<ext>`)
 //      — referenced by the `/assets/<key>` shortcut, served on the cloud from
 //      the BUCKET proxy. Push → `PUT /assets/<key>` (bucket + checkout mirror).
-//   2. DS / BRAND assets (`<designRoot>/system/<ds>/assets/logos/x.svg`, fonts,
-//      photos) — referenced by their FULL designRoot path
-//      (`/.design/system/<ds>/assets/…`) and served from the CHECKOUT by the
-//      studio child, never the bucket. The original fix only swept class 1, so
-//      these stayed grey (alligators has 93 of them). Push → `PUT
-//      /_asset-file/<designRoot-rel>` (checkout only, no bucket).
+//   2. EVERYTHING ELSE (DS assets, stylesheets, docs, shared modules) —
+//      referenced by designRoot path, served from the CHECKOUT. Push →
+//      `PUT /_asset-file/<designRoot-rel>` (classifier-gated on the hub too).
 //
-// Both are HEAD-first (skip what the cloud already holds) and streamed. The
+// Both are probe-first (skip what the cloud already holds) and streamed. The
 // HUB's validation is the authoritative gate at each trust boundary; the
 // filters here are the courtesy layer that keeps junk off the wire.
 
-import { type Dirent, readdirSync, statSync } from 'node:fs';
+import { type Dirent, readdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 
-/** One path segment charset — matches the hub's component regexes. */
-const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/;
+import { type CanvasGroupLike, classifyProjectFile, isFilePlaneClass } from './file-membership.ts';
 
-/** Max designRoot-relative depth (matches the hub's 8-segment cap). */
+/** Max designRoot-relative depth (matches the classifier's 8-segment cap). */
 const MAX_SEGMENTS = 8;
 
-/** Max relative-path length (matches the hub's 512 cap). */
-const MAX_REL_LEN = 512;
-
-/**
- * The binary asset extensions that actually render — images, fonts, media.
- * Deliberately NOT `.json`/`.meta.json`/`.photo.json`/`.tsx`/`.css`: a
- * `.photo.json` sidecar is edit metadata, not a served asset, and the checkout
- * route refuses non-asset extensions anyway (so pushing them would just waste
- * the wire and 400). Case-insensitive — a DS ships `…P1020428.JPG`.
- */
-const ASSET_EXTS = new Set([
-  'png',
-  'jpg',
-  'jpeg',
-  'gif',
-  'webp',
-  'avif',
-  'svg',
-  'mp4',
-  'webm',
-  'mov',
-  'mp3',
-  'wav',
-  'm4a',
-  'ogg',
-  'woff2',
-  'woff',
-  'ttf',
-  'otf',
-]);
-
 /** A 2 GB file in an assets dir is a mistake — don't move it silently. */
 const MAX_PUSH_BYTES = 512 * 1024 * 1024;
 
@@ -181,51 +157,63 @@ export function putTimeoutMs(bytes: number): number {
  *  final emit always go out regardless. */
 const PROGRESS_INTERVAL_MS = 200;
 
-function extOf(name: string): string {
-  const dot = name.lastIndexOf('.');
-  return dot < 0 ? '' : name.slice(dot + 1).toLowerCase();
-}
-
 /**
- * Every pushable binary asset under designRoot, as a designRoot-relative path.
- * Walks into any directory named `assets` at any level (top-level `assets/`,
- * `system/<ds>/assets/`, …) and collects the asset-extension files inside it.
- * Skips runtime-state (`_*`), `.git`, `node_modules`. Missing root → [].
+ * Canvas groups + the file-plane flag from `<designRoot>/config.json`. Read
+ * here rather than threaded through the worker protocol: the sweep runs
+ * out-of-process, and the config is the ONE source both processes share.
  */
+function readProjectConfig(designRoot: string): {
+  canvasGroups?: readonly CanvasGroupLike[];
+  syncFiles: boolean;
+} {
+  let parsed: { canvasGroups?: unknown; linkedHub?: { syncFiles?: unknown } } | null = null;
+  try {
+    parsed = JSON.parse(readFileSync(path.join(designRoot, 'config.json'), 'utf8'));
+  } catch {
+    parsed = null;
+  }
+  return {
+    canvasGroups: Array.isArray(parsed?.canvasGroups)
+      ? (parsed.canvasGroups as CanvasGroupLike[])
+      : undefined,
+    syncFiles: process.env.MAUDE_SYNC_FILES === '1' || parsed?.linkedHub?.syncFiles === true,
+  };
+}
+
 /**
  * Would `listPushableAssets` have returned this designRoot-relative path?
  *
  * The cheap, no-disk half of the same rule, for deciding whether an `fs:any`
- * event is worth a sweep. It must not drift from the walk below — the two are
- * kept adjacent for that reason — but it is deliberately CONSERVATIVE where it
- * cannot be sure: a `false` here means an asset silently never uploads until
- * the next boot, which is the bug this predicate exists to end, so anything
- * shaped like an asset under an `assets/` directory answers true and lets the
- * sweep itself decide.
+ * event is worth a sweep. Classifier-judged, with NO tree knowledge on
+ * purpose: this is a scheduling hint, and the conservative direction is
+ * answering true — a group `.css` whose sibling status is unknowable here
+ * answers true and lets the sweep itself decide with the disk in hand. A
+ * `false` means a file silently never uploads until the next boot, which is
+ * the bug this predicate exists to end.
  */
-export function isPushableAssetRel(rel: string): boolean {
+export function isPushableAssetRel(
+  rel: string,
+  canvasGroups?: readonly CanvasGroupLike[]
+): boolean {
   if (typeof rel !== 'string' || !rel) return false;
   const norm = rel.replace(/\\/g, '/');
-  if (norm.length > MAX_REL_LEN) return false;
-  const parts = norm.split('/');
-  if (parts.length < 2 || parts.length > MAX_SEGMENTS) return false;
-  let insideAssets = false;
-  for (let i = 0; i < parts.length - 1; i++) {
-    const seg = parts[i];
-    if (seg.startsWith('_') || seg === '.git' || seg === 'node_modules') return false;
-    if (!SEGMENT.test(seg)) return false;
-    if (seg === 'assets') insideAssets = true;
-  }
-  if (!insideAssets) return false;
-  const name = parts[parts.length - 1];
-  if (name.startsWith('_') || !SEGMENT.test(name)) return false;
-  return ASSET_EXTS.has(extOf(name));
+  return isFilePlaneClass(classifyProjectFile(norm, { canvasGroups }));
 }
 
-export function listPushableAssets(designRoot: string): string[] {
-  const out: string[] = [];
-  // Walk the tree; once inside an `assets` dir, collect asset files below it.
-  const walk = (dir: string, rel: string, insideAssets: boolean): void => {
+/**
+ * Every pushable project file under designRoot, as a designRoot-relative
+ * path: the classifier's three flowing classes, judged against the walked
+ * snapshot (so a canvas's sibling css is recognized as canvas-owned and
+ * stays home). Skips runtime-state directories (`_*`), dotfiles,
+ * `node_modules`; refuses oversized files. Missing root → [].
+ */
+export function listPushableAssets(
+  designRoot: string,
+  opts: { canvasGroups?: readonly CanvasGroupLike[]; syncFiles?: boolean } = {}
+): string[] {
+  const found: string[] = [];
+  const walk = (dir: string, rel: string, depth: number): void => {
+    if (depth > MAX_SEGMENTS) return;
     let entries: Dirent[];
     try {
       entries = readdirSync(dir, { withFileTypes: true });
@@ -234,26 +222,43 @@ export function listPushableAssets(designRoot: string): string[] {
     }
     for (const entry of entries) {
       const name = entry.name;
-      if (name.startsWith('_') || name === '.git' || name === 'node_modules') continue;
-      if (!SEGMENT.test(name)) continue; // dotfiles + odd charset
+      if (name.startsWith('.') || name === 'node_modules') continue;
+      if (name.startsWith('_') && entry.isDirectory()) continue;
       const childRel = rel ? `${rel}/${name}` : name;
-      if (childRel.length > MAX_REL_LEN || childRel.split('/').length > MAX_SEGMENTS) continue;
       if (entry.isDirectory()) {
-        walk(path.join(dir, name), childRel, insideAssets || name === 'assets');
-      } else if (entry.isFile()) {
-        if (!insideAssets) continue; // only files under some assets/ dir
-        if (!ASSET_EXTS.has(extOf(name))) continue;
-        try {
-          if (statSync(path.join(dir, name)).size > MAX_PUSH_BYTES) continue;
-        } catch {
-          continue;
-        }
-        out.push(childRel);
+        walk(path.join(dir, name), childRel, depth + 1);
+        continue;
       }
+      if (!entry.isFile()) continue; // symlinks stay home
+      try {
+        if (statSync(path.join(dir, name)).size > MAX_PUSH_BYTES) continue;
+      } catch {
+        continue;
+      }
+      found.push(childRel);
     }
   };
-  walk(designRoot, '', false);
-  return out.sort();
+  walk(designRoot, '', 1);
+
+  const cfg = readProjectConfig(designRoot);
+  const syncFiles = opts.syncFiles ?? cfg.syncFiles;
+  const fileSet = new Set(found);
+  const clsOpts = {
+    canvasGroups: opts.canvasGroups ?? cfg.canvasGroups,
+    hasFile: (r: string) => fileSet.has(r),
+  };
+  return found
+    .filter((rel) => {
+      const cls = classifyProjectFile(rel, clsOpts);
+      if (!isFilePlaneClass(cls)) return false;
+      if (syncFiles) return true;
+      // Flag OFF ⇒ today's DDR-217 lane, unchanged in reach: binary media
+      // under some `assets/` directory. The file plane (companion text, code
+      // modules, media outside assets/) waits for `linkedHub.syncFiles` /
+      // MAUDE_SYNC_FILES=1 — the flag gates ONLY the new plane.
+      return cls === 'inert-media' && rel.split('/').slice(0, -1).includes('assets');
+    })
+    .sort();
 }
 
 /** Where a given asset pushes: the bucket-backed route (top-level `assets/`) or
@@ -408,6 +413,11 @@ export async function pushAssets(opts: {
   hubUrl: string;
   /** Read at call time — silent renewal swaps the credential in place. */
   token: () => string;
+  /** Declared canvas groups; absent ⇒ read from `<designRoot>/config.json`
+   *  (the out-of-process worker's path — see `readProjectConfig`). */
+  canvasGroups?: readonly CanvasGroupLike[];
+  /** The file-plane flag; absent ⇒ read from config/env the same way. */
+  syncFiles?: boolean;
   fetchImpl?: typeof fetch;
   log?: Pick<Console, 'log' | 'warn'>;
   /** feature-sync-progress-modal — incremental progress (throttled; failures
@@ -436,7 +446,10 @@ export async function pushAssets(opts: {
   const base = hubUrl.replace(/\/+$/, '');
   const out: AssetPushResult = { pushed: [], skipped: 0, failed: [] };
 
-  const assets = listPushableAssets(designRoot);
+  const assets = listPushableAssets(designRoot, {
+    canvasGroups: opts.canvasGroups,
+    syncFiles: opts.syncFiles,
+  });
   // -Infinity seeds the throttle open, so the first emit always passes.
   let lastEmit = -Infinity;
   const emitProgress = (active: string | null, finished: boolean, force = false): void => {

package/apps/studio/sync/codec.ts

@@ -186,6 +186,25 @@ export function annotationsFromDoc(doc: Y.Doc): string | null {
   return typeof svg === 'string' ? svg : null;
 }
 
+/**
+ * True when an annotations value carries ZERO strokes: null, `''`, or the bare
+ * serialized wrapper `<svg …></svg>` with no child elements (what
+ * `strokesToSvg([])` emits — 72 bytes, constant across peers).
+ *
+ * This distinction is load-bearing for cold start (the 2026-08-14 annotations
+ * eraser): the wrapper is a non-empty STRING, so every `!== ''` emptiness
+ * guard let a stale hub wrapper overwrite a peer's real strokes — and with the
+ * strokes went the `assets/<sha8>` references `asset-pull` scans, so freshly
+ * dropped images never crossed machines. Live delete-all still materializes
+ * the wrapper through `writeAnnotationsIfChanged` (deletes must propagate);
+ * only COLD-START decisions treat it as emptiness.
+ */
+export function isEmptyAnnotationsSvg(svg: string | null): boolean {
+  if (svg === null) return true;
+  if (svg.trim() === '') return true;
+  return /^\s*<svg\b[^>]*>\s*<\/svg>\s*$/i.test(svg);
+}
+
 export function applyAnnotationsToDoc(doc: Y.Doc, next: string | null, origin?: unknown): boolean {
   if (next !== null && byteLengthUtf8(next) > MAX_ANNOTATIONS_BYTES) {
     console.warn(
@@ -344,6 +363,34 @@ export function bodyEditAtFromDoc(doc: Y.Doc): number | null {
   return typeof v === 'number' && Number.isFinite(v) ? v : null;
 }
 
+/**
+ * Stamp `syncMeta.annotationsEditAt` — the annotations lane's own newest-wins
+ * timestamp (extends DDR-102's `bodyEditAt` per-lane). Call in the SAME
+ * transaction + origin as every local→doc annotations apply (agent applyFromFs
+ * annotations branch, cold-start local-wins seed, adopt) so peers receive ONE
+ * update. Before this stamp existed, cold start resolved annotations by the
+ * BODY winner — but annotation edits don't move the body's edit time, so a
+ * hub with a newer body and a stale (empty) annotations lane erased newer
+ * local strokes (the 2026-08-14 annotations eraser).
+ *
+ * `nowMs` override: cold-start seeding passes the local FILE's mtime so stale
+ * content can't claim apply-time freshness.
+ */
+export function stampAnnotationsEdit(doc: Y.Doc, origin?: unknown, nowMs?: number): void {
+  const map = doc.getMap<unknown>(Y_SYNC_TYPES.syncMeta);
+  doc.transact(() => {
+    map.set('annotationsEditAt', nowMs ?? Date.now());
+  }, origin);
+}
+
+/** The doc-side annotations-edit stamp, or null when no peer ever stamped
+ *  (pre-annotationsEditAt docs → callers fall back to the body-winner
+ *  coupling, interop-safe). */
+export function annotationsEditAtFromDoc(doc: Y.Doc): number | null {
+  const v = doc.getMap<unknown>(Y_SYNC_TYPES.syncMeta).get('annotationsEditAt');
+  return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+
 /**
  * Record THIS doc's clientID as the seeder in `syncMeta.seededBy` (F1). Call it
  * in the SAME transaction + origin as a `seed-local-up` body apply. The value is

package/apps/studio/sync/cold-start.ts

@@ -196,3 +196,99 @@ export function decideColdStart(input: ColdStartInput): ColdStartDecision {
         : 'diverged — timestamps tied, falling back to hub-wins (recoverable: both sides snapshotted)',
   };
 }
+
+/* ------------------------------------------------- annotations (per-lane) */
+
+export interface AnnotationsColdStartInput {
+  /** Local `.annotations.svg` content, or null when the file doesn't exist. */
+  local: string | null;
+  /** Annotations currently held by the doc (`''` when the lane is unset). */
+  doc: string;
+  /** True when the value carries zero strokes — callers pass
+   *  `isEmptyAnnotationsSvg` (codec.ts) so this table stays Y-free. */
+  isEmpty: (svg: string | null) => boolean;
+  /** Local annotations file mtime (ms epoch), or null when unavailable. */
+  localMtimeMs: number | null;
+  /** Doc-side syncMeta.annotationsEditAt stamp, or null when no peer ever
+   *  stamped (pre-stamp interop). */
+  docEditAtMs: number | null;
+  /** The body lane's resolved winner — the legacy coupling, used only as the
+   *  fallback when both sides are non-empty and neither is stamped. */
+  bodyWinner: 'local' | 'hub';
+}
+
+export interface AnnotationsColdStartDecision {
+  winner: 'local' | 'hub' | 'none';
+  reason: string;
+}
+
+/**
+ * Per-lane cold-start resolution for annotations (extends DDR-102 to the
+ * annotations lane; the 2026-08-14 annotations eraser).
+ *
+ * Annotations used to blindly follow the body winner — but annotation edits
+ * don't move the body's edit time, so a hub with a newer body and a STALE
+ * (empty-wrapper) annotations lane erased newer local strokes on every cold
+ * start, and with the strokes went the `assets/<sha8>` references the asset
+ * pull scans. The one load-bearing rule here: **unstamped emptiness never
+ * beats content.** A STAMPED emptiness that is provably newer is a deliberate
+ * delete-all and is honored; everything else prefers the side with strokes.
+ */
+export function decideAnnotationsColdStart(
+  input: AnnotationsColdStartInput
+): AnnotationsColdStartDecision {
+  const { local, doc, isEmpty, localMtimeMs, docEditAtMs, bodyWinner } = input;
+  const localEmpty = isEmpty(local);
+  const docEmpty = isEmpty(doc === '' ? null : doc);
+
+  if (localEmpty && docEmpty) return { winner: 'none', reason: 'both sides empty' };
+
+  if (docEmpty && !localEmpty) {
+    // A stamped hub emptiness NEWER than the local file is a deliberate
+    // delete-all made while this peer was offline — honor it.
+    if (docEditAtMs !== null && localMtimeMs !== null && docEditAtMs > localMtimeMs) {
+      return {
+        winner: 'hub',
+        reason: `hub delete-all is newer than local strokes (annotationsEditAt ${new Date(docEditAtMs).toISOString()} > local mtime ${new Date(localMtimeMs).toISOString()})`,
+      };
+    }
+    return {
+      winner: 'local',
+      reason:
+        'hub annotations are empty but local has strokes — keeping local + seeding it up (unstamped emptiness never beats content)',
+    };
+  }
+
+  if (!docEmpty && localEmpty) {
+    // Symmetric: a local delete-all (empty wrapper on disk) newer than the
+    // doc's stamp is honored; an absent/stale local file materializes the hub.
+    if (
+      local !== null &&
+      localMtimeMs !== null &&
+      docEditAtMs !== null &&
+      localMtimeMs > docEditAtMs
+    ) {
+      return {
+        winner: 'local',
+        reason: `local delete-all is newer than hub strokes (local mtime ${new Date(localMtimeMs).toISOString()} > annotationsEditAt ${new Date(docEditAtMs).toISOString()})`,
+      };
+    }
+    return { winner: 'hub', reason: 'local annotations empty/absent — materializing hub strokes' };
+  }
+
+  // Both non-empty.
+  if (doc === local) return { winner: 'none', reason: 'both sides equal' };
+  if (docEditAtMs !== null && localMtimeMs !== null && docEditAtMs !== localMtimeMs) {
+    const winner = localMtimeMs > docEditAtMs ? 'local' : 'hub';
+    return {
+      winner,
+      reason: `diverged — newest wins: local mtime ${new Date(localMtimeMs).toISOString()} ${
+        winner === 'local' ? '>' : '<'
+      } doc annotationsEditAt ${new Date(docEditAtMs).toISOString()}`,
+    };
+  }
+  return {
+    winner: bodyWinner,
+    reason: `diverged — no per-lane stamp on one side, following the body winner (${bodyWinner})`,
+  };
+}