@1agh/maude 0.28.1 → 0.30.0

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

@@ -0,0 +1,244 @@
+// Cold-start decision matrix — hub-sync cold-start safety (DDR-102).
+//
+// Exhaustive table over (local: absent/empty/clean/diverged) × (doc:
+// empty/same/different) × (journal: absent/match/stale), plus both winner
+// directions and the null-timestamp fallbacks. Mirrors the table style of
+// sync-codec.test.ts: every case is a row with explicit inputs + expected
+// action.
+
+import { describe, expect, test } from 'bun:test';
+
+import { type ColdStartInput, decideColdStart } from '../sync/cold-start.ts';
+import { hashBytes } from '../sync/echo-guard.ts';
+
+const BODY_LOCAL = '<div>local work — a day of mascot edits</div>';
+const BODY_HUB = '<div>hub state</div>';
+
+/** Convenience: build an input with safe defaults, override per case. */
+function input(over: Partial<ColdStartInput>): ColdStartInput {
+  return {
+    localBody: null,
+    docBody: '',
+    journalHash: null,
+    localMtimeMs: null,
+    docBodyEditAtMs: null,
+    ...over,
+  };
+}
+
+describe('decideColdStart — empty/absent sides', () => {
+  test('local absent + doc empty → noop', () => {
+    expect(decideColdStart(input({})).action).toBe('noop');
+  });
+
+  test('local empty-string + doc empty → noop', () => {
+    expect(decideColdStart(input({ localBody: '' })).action).toBe('noop');
+  });
+
+  test('whitespace-only local counts as empty (mirrors the trim guard)', () => {
+    const d = decideColdStart(input({ localBody: '  \n\t ', docBody: BODY_HUB }));
+    expect(d.action).toBe('materialize-hub');
+  });
+
+  test('local absent + doc non-empty → materialize-hub (clean first sync)', () => {
+    const d = decideColdStart(input({ docBody: BODY_HUB }));
+    expect(d.action).toBe('materialize-hub');
+  });
+
+  test('local empty + doc non-empty → materialize-hub', () => {
+    const d = decideColdStart(input({ localBody: '', docBody: BODY_HUB }));
+    expect(d.action).toBe('materialize-hub');
+  });
+
+  test('local non-empty + doc empty → seed-local-up (DDR-064 guard as a named case)', () => {
+    const d = decideColdStart(input({ localBody: BODY_LOCAL, docBody: '' }));
+    expect(d.action).toBe('seed-local-up');
+  });
+
+  test('local non-empty + whitespace-only doc → seed-local-up', () => {
+    const d = decideColdStart(input({ localBody: BODY_LOCAL, docBody: ' \n ' }));
+    expect(d.action).toBe('seed-local-up');
+  });
+
+  test('seed-local-up holds regardless of journal state (stale journal must not block it)', () => {
+    const d = decideColdStart(
+      input({ localBody: BODY_LOCAL, docBody: '', journalHash: 'stale-hash' })
+    );
+    expect(d.action).toBe('seed-local-up');
+  });
+});
+
+describe('decideColdStart — identical sides', () => {
+  test('local == doc → noop (caller records journal)', () => {
+    const d = decideColdStart(input({ localBody: BODY_HUB, docBody: BODY_HUB }));
+    expect(d.action).toBe('noop');
+  });
+
+  test('local == doc with a stale journal is still a noop (content equality wins)', () => {
+    const d = decideColdStart(
+      input({ localBody: BODY_HUB, docBody: BODY_HUB, journalHash: 'stale' })
+    );
+    expect(d.action).toBe('noop');
+  });
+});
+
+describe('decideColdStart — journal-gated fast-forward', () => {
+  test('local ≠ doc, journal matches hash(local) → fast-forward-hub (no conflict)', () => {
+    const d = decideColdStart(
+      input({
+        localBody: BODY_LOCAL,
+        docBody: BODY_HUB,
+        journalHash: hashBytes(BODY_LOCAL),
+      })
+    );
+    expect(d.action).toBe('fast-forward-hub');
+    expect(d.winner).toBeUndefined();
+  });
+
+  test('journal match overrides timestamps — even a NEWER local mtime fast-forwards', () => {
+    // mtime newer than the doc stamp, but the bytes are exactly what we last
+    // synced (e.g. touch / checkout changed mtime only) → not a conflict.
+    const d = decideColdStart(
+      input({
+        localBody: BODY_LOCAL,
+        docBody: BODY_HUB,
+        journalHash: hashBytes(BODY_LOCAL),
+        localMtimeMs: 2_000,
+        docBodyEditAtMs: 1_000,
+      })
+    );
+    expect(d.action).toBe('fast-forward-hub');
+  });
+});
+
+describe('decideColdStart — divergence (conflict + newest-wins)', () => {
+  test('journal ABSENT, local newer → conflict, winner=local (the incident shape)', () => {
+    const d = decideColdStart(
+      input({
+        localBody: BODY_LOCAL,
+        docBody: BODY_HUB,
+        localMtimeMs: 2_000,
+        docBodyEditAtMs: 1_000,
+      })
+    );
+    expect(d.action).toBe('conflict');
+    expect(d.winner).toBe('local');
+  });
+
+  test('journal ABSENT, doc newer → conflict, winner=hub', () => {
+    const d = decideColdStart(
+      input({
+        localBody: BODY_LOCAL,
+        docBody: BODY_HUB,
+        localMtimeMs: 1_000,
+        docBodyEditAtMs: 2_000,
+      })
+    );
+    expect(d.action).toBe('conflict');
+    expect(d.winner).toBe('hub');
+  });
+
+  test('journal STALE (≠ hash(local)), local newer → conflict, winner=local', () => {
+    const d = decideColdStart(
+      input({
+        localBody: BODY_LOCAL,
+        docBody: BODY_HUB,
+        journalHash: hashBytes('<div>some older synced state</div>'),
+        localMtimeMs: 5_000,
+        docBodyEditAtMs: 4_000,
+      })
+    );
+    expect(d.action).toBe('conflict');
+    expect(d.winner).toBe('local');
+  });
+
+  test('journal STALE, doc newer → conflict, winner=hub', () => {
+    const d = decideColdStart(
+      input({
+        localBody: BODY_LOCAL,
+        docBody: BODY_HUB,
+        journalHash: hashBytes('<div>some older synced state</div>'),
+        localMtimeMs: 4_000,
+        docBodyEditAtMs: 5_000,
+      })
+    );
+    expect(d.action).toBe('conflict');
+    expect(d.winner).toBe('hub');
+  });
+
+  test('journal matching hash(DOC) — not local — is still divergence', () => {
+    // The journal proves we once synced what the HUB now holds reverted to;
+    // local moved past it → local is unreconciled work, must conflict.
+    const d = decideColdStart(
+      input({
+        localBody: BODY_LOCAL,
+        docBody: BODY_HUB,
+        journalHash: hashBytes(BODY_HUB),
+        localMtimeMs: 2_000,
+        docBodyEditAtMs: 1_000,
+      })
+    );
+    expect(d.action).toBe('conflict');
+    expect(d.winner).toBe('local');
+  });
+
+  test('doc stamp NULL (older peer never stamped) → hub-wins fallback', () => {
+    const d = decideColdStart(
+      input({
+        localBody: BODY_LOCAL,
+        docBody: BODY_HUB,
+        localMtimeMs: 2_000,
+        docBodyEditAtMs: null,
+      })
+    );
+    expect(d.action).toBe('conflict');
+    expect(d.winner).toBe('hub');
+  });
+
+  test('local mtime NULL → hub-wins fallback', () => {
+    const d = decideColdStart(
+      input({
+        localBody: BODY_LOCAL,
+        docBody: BODY_HUB,
+        localMtimeMs: null,
+        docBodyEditAtMs: 2_000,
+      })
+    );
+    expect(d.action).toBe('conflict');
+    expect(d.winner).toBe('hub');
+  });
+
+  test('both timestamps NULL → hub-wins fallback', () => {
+    const d = decideColdStart(input({ localBody: BODY_LOCAL, docBody: BODY_HUB }));
+    expect(d.action).toBe('conflict');
+    expect(d.winner).toBe('hub');
+  });
+
+  test('timestamps TIED → hub-wins fallback', () => {
+    const d = decideColdStart(
+      input({
+        localBody: BODY_LOCAL,
+        docBody: BODY_HUB,
+        localMtimeMs: 1_000,
+        docBodyEditAtMs: 1_000,
+      })
+    );
+    expect(d.action).toBe('conflict');
+    expect(d.winner).toBe('hub');
+  });
+
+  test('every decision carries a human-readable reason', () => {
+    const cases: ColdStartInput[] = [
+      input({}),
+      input({ docBody: BODY_HUB }),
+      input({ localBody: BODY_LOCAL }),
+      input({ localBody: BODY_HUB, docBody: BODY_HUB }),
+      input({ localBody: BODY_LOCAL, docBody: BODY_HUB, journalHash: hashBytes(BODY_LOCAL) }),
+      input({ localBody: BODY_LOCAL, docBody: BODY_HUB }),
+    ];
+    for (const c of cases) {
+      const d = decideColdStart(c);
+      expect(d.reason.length).toBeGreaterThan(0);
+    }
+  });
+});

