@1agh/maude 0.60.7 → 1.0.3

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

@@ -0,0 +1,117 @@
+// The cell child's file-event wiring — Sync v2 Increment 2/3 (DDR-226 §4/§6).
+//
+// The doorbell, both buttons, assembled once at boot:
+//
+//   resolveCellCtl      → do we have a loopback hub and a token? (workspace mode)
+//   createCtlProvider   → hold the read-only `maude.files` channel open
+//   createCtlHealer     → hub → child: poke ⇒ read the journal ⇒ emit the
+//                         `fs:any` the container's watcher owed us
+//   createCellWriteNudge → child → hub: we wrote ⇒ name the paths ⇒ the hub
+//                         re-reads its own disk and journals them
+//
+// The two directions are deliberately symmetric and deliberately unequal in
+// what they carry: the hub's frame carries a head and no path (DDR-054 — a path
+// would be a path the hub chose), and the child's carries paths and no content
+// (the hub re-stats and re-hashes for itself). Neither end can make the other
+// believe something about bytes it did not look at.
+//
+// Downstream of the heal, everything is machinery that already exists:
+// `fs:any` → `createHmrBroadcaster` → `canvas-hmr {mode:'asset'|'css'|'module'}`
+// → the iframe repoints a broken `<img>` (DDR-224) or swaps a stylesheet. No new
+// UI path, no new reload semantics.
+//
+// GATED ON WORKSPACE MODE, NOT ON CELL PAIRING — the whole point. Pairing is a
+// one-tenant pilot allowlist; the watcher gap is on every cell. See the header
+// of `ctl-provider.ts` for why the pairing preconditions do not apply to a
+// read-only stateless channel.
+//
+// Locally this never starts: outside a container `fs.watch` fires and a second
+// event source would double-reload every canvas on every edit, exactly the
+// reason `createContainerWriteBridge` carries the same gate.
+
+import type { Context } from '../context.ts';
+import { createCellWriteNudge } from './cell-write-nudge.ts';
+import { createCtlHealer } from './ctl-heal.ts';
+import { createCtlProvider, resolveCellCtl } from './ctl-provider.ts';
+
+export interface CellFileEvents {
+  stop(): void;
+  /** Pokes received on the channel. */
+  received(): number;
+  /** Paths announced onward as `fs:any`. */
+  healed(): number;
+  /** Nudge requests the hub accepted. */
+  nudged(): number;
+  /** Paths named in those requests. */
+  nudgedPaths(): number;
+}
+
+/**
+ * Start the hub→child file-event bridge. Returns null when this process is not
+ * a cell studio child (which is every desktop, and every local dev server).
+ *
+ * Never throws: the studio must start whether or not it has a doorbell.
+ */
+export function startCellFileEvents(
+  ctx: Context,
+  env: Record<string, string | undefined> = process.env
+): CellFileEvents | null {
+  const target = resolveCellCtl(env);
+  if (!target) return null;
+
+  const nudge = createCellWriteNudge({
+    hubUrl: target.url,
+    token: target.token,
+  });
+
+  const healer = createCtlHealer({
+    hubUrl: target.url,
+    token: target.token,
+    // The one side effect: announce a path onto the bus. Nothing here writes a
+    // file, and nothing here trusts the hub's row beyond its shape — the
+    // canvas layer re-reads the real disk to decide what to do about it.
+    //
+    // The mute is what stops us telling the hub a fact it just told us. It is
+    // not a loop guard — `recordWrite` is a no-op on identical bytes, so the
+    // echo would die on its own — it is simply not paying for the round trip.
+    emit: (rel) => {
+      nudge.mute(rel);
+      ctx.bus.emit('fs:any', rel);
+    },
+  });
+
+  // Baseline the heal cursor from the hub's head BEFORE the first poke — see
+  // `anchor`. Fire-and-forget: the studio must start whether or not the hub
+  // answers, and an unanchored healer still works the way it always did.
+  void healer.anchor();
+
+  const provider = createCtlProvider({
+    url: target.url,
+    token: target.token,
+    onPoke: (head) => healer.onPoke(head),
+  });
+
+  // Every write this process makes surfaces here, because both synthetic-event
+  // sources (`createContainerWriteBridge` off `activity:suppress`, and
+  // `announceWrite` off the projector) converge on `fs:any`. See the module
+  // header for why that is the complete set and why incompleteness would only
+  // cost latency.
+  const offFsAny = ctx.bus.on('fs:any', (rel: string) => nudge.note(rel));
+
+  console.log(
+    '[sync/ctl] file-event channel attached to this cell’s own hub — hub-process writes heal open canvases without a reload, and writes made here reach the journal at once instead of on the walk-import belt.'
+  );
+
+  return {
+    stop() {
+      offFsAny();
+      provider.stop();
+      healer.stop();
+      nudge.stop();
+    },
+    received: () => provider.received(),
+    healed: () => healer.healed(),
+    nudged: () => nudge.sent(),
+    nudgedPaths: () => nudge.named(),
+  };
+}

