@1agh/maude 0.29.0 → 0.31.0

package/apps/studio/test/shared-doc-migrate.test.ts

@@ -12,7 +12,8 @@ import * as Y from 'yjs';
 
 import { createPersistence, Y_TYPES } from '../collab/persistence.ts';
 import type { Context } from '../context.ts';
-import { applyCommentsToDoc, applyHtmlToDoc } from '../sync/codec.ts';
+import { applyCommentsToDoc, applyCssToDoc, applyHtmlToDoc } from '../sync/codec.ts';
+import { hashBytes } from '../sync/echo-guard.ts';
 import { docIsEmpty, migrateSeed } from '../sync/migrate-seed.ts';
 
 let dir: string;
@@ -43,28 +44,28 @@ describe('docIsEmpty', () => {
 });
 
 describe('migrateSeed — adopt (hub was empty)', () => {
-  test('seeds an empty doc from local files and reports local-adopt', () => {
+  test('seeds an empty doc from local files and reports local-adopt', async () => {
     const p = paths();
     writeFileSync(p.html, '<main>local body</main>');
     writeFileSync(p.comments, JSON.stringify([{ id: 'c1', text: 'local' }]));
 
     const doc = new Y.Doc();
-    const result = migrateSeed({ slug: 's', doc, paths: p });
+    const result = await migrateSeed({ slug: 's', doc, paths: p });
 
     expect(result).toBe('local-adopt');
     expect(doc.getText('html').toString()).toBe('<main>local body</main>');
     expect(doc.getArray(Y_TYPES.comments).toArray()).toEqual([{ id: 'c1', text: 'local' }]);
   });
 
-  test('empty doc + no local files → "empty" (nothing to seed)', () => {
+  test('empty doc + no local files → "empty" (nothing to seed)', async () => {
     const doc = new Y.Doc();
-    expect(migrateSeed({ slug: 's', doc, paths: paths() })).toBe('empty');
+    expect(await migrateSeed({ slug: 's', doc, paths: paths() })).toBe('empty');
     expect(docIsEmpty(doc)).toBe(true);
   });
 });
 
 describe('migrateSeed — idempotent (no duplication on re-run)', () => {
-  test('adopting twice leaves comments un-duplicated', () => {
+  test('adopting twice leaves comments un-duplicated', async () => {
     const p = paths();
     writeFileSync(
       p.comments,
@@ -75,12 +76,12 @@ describe('migrateSeed — idempotent (no duplication on re-run)', () => {
     );
 
     const doc = new Y.Doc();
-    expect(migrateSeed({ slug: 's', doc, paths: p })).toBe('local-adopt');
+    expect(await migrateSeed({ slug: 's', doc, paths: p })).toBe('local-adopt');
     expect(doc.getArray(Y_TYPES.comments).length).toBe(2);
 
     // Second run (e.g. server restart): the doc is now non-empty → hub-wins
     // branch → no re-adopt → still exactly 2 comments, byte-identical.
-    expect(migrateSeed({ slug: 's', doc, paths: p })).toBe('hub-wins');
+    expect(await migrateSeed({ slug: 's', doc, paths: p })).toBe('hub-wins');
     expect(doc.getArray(Y_TYPES.comments).toArray()).toEqual([
       { id: 'c1', text: 'x' },
       { id: 'c2', text: 'y' },
@@ -123,7 +124,7 @@ describe('room file-seed disable (the other half of the Risk-1 fix)', () => {
 });
 
 describe('migrateSeed — hub-wins (the duplication trap avoided)', () => {
-  test('a doc already holding hub comments is NOT merged with the local file → no dup', () => {
+  test('a doc already holding hub comments is NOT merged with the local file → no dup', async () => {
     const p = paths();
     // Local file (e.g. copied via git) holds the SAME logical comment id…
     writeFileSync(p.comments, JSON.stringify([{ id: 'c1', text: 'from disk' }]));
@@ -132,14 +133,15 @@ describe('migrateSeed — hub-wins (the duplication trap avoided)', () => {
     const doc = new Y.Doc();
     applyCommentsToDoc(doc, [{ id: 'c1', text: 'from hub' }], 'hub');
 
-    const result = migrateSeed({ slug: 's', doc, paths: p });
+    const result = await migrateSeed({ slug: 's', doc, paths: p });
 
-    // Hub wins; the local file is NOT pushed as a second item — exactly ONE c1.
+    // Hub wins; the local file is NOT pushed as a second item — exactly ONE c1
+    // (DDR-102 id-union keeps the doc's version for a shared id).
     expect(result).toBe('hub-wins');
     expect(doc.getArray(Y_TYPES.comments).toArray()).toEqual([{ id: 'c1', text: 'from hub' }]);
   });
 
-  test('snapshots divergent local files to historyDir before the hub-wins overwrite', () => {
+  test('snapshots divergent local files to historyDir before the hub-wins overwrite', async () => {
     const p = paths();
     writeFileSync(p.html, '<main>LOCAL divergent</main>');
     writeFileSync(p.comments, JSON.stringify([{ id: 'local' }]));
@@ -148,12 +150,220 @@ describe('migrateSeed — hub-wins (the duplication trap avoided)', () => {
     applyHtmlToDoc(doc, '<main>HUB</main>', 'hub'); // doc holds hub state
 
     const historyDir = join(dir, '_history', 's');
-    const result = migrateSeed({ slug: 's', doc, paths: p, historyDir });
+    // DDR-102: this divergence (no journal, no doc stamp) resolves
+    // conflict-hub-wins — the legacy whole-set safety copy still happens.
+    const result = await migrateSeed({ slug: 's', doc, paths: p, historyDir });
 
-    expect(result).toBe('hub-wins');
+    expect(result).toBe('conflict-hub-wins');
     // The pre-migration snapshot captured the local files for rollback.
     const snapped = readdirSync(join(historyDir, 'pre-shared-doc-migration'));
     expect(snapped).toContain('screen.html');
     expect(snapped).toContain('screen.comments.json');
   });
 });
+
+// ---------------------------------------------------------------------------
+// DDR-102 — the shared-doc path consumes the same cold-start decision table:
+// journal-gated fast-forward, dual snapshot + newest-wins on divergence,
+// comments id-union.
+describe('migrateSeed — DDR-102 divergence matrix', () => {
+  function makeJournal(initial: Record<string, { bodyHash: string }> = {}) {
+    const entries = new Map(Object.entries(initial));
+    return {
+      get: (slug: string) => entries.get(slug) ?? null,
+      record: (slug: string, hashes: { bodyHash?: string; cssHash?: string }) => {
+        const prev = entries.get(slug);
+        entries.set(slug, { bodyHash: hashes.bodyHash ?? prev?.bodyHash ?? '' });
+      },
+      invalidateIfHubChanged: () => {},
+      flush: () => {},
+      stop: () => {},
+      size: () => entries.size,
+    };
+  }
+
+  test('journal match → fast-forward (hub keeps), no snapshot, no conflict', async () => {
+    const p = paths();
+    writeFileSync(p.html, '<main>synced-v1</main>');
+    const doc = new Y.Doc();
+    applyHtmlToDoc(doc, '<main>hub-v2</main>', 'hub');
+
+    const journal = makeJournal({ s: { bodyHash: hashBytes('<main>synced-v1</main>') } });
+    const snapshots: string[] = [];
+    const conflicts: unknown[] = [];
+    const result = await migrateSeed({
+      slug: 's',
+      doc,
+      paths: p,
+      journal,
+      snapshot: async (_c, reason) => {
+        snapshots.push(reason);
+        return 'ts';
+      },
+      onConflict: (info) => {
+        conflicts.push(info);
+      },
+    });
+
+    expect(result).toBe('hub-wins');
+    expect(doc.getText('html').toString()).toBe('<main>hub-v2</main>'); // doc untouched
+    expect(snapshots).toHaveLength(0);
+    expect(conflicts).toHaveLength(0);
+  });
+
+  test('diverged + local newer → conflict-local-wins: doc REBUILT from local in one MIGRATION tx', async () => {
+    const p = paths();
+    writeFileSync(p.html, '<main>local-newer</main>');
+    writeFileSync(p.css, '.local{}');
+    const doc = new Y.Doc();
+    doc.transact(() => {
+      applyHtmlToDoc(doc, '<main>hub-older</main>', 'hub');
+      applyCssToDoc(doc, '.hub{}', 'hub');
+      doc.getMap('syncMeta').set('bodyEditAt', Date.now() - 60_000);
+    });
+
+    const snapshots: Array<{ content: string; reason: string }> = [];
+    const conflicts: Array<{ winner?: string; snapshots?: { local?: string; hub?: string } }> = [];
+    const result = await migrateSeed({
+      slug: 's',
+      doc,
+      paths: p,
+      journal: makeJournal(),
+      snapshot: async (content, reason) => {
+        snapshots.push({ content, reason });
+        return `ts-${snapshots.length}`;
+      },
+      onConflict: (info) => {
+        conflicts.push(info);
+      },
+    });
+
+    expect(result).toBe('conflict-local-wins');
+    expect(doc.getText('html').toString()).toBe('<main>local-newer</main>');
+    // css follows the body winner.
+    expect(doc.getText('css').toString()).toBe('.local{}');
+    // Dual snapshot captured BOTH pre-resolution versions.
+    expect(snapshots.map((s) => s.reason)).toEqual(['pre-sync-local', 'pre-sync-hub']);
+    expect(snapshots[0].content).toBe('<main>local-newer</main>');
+    expect(snapshots[1].content).toBe('<main>hub-older</main>');
+    expect(conflicts[0].winner).toBe('local');
+    expect(conflicts[0].snapshots).toEqual({ local: 'ts-1', hub: 'ts-2' });
+  });
+
+  test('diverged + hub newer (stamp) → conflict-hub-wins: doc untouched', async () => {
+    const p = paths();
+    writeFileSync(p.html, '<main>local-older</main>');
+    const doc = new Y.Doc();
+    doc.transact(() => {
+      applyHtmlToDoc(doc, '<main>hub-newer</main>', 'hub');
+      doc.getMap('syncMeta').set('bodyEditAt', Date.now() + 60_000);
+    });
+
+    const conflicts: Array<{ winner?: string }> = [];
+    const result = await migrateSeed({
+      slug: 's',
+      doc,
+      paths: p,
+      journal: makeJournal(),
+      onConflict: (info) => {
+        conflicts.push(info);
+      },
+    });
+
+    expect(result).toBe('conflict-hub-wins');
+    expect(doc.getText('html').toString()).toBe('<main>hub-newer</main>');
+    expect(conflicts[0].winner).toBe('hub');
+  });
+
+  test('doc holds comments but NO body + local body → body-seed-up (gap closed)', async () => {
+    const p = paths();
+    writeFileSync(p.html, '<main>only-local-body</main>');
+    const doc = new Y.Doc();
+    doc.getArray(Y_TYPES.comments).push([{ id: 'h1' }]); // doc non-empty, body empty
+
+    const result = await migrateSeed({ slug: 's', doc, paths: p, journal: makeJournal() });
+
+    expect(result).toBe('body-seed-up');
+    expect(doc.getText('html').toString()).toBe('<main>only-local-body</main>');
+    // Hub comments survive untouched.
+    expect(doc.getArray(Y_TYPES.comments).toArray()).toEqual([{ id: 'h1' }]);
+  });
+
+  test('comments id-union: local-only comments survive a hub-wins cutover', async () => {
+    const p = paths();
+    writeFileSync(p.html, '<main>same</main>');
+    writeFileSync(
+      p.comments,
+      JSON.stringify([
+        { id: 'c1', text: 'shared' },
+        { id: 'c3', text: 'local-only' },
+      ])
+    );
+    const doc = new Y.Doc();
+    doc.transact(() => {
+      applyHtmlToDoc(doc, '<main>same</main>', 'hub');
+      applyCommentsToDoc(
+        doc,
+        [
+          { id: 'c1', text: 'shared (hub copy wins)' },
+          { id: 'c2', text: 'hub-only' },
+        ],
+        'hub'
+      );
+    });
+
+    const result = await migrateSeed({ slug: 's', doc, paths: p });
+
+    expect(result).toBe('hub-wins');
+    expect(doc.getArray(Y_TYPES.comments).toArray()).toEqual([
+      { id: 'c1', text: 'shared (hub copy wins)' },
+      { id: 'c2', text: 'hub-only' },
+      { id: 'c3', text: 'local-only' },
+    ]);
+  });
+});
+
+// DDR-102 fail-closed (security review F1) — the shared-doc path must also
+// refuse a hub-wins cutover when the local snapshot didn't land.
+describe('migrateSeed — fail-closed on snapshot failure (DDR-102 F1)', () => {
+  function makeJournal() {
+    const entries = new Map<string, { bodyHash: string }>();
+    return {
+      get: (slug: string) => entries.get(slug) ?? null,
+      record: (slug: string, h: { bodyHash?: string; cssHash?: string }) =>
+        entries.set(slug, { bodyHash: h.bodyHash ?? entries.get(slug)?.bodyHash ?? '' }),
+      invalidateIfHubChanged: () => {},
+      flush: () => {},
+      stop: () => {},
+      size: () => entries.size,
+    };
+  }
+
+  test('hub newer BUT local snapshot null → rebuild doc from local (no overwrite), conflict-local-wins', async () => {
+    const p = paths();
+    writeFileSync(p.html, '<main>local-work</main>');
+    const doc = new Y.Doc();
+    doc.transact(() => {
+      applyHtmlToDoc(doc, '<main>hub-stale</main>', 'hub');
+      doc.getMap('syncMeta').set('bodyEditAt', Date.now() + 60_000); // hub would win
+    });
+
+    const conflicts: Array<{ winner?: string; snapshotFailed?: boolean }> = [];
+    const result = await migrateSeed({
+      slug: 's',
+      doc,
+      paths: p,
+      journal: makeJournal(),
+      snapshot: async () => null, // _history write fails
+      onConflict: (info) => {
+        conflicts.push(info);
+      },
+    });
+
+    // Doc rebuilt from local → projection would write local back (no loss).
+    expect(result).toBe('conflict-local-wins');
+    expect(doc.getText('html').toString()).toBe('<main>local-work</main>');
+    expect(conflicts[0].winner).toBe('local');
+    expect(conflicts[0].snapshotFailed).toBe(true);
+  });
+});

package/apps/studio/test/sync-agent.test.ts

@@ -11,13 +11,13 @@
 // 100-event stress scenario from the plan without booting a real hub.
 
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import * as Y from 'yjs';
 
 import { type CanvasSyncAgent, createCanvasSyncAgent } from '../sync/agent.ts';
-import { applyHtmlToDoc, htmlFromDoc, Y_SYNC_TYPES } from '../sync/codec.ts';
+import { applyHtmlToDoc, htmlFromDoc } from '../sync/codec.ts';
 import { createEchoGuard, hashBytes } from '../sync/echo-guard.ts';
 import { createFsReader } from '../sync/fs-mirror.ts';
 
@@ -303,3 +303,273 @@ describe('CanvasSyncAgent — stress: 100 rapid disk writes converge with no ech
     expect(docUpdates).toBeGreaterThan(0);
   });
 });
+
+// ---------------------------------------------------------------------------
+// DDR-102 — cold-start conflict protocol (journal-gated fast-forward, dual
+// snapshot, newest-wins, comments id-union).
+describe('CanvasSyncAgent — DDR-102 cold-start conflict protocol', () => {
+  interface SnapCall {
+    content: string;
+    reason: string;
+  }
+
+  function makeJournal(initial: Record<string, { bodyHash: string }> = {}) {
+    const entries = new Map(Object.entries(initial));
+    const records: Array<{ slug: string; hashes: Record<string, string | undefined> }> = [];
+    return {
+      journal: {
+        get: (slug: string) => entries.get(slug) ?? null,
+        record: (slug: string, hashes: { bodyHash?: string; cssHash?: string }) => {
+          records.push({ slug, hashes });
+          const prev = entries.get(slug);
+          entries.set(slug, { bodyHash: hashes.bodyHash ?? prev?.bodyHash ?? '' });
+        },
+        invalidateIfHubChanged: () => {},
+        flush: () => {},
+        stop: () => {},
+        size: () => entries.size,
+      },
+      records,
+    };
+  }
+
+  function protocolAgent(extra: {
+    journal?: ReturnType<typeof makeJournal>['journal'];
+    snapshots?: SnapCall[];
+    conflicts?: unknown[];
+  }) {
+    const a = createCanvasSyncAgent({
+      slug: 'screen',
+      doc: docB,
+      paths: paths(),
+      echoGuard: createEchoGuard(),
+      flushMs: 0,
+      journal: extra.journal,
+      snapshot: extra.snapshots
+        ? async (content, reason) => {
+            extra.snapshots?.push({ content, reason });
+            return `ts-${extra.snapshots?.length}`;
+          }
+        : undefined,
+      onConflict: (info) => {
+        extra.conflicts?.push(info);
+      },
+    });
+    a.start();
+    return a;
+  }
+
+  test('journal match → silent fast-forward: hub overwrites disk, NO snapshot, NO conflict', async () => {
+    const { setHtml } = await import('node:fs').then(() => ({ setHtml: writeFileSync }));
+    setHtml(paths().html, '<button>synced-v1</button>');
+    applyHtmlToDoc(docA, '<button>hub-v2</button>');
+
+    const { journal } = makeJournal({
+      screen: { bodyHash: hashBytes('<button>synced-v1</button>') },
+    });
+    const snapshots: SnapCall[] = [];
+    const conflicts: unknown[] = [];
+    agent = protocolAgent({ journal, snapshots, conflicts });
+    await agent.reconcile();
+
+    expect(readFileSync(paths().html, 'utf8')).toBe('<button>hub-v2</button>');
+    expect(snapshots).toHaveLength(0);
+    expect(conflicts).toHaveLength(0);
+  });
+
+  test('diverged + local newer → local wins, BOTH sides snapshotted, conflict recorded', async () => {
+    writeFileSync(paths().html, '<button>local-newer</button>');
+    // Hub doc carries different body with an OLDER bodyEditAt stamp.
+    docA.transact(() => {
+      applyHtmlToDoc(docA, '<button>hub-older</button>');
+      docA.getMap('syncMeta').set('bodyEditAt', Date.now() - 60_000);
+    });
+
+    const { journal } = makeJournal(); // no entry → divergence
+    const snapshots: SnapCall[] = [];
+    const conflicts: Array<{ kind: string; winner?: string; snapshots?: object }> = [];
+    agent = protocolAgent({ journal, snapshots, conflicts });
+    await agent.reconcile();
+
+    // Local body survives on disk AND is pushed up to the hub.
+    expect(readFileSync(paths().html, 'utf8')).toBe('<button>local-newer</button>');
+    expect(htmlFromDoc(docA)).toBe('<button>local-newer</button>');
+    // Dual snapshot: local first, hub second.
+    expect(snapshots.map((s) => s.reason)).toEqual(['pre-sync-local', 'pre-sync-hub']);
+    expect(snapshots[0].content).toBe('<button>local-newer</button>');
+    expect(snapshots[1].content).toBe('<button>hub-older</button>');
+    // Conflict entry carries winner + snapshot refs.
+    expect(conflicts).toHaveLength(1);
+    expect(conflicts[0].kind).toBe('cold-start-diverged');
+    expect(conflicts[0].winner).toBe('local');
+    expect(conflicts[0].snapshots).toBeDefined();
+  });
+
+  test('diverged + hub newer → hub wins, both sides snapshotted', async () => {
+    writeFileSync(paths().html, '<button>local-older</button>');
+    docA.transact(() => {
+      applyHtmlToDoc(docA, '<button>hub-newer</button>');
+      docA.getMap('syncMeta').set('bodyEditAt', Date.now() + 60_000);
+    });
+
+    const { journal } = makeJournal();
+    const snapshots: SnapCall[] = [];
+    const conflicts: Array<{ winner?: string }> = [];
+    agent = protocolAgent({ journal, snapshots, conflicts });
+    await agent.reconcile();
+
+    expect(readFileSync(paths().html, 'utf8')).toBe('<button>hub-newer</button>');
+    expect(snapshots.map((s) => s.reason)).toEqual(['pre-sync-local', 'pre-sync-hub']);
+    expect(conflicts[0].winner).toBe('hub');
+  });
+
+  test('DDR-064 empty-hub guard is bit-identical: seed-local-up, no snapshot, no conflict', async () => {
+    writeFileSync(paths().html, '<button>real-canvas</button>');
+    // docA/docB empty — fresh hub.
+    const { journal } = makeJournal();
+    const snapshots: SnapCall[] = [];
+    const conflicts: unknown[] = [];
+    agent = protocolAgent({ journal, snapshots, conflicts });
+    await agent.reconcile();
+
+    expect(readFileSync(paths().html, 'utf8')).toBe('<button>real-canvas</button>');
+    expect(htmlFromDoc(docA)).toBe('<button>real-canvas</button>');
+    expect(snapshots).toHaveLength(0);
+    expect(conflicts).toHaveLength(0);
+  });
+
+  test('journal checkpoints: doc→disk flush and disk→doc apply both record', async () => {
+    const { journal, records } = makeJournal();
+    agent = createCanvasSyncAgent({
+      slug: 'screen',
+      doc: docB,
+      paths: paths(),
+      echoGuard: createEchoGuard(),
+      flushMs: 0,
+      journal,
+    });
+    agent.start();
+
+    // Hub edit → disk write → checkpoint.
+    applyHtmlToDoc(docA, '<button>from-hub</button>');
+    await agent.flush();
+    expect(records.some((r) => r.hashes.bodyHash === hashBytes('<button>from-hub</button>'))).toBe(
+      true
+    );
+
+    // Local edit → doc apply → checkpoint.
+    const bytes = new TextEncoder().encode('<button>from-disk</button>');
+    agent.applyFromFs({ path: paths().html, bytes, hash: hashBytes(bytes) });
+    expect(records.some((r) => r.hashes.bodyHash === hashBytes(bytes))).toBe(true);
+  });
+
+  test('comments id-union: doc order first, local-only appended, both sides converge', async () => {
+    // Local file has c1 + c3; hub doc has c1 + c2.
+    const localComments = [
+      { id: 'c1', body: 'shared' },
+      { id: 'c3', body: 'local-only' },
+    ];
+    mkdirSync(join(dir, '_comments'), { recursive: true });
+    writeFileSync(paths().comments, `${JSON.stringify(localComments, null, 2)}\n`);
+    docA.transact(() => {
+      docA.getArray('comments').push([
+        { id: 'c1', body: 'shared' },
+        { id: 'c2', body: 'hub-only' },
+      ]);
+    });
+
+    agent = protocolAgent({});
+    await agent.reconcile();
+
+    const expectUnion = [
+      { id: 'c1', body: 'shared' },
+      { id: 'c2', body: 'hub-only' },
+      { id: 'c3', body: 'local-only' },
+    ];
+    // Doc (and the peer) hold the union…
+    expect(docA.getArray('comments').toArray()).toEqual(expectUnion);
+    // …and the disk file was rewritten to the union too.
+    expect(JSON.parse(readFileSync(paths().comments, 'utf8'))).toEqual(expectUnion);
+  });
+
+  test('comments union with empty hub doc keeps + pushes local comments', async () => {
+    const localComments = [{ id: 'c9', body: 'only-local' }];
+    mkdirSync(join(dir, '_comments'), { recursive: true });
+    writeFileSync(paths().comments, `${JSON.stringify(localComments, null, 2)}\n`);
+
+    agent = protocolAgent({});
+    await agent.reconcile();
+
+    expect(docA.getArray('comments').toArray()).toEqual(localComments);
+    expect(JSON.parse(readFileSync(paths().comments, 'utf8'))).toEqual(localComments);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// DDR-102 fail-closed (security review F1): a hub-wins resolution must NEVER
+// overwrite local when the local snapshot didn't land — keep local + push up.
+describe('CanvasSyncAgent — fail-closed on snapshot failure (DDR-102 F1)', () => {
+  function failClosedAgent(
+    snapshotImpl: (content: string, reason: string) => Promise<string | null>,
+    conflicts: unknown[]
+  ) {
+    const a = createCanvasSyncAgent({
+      slug: 'screen',
+      doc: docB,
+      paths: paths(),
+      echoGuard: createEchoGuard(),
+      flushMs: 0,
+      // No journal → every diff is divergence (conflict path).
+      snapshot: snapshotImpl,
+      onConflict: (info) => {
+        conflicts.push(info);
+      },
+    });
+    a.start();
+    return a;
+  }
+
+  test('hub newer BUT local snapshot returns null → REFUSE overwrite, keep local, push up', async () => {
+    writeFileSync(paths().html, '<button>local-work</button>');
+    // Hub doc carries a NEWER stamp so newest-wins would pick hub.
+    docA.transact(() => {
+      applyHtmlToDoc(docA, '<button>hub-stale</button>');
+      docA.getMap('syncMeta').set('bodyEditAt', Date.now() + 60_000);
+    });
+
+    const conflicts: Array<{ winner?: string; snapshotFailed?: boolean }> = [];
+    // Snapshot writer that FAILS (disk full / read-only _history): returns null.
+    agent = failClosedAgent(async () => null, conflicts);
+    await agent.reconcile();
+
+    // Local work survives on disk (NOT overwritten by hub-stale) …
+    expect(readFileSync(paths().html, 'utf8')).toBe('<button>local-work</button>');
+    // … and is pushed UP to the hub (nothing lost on either side).
+    expect(htmlFromDoc(docA)).toBe('<button>local-work</button>');
+    // The conflict is recorded with the degraded-snapshot flag + flipped winner.
+    expect(conflicts).toHaveLength(1);
+    expect(conflicts[0].winner).toBe('local');
+    expect(conflicts[0].snapshotFailed).toBe(true);
+  });
+
+  test('hub newer + local snapshot SUCCEEDS → normal hub-wins (control)', async () => {
+    writeFileSync(paths().html, '<button>local-work</button>');
+    docA.transact(() => {
+      applyHtmlToDoc(docA, '<button>hub-newer</button>');
+      docA.getMap('syncMeta').set('bodyEditAt', Date.now() + 60_000);
+    });
+
+    const conflicts: Array<{ winner?: string; snapshotFailed?: boolean }> = [];
+    // Only the local snapshot succeeds; hub snapshot can fail without changing
+    // the outcome (local is the loser when hub wins).
+    agent = failClosedAgent(
+      async (_c, reason) => (reason === 'pre-sync-local' ? 'ts-local' : null),
+      conflicts
+    );
+    await agent.reconcile();
+
+    expect(readFileSync(paths().html, 'utf8')).toBe('<button>hub-newer</button>');
+    expect(conflicts[0].winner).toBe('hub');
+    expect(conflicts[0].snapshotFailed).toBeUndefined();
+  });
+});

package/apps/studio/test/sync-codec.test.ts

@@ -12,8 +12,10 @@ import {
   applyAnnotationsToDoc,
   applyCommentsToDoc,
   applyHtmlToDoc,
+  bodyEditAtFromDoc,
   commentsFromDoc,
   htmlFromDoc,
+  stampBodyEdit,
   Y_SYNC_TYPES,
 } from '../sync/codec.ts';
 
@@ -163,3 +165,66 @@ describe('Annotations codec', () => {
     expect(doc.getMap<string>(Y_TYPES.annotations).get('svg')).toBe('<svg>x</svg>');
   });
 });
+
+// syncMeta lane — DDR-102. The doc-side body-edit stamp the cold-start
+// newest-wins decision reads. Dedicated Y.Map lane because meta's
+// `last_modified` is in META_LOCAL_KEYS (per-machine, never syncs).
+describe('syncMeta codec (DDR-102)', () => {
+  test('bodyEditAtFromDoc returns null on a fresh doc (older-peer interop)', () => {
+    const doc = new Y.Doc();
+    expect(bodyEditAtFromDoc(doc)).toBeNull();
+  });
+
+  test('stampBodyEdit → bodyEditAtFromDoc round-trip with explicit nowMs', () => {
+    const doc = new Y.Doc();
+    stampBodyEdit(doc, undefined, 1_700_000_000_000);
+    expect(bodyEditAtFromDoc(doc)).toBe(1_700_000_000_000);
+    const by = doc.getMap<unknown>(Y_SYNC_TYPES.syncMeta).get('by');
+    expect(typeof by).toBe('string');
+    expect((by as string).length).toBeGreaterThan(0);
+    expect((by as string).length).toBeLessThanOrEqual(32);
+  });
+
+  test('stampBodyEdit defaults to Date.now()', () => {
+    const doc = new Y.Doc();
+    const before = Date.now();
+    stampBodyEdit(doc);
+    const after = Date.now();
+    const at = bodyEditAtFromDoc(doc);
+    expect(at).not.toBeNull();
+    expect(at as number).toBeGreaterThanOrEqual(before);
+    expect(at as number).toBeLessThanOrEqual(after);
+  });
+
+  test('a hostile/garbage bodyEditAt value reads as null', () => {
+    const doc = new Y.Doc();
+    doc.getMap<unknown>(Y_SYNC_TYPES.syncMeta).set('bodyEditAt', 'not-a-number');
+    expect(bodyEditAtFromDoc(doc)).toBeNull();
+    doc.getMap<unknown>(Y_SYNC_TYPES.syncMeta).set('bodyEditAt', Number.POSITIVE_INFINITY);
+    expect(bodyEditAtFromDoc(doc)).toBeNull();
+  });
+
+  test('body apply + stamp wrapped in one transaction emits ONE update', () => {
+    const doc = new Y.Doc();
+    let updates = 0;
+    doc.on('update', () => {
+      updates++;
+    });
+    const origin = { agent: 'test' };
+    doc.transact(() => {
+      applyHtmlToDoc(doc, '<div>v1</div>', origin);
+      stampBodyEdit(doc, origin, 123);
+    }, origin);
+    expect(updates).toBe(1);
+    expect(htmlFromDoc(doc)).toBe('<div>v1</div>');
+    expect(bodyEditAtFromDoc(doc)).toBe(123);
+  });
+
+  test('the stamp syncs to a peer doc via update exchange', () => {
+    const a = new Y.Doc();
+    const b = new Y.Doc();
+    a.on('update', (u: Uint8Array) => Y.applyUpdate(b, u));
+    stampBodyEdit(a, undefined, 456);
+    expect(bodyEditAtFromDoc(b)).toBe(456);
+  });
+});