@1agh/maude 0.29.0 → 0.31.0

package/apps/studio/test/sync-incident-replay.test.ts

@@ -0,0 +1,211 @@
+// Incident replay — the 2026-06-11 `ui-maskot` data loss (DDR-102).
+//
+// The shape that ate a day of work: peer A seeded a STALE body to the hub;
+// peer B booted later holding a NEWER divergent local file and no journal
+// (first link on that machine). v1.1 hub-wins overwrote B's disk with A's
+// stale body; the only trace was a conflict notice. This test replays the
+// exact shape against the REAL journal + REAL history snapshots and asserts
+// the DDR-102 outcome: B loses nothing.
+//
+// Scenario 2 is the everyday case that must stay silent: B's local matches
+// what this machine last synced (journal hash) → the hub being ahead is a
+// clean fast-forward, no snapshots, no conflict noise.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as Y from 'yjs';
+
+import type { Context } from '../context.ts';
+import { createHistory } from '../history.ts';
+import { createCanvasSyncAgent } from '../sync/agent.ts';
+import { applyHtmlToDoc, htmlFromDoc, stampBodyEdit } from '../sync/codec.ts';
+import { createEchoGuard, hashBytes } from '../sync/echo-guard.ts';
+import { loadJournal, type SyncJournal } from '../sync/journal.ts';
+
+const STALE_BODY = '<div class="maskot">stale 2551-byte version that seeded the hub</div>';
+const NEWER_BODY = '<div class="maskot">a full day of mascot work — 6 kB of it</div>';
+
+let dir: string; // peer B's design root
+let journal: SyncJournal;
+
+function paths() {
+  return {
+    html: join(dir, 'ui', 'maskot.html'),
+    comments: join(dir, '_comments', 'ui-maskot.json'),
+    annotations: join(dir, 'ui-maskot.annotations.svg'),
+  };
+}
+
+/** Minimal ctx for the REAL history lib (snapshots under <dir>/_history). */
+function historyCtx(): Context {
+  return {
+    paths: {
+      repoRoot: dir,
+      designRel: '.',
+      designRoot: dir,
+      historyDir: join(dir, '_history'),
+    },
+  } as unknown as Context;
+}
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'incident-replay-'));
+  mkdirSync(join(dir, 'ui'), { recursive: true });
+  journal = loadJournal(dir, { flushMs: 0 });
+});
+
+afterEach(() => {
+  journal.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+/** Build peer B's agent against `doc` with the REAL journal + history. */
+function makeAgentB(doc: Y.Doc, conflicts: unknown[]) {
+  const history = createHistory(historyCtx());
+  const agent = createCanvasSyncAgent({
+    slug: 'ui-maskot',
+    doc,
+    paths: paths(),
+    echoGuard: createEchoGuard(),
+    flushMs: 0,
+    journal,
+    snapshot: async (content, reason) => {
+      try {
+        const snap = await history.writeSnapshot('ui/maskot.html', content, reason);
+        return snap.ts;
+      } catch {
+        return null;
+      }
+    },
+    onConflict: (info) => {
+      conflicts.push(info);
+    },
+  });
+  agent.start();
+  return agent;
+}
+
+describe('incident replay — ui-maskot cold-start divergence (DDR-102)', () => {
+  test('peer B (newer divergent local, no journal) loses NOTHING: winner=local, dual snapshot, hub gets B body', async () => {
+    // Peer A seeded the hub with the stale body an hour ago (older stamp).
+    const hubDoc = new Y.Doc();
+    hubDoc.transact(() => {
+      applyHtmlToDoc(hubDoc, STALE_BODY);
+      stampBodyEdit(hubDoc, undefined, Date.now() - 60 * 60 * 1000);
+    });
+
+    // Peer B holds a NEWER divergent local file (mtime = now) and has never
+    // synced on this machine (journal absent).
+    writeFileSync(paths().html, NEWER_BODY);
+
+    const conflicts: Array<{
+      kind?: string;
+      winner?: string;
+      snapshots?: { local?: string; hub?: string };
+    }> = [];
+    const agent = makeAgentB(hubDoc, conflicts);
+    await agent.reconcile();
+    agent.stop();
+
+    // 1) B's file is byte-identical on disk — the day of work survived.
+    expect(readFileSync(paths().html, 'utf8')).toBe(NEWER_BODY);
+    // 2) Winner = local (newer mtime beats the hub's older stamp).
+    expect(conflicts).toHaveLength(1);
+    expect(conflicts[0].kind).toBe('cold-start-diverged');
+    expect(conflicts[0].winner).toBe('local');
+    // 3) BOTH versions snapshotted to _history/ui-maskot/ (real files).
+    expect(conflicts[0].snapshots?.local).toBeDefined();
+    expect(conflicts[0].snapshots?.hub).toBeDefined();
+    const snapDir = join(dir, '_history', 'ui-maskot');
+    const blobs = readdirSync(snapDir).filter((f) => f.endsWith('.html'));
+    const contents = blobs.map((f) => readFileSync(join(snapDir, f), 'utf8'));
+    expect(contents).toContain(NEWER_BODY);
+    expect(contents).toContain(STALE_BODY);
+    // 4) The hub doc now carries B's body (seeded up, stamped).
+    expect(htmlFromDoc(hubDoc)).toBe(NEWER_BODY);
+    // 5) The journal checkpointed — the NEXT boot is a clean fast-forward.
+    expect(journal.get('ui-maskot')?.bodyHash).toBe(hashBytes(NEWER_BODY));
+  });
+
+  test('peer B with a CLEAN journal fast-forwards silently: no snapshot, no conflict', async () => {
+    // B previously synced STALE_BODY on this machine (journal checkpoint),
+    // disk still holds exactly that; the hub then moved ahead.
+    writeFileSync(paths().html, STALE_BODY);
+    journal.record('ui-maskot', { bodyHash: hashBytes(STALE_BODY) });
+
+    const hubDoc = new Y.Doc();
+    hubDoc.transact(() => {
+      applyHtmlToDoc(hubDoc, NEWER_BODY);
+      stampBodyEdit(hubDoc);
+    });
+
+    const conflicts: unknown[] = [];
+    const agent = makeAgentB(hubDoc, conflicts);
+    await agent.reconcile();
+    agent.stop();
+
+    // Disk fast-forwarded to hub state…
+    expect(readFileSync(paths().html, 'utf8')).toBe(NEWER_BODY);
+    // …with zero conflict noise and zero history spam.
+    expect(conflicts).toHaveLength(0);
+    const snapDir = join(dir, '_history', 'ui-maskot');
+    let blobs: string[] = [];
+    try {
+      blobs = readdirSync(snapDir);
+    } catch {
+      /* dir never created — exactly the point */
+    }
+    expect(blobs).toHaveLength(0);
+    // Journal advanced to the new state.
+    expect(journal.get('ui-maskot')?.bodyHash).toBe(hashBytes(NEWER_BODY));
+  });
+
+  test('boot order REVERSED (B first, then A): A fast-forwards to B state, nothing lost either way', async () => {
+    // B boots first against an empty hub → DDR-064 seed-local-up.
+    writeFileSync(paths().html, NEWER_BODY);
+    const hubDoc = new Y.Doc();
+    const conflictsB: unknown[] = [];
+    const agentB = makeAgentB(hubDoc, conflictsB);
+    await agentB.reconcile();
+    agentB.stop();
+    expect(htmlFromDoc(hubDoc)).toBe(NEWER_BODY);
+    expect(conflictsB).toHaveLength(0); // empty-hub seed is not a conflict
+
+    // Peer A (separate design root + journal) holds the stale body it synced
+    // before — its journal matches its disk → clean fast-forward to B's state.
+    const dirA = mkdtempSync(join(tmpdir(), 'incident-replay-A-'));
+    mkdirSync(join(dirA, 'ui'), { recursive: true });
+    try {
+      writeFileSync(join(dirA, 'ui', 'maskot.html'), STALE_BODY);
+      const journalA = loadJournal(dirA, { flushMs: 0 });
+      journalA.record('ui-maskot', { bodyHash: hashBytes(STALE_BODY) });
+      const conflictsA: unknown[] = [];
+      const agentA = createCanvasSyncAgent({
+        slug: 'ui-maskot',
+        doc: hubDoc,
+        paths: {
+          html: join(dirA, 'ui', 'maskot.html'),
+          comments: join(dirA, '_comments', 'ui-maskot.json'),
+          annotations: join(dirA, 'ui-maskot.annotations.svg'),
+        },
+        echoGuard: createEchoGuard(),
+        flushMs: 0,
+        journal: journalA,
+        onConflict: (info) => {
+          conflictsA.push(info);
+        },
+      });
+      agentA.start();
+      await agentA.reconcile();
+      agentA.stop();
+      journalA.stop();
+
+      expect(readFileSync(join(dirA, 'ui', 'maskot.html'), 'utf8')).toBe(NEWER_BODY);
+      expect(conflictsA).toHaveLength(0);
+    } finally {
+      rmSync(dirA, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -0,0 +1,176 @@
+// Sync journal unit tests — hub-sync cold-start safety (DDR-102).
+//
+// The journal is the divergence detector's memory: it records, per slug, the
+// content hash this machine last reconciled disk↔doc. These tests cover the
+// load/record/flush/invalidate API, the corrupt-file → absent posture, and
+// the per-hub invalidation rule.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { hashBytes } from '../sync/echo-guard.ts';
+import { journalPath, loadJournal, type SyncJournal } from '../sync/journal.ts';
+
+let dir: string;
+let journal: SyncJournal | null = null;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'sync-journal-'));
+  journal = null;
+});
+
+afterEach(() => {
+  journal?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe('loadJournal — basic API', () => {
+  test('get returns null for a never-recorded slug', () => {
+    journal = loadJournal(dir, { flushMs: 0 });
+    expect(journal.get('ui-maskot')).toBeNull();
+  });
+
+  test('record + get round-trip with bodyHash and optional cssHash', () => {
+    journal = loadJournal(dir, { flushMs: 0, now: () => 42 });
+    const bodyHash = hashBytes('<div>v1</div>');
+    journal.record('ui-maskot', { bodyHash });
+    expect(journal.get('ui-maskot')).toEqual({ bodyHash, at: 42 });
+
+    const cssHash = hashBytes('.a{}');
+    journal.record('ui-maskot', { bodyHash, cssHash });
+    expect(journal.get('ui-maskot')).toEqual({ bodyHash, cssHash, at: 42 });
+  });
+
+  test('flush persists to <designRoot>/_state/sync-journal.json, creating _state/ on demand', () => {
+    journal = loadJournal(dir, { flushMs: 0 });
+    expect(existsSync(join(dir, '_state'))).toBe(false);
+    journal.record('ui-a', { bodyHash: 'h1' });
+
+    const file = journalPath(dir);
+    expect(existsSync(file)).toBe(true);
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    expect(parsed.slugs['ui-a'].bodyHash).toBe('h1');
+    expect(typeof parsed.updatedAt).toBe('number');
+  });
+
+  test('a fresh journal instance reads back what a previous one persisted', () => {
+    const first = loadJournal(dir, { flushMs: 0, now: () => 7 });
+    first.record('ui-a', { bodyHash: 'h1' });
+    first.stop();
+
+    journal = loadJournal(dir);
+    expect(journal.get('ui-a')).toEqual({ bodyHash: 'h1', at: 7 });
+    expect(journal.size()).toBe(1);
+  });
+
+  test('debounces rapid records into one write', async () => {
+    let writes = 0;
+    journal = loadJournal(dir, {
+      flushMs: 20,
+      writer: () => {
+        writes++;
+      },
+    });
+    for (let i = 0; i < 10; i++) journal.record('ui-a', { bodyHash: `h${i}` });
+    expect(writes).toBe(0); // still pending
+    await new Promise((res) => setTimeout(res, 60));
+    expect(writes).toBe(1);
+  });
+
+  test('stop() flushes the pending debounce', () => {
+    let written: string | null = null;
+    journal = loadJournal(dir, {
+      flushMs: 10_000,
+      writer: (_p, bytes) => {
+        written = bytes;
+      },
+    });
+    journal.record('ui-a', { bodyHash: 'h1' });
+    expect(written).toBeNull();
+    journal.stop();
+    expect(written).not.toBeNull();
+    expect(JSON.parse(written as unknown as string).slugs['ui-a'].bodyHash).toBe('h1');
+  });
+});
+
+describe('loadJournal — corrupt / hostile file posture', () => {
+  test('corrupt JSON → treated as absent, never throws', () => {
+    const file = journalPath(dir);
+    // Persist a valid journal first (creates _state/), then corrupt it.
+    journal = loadJournal(dir, { flushMs: 0 });
+    journal.record('ui-a', { bodyHash: 'h1' });
+    journal.stop();
+
+    writeFileSync(file, '{not json');
+    journal = loadJournal(dir);
+    expect(journal.get('ui-a')).toBeNull();
+    expect(journal.size()).toBe(0);
+  });
+
+  test('wrong-shape JSON (array / non-object slugs / bad entries) → absent entries', () => {
+    const file = journalPath(dir);
+    journal = loadJournal(dir, { flushMs: 0 });
+    journal.record('seed', { bodyHash: 'x' }); // creates _state/
+    journal.stop();
+
+    writeFileSync(file, JSON.stringify([1, 2, 3]));
+    expect(loadJournal(dir).size()).toBe(0);
+
+    writeFileSync(file, JSON.stringify({ hubUrl: 1, slugs: { 'ui-a': { bodyHash: 99 } } }));
+    const j = loadJournal(dir);
+    expect(j.get('ui-a')).toBeNull();
+    expect(j.size()).toBe(0);
+  });
+
+  test('writer failure is swallowed (never throws into the sync path)', () => {
+    journal = loadJournal(dir, {
+      flushMs: 0,
+      writer: () => {
+        throw new Error('disk full');
+      },
+    });
+    expect(() => journal?.record('ui-a', { bodyHash: 'h1' })).not.toThrow();
+    expect(journal.get('ui-a')?.bodyHash).toBe('h1'); // in-memory state intact
+  });
+});
+
+describe('loadJournal — per-hub invalidation', () => {
+  test('first invalidateIfHubChanged adopts the URL without wiping', () => {
+    journal = loadJournal(dir, { flushMs: 0 });
+    journal.record('ui-a', { bodyHash: 'h1' });
+    journal.invalidateIfHubChanged('https://hub.example.com');
+    expect(journal.get('ui-a')?.bodyHash).toBe('h1');
+  });
+
+  test('same hub URL on a later boot keeps entries', () => {
+    const first = loadJournal(dir, { flushMs: 0 });
+    first.invalidateIfHubChanged('https://hub.example.com');
+    first.record('ui-a', { bodyHash: 'h1' });
+    first.stop();
+
+    journal = loadJournal(dir, { flushMs: 0 });
+    journal.invalidateIfHubChanged('https://hub.example.com');
+    expect(journal.get('ui-a')?.bodyHash).toBe('h1');
+  });
+
+  test('a DIFFERENT hub URL wipes every entry (hashes are per-hub)', () => {
+    const first = loadJournal(dir, { flushMs: 0 });
+    first.invalidateIfHubChanged('https://hub-one.example.com');
+    first.record('ui-a', { bodyHash: 'h1' });
+    first.record('ui-b', { bodyHash: 'h2' });
+    first.stop();
+
+    journal = loadJournal(dir, { flushMs: 0 });
+    journal.invalidateIfHubChanged('https://hub-two.example.com');
+    expect(journal.get('ui-a')).toBeNull();
+    expect(journal.get('ui-b')).toBeNull();
+    expect(journal.size()).toBe(0);
+
+    // …and the wipe is persisted.
+    const parsed = JSON.parse(readFileSync(journalPath(dir), 'utf8'));
+    expect(parsed.hubUrl).toBe('https://hub-two.example.com');
+    expect(Object.keys(parsed.slugs)).toHaveLength(0);
+  });
+});