package/{plugins/design/dev-server → apps/studio}/test/sync-connection-state.test.ts

@@ -144,3 +144,71 @@ describe('connection monitor', () => {
     expect(changes.length).toBe(before); // no offline transition fired
   });
 });
+
+// DDR-102 — per-doc states + real lastSyncAt.
+describe('connection monitor — per-doc states (DDR-102)', () => {
+  test('noteDocState rolls up into docs counts + rejectedSlugs', () => {
+    const { monitor } = makeMonitor();
+    monitor.noteDocState('ui-a', 'pending');
+    monitor.noteDocState('ui-b', 'connected');
+    monitor.noteDocState('ui-c', 'auth-rejected');
+    monitor.noteDocState('ui-d', 'auth-rejected');
+
+    const snap = monitor.snapshot();
+    expect(snap.docs).toEqual({ synced: 1, pending: 1, rejected: 2 });
+    expect(snap.rejectedSlugs?.sort()).toEqual(['ui-c', 'ui-d']);
+  });
+
+  test('doc state transitions update the rollup (rejected → connected after re-link)', () => {
+    const { monitor, changes } = makeMonitor();
+    monitor.noteDocState('ui-a', 'auth-rejected');
+    expect(monitor.snapshot().docs?.rejected).toBe(1);
+    monitor.noteDocState('ui-a', 'connected');
+    const snap = monitor.snapshot();
+    expect(snap.docs).toEqual({ synced: 1, pending: 0, rejected: 0 });
+    expect(snap.rejectedSlugs).toEqual([]);
+    // Each transition emitted (no-op repeats don't).
+    const emitted = changes.length;
+    monitor.noteDocState('ui-a', 'connected');
+    expect(changes.length).toBe(emitted);
+  });
+
+  test('rejectedSlugs caps at 20 while docs.rejected carries the true count', () => {
+    const { monitor } = makeMonitor();
+    for (let i = 0; i < 25; i++) monitor.noteDocState(`ui-${i}`, 'auth-rejected');
+    const snap = monitor.snapshot();
+    expect(snap.docs?.rejected).toBe(25);
+    expect(snap.rejectedSlugs).toHaveLength(20);
+  });
+
+  test('noteSyncActivity sets lastSyncAt to now and promotes a pending doc', () => {
+    const { clock, monitor } = makeMonitor();
+    monitor.noteDocState('ui-a', 'pending');
+    expect(monitor.snapshot().lastSyncAt).toBeNull();
+
+    clock.advance(5_000);
+    monitor.noteSyncActivity('ui-a');
+    const snap = monitor.snapshot();
+    expect(snap.lastSyncAt).toBe(clock.now());
+    expect(snap.docs?.synced).toBe(1);
+    expect(snap.docs?.pending).toBe(0);
+  });
+
+  test('noteSyncActivity does NOT resurrect an auth-rejected doc', () => {
+    const { monitor } = makeMonitor();
+    monitor.noteDocState('ui-a', 'auth-rejected');
+    monitor.noteSyncActivity('ui-a');
+    expect(monitor.snapshot().docs?.rejected).toBe(1);
+    expect(monitor.snapshot().lastSyncAt).not.toBeNull();
+  });
+
+  test('lastSyncAt advances on repeated activity (real activity, not just transitions)', () => {
+    const { clock, monitor } = makeMonitor();
+    monitor.noteDocState('ui-a', 'connected');
+    monitor.noteSyncActivity('ui-a');
+    const first = monitor.snapshot().lastSyncAt;
+    clock.advance(10_000);
+    monitor.noteSyncActivity('ui-a');
+    expect(monitor.snapshot().lastSyncAt).toBe((first as number) + 10_000);
+  });
+});

