@1agh/maude 1.2.0 → 1.3.1

package/apps/studio/collab/awareness-bridge.ts

@@ -27,8 +27,45 @@
 // originating clientID — the random 32-bit ids make local↔remote collisions
 // negligible.
 
+import * as encoding from 'lib0/encoding';
 import type { Awareness } from 'y-protocols/awareness';
-import { applyAwarenessUpdate, encodeAwarenessUpdate } from 'y-protocols/awareness';
+import {
+  applyAwarenessUpdate,
+  encodeAwarenessUpdate,
+  removeAwarenessStates,
+} from 'y-protocols/awareness';
+
+/**
+ * A departed relayed client, as the hub can carry it.
+ *
+ * A peer leaving is a REMOVAL — a null awareness state. The hub (Hocuspocus 4)
+ * runs every incoming awareness frame through a scratch Awareness for its
+ * `beforeHandleAwareness` hook and re-encodes only the states that scratch
+ * still HOLDS, so a null state is dropped on the way in: a tab closing behind
+ * this studio never left anyone else's presence until the 30 s awareness
+ * timeout (plan T31/L19). The one thing it forwards is a state, so a departure
+ * crosses as this marker with a newer clock; every bridge turns it back into a
+ * real removal on its room. It carries no `name`, so a client that predates
+ * the marker drops it at the trust boundary (`sanitizeForeignState`) instead
+ * of drawing a nameless avatar.
+ */
+export const DEPARTED = Object.freeze({ __left: true });
+
+function isDeparted(state: unknown): boolean {
+  return !!state && typeof state === 'object' && (state as { __left?: unknown }).__left === true;
+}
+
+/** Encode a departure for each of `clients`, one clock past what `from` knows. */
+function encodeDepartures(from: Awareness, clients: readonly number[]): Uint8Array {
+  const enc = encoding.createEncoder();
+  encoding.writeVarUint(enc, clients.length);
+  for (const clientID of clients) {
+    encoding.writeVarUint(enc, clientID);
+    encoding.writeVarUint(enc, (from.meta.get(clientID)?.clock ?? 0) + 1);
+    encoding.writeVarString(enc, JSON.stringify(DEPARTED));
+  }
+  return encoding.toUint8Array(enc);
+}
 
 interface AwarenessChange {
   added: number[];
@@ -49,22 +86,36 @@ export function bridgeAwareness(a: Awareness, b: Awareness): () => void {
   // so it relays; a change this bridge applied carries BRIDGE, so it stops.
   const BRIDGE = { awarenessBridge: true };
 
-  function makeRelay(from: Awareness, to: Awareness) {
-    return ({ added, updated, removed }: AwarenessChange, origin: unknown) => {
-      if (origin === BRIDGE) return;
-      const changed = added.concat(updated, removed);
-      if (changed.length === 0) return;
-      applyAwarenessUpdate(to, encodeAwarenessUpdate(from, changed), BRIDGE);
-    };
-  }
-
-  const aToB = makeRelay(a, b);
-  const bToA = makeRelay(b, a);
+  // Room → hub. A client that left the room leaves as a DEPARTED marker (see
+  // above) — never as the null state the hub would drop. Everything else
+  // relays as it is.
+  const aToB = ({ added, updated, removed }: AwarenessChange, origin: unknown) => {
+    if (origin === BRIDGE) return;
+    const present = added.concat(updated);
+    if (present.length > 0) applyAwarenessUpdate(b, encodeAwarenessUpdate(a, present), BRIDGE);
+    const gone = removed.filter((id) => id !== b.clientID && b.getStates().has(id));
+    if (gone.length > 0) applyAwarenessUpdate(b, encodeDepartures(b, gone), BRIDGE);
+  };
+  // Hub → room. A DEPARTED marker is a removal here; a real removal (the hub's
+  // own timeout, a peer's socket closing) relays as ever.
+  const bToA = ({ added, updated, removed }: AwarenessChange, origin: unknown) => {
+    if (origin === BRIDGE) return;
+    const states = b.getStates();
+    const departed = added.concat(updated).filter((id) => isDeparted(states.get(id)));
+    const live = added.concat(updated).filter((id) => !isDeparted(states.get(id)));
+    const changed = live.concat(removed);
+    if (changed.length > 0) applyAwarenessUpdate(a, encodeAwarenessUpdate(b, changed), BRIDGE);
+    const leaving = departed.filter((id) => a.getStates().has(id));
+    if (leaving.length > 0) removeAwarenessStates(a, leaving, BRIDGE);
+  };
 
-  // Initial state exchange — push each side's current states to the other.
+  // Initial state exchange — push each side's current states to the other
+  // (departed markers are not a presence).
   const aClients = Array.from(a.getStates().keys());
   if (aClients.length > 0) applyAwarenessUpdate(b, encodeAwarenessUpdate(a, aClients), BRIDGE);
-  const bClients = Array.from(b.getStates().keys());
+  const bClients = Array.from(b.getStates().entries())
+    .filter(([, state]) => !isDeparted(state))
+    .map(([id]) => id);
   if (bClients.length > 0) applyAwarenessUpdate(a, encodeAwarenessUpdate(b, bClients), BRIDGE);
 
   a.on('update', aToB);

package/apps/studio/collab/index.ts

@@ -64,6 +64,10 @@ export function createCollab(ctx: Context, api: Api): Collab {
     fileForSlug,
     shouldSeed: (slug) => !(ctx.sharedDoc && registryRef?.isPinned(slug)),
   });
+  // Accepted revisions: browser writes to a synced canvas's room are refused
+  // (the room doc is the hub's accepted replica). Asked per frame — the save
+  // mode can change while the studio runs.
+  persistence.acceptedMode = () => ctx.syncControl?.current?.()?.acceptedMode?.() === true;
   const registry = createRegistry(persistence);
   registryRef = registry;
 

package/apps/studio/collab/persistence.ts

@@ -284,7 +284,11 @@ export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
     const svg = map.get('svg');
     if (typeof svg === 'string' && svg) {
       if (withinCap(slug, 'annotations', svg, MAX_ANNOTATIONS_BYTES)) {
-        await api.saveAnnotations(file, svg);
+        // Projection must never re-enter onAnnotationsChanged: an old flush
+        // finishing after a new edit otherwise republishes the old SVG and
+        // rolls back every peer. The API checks freshness after async IO and
+        // before its atomic rename; a later doc update schedules a new flush.
+        await api.projectAnnotations(file, svg, () => map.get('svg') === svg);
       }
     }
   }

