@1agh/maude 0.22.2 → 0.24.0

package/plugins/design/dev-server/test/shared-doc-convergence.test.ts

@@ -0,0 +1,265 @@
+// Phase 9.2 (DDR-064) Phase F — convergence + stress property suite (Task 12).
+//
+// The load-bearing gate for the refactor (the no-break-exhaustive-verify bar):
+// once every change flows through ONE shared Y.Doc, convergence must hold BY
+// CONSTRUCTION. These tests pin the CRDT properties on the composed canvas doc
+// (all five synced types) + the diff-importer + the disk projection:
+//
+//   - commutativity  — concurrent edits merge to the same state regardless of
+//                      delivery order;
+//   - idempotency    — re-delivering an update changes nothing;
+//   - round-trip laws — materialize∘import is stable (id on the canonical view);
+//                       a projection's import∘materialize is a no-op (echo drop);
+//   - N-peer stress  — N docs + a randomized-delivery relay + a file-importer,
+//                      seeded RNG, → all replicas materialize byte-identical.
+//
+// In-process (no hub process): a relay models Hocuspocus by re-broadcasting each
+// doc update to every other peer (Yjs updates are commutative/idempotent, so a
+// re-broadcast relay IS the hub's convergence contract). The real-hub N-peer
+// soak lives in plugins/design/hub/test/stress-integration.test.mjs + the live
+// cross-machine manual run; this suite is the deterministic property gate.
+
+import { describe, expect, test } from 'bun:test';
+import * as Y from 'yjs';
+
+import { Y_TYPES } from '../collab/persistence.ts';
+import {
+  Y_SYNC_TYPES,
+  applyCommentsToDoc,
+  applyCssToDoc,
+  applyHtmlToDoc,
+  applyMetaToDoc,
+} from '../sync/codec.ts';
+import { createEchoGuard, hashBytes } from '../sync/echo-guard.ts';
+import { materialize, materializeCanonical } from '../sync/materialize.ts';
+import { createDocProjection } from '../sync/projection.ts';
+
+const enc = (s: string) => new TextEncoder().encode(s);
+
+/** Deterministic PRNG (mulberry32) so the stress is reproducible across runs. */
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const TRANSPORT = Symbol('relay-transport');
+
+/**
+ * A queued, randomized-delivery relay over N docs that models a hub. Each doc's
+ * non-transport updates are queued; flush() delivers them to every OTHER doc in
+ * a seeded-random order (and re-delivers a fraction, exercising idempotency).
+ */
+function makeRelay(docs: Y.Doc[], rnd: () => number) {
+  const queue: Array<{ from: number; update: Uint8Array }> = [];
+  docs.forEach((doc, i) => {
+    doc.on('update', (update: Uint8Array, origin: unknown) => {
+      if (origin === TRANSPORT) return;
+      queue.push({ from: i, update });
+    });
+  });
+  return {
+    flush() {
+      // Drain in waves until quiescent (a delivery can enqueue nothing new since
+      // applies are TRANSPORT-origin, so one shuffled pass suffices — but loop to
+      // be safe against any future re-entrancy).
+      let guard = 0;
+      while (queue.length > 0 && guard++ < 1000) {
+        const batch = queue.splice(0, queue.length);
+        // Shuffle (seeded) → out-of-order delivery tests commutativity.
+        for (let i = batch.length - 1; i > 0; i--) {
+          const j = Math.floor(rnd() * (i + 1));
+          [batch[i], batch[j]] = [batch[j], batch[i]];
+        }
+        for (const { from, update } of batch) {
+          docs.forEach((doc, i) => {
+            if (i === from) return;
+            Y.applyUpdate(doc, update, TRANSPORT);
+            // Idempotency: ~25% of deliveries are applied a second time.
+            if (rnd() < 0.25) Y.applyUpdate(doc, update, TRANSPORT);
+          });
+        }
+      }
+    },
+  };
+}
+
+describe('convergence laws on the composed shared doc', () => {
+  test('commutativity — concurrent edits merge identically regardless of order', () => {
+    // Peer A adds a comment; peer B sets an annotation; peer C edits the body.
+    const a = new Y.Doc();
+    const b = new Y.Doc();
+    const c = new Y.Doc();
+    const relay = makeRelay([a, b, c], mulberry32(1));
+
+    a.getArray(Y_TYPES.comments).push([{ id: 'c1', text: 'from A' }]);
+    b.getMap(Y_TYPES.annotations).set('svg', '<svg><rect/></svg>');
+    c.getText(Y_SYNC_TYPES.html).insert(0, '<main>from C</main>');
+    relay.flush();
+
+    // All three converge to the SAME canonical materialization.
+    expect(materializeCanonical(a)).toBe(materializeCanonical(b));
+    expect(materializeCanonical(b)).toBe(materializeCanonical(c));
+    // …and all three edits survived (no clobber).
+    const m = materialize(a);
+    expect(m.comments).toEqual([{ id: 'c1', text: 'from A' }]);
+    expect(m.annotations).toBe('<svg><rect/></svg>');
+    expect(m.html).toBe('<main>from C</main>');
+  });
+
+  test('idempotency — re-delivering updates does not duplicate or diverge', () => {
+    const a = new Y.Doc();
+    const b = new Y.Doc();
+    // Relay re-delivers a fraction of updates (see makeRelay) — comments must
+    // not duplicate, state must not drift.
+    const relay = makeRelay([a, b], mulberry32(42));
+    a.getArray(Y_TYPES.comments).push([{ id: 'c1' }, { id: 'c2' }]);
+    relay.flush();
+    relay.flush(); // flush again — nothing queued, no-op
+    expect(materializeCanonical(a)).toBe(materializeCanonical(b));
+    expect(materialize(b).comments).toEqual([{ id: 'c1' }, { id: 'c2' }]);
+  });
+});
+
+describe('round-trip laws', () => {
+  test('materialize∘import is stable (id on the canonical view)', () => {
+    // Build a doc via the codecs (the file→doc import path), materialize it,
+    // re-import each piece into a fresh doc → identical canonical view.
+    const src = new Y.Doc();
+    applyHtmlToDoc(src, '<main>body</main>', 'x');
+    applyCssToDoc(src, '.a{color:red}', 'x');
+    applyMetaToDoc(src, JSON.stringify({ title: 'T', viewport: { x: 1 } }), 'x');
+    applyCommentsToDoc(src, [{ id: 'c1', text: 'hi' }], 'x');
+    src.getMap(Y_TYPES.annotations).set('svg', '<svg/>');
+
+    const m = materialize(src);
+    const dst = new Y.Doc();
+    applyHtmlToDoc(dst, m.html, 'y');
+    applyCssToDoc(dst, m.css, 'y');
+    // meta materializes to the SHARED canonical (viewport already stripped), so
+    // re-importing it is a no-op-equivalent round-trip.
+    dst.getText(Y_SYNC_TYPES.meta).insert(0, m.meta);
+    applyCommentsToDoc(dst, m.comments, 'y');
+    dst.getMap(Y_TYPES.annotations).set('svg', m.annotations);
+
+    expect(materializeCanonical(dst)).toBe(materializeCanonical(src));
+    // meta lost its per-user viewport on the way into the doc (shared subset).
+    expect(m.meta).not.toContain('viewport');
+  });
+
+  test('projection import∘materialize is a no-op (the echo is dropped)', async () => {
+    const doc = new Y.Doc();
+    const echoGuard = createEchoGuard();
+    const files: Record<string, string> = {};
+    const paths = {
+      html: '/d/x.html',
+      comments: '/d/x.comments.json',
+      annotations: '/d/x.svg',
+      meta: '/d/x.meta.json',
+      css: '/d/x.css',
+    };
+    const proj = createDocProjection({
+      slug: 'x',
+      doc,
+      paths,
+      echoGuard,
+      flushMs: 0,
+      writer: (p, bytes) => {
+        files[p] = bytes.toString();
+      },
+    });
+    proj.start();
+    doc.getText(Y_SYNC_TYPES.html).insert(0, '<main>v1</main>');
+    await proj.flush(); // materialize → files[html] written + echo hash recorded
+
+    // Now feed the just-written file back in (the fs.watch echo). The hash
+    // matches → dropped → doc unchanged (import∘materialize == noop).
+    let updates = 0;
+    doc.on('update', () => {
+      updates++;
+    });
+    const body = files[paths.html];
+    expect(proj.applyFromFs({ path: paths.html, bytes: enc(body), hash: hashBytes(body) })).toBe(
+      false
+    );
+    expect(updates).toBe(0);
+  });
+});
+
+describe('N-peer stress (randomized delivery + file-importer, seeded)', () => {
+  // Run a handful of seeds so the property is exercised across orderings.
+  for (const seed of [1, 7, 99, 2024]) {
+    test(`5 peers converge byte-identical (seed ${seed})`, () => {
+      const N = 5;
+      const docs = Array.from({ length: N }, () => new Y.Doc());
+      const rnd = mulberry32(seed);
+      const relay = makeRelay(docs, rnd);
+
+      // Each peer has a projection so a subset of ops are file→doc imports
+      // (html diff-import, the realistic /design:edit path). Comments/annotations
+      // are granular Y-ops (the browser path). All are CRDT-mergeable.
+      const projections = docs.map((doc, i) =>
+        createDocProjection({
+          slug: `p${i}`,
+          doc,
+          paths: {
+            html: `/d/p${i}.html`,
+            comments: `/d/p${i}.json`,
+            annotations: `/d/p${i}.svg`,
+          },
+          echoGuard: createEchoGuard(),
+          flushMs: 0,
+          // No-op writer: this stress asserts DOC convergence, not disk; the
+          // paths are synthetic, so skip real fs writes (avoids EROFS noise).
+          writer: () => {},
+        })
+      );
+      for (const p of projections) p.start();
+
+      const OPS = 60;
+      for (let k = 0; k < OPS; k++) {
+        const peer = Math.floor(rnd() * N);
+        const doc = docs[peer];
+        const r = rnd();
+        if (r < 0.4) {
+          // browser: append a comment (unique id → all survive the merge)
+          doc.getArray(Y_TYPES.comments).push([{ id: `c-${peer}-${k}`, text: `op${k}` }]);
+        } else if (r < 0.6) {
+          // browser: set the annotation key (LWW — converges to one value)
+          doc.getMap(Y_TYPES.annotations).set('svg', `<svg data-k="${k}"/>`);
+        } else if (r < 0.8) {
+          // browser: insert into the body text CRDT
+          const t = doc.getText(Y_SYNC_TYPES.html);
+          t.insert(Math.min(t.length, Math.floor(rnd() * (t.length + 1))), `<i>${k}</i>`);
+        } else {
+          // /design:edit: a whole-file body import via the projection (diff)
+          const body = `<main>edit ${peer}/${k}</main>`;
+          projections[peer].applyFromFs({
+            path: `/d/p${peer}.html`,
+            bytes: enc(body),
+            hash: hashBytes(body),
+          });
+        }
+        // Flush intermittently (partial delivery) to interleave ordering.
+        if (rnd() < 0.5) relay.flush();
+      }
+      relay.flush(); // final quiescence
+
+      // Every replica converged to byte-identical canonical state.
+      const ref = materializeCanonical(docs[0]);
+      for (let i = 1; i < N; i++) {
+        expect(materializeCanonical(docs[i])).toBe(ref);
+      }
+      // And every comment that was appended survived (no clobber, no dup).
+      const commentIds = new Set(
+        (materialize(docs[0]).comments as Array<{ id: string }>).map((c) => c.id)
+      );
+      // At least one comment landed; ids are unique by construction.
+      expect(commentIds.size).toBe(materialize(docs[0]).comments.length);
+    });
+  }
+});

