@1agh/maude 1.2.0 → 1.3.1

package/apps/studio/sync/action-stage.ts

@@ -0,0 +1,343 @@
+// AI and multi-file action boundaries — plan T16 (DDR-241).
+//
+// An agent turn (the in-app chat) or a `/design:edit` run changes several
+// files, one tool call at a time. Proposed as they land, the project would
+// accept a canvas edited against a module the agent has not written yet, and
+// an agent that fails half way would leave that half published. So while an
+// AI action is OPEN, the file changes it makes are STAGED here instead of
+// proposed: kept on disk, remembered with the value each was derived from,
+// and proposed together — one transaction, one history action — when the
+// action ends well.
+//
+// When it does not (the agent errors, is cancelled, stops at its token limit,
+// or its heartbeat goes silent) the stage is HELD: nothing is published and
+// nothing is thrown away. The person decides — publish it as it stands, or
+// discard it (the accepted version returns; the candidate stays in the
+// recovery slots). A held stage survives a restart (`_state/ai-stage.json`),
+// so a crash can never turn into a partial publish by the next cold start.
+//
+// What is staged is only a WATCHER change (a tool writing a file). An edit the
+// person makes in the UI is theirs and is proposed at once — unless it is made
+// on top of a staged file, in which case it carries the agent's unpublished
+// bytes and waits behind the stage (`dependents`), exactly as U2 waits on U1.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import type { LaneProposal, ProposalOutcome } from './projection.ts';
+import type { Operation, ProposalResult } from './transaction-client.ts';
+
+export type StageState = 'open' | 'held';
+
+export interface StagedLane {
+  slug: string;
+  doc: string;
+  lane: LaneProposal['lane'];
+  /** The value the FIRST staged change was derived from — the group's base. */
+  baseContent: string;
+  /** The latest staged value. */
+  content: string;
+  writeId?: string;
+  /** Every staged proposal's transaction id — aliased to the group's on commit. */
+  txs: string[];
+  resolvers: Array<(o: ProposalOutcome) => void>;
+}
+
+export interface StageSummary {
+  state: StageState;
+  label: string;
+  canvases: string[];
+  since: number;
+}
+
+interface Dependent {
+  send: (dependsOn: string[] | undefined) => void;
+  drop: (o: ProposalOutcome) => void;
+  dependsOn: string[];
+}
+
+export interface ActionStageOptions {
+  designRoot: string;
+  /** Send one grouped action; resolves with the final result. */
+  propose: (action: {
+    label: string;
+    kind: string;
+    operations: Operation[];
+    transactionId: string;
+  }) => Promise<ProposalResult>;
+  newTransactionId: () => string;
+  onChange?: (summary: StageSummary | null) => void;
+  log?: Pick<Console, 'log' | 'warn'>;
+  now?: () => number;
+}
+
+export function createActionStage(opts: ActionStageOptions) {
+  const log = opts.log ?? console;
+  const now = opts.now ?? Date.now;
+  const file = path.join(opts.designRoot, '_state', 'ai-stage.json');
+
+  let state: StageState | null = null;
+  let label = '';
+  let since = 0;
+  const keys = new Set<string>();
+  let failed = false;
+  const lanes = new Map<string, StagedLane>();
+  const dependents: Dependent[] = [];
+  /** A staged transaction id → the group transaction that carried it. */
+  const alias = new Map<string, string>();
+  /** Slugs a restored (held) stage covers — cold-start changes to them are staged. */
+  const restoredSlugs = new Set<string>();
+  /** Bases restored from disk after a restart: `${slug}|${lane}` → baseContent. */
+  const restoredBases = new Map<string, string>();
+
+  function summary(): StageSummary | null {
+    if (!state) return null;
+    const canvases = new Set<string>([...restoredSlugs]);
+    for (const l of lanes.values()) canvases.add(l.slug);
+    return { state, label, canvases: [...canvases].sort(), since };
+  }
+
+  function persist(): void {
+    try {
+      if (!state || (lanes.size === 0 && restoredSlugs.size === 0)) {
+        rmSync(file, { force: true });
+        return;
+      }
+      mkdirSync(path.dirname(file), { recursive: true });
+      const body = {
+        v: 1,
+        state,
+        label,
+        since,
+        lanes: [...lanes.values()].map((l) => ({
+          slug: l.slug,
+          doc: l.doc,
+          lane: l.lane,
+          baseContent: l.baseContent,
+        })),
+        restored: [...restoredBases.entries()].map(([k, baseContent]) => {
+          const [slug, lane] = k.split('|');
+          return { slug, lane, baseContent };
+        }),
+      };
+      writeFileSync(`${file}.tmp`, JSON.stringify(body));
+      renameSync(`${file}.tmp`, file);
+    } catch (err) {
+      log.warn(`[sync/ai] could not record the unfinished action: ${(err as Error).message}`);
+    }
+  }
+
+  function changed(): void {
+    persist();
+    opts.onChange?.(summary());
+  }
+
+  /** A previous process left a stage: it comes back HELD. */
+  function restore(): void {
+    if (!existsSync(file)) return;
+    try {
+      const body = JSON.parse(readFileSync(file, 'utf8')) as {
+        label?: string;
+        since?: number;
+        lanes?: { slug: string; lane: string; baseContent: string }[];
+        restored?: { slug: string; lane: string; baseContent: string }[];
+      };
+      const all = [...(body.lanes ?? []), ...(body.restored ?? [])];
+      if (all.length === 0) return;
+      state = 'held';
+      label = typeof body.label === 'string' ? body.label : 'AI edit';
+      since = typeof body.since === 'number' ? body.since : now();
+      for (const l of all) {
+        restoredSlugs.add(l.slug);
+        restoredBases.set(`${l.slug}|${l.lane}`, l.baseContent);
+      }
+      log.warn(
+        `[sync/ai] an unfinished AI edit (${label}) to ${restoredSlugs.size} canvas(es) was kept from the last session — it is not published until you choose.`
+      );
+      opts.onChange?.(summary());
+    } catch {
+      /* unreadable → nothing to restore */
+    }
+  }
+
+  function begin(key: string, nextLabel: string): void {
+    keys.add(key);
+    if (state === 'open') return;
+    if (state === 'held') {
+      // A new action on top of an unfinished one continues it: its files may
+      // already carry the held bytes. It stays one decision for the person.
+      state = 'open';
+      failed = false;
+      changed();
+      return;
+    }
+    state = 'open';
+    failed = false;
+    label = nextLabel.slice(0, 120) || 'AI edit';
+    since = now();
+    changed();
+  }
+
+  /** Should this proposal be staged instead of sent? */
+  function captures(slug: string, stageable: boolean): boolean {
+    if (!stageable || !state) return false;
+    return (
+      state === 'open' ||
+      restoredSlugs.has(slug) ||
+      [...lanes.values()].some((l) => l.slug === slug)
+    );
+  }
+
+  function capture(slug: string, doc: string, p: LaneProposal): Promise<ProposalOutcome> {
+    const k = `${slug}|${p.lane}`;
+    return new Promise((resolve) => {
+      const existing = lanes.get(k);
+      if (existing) {
+        existing.content = p.content;
+        existing.txs.push(p.transactionId);
+        existing.resolvers.push(resolve);
+        if (p.writeId) existing.writeId = p.writeId;
+      } else {
+        lanes.set(k, {
+          slug,
+          doc,
+          lane: p.lane,
+          baseContent: restoredBases.get(k) ?? p.baseContent,
+          content: p.content,
+          ...(p.writeId ? { writeId: p.writeId } : {}),
+          txs: [p.transactionId],
+          resolvers: [resolve],
+        });
+        changed();
+      }
+    });
+  }
+
+  function isStagedTx(id: string): boolean {
+    for (const l of lanes.values()) if (l.txs.includes(id)) return true;
+    return false;
+  }
+
+  /** A non-staged proposal authored on top of a staged one waits behind the stage. */
+  function holdsDependency(dependsOn: string[] | undefined): boolean {
+    return !!dependsOn?.some((id) => isStagedTx(id));
+  }
+
+  function wait(dep: Dependent): void {
+    dependents.push(dep);
+  }
+
+  /** Rewrite a dependency on a staged proposal to the group that carried it. */
+  function mapDeps(dependsOn: string[] | undefined): string[] | undefined {
+    if (!dependsOn?.length) return dependsOn;
+    return dependsOn.map((id) => alias.get(id) ?? id);
+  }
+
+  function laneOutcome(r: ProposalResult, l: StagedLane): ProposalOutcome {
+    const mine = r.doc === l.doc && r.lane === l.lane;
+    return {
+      status: r.status,
+      ...(r.code ? { code: r.code } : {}),
+      ...(mine && typeof r.head === 'string' ? { head: r.head } : {}),
+      ...(typeof r.actionId === 'string' ? { actionId: r.actionId } : {}),
+    };
+  }
+
+  function reset(): void {
+    state = null;
+    label = '';
+    since = 0;
+    keys.clear();
+    failed = false;
+    lanes.clear();
+    restoredSlugs.clear();
+    restoredBases.clear();
+    changed();
+  }
+
+  /** Propose everything staged as ONE action. */
+  async function publish(): Promise<ProposalResult | null> {
+    if (!state) return null;
+    const staged = [...lanes.values()];
+    const waiting = dependents.splice(0);
+    const groupLabel = label || 'AI edit';
+    if (staged.length === 0) {
+      reset();
+      for (const d of waiting) d.send(mapDeps(d.dependsOn));
+      return null;
+    }
+    const transactionId = opts.newTransactionId();
+    for (const l of staged) for (const tx of l.txs) alias.set(tx, transactionId);
+    const operations: Operation[] = staged.map((l) => ({
+      op: 'lane.replace',
+      doc: l.doc,
+      lane: l.lane,
+      content: l.content,
+      baseContent: l.baseContent,
+      ...(l.writeId ? { writeId: l.writeId } : {}),
+    }));
+    // The stage is closed before the answer: the next action starts clean,
+    // and the dependents go out right behind the group (same ordered outbox).
+    reset();
+    const sent = opts.propose({ label: groupLabel, kind: 'ai', operations, transactionId });
+    for (const d of waiting) d.send(mapDeps(d.dependsOn));
+    const r = await sent.catch((err: unknown) => {
+      const code = (err as { code?: string })?.code ?? 'retryable';
+      return { protocol: 1, status: 'rejected', code, transactionId } as ProposalResult;
+    });
+    for (const l of staged) for (const fn of l.resolvers) fn(laneOutcome(r, l));
+    log.log(
+      `[sync/ai] ${groupLabel}: ${staged.length} change(s) ${r.status === 'accepted' ? 'published as one action' : `refused (${r.code ?? 'rejected'})`}.`
+    );
+    return r;
+  }
+
+  /** End one participant. The last `done` publishes; any failure holds. */
+  async function end(key: string, outcome: 'done' | 'failed'): Promise<ProposalResult | null> {
+    if (!keys.has(key)) return null;
+    keys.delete(key);
+    if (outcome === 'failed') failed = true;
+    if (keys.size > 0 || state !== 'open') return null;
+    if (failed) {
+      state = 'held';
+      changed();
+      log.warn(
+        `[sync/ai] ${label}: the action did not finish — ${lanes.size} change(s) kept on this device, not published.`
+      );
+      return null;
+    }
+    return publish();
+  }
+
+  /** Throw the held changes away: every lane returns to the accepted version. */
+  function discard(): number {
+    if (state !== 'held') return 0;
+    const staged = [...lanes.values()];
+    const waiting = dependents.splice(0);
+    const slugs = new Set([...restoredSlugs, ...staged.map((l) => l.slug)]);
+    reset();
+    for (const l of staged)
+      for (const fn of l.resolvers) fn({ status: 'rejected', code: 'discarded' });
+    for (const d of waiting) d.drop({ status: 'rejected', code: 'discarded' });
+    return slugs.size;
+  }
+
+  return {
+    restore,
+    begin,
+    end,
+    publish,
+    discard,
+    captures,
+    capture,
+    holdsDependency,
+    wait,
+    mapDeps,
+    summary,
+    get state() {
+      return state;
+    },
+  };
+}
+
+export type ActionStage = ReturnType<typeof createActionStage>;