package/{plugins/design/dev-server → apps/studio}/test/sync-hardening.test.ts

@@ -54,25 +54,19 @@ describe('DDR-054 §2a — CI environment gate', () => {
     savedCi = process.env.CI;
     savedGha = process.env.GITHUB_ACTIONS;
     savedOverride = process.env.MAUDE_SYNC_IN_CI;
-    // biome-ignore lint/performance/noDelete: process.env semantics
     delete process.env.CI;
-    // biome-ignore lint/performance/noDelete: process.env semantics
     delete process.env.GITHUB_ACTIONS;
-    // biome-ignore lint/performance/noDelete: process.env semantics
     delete process.env.MAUDE_SYNC_IN_CI;
   });
 
   afterEach(() => {
     if (savedCi === undefined) {
-      // biome-ignore lint/performance/noDelete: process.env semantics
       delete process.env.CI;
     } else process.env.CI = savedCi;
     if (savedGha === undefined) {
-      // biome-ignore lint/performance/noDelete: process.env semantics
       delete process.env.GITHUB_ACTIONS;
     } else process.env.GITHUB_ACTIONS = savedGha;
     if (savedOverride === undefined) {
-      // biome-ignore lint/performance/noDelete: process.env semantics
       delete process.env.MAUDE_SYNC_IN_CI;
     } else process.env.MAUDE_SYNC_IN_CI = savedOverride;
   });