package/plugins/design/dev-server/test/shared-doc-foundation.test.ts

@@ -0,0 +1,63 @@
+// Phase 9.2 (DDR-064) Phase A — single-shared-doc foundation.
+//
+// Phase A is pure plumbing: the registry exposes one cached Y.Doc per slug
+// (the seam the hub provider attaches to in Phase B) and the MAUDE_SHARED_DOC
+// flag is threaded onto Context (default OFF = the two-doc path = zero
+// regression). These tests pin the Task 2 contract + the Risk 2 mitigation
+// (a single yjs instance — "imported twice" silently breaks sync).
+
+import { describe, expect, test } from 'bun:test';
+import * as Y from 'yjs';
+
+import { createRegistry } from '../collab/registry.ts';
+import type { RoomCallbacks } from '../collab/room.ts';
+
+function noopCallbacks(): RoomCallbacks {
+  return {
+    async seed() {},
+    async persistJson() {},
+    async persistBinary() {},
+  };
+}
+
+describe('Phase A — registry.getDoc (single shared doc per slug)', () => {
+  test('getDoc caches: repeated calls return the SAME Y.Doc instance', () => {
+    const r = createRegistry(noopCallbacks());
+    const a = r.getDoc('canvas-x');
+    const b = r.getDoc('canvas-x');
+    expect(a).toBe(b);
+  });
+
+  test('getDoc returns the owning room.doc (single source of truth)', () => {
+    const r = createRegistry(noopCallbacks());
+    const doc = r.getDoc('canvas-x');
+    // get() is get-or-create; it must reuse the room getDoc just created, so
+    // the doc the browser room syncs IS the doc the provider would attach to.
+    expect(r.get('canvas-x').doc).toBe(doc);
+    expect(r.peek('canvas-x')?.doc).toBe(doc);
+  });
+
+  test('distinct slugs get distinct docs', () => {
+    const r = createRegistry(noopCallbacks());
+    expect(r.getDoc('a')).not.toBe(r.getDoc('b'));
+  });
+
+  test('Risk 2 — getDoc yields a real Y.Doc from the single yjs instance', () => {
+    // If room.ts ever resolved a SECOND copy of yjs, this instanceof against
+    // the test's own import would be false and live sync would silently break.
+    const r = createRegistry(noopCallbacks());
+    expect(r.getDoc('canvas-x')).toBeInstanceOf(Y.Doc);
+  });
+
+  test('getDoc creates the room before any browser connects (provider can attach at serve start)', () => {
+    const r = createRegistry(noopCallbacks());
+    expect(r.peek('canvas-x')).toBeNull(); // nothing created yet
+    const doc = r.getDoc('canvas-x');
+    // The room now exists with zero connections — exactly the state the hub
+    // provider attaches into at serve start (Phase B gotcha).
+    const room = r.peek('canvas-x');
+    expect(room).not.toBeNull();
+    expect(room?.size()).toBe(0);
+    expect(room?.doc).toBe(doc);
+  });
+});

