@1agh/maude 1.0.11 → 1.2.0

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

@@ -1,265 +0,0 @@
-// 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 apps/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 {
-  applyCommentsToDoc,
-  applyCssToDoc,
-  applyHtmlToDoc,
-  applyMetaToDoc,
-  Y_SYNC_TYPES,
-} 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/apps/studio/test/shared-doc-foundation.test.ts

@@ -1,63 +0,0 @@
-// 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);
-  });
-});