package/apps/studio/sync/cell-pairing.ts

@@ -65,11 +65,25 @@ export interface CellPairingVerdict {
   detail?: string;
 }
 
-/** Env truthiness, matching `server.ts`'s MAUDE_SHARED_DOC parsing exactly. */
+/** Env truthiness for the opt-in interlocks below (explicit `1`-style value). */
 function on(value: string | undefined): boolean {
   return /^(1|true|on|yes)$/i.test(value ?? '');
 }
 
+/**
+ * Is the single-shared-doc model enabled? — DEFAULT ON (the DDR-064 cutover,
+ * Sync v2 Increment 7). Only an explicit falsy value opts a machine back onto
+ * the proven two-doc path, and that opt-out IS the rollback for this release:
+ * both paths coexist, nothing is deleted, `MAUDE_SHARED_DOC=0` flips back.
+ *
+ * ONE parser, exported — `server.ts` and the pairing gate used to carry
+ * byte-identical mirrors of the opt-in regex, and a default flip is exactly
+ * the change that would have let them drift.
+ */
+export function sharedDocEnabled(env: Record<string, string | undefined> = process.env): boolean {
+  return !/^(0|false|off|no)$/i.test(env.MAUDE_SHARED_DOC ?? '');
+}
+
 /**
  * Strip control characters and cap length before a value reaches a log line.
  *
@@ -159,14 +173,15 @@ export function resolveCellPairing(
     };
   }
 
-  if (!on(env.MAUDE_SHARED_DOC)) {
+  if (!sharedDocEnabled(env)) {
     return {
       pairing: null,
       refusal: 'shared-doc-off',
       detail:
-        'refusing to pair without MAUDE_SHARED_DOC=1 — pairing IS the single-shared-doc ' +
-        'model (DDR-064). Without it the loopback provider would open a second Y.Doc per ' +
-        'canvas beside the browser room, which is the two-doc world pairing exists to end.',
+        'refusing to pair with MAUDE_SHARED_DOC explicitly off — pairing IS the ' +
+        'single-shared-doc model (DDR-064). Without it the loopback provider would open a ' +
+        'second Y.Doc per canvas beside the browser room, which is the two-doc world ' +
+        'pairing exists to end.',
     };
   }
 

package/apps/studio/sync/cell-write-nudge.ts

@@ -0,0 +1,244 @@
+// The doorbell's other button — the cell child telling its hub it wrote.
+//
+// Increment 3 shipped `POST /api/journal/report` and nothing that calls it. The
+// asymmetry that left is the one a user actually feels:
+//
+//   desktop → cloud   a peer PUTs through the write door, the door hooks the
+//                     journal synchronously, the hub pokes, peers pull. Seconds.
+//   cloud → desktop   the cell's OWN studio child writes straight to the shared
+//                     checkout. No door, no hook, no row — so the hub does not
+//                     know, cannot poke, and the change waits for the 15-minute
+//                     walk-import belt.
+//
+// Both halves "work"; only one is prompt, and that reads as "sync is broken"
+// because a person drops an image in the cloud and it is not on their laptop
+// ten minutes later. Observed live: `assets/2e32c88c.png` written at 14:45,
+// journalled at 14:55 with `source: walk-import`.
+//
+// ── Why a nudge and not a report ───────────────────────────────────────────
+//
+// This carries PATHS ONLY. It cannot state a hash, a size, a class, or a
+// deletion, because the hub re-stats and re-hashes its own disk for every path
+// it is handed (`journal.recordWrite`). That is what makes it safe to accept
+// from a process the hub supervises but does not trust to speak about content —
+// and it is why being INCOMPLETE here is a latency bug and never a correctness
+// one. `walk-import` remains the backstop it always was.
+//
+// ── Why `fs:any` is the right input ────────────────────────────────────────
+//
+// A cell's recursive `fs.watch` does not fire for atomic tmp+rename writes, so
+// there is no watcher to subscribe to. But the studio already had to solve
+// exactly this for hot-reload, and the answer it landed on is a single bus
+// event: `createContainerWriteBridge` synthesises `fs:any` from the
+// `activity:suppress` every API write path arms, and `announceWrite` does the
+// same for the doc→file projector, which arms nothing. Between them they are
+// the complete set of writes this process makes — which is the same
+// completeness argument the HMR path already stakes itself on. Subscribing to
+// their common output means this module needs no new instrumentation at any
+// write site, and a future write path that remembers to hot-reload gets a
+// journal row for free.
+//
+// ── The one thing it must not do ───────────────────────────────────────────
+//
+// `createCtlHealer` emits `fs:any` too, for paths the HUB just told us about.
+// Nudging those back is harmless — same bytes, same hash, `recordWrite` is a
+// no-op, no row, no poke, so it cannot loop — but it is a request per healed
+// path for a fact the hub stated in the first place. `mute()` drops that echo
+// at the source instead of paying for it.
+
+import { isProjectFileShape, isRuntimeStateRel } from './file-membership.ts';
+
+/** Collect a burst of writes into one request. */
+const COALESCE_MS = 250;
+
+/**
+ * How long a healed path stays muted. Long enough to cover the healer's own
+ * `fs:any` (immediate) and the coalesce window behind it; short enough that a
+ * genuine local edit to a file we just pulled still nudges.
+ */
+const MUTE_MS = 1_500;
+
+/** The route's own ceiling (`MAX_NUDGE_PATHS`). Batches split at it. */
+const MAX_PATHS_PER_NUDGE = 64;
+
+export interface CellWriteNudgeOptions {
+  hubUrl: string;
+  token: string;
+  fetchImpl?: typeof fetch;
+  log?: Pick<Console, 'log' | 'warn' | 'error'>;
+  coalesceMs?: number;
+  muteMs?: number;
+  setTimeoutImpl?: typeof setTimeout;
+  clearTimeoutImpl?: typeof clearTimeout;
+  /** Injected in tests. Defaults to `Date.now`. */
+  now?: () => number;
+}
+
+export interface CellWriteNudge {
+  /** A path this process wrote. Filtered, coalesced, then named in a nudge. */
+  note(rel: string): void;
+  /** This path came FROM the hub — do not tell the hub about it. */
+  mute(rel: string): void;
+  /** Send whatever is pending now (boot, tests, shutdown). */
+  flush(): Promise<void>;
+  stop(): void;
+  /** Requests that got a 2xx — the sender half of the honesty counters. */
+  sent(): number;
+  /** Paths named across all requests. */
+  named(): number;
+  /** Paths dropped as hub echoes. */
+  muted(): number;
+  /** Consecutive failed requests. Non-zero and climbing means the hub is gone. */
+  failures(): number;
+}
+
+/**
+ * Build the nudge sender.
+ *
+ * Never throws and never rejects: a hub that refuses the nudge costs the
+ * freshness this module exists to buy, and nothing else. The child keeps
+ * serving, the checkout keeps its bytes, and the reconciler still finds the
+ * drift on its own belt.
+ */
+export function createCellWriteNudge(opts: CellWriteNudgeOptions): CellWriteNudge {
+  const log = opts.log ?? console;
+  const coalesceMs = opts.coalesceMs ?? COALESCE_MS;
+  const muteMs = opts.muteMs ?? MUTE_MS;
+  const setTimeoutImpl = opts.setTimeoutImpl ?? setTimeout;
+  const clearTimeoutImpl = opts.clearTimeoutImpl ?? clearTimeout;
+  const now = opts.now ?? Date.now;
+  const doFetch = opts.fetchImpl ?? fetch;
+  const url = `${opts.hubUrl.replace(/\/+$/, '')}/api/journal/report`;
+
+  const pending = new Set<string>();
+  const mutedUntil = new Map<string, number>();
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let inFlight: Promise<void> | null = null;
+  let stopped = false;
+  let sent = 0;
+  let named = 0;
+  let muted = 0;
+  let failures = 0;
+  /** Log the first failure at error, the rest at debug — one hub outage is one line. */
+  let warnedFailure = false;
+
+  function sweepMutes(at: number): void {
+    for (const [rel, until] of mutedUntil) {
+      if (until <= at) mutedUntil.delete(rel);
+    }
+  }
+
+  async function postOnce(paths: string[]): Promise<boolean> {
+    try {
+      const res = await doFetch(url, {
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${opts.token}`,
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify({ paths }),
+      });
+      // The answer is `{ noted }` and deliberately says nothing about what
+      // landed (it would be an existence oracle over the checkout). So the ONLY
+      // thing worth reading here is the status.
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  async function drain(): Promise<void> {
+    if (stopped || pending.size === 0) return;
+    const batch = [...pending];
+    pending.clear();
+    for (let i = 0; i < batch.length; i += MAX_PATHS_PER_NUDGE) {
+      const slice = batch.slice(i, i + MAX_PATHS_PER_NUDGE);
+      const ok = await postOnce(slice);
+      if (ok) {
+        sent += 1;
+        named += slice.length;
+        failures = 0;
+        warnedFailure = false;
+        continue;
+      }
+      failures += 1;
+      if (!warnedFailure) {
+        warnedFailure = true;
+        log.warn?.(
+          `[sync/nudge] could not tell the hub about ${slice.length} write(s) — it will find them on the walk-import belt instead. Changes made here reach peers late until this recovers.`
+        );
+      }
+      // A dropped nudge is latency, not loss: `walk-import` still finds the
+      // drift. Re-queueing a failed batch forever would turn a hub restart into
+      // an unbounded retry storm against a route that is rate-limited, so the
+      // paths go and the backstop takes it from here.
+    }
+  }
+
+  function schedule(): void {
+    if (stopped || timer !== null) return;
+    timer = setTimeoutImpl(() => {
+      timer = null;
+      void flush();
+    }, coalesceMs);
+    timer.unref?.();
+  }
+
+  async function flush(): Promise<void> {
+    if (inFlight) return inFlight;
+    inFlight = drain().finally(() => {
+      inFlight = null;
+    });
+    return inFlight;
+  }
+
+  return {
+    note(rel: string): void {
+      if (stopped || typeof rel !== 'string' || rel.length === 0) return;
+      // Separators are NOT normalised here. Every `fs:any` producer already
+      // emits forward slashes (`fs-watch`, both halves of `hmr-broadcast`,
+      // `announceWrite`, the healer's journal rows), so there is nothing left to
+      // fix — and rewriting anyway would be actively wrong on POSIX, where
+      // `a\b.css` is one legal filename and `a/b.css` is a different file. Let
+      // the classifier judge what arrives, exactly as the hub will.
+      //
+      // Cheap and pure. The hub's classifier is still the authority on
+      // membership; this only keeps the obvious noise off the wire, and
+      // `_state/` alone would otherwise be most of the traffic on a busy canvas.
+      if (!isProjectFileShape(rel) || isRuntimeStateRel(rel)) return;
+      const at = now();
+      const until = mutedUntil.get(rel);
+      if (until !== undefined && until > at) {
+        mutedUntil.delete(rel);
+        muted += 1;
+        return;
+      }
+      pending.add(rel);
+      schedule();
+    },
+
+    mute(rel: string): void {
+      if (stopped || typeof rel !== 'string' || rel.length === 0) return;
+      const at = now();
+      sweepMutes(at);
+      mutedUntil.set(rel, at + muteMs);
+    },
+
+    flush,
+
+    stop(): void {
+      stopped = true;
+      if (timer !== null) {
+        clearTimeoutImpl(timer);
+        timer = null;
+      }
+      pending.clear();
+      mutedUntil.clear();
+    },
+
+    sent: () => sent,
+    named: () => named,
+    muted: () => muted,
+    failures: () => failures,
+  };
+}

package/apps/studio/sync/codec.ts

@@ -194,8 +194,8 @@ export function annotationsFromDoc(doc: Y.Doc): string | null {
  * This distinction is load-bearing for cold start (the 2026-08-14 annotations
  * eraser): the wrapper is a non-empty STRING, so every `!== ''` emptiness
  * guard let a stale hub wrapper overwrite a peer's real strokes — and with the
- * strokes went the `assets/<sha8>` references `asset-pull` scans, so freshly
- * dropped images never crossed machines. Live delete-all still materializes
+ * strokes went the `assets/<sha8>` references the asset lane pulled by, so
+ * freshly dropped images never crossed machines. Live delete-all still materializes
  * the wrapper through `writeAnnotationsIfChanged` (deletes must propagate);
  * only COLD-START decisions treat it as emptiness.
  */
@@ -256,8 +256,58 @@ function sharedMetaCanonical(meta: Record<string, unknown>): string {
   return JSON.stringify(out);
 }
 
+/**
+ * THE META LANE CAN DUPLICATE ITSELF, SO IT HAS TO BE ABLE TO HEAL.
+ *
+ * Meta is a WHOLE VALUE carried in a Y.Text, written by delete-all +
+ * insert-all. That is duplication-prone by construction, and the case is not
+ * exotic — it is the normal one: every peer holding the file tries to publish
+ * it, and two peers inserting the same string into an empty lane produce two
+ * inserts Yjs has no reason to merge. The result is
+ * `{"title":"Home"}{"title":"Home"}`: not a value, not empty, and — because
+ * every consumer runs it through `JSON.parse` and bails — indistinguishable
+ * from "this canvas has no meta".
+ *
+ * Observed live: nine canvases created on a laptop reached the hub with correct
+ * bodies and doubled meta, so a third machine syncing the project got their
+ * titles, kinds and design-system bindings dropped on the floor. Silently.
+ *
+ * Preventing every interleaving is not on offer while the lane is a Y.Text. So
+ * the lane repairs instead: a stack of IDENTICAL copies is recognised for what
+ * it is — one value, published twice — and collapses back to one. Anything else
+ * unparseable stays `null`, which routes to the existing "the doc has no
+ * opinion" path rather than to a guess.
+ */
+export function normalizeSharedMeta(raw: string | null): string | null {
+  if (raw === null || raw.length === 0) return null;
+  if (parsesAsObject(raw)) return raw;
+  // Split only at a `}{` seam — the exact shape concurrent whole-value inserts
+  // produce. A JSON string containing "}{" cannot create a false seam here,
+  // because each resulting segment must itself parse as a complete object.
+  const parts = raw.split(/(?<=\})(?=\{)/);
+  if (parts.length < 2) return null;
+  const first = parts[0] ?? '';
+  if (!parts.every((p) => p === first) || !parsesAsObject(first)) return null;
+  return first;
+}
+
+function parsesAsObject(s: string): boolean {
+  try {
+    const v = parseJsonSafe(s);
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+  } catch {
+    return false;
+  }
+}
+
 /** The synced shared-meta JSON string held in the doc, or null when unset. */
 export function metaFromDoc(doc: Y.Doc): string | null {
+  return normalizeSharedMeta(doc.getText(Y_SYNC_TYPES.meta).toString());
+}
+
+/** What the doc LITERALLY holds — for the repair path, which needs to know
+ *  that the stored text differs from the value it normalises to. */
+export function rawMetaFromDoc(doc: Y.Doc): string | null {
   const s = doc.getText(Y_SYNC_TYPES.meta).toString();
   return s.length > 0 ? s : null;
 }
@@ -283,7 +333,10 @@ export function applyMetaToDoc(doc: Y.Doc, fullMetaJson: string, origin?: unknow
     return false;
   }
   const t = doc.getText(Y_SYNC_TYPES.meta);
-  if (t.toString() === shared) return false;
+  // Compare against the NORMALISED value, not the literal text: a lane holding
+  // two identical copies already carries this exact meta, and treating it as a
+  // difference would rewrite it on every pass forever.
+  if (normalizeSharedMeta(t.toString()) === shared) return false;
   doc.transact(() => {
     if (t.length > 0) t.delete(0, t.length);
     t.insert(0, shared);
@@ -291,6 +344,30 @@ export function applyMetaToDoc(doc: Y.Doc, fullMetaJson: string, origin?: unknow
   return true;
 }
 
+/**
+ * Collapse a duplicated meta lane back to one copy.
+ *
+ * Repairing on APPLY alone is not enough — a canvas nobody edits again would
+ * keep its doubled meta forever, and a machine that syncs the project
+ * afterwards would keep dropping it. This runs on cold start, where the doc has
+ * synced and "what it holds" is a fact rather than ignorance.
+ *
+ * Returns true when it changed something. A lane that is empty, already single,
+ * or unparseable-in-some-other-way is left exactly as it is: this repairs the
+ * one shape it can prove, and guesses at nothing.
+ */
+export function repairSharedMeta(doc: Y.Doc, origin?: unknown): boolean {
+  const t = doc.getText(Y_SYNC_TYPES.meta);
+  const raw = t.toString();
+  const single = normalizeSharedMeta(raw);
+  if (single === null || single === raw) return false;
+  doc.transact(() => {
+    t.delete(0, t.length);
+    t.insert(0, single);
+  }, origin);
+  return true;
+}
+
 /**
  * Merge the synced shared-meta into a local `.meta.json` string, PRESERVING the
  * local per-user/security keys (META_LOCAL_KEYS). Shared keys become exactly
@@ -457,6 +534,81 @@ export function canvasPathFromDoc(doc: Y.Doc): string | null {
   return typeof v === 'string' && v.length > 0 ? v : null;
 }
 
+/* ------------------------------------------------------------- retirement */
+
+/**
+ * Mark this document RETIRED BY A MOVE: its canvas now lives at `toRel`, in a
+ * DIFFERENT document (the slug is derived from the path, so a moved canvas is
+ * a new document by construction — nothing can rename a Hocuspocus doc).
+ *
+ * Before this stamp existed, the pre-move document simply lived on: the hub
+ * kept materialising it at the old path, every peer's cold start saw "doc has
+ * a body, disk has no file" and resurrected it, and a moved canvas came back
+ * as a duplicate on every machine that ever synced it. Observed live: moving
+ * `shoj` into a folder on the desktop left BOTH `ui/dbucket/shoj.tsx` and a
+ * re-materialised `ui/shoj.tsx` on both machines, plus two documents on the
+ * hub.
+ *
+ * The stamp is a STATEMENT, deliberately not an empty body: emptiness is
+ * ambiguous (a crash mid-write, an unseeded doc), and DDR-223 spent a whole
+ * arc making emptiness weak. `movedTo` is unambiguous, carries WHERE the
+ * content went, and — because the content provably lives at the new path in
+ * the new document — quarantining the old file against it is safe in a way
+ * that acting on a bare deletion never is (that one stays Increment 6).
+ *
+ * Consumers:
+ *   - every materialise path treats a retired doc as WRITE-INERT — it never
+ *     lands another byte on disk and never accepts another local edit;
+ *   - the sync runtime, on SEEING the stamp arrive, releases the canvas and
+ *     quarantines the stale local copy into `_trash/` (recoverable, DDR-102's
+ *     spine) — except on the machine performing the move, which renames the
+ *     file itself;
+ *   - the hub's workspace agent quarantines the checkout copy and commits the
+ *     deletion, so the cloud tree stops listing the ghost.
+ */
+export function stampMovedTo(doc: Y.Doc, toRel: string, origin?: unknown): boolean {
+  const next = String(toRel ?? '').replace(/\\/g, '/');
+  if (!next) return false;
+  const map = doc.getMap<unknown>(Y_SYNC_TYPES.syncMeta);
+  if (map.get('movedTo') === next) return false;
+  doc.transact(() => {
+    map.set('movedTo', next);
+    map.set('movedAt', Date.now());
+    map.set('movedBy', peerLabel());
+  }, origin);
+  return true;
+}
+
+/**
+ * Un-retire a document that says it moved to where it already is.
+ *
+ * A move renames the canvas's artifacts onto the new slug, and the retirement
+ * stamp lives INSIDE the document — so any copy of the old document that reaches
+ * the new slug arrives pre-stamped "I have moved away", and every peer that
+ * opens it releases the canvas instead of syncing it. Clearing the stamp is the
+ * correction, and because it is a doc edit it travels to every peer that already
+ * believed the lie. The caller decides the "already is" part; this only writes.
+ */
+export function clearMovedTo(doc: Y.Doc, origin?: unknown): boolean {
+  const map = doc.getMap<unknown>(Y_SYNC_TYPES.syncMeta);
+  if (map.get('movedTo') === undefined) return false;
+  doc.transact(() => {
+    map.delete('movedTo');
+    map.delete('movedAt');
+    map.delete('movedBy');
+  }, origin);
+  return true;
+}
+
+/** Where a retired document says its canvas went, or null for a live one.
+ *  UNTRUSTED — a consumer that turns this into a path must validate it the
+ *  same way it validates `syncMeta.path`. Most consumers only need the
+ *  null/non-null fact. */
+export function movedToFromDoc(doc: Y.Doc): string | null {
+  const v = doc.getMap<unknown>(Y_SYNC_TYPES.syncMeta).get('movedTo');
+  return typeof v === 'string' && v.length > 0 ? v : null;
+}
+
 /* ---------------------------------------------------------------- css */
 
 /** The synced canvas CSS string held in the doc, or null when unset/empty. */