package/plugins/design/dev-server/test/shared-doc-migrate.test.ts

@@ -0,0 +1,160 @@
+// Phase 9.2 (DDR-064) Phase E — the one-time authoritative seed (Task 9).
+//
+// Pins the fix for Risk 1, the duplication-on-merge trap: a shared doc must be
+// populated from ONE source. These tests prove migrateSeed never duplicates
+// comments and is idempotent across re-runs (server restarts).
+
+import { mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import * as Y from 'yjs';
+
+import { Y_TYPES, createPersistence } from '../collab/persistence.ts';
+import type { Context } from '../context.ts';
+import { applyCommentsToDoc, applyHtmlToDoc } from '../sync/codec.ts';
+import { docIsEmpty, migrateSeed } from '../sync/migrate-seed.ts';
+
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'migrate-seed-'));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function paths() {
+  return {
+    html: join(dir, 'screen.html'),
+    comments: join(dir, 'screen.comments.json'),
+    annotations: join(dir, 'screen.annotations.svg'),
+    meta: join(dir, 'screen.meta.json'),
+    css: join(dir, 'screen.css'),
+  };
+}
+
+describe('docIsEmpty', () => {
+  test('true for a fresh doc, false once any type is populated', () => {
+    const doc = new Y.Doc();
+    expect(docIsEmpty(doc)).toBe(true);
+    doc.getArray(Y_TYPES.comments).push([{ id: 'c1' }]);
+    expect(docIsEmpty(doc)).toBe(false);
+  });
+});
+
+describe('migrateSeed — adopt (hub was empty)', () => {
+  test('seeds an empty doc from local files and reports local-adopt', () => {
+    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 });
+
+    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)', () => {
+    const doc = new Y.Doc();
+    expect(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', () => {
+    const p = paths();
+    writeFileSync(
+      p.comments,
+      JSON.stringify([
+        { id: 'c1', text: 'x' },
+        { id: 'c2', text: 'y' },
+      ])
+    );
+
+    const doc = new Y.Doc();
+    expect(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(doc.getArray(Y_TYPES.comments).toArray()).toEqual([
+      { id: 'c1', text: 'x' },
+      { id: 'c2', text: 'y' },
+    ]);
+  });
+});
+
+describe('room file-seed disable (the other half of the Risk-1 fix)', () => {
+  test('persistence.seed is a no-op for a pinned slug — never touches api or the doc', async () => {
+    let apiCalled = false;
+    // Minimal api stub; seed must short-circuit before reaching it.
+    const api = {
+      loadCommentsForFile: async () => {
+        apiCalled = true;
+        return [];
+      },
+      loadAnnotations: async () => {
+        apiCalled = true;
+        return null;
+      },
+    } as unknown as import('../api.ts').Api;
+    const ctx = { paths: { designRoot: dir } } as unknown as Context;
+
+    const persistence = createPersistence({
+      ctx,
+      api,
+      fileForSlug: async () => 'ui/x.html',
+      // Mirrors createCollab's predicate: don't seed a pinned (provider-attached)
+      // slug under sharedDoc — the migrate-seed + provider own population.
+      shouldSeed: (slug) => slug !== 'pinned',
+    });
+
+    const doc = new Y.Doc();
+    await persistence.seed('pinned', doc);
+    // Returned before touching the api or mutating the doc → no duplicate items
+    // can be introduced by the file-seed after the migrate-seed ran.
+    expect(apiCalled).toBe(false);
+    expect(docIsEmpty(doc)).toBe(true);
+  });
+});
+
+describe('migrateSeed — hub-wins (the duplication trap avoided)', () => {
+  test('a doc already holding hub comments is NOT merged with the local file → no dup', () => {
+    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' }]));
+
+    // …but the doc already received it from the hub (a DIFFERENT CRDT item).
+    const doc = new Y.Doc();
+    applyCommentsToDoc(doc, [{ id: 'c1', text: 'from hub' }], 'hub');
+
+    const result = migrateSeed({ slug: 's', doc, paths: p });
+
+    // Hub wins; the local file is NOT pushed as a second item — exactly ONE c1.
+    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', () => {
+    const p = paths();
+    writeFileSync(p.html, '<main>LOCAL divergent</main>');
+    writeFileSync(p.comments, JSON.stringify([{ id: 'local' }]));
+
+    const doc = new Y.Doc();
+    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 });
+
+    expect(result).toBe('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');
+  });
+});