package/apps/studio/collab/registry.ts

@@ -8,6 +8,7 @@
 
 import type { Awareness } from 'y-protocols/awareness';
 
+import { ANNOTATION_WRITE_ID, validAnnotationWriteId } from '../annotations-sync.ts';
 import { applyCommentsToDoc } from '../sync/codec.ts';
 import { bridgeAwareness } from './awareness-bridge.ts';
 import { Y_TYPES } from './persistence.ts';
@@ -52,7 +53,7 @@ export interface Registry {
    * post-write SVG; the room replaces `Y.Map.svg` so collab peers see the
    * updated stroke set without waiting for a cold-open re-seed.
    */
-  syncRoomFromAnnotations(slug: string, svg: string): void;
+  syncRoomFromAnnotations(slug: string, svg: string, writeId?: string): void;
   /**
    * Phase 30 — project agent editing-presence onto a slug's room awareness so
    * it crosses the hub (the loopback `ai-activity` bus event does not). `null`
@@ -192,13 +193,18 @@ export function createRegistry(callbacks: RoomCallbacks): Registry {
     applyCommentsToDoc(room.doc, comments as unknown[], 'inspector-write');
   }
 
-  function syncRoomFromAnnotations(slug: string, svg: string): void {
+  function syncRoomFromAnnotations(slug: string, svg: string, writeId?: string): void {
     const room = rooms.get(slug);
     if (!room) return;
     const map = room.doc.getMap<string>(Y_TYPES.annotations);
-    if (map.get('svg') === svg) return; // no-op guard — same rationale as comments
+    // Identical disk notifications remain no-ops. A new UI operation may
+    // deliberately restore identical content while an author has pending work.
+    const id = validAnnotationWriteId(writeId) ? writeId : undefined;
+    if (map.get('svg') === svg && (!id || map.get(ANNOTATION_WRITE_ID) === id)) return;
     room.doc.transact(() => {
       map.set('svg', svg);
+      if (id) map.set(ANNOTATION_WRITE_ID, id);
+      else map.delete(ANNOTATION_WRITE_ID);
     }, 'inspector-write');
   }
 

package/apps/studio/collab/room.ts

@@ -77,6 +77,15 @@ export interface RoomCallbacks {
    * the seeded state.
    */
   seed(slug: string, doc: Y.Doc): Promise<void> | void;
+
+  /**
+   * Accepted revisions (DDR-241 §7): while true, this room's document is a
+   * replica of the project's accepted state — no browser connection may write
+   * a persistent lane into it (the hub would drop it and the replica would
+   * diverge). Comments and annotations go through the API as proposals.
+   * Awareness is unaffected. Optional; absent means false.
+   */
+  acceptedMode?: () => boolean;
 }
 
 export interface Room {
@@ -216,6 +225,8 @@ export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
    */
   function refusedLanes(conn: RoomConn, roots: ReadonlySet<string>): string[] {
     const refused: string[] = [];
+    // Accepted revisions: every persistent lane is the hub's to change.
+    if (callbacks.acceptedMode?.()) return [...roots];
     for (const r of roots) {
       if (conn.realm === 'canvas' && (isBodyLane(r) || r === '<unresolved>')) {
         refused.push(r);
@@ -255,7 +266,7 @@ export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
       gateRefusalCount += 1;
       discardMirror();
       console.warn(
-        `[collab/${slug}] origin gate REFUSED a ${conn.readOnly ? 'read-only' : 'canvas-realm'} ` +
+        `[collab/${slug}] origin gate REFUSED a ${callbacks.acceptedMode?.() ? 'accepted-replica' : conn.readOnly ? 'read-only' : 'canvas-realm'} ` +
           `sync frame (lanes: ${refused.join(', ') || 'unclassifiable'}). ` +
           (conn.readOnly
             ? 'A viewer-role socket may only write comments — role matrix, cloud collab lane.'
@@ -351,7 +362,7 @@ export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
   }
 
   function receive(conn: RoomConn, payload: Uint8Array): void {
-    if (conn.realm === 'canvas' || conn.readOnly === true) {
+    if (conn.realm === 'canvas' || conn.readOnly === true || callbacks.acceptedMode?.()) {
       receiveGated(conn, payload);
       return;
     }

package/apps/studio/context.ts

@@ -259,6 +259,65 @@ export interface Context {
     current?(): {
       cancelAssetSweep(): boolean;
       retireForMove?(fromSlug: string, toRel: string): Promise<boolean>;
+      /** Accepted-revisions mode (DDR-241) — see SyncRuntime.proposeLane. */
+      proposeLane?(
+        slug: string,
+        lane: 'comments' | 'annotations' | 'meta',
+        text: string,
+        opts?: { baseText?: string; writeId?: string }
+      ): Promise<{ status: 'accepted' | 'rejected'; code?: string }> | null;
+      /** Accepted-revisions mode (DDR-241) — see SyncRuntime.proposeFolder. */
+      proposeFolder?(
+        op:
+          | { op: 'dir.create'; path: string }
+          | { op: 'dir.delete'; path: string }
+          | { op: 'dir.move'; from: string; to: string }
+      ): Promise<{ status: 'accepted' | 'rejected'; code?: string; queued?: boolean }> | null;
+      acceptedMode?(): boolean;
+      acceptedHistory?(q: {
+        limit?: number;
+        before?: number | null;
+        path?: string | null;
+      }): Promise<unknown[] | null>;
+      acceptedVersion?(repoRel: string, revision: number): Promise<string | null>;
+      acceptedRestore?(
+        repoRel: string,
+        revision: number
+      ): Promise<{ status: 'accepted' | 'rejected'; code?: string; queued?: boolean } | null>;
+      acceptedUndo?(
+        actionId: string,
+        redo?: boolean
+      ): Promise<{
+        status: 'accepted' | 'rejected';
+        code?: string;
+        queued?: boolean;
+        actionId?: string;
+      } | null>;
+      acceptedActionForContent?(repoRel: string, content: string): string | null;
+      prepareOffline?(): Promise<{
+        complete: boolean;
+        pulled: number;
+        passes: number;
+        failed: number;
+      } | null>;
+      conflictVersions?(
+        repoRel: string
+      ): { slug: string; mine: string | null; theirs: string } | null;
+      resolveConflict?(
+        repoRel: string,
+        choice: 'mine' | 'theirs'
+      ): Promise<{ status: 'accepted' | 'rejected' | 'taken'; code?: string } | null>;
+      /** T16 — AI action boundaries (see sync/action-stage.ts). */
+      beginAiAction?(key: string, label: string): void;
+      endAiAction?(
+        key: string,
+        outcome: 'done' | 'failed'
+      ): Promise<{ status: 'accepted' | 'rejected'; code?: string } | null>;
+      resolveAiAction?(choice: 'publish' | 'discard'): Promise<{
+        status: 'accepted' | 'rejected' | 'discarded';
+        code?: string;
+        canvases?: number;
+      } | null>;
     } | null;
   };
 }