package/apps/studio/sync/agent.ts

@@ -52,12 +52,10 @@ import {
   cssFromDoc,
   htmlFromDoc,
   isEmptyAnnotationsSvg,
-  markSeeded,
   mergeSharedMetaIntoLocal,
   metaFromDoc,
   movedToFromDoc,
   repairSharedMeta,
-  seededByFromDoc,
   stampAnnotationsEdit,
   stampBodyEdit,
   Y_SYNC_TYPES,
@@ -66,13 +64,13 @@ import {
   decideAnnotationsColdStart,
   decideColdStart,
   decideCssColdStart,
-  isExactRepeat,
   unionCommentsById,
 } from './cold-start.ts';
 import { applyColdStart, type ColdStartSnapshotReason } from './cold-start-apply.ts';
 import { dedupeCommentsById, hasDuplicateComments } from './comment-identity.ts';
 import { type EchoGuard, hashBytes } from './echo-guard.ts';
 import type { SyncJournal } from './journal.ts';
+import { rememberSeed, repairSeedDuplication } from './seed-repair.ts';
 
 export const DOC_FLUSH_MS = 800;
 
@@ -82,7 +80,7 @@ export const DOC_FLUSH_MS = 800;
  * the cold-start race — a genuine peer edit that arrives minutes later is NEVER
  * collapsed back to our original seed. Generous relative to the hub sync RTT.
  */
-export const SEED_REPAIR_WINDOW_MS = 10_000;
+export { SEED_REPAIR_WINDOW_MS } from './seed-repair.ts';
 
 export interface CanvasSyncPaths {
   /** Absolute path to <designRoot>/<canvas>.html. */
@@ -187,18 +185,6 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
   let lastMeta: string | null = null;
   let lastCss: string | null = null;
 
-  // F1 — the content this agent pushed on `seed-local-up`, plus the deadline
-  // past which the de-dup repair stops firing. Set on seed; nulled only when the
-  // window lapses (after convergence the repair is a cheap no-op — the
-  // `=== seedInfo.x` guards short-circuit, so we don't bother clearing).
-  // Null = this agent never seeded (so it never repairs).
-  //
-  // `css` rides along with the body (issue #114): a seed writes BOTH lanes in
-  // the same breath, so both can collide with a concurrent peer's identical
-  // seed, and repairing only the body left the canvas un-buildable anyway —
-  // duplicated css is as fatal to the build as a duplicated `export default`.
-  let seedInfo: { body: string; css: string | null; until: number } | null = null;
-
   function onDocUpdate(_update: Uint8Array, updateOrigin: unknown): void {
     if (stopped) return;
     // Self-applied (we just synced from disk) — disk is already current.
@@ -246,45 +232,14 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
    * variant is an accepted follow-up, not handled in-flight.
    */
   function maybeRepairSeedDuplication(): void {
-    if (!seedInfo) return;
-    if (Date.now() > seedInfo.until) {
-      seedInfo = null;
-      return;
-    }
-    const owner = seededByFromDoc(doc);
-    if (owner === null || owner !== doc.clientID) return; // not the elected writer
-    const seeded = seedInfo;
-    const repaired: string[] = [];
-
-    const body = htmlFromDoc(doc);
-    // `=== seeded.body` → already a single copy; not an exact repeat → a
-    // divergent edit, which carries genuine bytes and belongs to the conflict
-    // path, not to a silent collapse.
-    if (body !== seeded.body && isExactRepeat(body, seeded.body)) {
-      const canonical = seeded.body;
-      doc.transact(() => {
-        if (applyHtmlToDoc(doc, canonical, origin)) stampBodyEdit(doc, origin);
-      }, origin);
-      lastHtml = canonical;
-      opts.journal?.record(slug, { bodyHash: hashBytes(canonical) });
-      repaired.push('body');
+    const repaired = repairSeedDuplication(doc, origin);
+    if (repaired.includes('body')) {
+      lastHtml = htmlFromDoc(doc);
+      opts.journal?.record(slug, { bodyHash: hashBytes(lastHtml) });
     }
-
-    // The css half of the same collision (issue #114). Same proof obligation as
-    // the body — an exact integer repeat of what WE seeded — and the same
-    // idempotence: the collapse deletes the same CRDT items on every peer that
-    // runs it, so concurrent recoveries converge instead of fighting.
-    if (paths.css && seeded.css !== null) {
-      const css = cssFromDoc(doc);
-      if (css !== null && css !== seeded.css && isExactRepeat(css, seeded.css)) {
-        const canonicalCss = seeded.css;
-        doc.transact(() => {
-          applyCssToDoc(doc, canonicalCss, origin);
-        }, origin);
-        lastCss = canonicalCss;
-        opts.journal?.record(slug, { cssHash: hashBytes(canonicalCss) });
-        repaired.push('css');
-      }
+    if (repaired.includes('css')) {
+      lastCss = cssFromDoc(doc);
+      if (lastCss !== null) opts.journal?.record(slug, { cssHash: hashBytes(lastCss) });
     }
 
     if (repaired.length > 0) {
@@ -518,9 +473,8 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
           // F1 — adopt is also a "seed local up" (first link / fresh hub); claim
           // it + arm the repair window so two peers adopting the same draft into
           // one hub at once self-heal the same way the decision-table seed does.
-          markSeeded(doc, origin);
+          rememberSeed(doc, localHtml, localCss, origin);
         }, origin);
-        seedInfo = { body: localHtml, css: localCss, until: Date.now() + SEED_REPAIR_WINDOW_MS };
       }
       if (localComments !== null) {
         const parsed = tryParseJsonArray(localComments);
@@ -575,15 +529,13 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
         if (applyHtmlToDoc(doc, body, origin)) stampBodyEdit(doc, origin);
         // F1 — claim the seed (clientID marker) in the SAME update so a
         // concurrent second seeder's merge resolves a single elected writer.
-        markSeeded(doc, origin);
+        rememberSeed(doc, body, localCss, origin);
       }, origin);
       lastHtml = body;
       // Arm the de-dup repair window: if another peer seeded the same content at
       // the same instant, the merged Y.Text will double — maybeRepairSeedDuplication
       // (on the elected owner) collapses it back during this window. `localCss`
-      // is armed too: the css lane is seeded by the same cold start a few lines
-      // below and collides identically (issue #114).
-      seedInfo = { body, css: localCss, until: Date.now() + SEED_REPAIR_WINDOW_MS };
+      // is remembered too, since it collides identically (issue #114).
       opts.journal?.record(slug, { bodyHash: hashBytes(body) });
     };
 

package/apps/studio/sync/cell-file-events.ts

@@ -89,6 +89,9 @@ export function startCellFileEvents(
     url: target.url,
     token: target.token,
     onPoke: (head) => healer.onPoke(head),
+    // The paired cell runtime does not open a second control provider. Route
+    // metadata invalidation to its bounded discovery queue, not the journal.
+    onDocuments: () => ctx.bus.emit('sync:documents-changed'),
   });
 
   // Every write this process makes surfaces here, because both synthetic-event

package/apps/studio/sync/codec.ts

@@ -1,3 +1,4 @@
+import { ANNOTATION_WRITE_ID } from '../annotations-sync.ts';
 // Y.Doc ↔ disk codecs for the bidirectional file sync agent (Phase 9 Task 4).
 //
 // The agent shuttles three classes of files between disk and the Y.Doc the
@@ -22,11 +23,11 @@
 // in the unchanged regions.
 
 import { hostname } from 'node:os';
-
+import { diffChars } from 'diff';
 import type * as Y from 'yjs';
 
 import { Y_TYPES } from '../collab/persistence.ts';
-import { commentKey } from './comment-identity.ts';
+import { commentKey, dedupeCommentsById } from './comment-identity.ts';
 import {
   MAX_ANNOTATIONS_BYTES,
   MAX_COMMENTS_BYTES,
@@ -97,8 +98,8 @@ export function htmlFromDoc(doc: Y.Doc): string {
 }
 
 /**
- * Apply `next` to one Y.Text lane as a minimal common-prefix / common-suffix
- * replace, so peers see a small op rather than a full replace.
+ * Apply `next` as bounded text hunks, preserving unchanged interior CRDT
+ * anchors as well as the common prefix/suffix (#121).
  *
  * THIS SHAPE IS A CONVERGENCE PROPERTY, NOT AN OPTIMIZATION (issue #114).
  * Collapsing a concurrency-duplicated lane — `X + X` back to `X` — comes out of
@@ -137,12 +138,37 @@ function applyTextLane(doc: Y.Doc, lane: string, next: string, origin?: unknown)
     suffix++;
   }
 
+  // Y.Text offsets are UTF-16; never leave half a surrogate outside a hunk.
+  if (prefix > 0 && /[\uD800-\uDBFF]/.test(current[prefix - 1] ?? '')) prefix--;
+  if (suffix > 0 && /[\uDC00-\uDFFF]/.test(current[current.length - suffix] ?? '')) suffix--;
   const deleteLen = current.length - prefix - suffix;
   const insertStr = next.slice(prefix, next.length - suffix);
 
+  // Keep pure inserts/deletes (especially repeat collapse) as one operation.
+  // For replacements preserve interior anchors: one prefix/suffix splice can
+  // move a concurrent insertion inside an unrelated JSX attribute (#121).
+  const changes =
+    deleteLen > 0 && insertStr.length > 0
+      ? diffChars(current.slice(prefix, current.length - suffix), insertStr, {
+          maxEditLength: 4096,
+          timeout: 50,
+        })
+      : null;
+  if (changes === undefined) throw new Error('Source diff exceeds the safe merge budget');
   doc.transact(() => {
-    if (deleteLen > 0) yText.delete(prefix, deleteLen);
-    if (insertStr.length > 0) yText.insert(prefix, insertStr);
+    if (changes) {
+      let offset = prefix;
+      for (const change of changes) {
+        if (change.removed) yText.delete(offset, change.value.length);
+        else {
+          if (change.added) yText.insert(offset, change.value);
+          offset += change.value.length;
+        }
+      }
+    } else {
+      if (deleteLen > 0) yText.delete(prefix, deleteLen);
+      if (insertStr.length > 0) yText.insert(prefix, insertStr);
+    }
   }, origin);
 
   return true;
@@ -306,6 +332,8 @@ export function applyAnnotationsToDoc(doc: Y.Doc, next: string | null, origin?:
   if (currentStr === next) return false;
 
   doc.transact(() => {
+    // A filesystem import is a new operation, never the previous UI author's echo.
+    map.delete(ANNOTATION_WRITE_ID);
     if (next === null || next === '') {
       map.delete('svg');
     } else {
@@ -389,6 +417,45 @@ function parsesAsObject(s: string): boolean {
 }
 
 /** The synced shared-meta JSON string held in the doc, or null when unset. */
+/**
+ * The canonical LANE value for a file's text — what the accepted-revisions
+ * kernel stores and what `readLaneFromDoc` returns once it is accepted
+ * (DDR-241). `null` when the file text cannot be a value of that lane.
+ */
+export function laneValueFromFile(
+  lane: 'html' | 'css' | 'meta' | 'annotations' | 'comments',
+  text: string
+): string | null {
+  if (lane === 'html' || lane === 'css' || lane === 'annotations') return text;
+  let parsed: unknown;
+  try {
+    parsed = parseJsonSafe(text);
+  } catch {
+    return null;
+  }
+  if (lane === 'meta') {
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    return sharedMetaCanonical(parsed as Record<string, unknown>);
+  }
+  if (!Array.isArray(parsed)) return null;
+  const list = dedupeCommentsById(parsed);
+  return list.length ? JSON.stringify(list) : '';
+}
+
+/** A lane's value as the accepted replica holds it (same canonical form). */
+export function readLaneFromDoc(
+  doc: Y.Doc,
+  lane: 'html' | 'css' | 'meta' | 'annotations' | 'comments'
+): string {
+  if (lane === 'html' || lane === 'css' || lane === 'meta') return doc.getText(lane).toString();
+  if (lane === 'annotations') {
+    const svg = doc.getMap<unknown>(Y_TYPES.annotations).get('svg');
+    return typeof svg === 'string' ? svg : '';
+  }
+  const list = doc.getArray<unknown>(Y_TYPES.comments).toArray();
+  return list.length ? JSON.stringify(list) : '';
+}
+
 export function metaFromDoc(doc: Y.Doc): string | null {
   return normalizeSharedMeta(doc.getText(Y_SYNC_TYPES.meta).toString());
 }

package/apps/studio/sync/ctl-provider.ts

@@ -95,6 +95,8 @@ export interface CtlProviderOptions {
   token: string;
   /** Fired with the hub's head on every well-formed poke. */
   onPoke: (head: number) => void;
+  /** Optional fast document-list invalidation; older consumers use onPoke. */
+  onDocuments?: () => void;
   documentName?: string;
   log?: Pick<Console, 'log' | 'warn' | 'error'>;
   /** Injected in tests; production builds one from `@hocuspocus/provider`. */
@@ -155,9 +157,19 @@ export function createCtlProvider(opts: CtlProviderOptions): CtlProvider {
 
   const wire = (p: CtlProviderLike): void => {
     p.on('status', (data: { status?: string }) => {
-      if (typeof data?.status === 'string') status = data.status;
+      if (typeof data?.status !== 'string') return;
+      const reconnect = data.status === 'connected' && status !== 'connected';
+      status = data.status;
+      if (reconnect && !stopped) {
+        try {
+          opts.onDocuments?.();
+        } catch (error) {
+          log.error?.(`[sync/ctl] discovery handler threw: ${(error as Error).message}`);
+        }
+      }
     });
     p.on('stateless', (data: { payload: string }) => {
+      if (stopped) return;
       const poke = parsePoke(data?.payload);
       if (poke === null) {
         malformed += 1;
@@ -172,7 +184,8 @@ export function createCtlProvider(opts: CtlProviderOptions): CtlProvider {
       }
       received += 1;
       try {
-        opts.onPoke(poke.head);
+        if (poke.documents && opts.onDocuments) opts.onDocuments();
+        else opts.onPoke(poke.head);
       } catch (err) {
         log.error?.(`[sync/ctl] poke handler threw: ${(err as Error).message}`);
       }