@@ -443,7 +437,6 @@ describe('DDR-054 §2i — auto-clear adopt after first success', () => {
     const savedHubsEnv = process.env.HUBS_CONFIG_PATH;
     process.env.HUBS_CONFIG_PATH = hubsPath;
     const savedCi = process.env.CI;
-    // biome-ignore lint/performance/noDelete: process.env semantics
     delete process.env.CI;
 
     try {
@@ -504,7 +497,6 @@ describe('DDR-054 §2i — auto-clear adopt after first success', () => {
       expect(typeof after.linkedHub.lastAdoptedAt).toBe('number');
     } finally {
       if (savedHubsEnv === undefined) {
-        // biome-ignore lint/performance/noDelete: process.env semantics
         delete process.env.HUBS_CONFIG_PATH;
       } else process.env.HUBS_CONFIG_PATH = savedHubsEnv;
       if (savedCi !== undefined) process.env.CI = savedCi;

package/{plugins/design/dev-server → apps/studio}/test/sync-hubs-config.test.ts

@@ -21,7 +21,6 @@ beforeEach(() => {
 afterEach(() => {
   // Node's process.env stringifies on assignment; assigning undefined yields
   // the literal string "undefined". delete is the correct restoration.
-  // biome-ignore lint/performance/noDelete: process.env semantics.
   if (savedEnv === undefined) delete process.env.HUBS_CONFIG_PATH;
   else process.env.HUBS_CONFIG_PATH = savedEnv;
   rmSync(dir, { recursive: true, force: true });

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 });
+    }
+  });
+});