@1agh/maude 0.60.3 → 0.60.4

package/apps/studio/sync/index.ts

@@ -29,6 +29,7 @@ import type { Context, LinkedHub } from '../context.ts';
 import { createHistory } from '../history.ts';
 import { SYNTHETIC_FS_DELAY_MS } from '../hmr-broadcast.ts';
 import { type CanvasSyncAgent, createCanvasSyncAgent } from './agent.ts';
+import { pullAssets } from './asset-pull.ts';
 import { isPushableAssetRel } from './asset-push.ts';
 import { type AssetSweepHandle, runAssetSweep } from './asset-sweep.ts';
 import { atomicWrite } from './atomic-write.ts';
@@ -43,6 +44,7 @@ import {
 import { createRescanScheduler, diffCanvasSet, type RescanScheduler } from './discovery.ts';
 import { createDocNameResolver } from './doc-name.ts';
 import { createEchoGuard } from './echo-guard.ts';
+import { type FilePullResult, pullFiles } from './file-pull.ts';
 import { createFsReader, type FsReader } from './fs-mirror.ts';
 import { getHubRecord } from './hubs-config.ts';
 import { loadJournal, type SyncJournal } from './journal.ts';
@@ -54,11 +56,16 @@ import { createDocProjection, type DocProjection } from './projection.ts';
 import {
   describeRemoteDiff,
   diffRemoteDocs,
-  fetchRemoteDocs,
+  fetchRemoteListing,
   pullTargets,
+  type RemoteTombstone,
   resolvePulledTarget,
+  slugFromDocName,
+  stateDocumentGone,
+  tombstonedSlugs,
 } from './remote-docs.ts';
 import { createSyncStatusStore, type SyncStatusStore } from './status.ts';
+import { quarantineCanvas } from './tombstone-apply.ts';
 import { writeUntrustedMarkers } from './untrusted.ts';
 
 /** A minimum-surface stand-in for the HocuspocusProvider's runtime API. */
@@ -250,7 +257,15 @@ export interface SyncRuntime {
    * discovery without the user authorising anything.
    */
   adopt(canvases: readonly CanvasDescriptor[]): Promise<number>;
-  /** Give up canvases that left the project. Returns how many were released. */
+  /**
+   * Give up canvases that left the project. Returns how many were released.
+   *
+   * NOT A DELETION, and the distinction is the whole delete lane: this says
+   * "this machine stopped carrying it", which the project is right to ignore.
+   * Stating that a canvas is GONE travels on the `canvas-deleted` bus event that
+   * `api.ts` emits from its privileged delete route — the one signal that
+   * carries intent rather than a filesystem observation.
+   */
   release(slugs: readonly string[]): Promise<number>;
   /**
    * Run the local canvas rescan immediately instead of waiting for the debounce.
@@ -502,6 +517,16 @@ export function createSyncRuntime(
   // hub body, so a bogus/far-future stamp must not schedule a renewal at boot.
   let tokenExpiresAt: number | null = validExpiry(storedRecord?.expiresAt);
 
+  // feature-sync-file-plane — Plane B, behind its flag. The flag gates ONLY
+  // the new plane (the downward file pull here + the widened sweep inside
+  // `listPushableAssets`); with it off, behavior is today's, byte-for-byte.
+  const syncFilesOn = linkedHub.syncFiles === true || process.env.MAUDE_SYNC_FILES === '1';
+  // The owner-hub gate for `code-module` entries, decided from LOCAL state
+  // only: the role this machine's credential store vouched for at sign-in
+  // (never a hub-supplied claim), or the hub being this cell's own loopback
+  // pairing — where the hub and the checkout are the same trust domain.
+  const allowCodeModules = cellPairing !== null || storedRecord?.role === 'owner';
+
   // DDR-102 — the default factory multiplexes every provider over ONE shared
   // WebSocket per hub URL; the runtime owns its disposal (stop(), after the
   // providers detach). An injected test factory has no shared socket.
@@ -697,6 +722,9 @@ export function createSyncRuntime(
    *  `stop()`. See the block that creates it and `discovery.ts`. */
   let discoveryRescan: RescanScheduler | null = null;
   let discoveryUnsub: (() => void) | null = null;
+  /** The outbound delete-lane subscriptions — see `noteToHub`. */
+  let deletedUnsub: (() => void) | null = null;
+  let createdUnsub: (() => void) | null = null;
   /** Periodic remote-document poll — the hub-side half of discovery. */
   let remotePollTimer: ReturnType<typeof setInterval> | null = null;
   /** Assigned by `start()`; the seam `pullRemoteNow()` and tests reach. */
@@ -724,6 +752,16 @@ export function createSyncRuntime(
    *  project" list accumulates instead of being replaced by the latest batch. */
   const everPulled = new Set<string>();
 
+  /**
+   * Every slug the PROJECT has deleted, as this run has learned it.
+   *
+   * The hub drops its `documents` row best-effort while the tombstone is the
+   * durable part, so a deleted canvas can still appear in one more listing. This
+   * set is what stops the pull lane from treating that listing as an invitation
+   * to write the canvas back — the resurrection, arrived at from the other side.
+   */
+  const tombstoned = new Set<string>();
+
   /**
    * The LIVE descriptor set, by slug.
    *
@@ -889,10 +927,20 @@ export function createSyncRuntime(
     // design root — see `pullTargets` for why flat); local-only canvases go up
     // as they always did. Best-effort: an older hub without the listing route,
     // or an unreachable one, syncs exactly as before.
-    const remoteDocs = await fetchRemoteDocs(linkedHub.url, resolvedToken);
+    const remoteListing = await fetchRemoteListing(linkedHub.url, resolvedToken);
+    // BOOT LEARNS THE DELETIONS BEFORE IT PULLS ANYTHING. The peer-side apply
+    // lives further down (it needs the live descriptor map), so this boot pass
+    // only has to make sure the pull does not fetch a canvas the project has
+    // deleted — the first poll then quarantines whatever is still on disk. Doing
+    // it in the other order would materialise a deleted canvas on every launch
+    // and delete it again seconds later, which is worse than the bug.
+    for (const stone of remoteListing?.tombstones ?? []) {
+      const slug = slugFromDocName(stone.name);
+      if (slug) tombstoned.add(slug);
+    }
     const remoteDiff = diffRemoteDocs(
       localCanvases.map((c) => docNameFor(c.slug)),
-      remoteDocs
+      remoteListing?.documents ?? null
     );
     // PROVISIONAL targets. The listing carries names and byte counts only — a
     // document's own `syncMeta.path` lives INSIDE it, so every target here is
@@ -1002,6 +1050,8 @@ export function createSyncRuntime(
     // Both were missing here too; the incremental lane just made their absence
     // permanent instead of momentary. See `admitPulledBody` and MAX_PULLS_PER_POLL.
     const admittedPulls = pulled
+      // A canvas the project deleted is never pulled, however it is still listed.
+      .filter((t) => !tombstoned.has(t.slug))
       .filter((t) => admitPullTarget(ctx, t.slug, t.bodyAbs))
       .filter((t) => admitPulledBody(t.slug, t.bodyAbs))
       .slice(0, Math.max(0, maxPinnedRooms() - localCanvases.length));
@@ -1172,7 +1222,7 @@ export function createSyncRuntime(
       // nobody had sent: a permanent empty frame that looked like a broken path.
       // Reported three times in one day on alligators, each time with a
       // different asset, which is what finally named it.
-      if (isPushableAssetRel(rel)) scheduleAssetSweep(linkedHub.url);
+      if (isPushableAssetRel(rel, ctx.cfg.canvasGroups)) scheduleAssetSweep(linkedHub.url);
     });
 
     /**
@@ -2083,6 +2133,74 @@ export function createSyncRuntime(
     discoveryRescan = rescan;
     discoveryUnsub = ctx.bus.on('canvas-list-update', () => rescan.schedule());
 
+    // The OUTBOUND half of the delete lane. `api.ts` emits these two only from
+    // its privileged create/delete routes, never from the filesystem watcher —
+    // see the comment at the emit site for why that distinction is what makes
+    // them safe to act on.
+    const noteToHub = (slug: unknown, revive: boolean): void => {
+      if (typeof slug !== 'string' || !slug) return;
+      if (revive) tombstoned.delete(slug);
+      else tombstoned.add(slug);
+      void stateDocumentGone(linkedHub.url, token, docNameFor(slug), { revive }).then((ok) => {
+        if (!ok) {
+          console.warn(
+            `[sync] could not tell the project that ${slug} was ${revive ? 're-created' : 'deleted'} — it stays ${revive ? 'buried' : 'in the project'} for other peers until this succeeds.`
+          );
+        }
+      });
+    };
+    deletedUnsub = ctx.bus.on('canvas-deleted', (p: { slug?: unknown }) =>
+      noteToHub(p?.slug, false)
+    );
+    createdUnsub = ctx.bus.on('canvas-created', (p: { slug?: unknown }) =>
+      noteToHub(p?.slug, true)
+    );
+
+    /**
+     * Apply the project's deletions to this machine.
+     *
+     * The runtime releases the canvas first and moves the bytes second: a live
+     * agent flushing its Y.Doc onto a path we are about to rename is how a
+     * "deleted" canvas comes back as a half-written file.
+     *
+     * `tombstoned` outlives the individual poll. The hub drops the `documents`
+     * row on a best-effort basis, so a tombstone and a still-listed document can
+     * coexist for a tick; without a local memory of what was deleted, that
+     * window is enough for the pull lane to fetch the canvas straight back.
+     */
+    const applyTombstones = async (stones: readonly RemoteTombstone[]): Promise<void> => {
+      if (stones.length === 0) return;
+      // Remember EVERY deletion, including names this peer never had — that is
+      // what makes the pull lane below refuse a document the project deleted but
+      // whose row has not gone yet.
+      for (const stone of stones) {
+        const slug = slugFromDocName(stone.name);
+        if (slug) tombstoned.add(slug);
+      }
+      const gone = tombstonedSlugs(stones, descriptors.keys());
+      if (gone.length === 0) return;
+      for (const slug of gone) {
+        const canvas = descriptors.get(slug);
+        await releaseOne(slug);
+        if (canvas) {
+          quarantineCanvas({
+            designRoot: ctx.paths.designRoot,
+            slug,
+            lanes: {
+              html: canvas.html,
+              meta: canvas.meta,
+              css: canvas.css,
+              annotations: canvas.annotations,
+            },
+          });
+        }
+        descriptors.delete(slug);
+      }
+      console.log(`[sync] the project deleted ${gone.length} canvas(es): ${gone.join(', ')}`);
+      // The set the DDR-054 §3 F3 markers describe just shrank.
+      markUntrusted();
+    };
+
     // ─── THE HUB HALF OF DISCOVERY ────────────────────────────────────────
     //
     // The rescan above sees this DISK. A document that exists only on the hub
@@ -2102,13 +2220,19 @@ export function createSyncRuntime(
     const pullRemoteOnce = async (): Promise<void> => {
       if (stopped) return;
       // Read `token` at call time: a silent renewal swaps it in place.
-      const docs = await fetchRemoteDocs(linkedHub.url, token);
+      const listing = await fetchRemoteListing(linkedHub.url, token);
       // null = unreachable, refused, or a hub without the route. Not an error
       // here any more than it is at boot — sync continues, we ask again later.
-      if (docs === null) return;
+      if (listing === null) return;
+      // ABSENCE BEFORE PRESENCE. A canvas the project deleted must leave before
+      // the pull runs, or a slug that is tombstoned AND still listed (the window
+      // between the tombstone and the row actually going) would be trashed and
+      // immediately pulled back — the resurrection this lane exists to end,
+      // reintroduced inside one tick.
+      await applyTombstones(listing.tombstones);
       const diff = diffRemoteDocs(
         [...descriptors.keys()].map((slug) => docNameFor(slug)),
-        docs
+        listing.documents
       );
       if (diff.hubOnly.length === 0) return;
       const targets = pullTargets(
@@ -2125,6 +2249,9 @@ export function createSyncRuntime(
         }
       );
       const admitted = targets
+        // A canvas the project deleted is not a canvas to fetch, even while the
+        // hub is still listing it — see `tombstoned`.
+        .filter((t) => !tombstoned.has(t.slug))
         .filter((t) => admitPullTarget(ctx, t.slug, t.bodyAbs))
         .filter((t) => admitPulledBody(t.slug, t.bodyAbs));
       const fresh = admitted.filter(
@@ -2169,10 +2296,67 @@ export function createSyncRuntime(
       notePulledAll();
       markUntrusted();
     };
+    /**
+     * Fetch the referenced assets this machine is missing.
+     *
+     * RUNS ON EVERY PEER, cell included — unlike the PUSH sweep, which is a
+     * desktop job because the desktop is the side that has the bytes. Wanting an
+     * asset you can see referenced and do not hold is symmetric, and so is the
+     * fix; making this desktop-only would rebuild the same one-way street facing
+     * the other way.
+     *
+     * After the document poll, deliberately: a canvas that arrives in this tick
+     * brings its references with it, and this is the pass that resolves them.
+     */
+    const pullAssetsOnce = async (): Promise<void> => {
+      if (stopped) return;
+      await pullAssets({
+        designRoot: ctx.paths.designRoot,
+        hubUrl: linkedHub.url,
+        token: () => token,
+      });
+    };
+    // Cumulative per boot — the Sync panel's one line. `synced` is the last
+    // pass's converged count; `pulled`/`conflicts` accumulate.
+    const fileTotals = { synced: 0, pulled: 0, conflicts: 0 };
+    const noteFilePull = (result: FilePullResult): void => {
+      fileTotals.synced = result.skipped + result.pulled.length;
+      fileTotals.pulled += result.pulled.length;
+      fileTotals.conflicts += result.conflicts.length;
+      statusStore?.updateFiles?.({ ...fileTotals });
+    };
+    /**
+     * Plane B's downward pass — after the doc poll and the asset pull, so a
+     * canvas that arrived this tick has its design system resolved in the
+     * same tick. Flag-gated; a no-op when off.
+     *
+     * On a cell the hub shares the checkout, so every manifest entry is
+     * hash-equal by construction and the pass skips itself — deliberately
+     * NOT special-cased: the invariant covers it, and a special case would
+     * be one more branch that can drift.
+     */
+    const pullFilesOnce = async (): Promise<void> => {
+      if (stopped || !syncFilesOn) return;
+      const result = await pullFiles({
+        designRoot: ctx.paths.designRoot,
+        hubUrl: linkedHub.url,
+        token: () => token,
+        canvasGroups: ctx.cfg.canvasGroups,
+        allowCodeModules,
+      });
+      noteFilePull(result);
+    };
     const pollRemote = (): void => {
-      void pullRemoteOnce().catch((err) => console.error('[sync] remote poll failed:', err));
+      void pullRemoteOnce()
+        .then(() => pullAssetsOnce())
+        .then(() => pullFilesOnce())
+        .catch((err) => console.error('[sync] remote poll failed:', err));
+    };
+    remotePull = async () => {
+      await pullRemoteOnce();
+      await pullAssetsOnce();
+      await pullFilesOnce();
     };
-    remotePull = pullRemoteOnce;
     remotePollTimer = setInterval(pollRemote, REMOTE_POLL_MS);
     // `setInterval` keeps a Bun process alive; a poll is not a reason for the
     // dev server to refuse to exit.
@@ -2192,6 +2376,10 @@ export function createSyncRuntime(
     attachOne = null;
     discoveryUnsub?.();
     discoveryUnsub = null;
+    deletedUnsub?.();
+    deletedUnsub = null;
+    createdUnsub?.();
+    createdUnsub = null;
     discoveryRescan?.stop();
     discoveryRescan = null;
     if (remotePollTimer !== null) clearInterval(remotePollTimer);

package/apps/studio/sync/remote-docs.ts

@@ -32,6 +32,29 @@ export interface RemoteDoc {
   bytes: number;
 }
 
+/** One deletion the project has stated — see the hub's `tombstones.mjs`. */
+export interface RemoteTombstone {
+  name: string;
+  deletedAt: number;
+}
+
+/**
+ * The whole listing: what the project HAS, and what it has DELETED.
+ *
+ * Both halves are needed, and for symmetric reasons. Presence alone made a
+ * hub-only document authority to create a local file — correct, and the reason
+ * a project arrives in full. Absence alone was un-representable, so a delete was
+ * indistinguishable from "this peer has not discovered it yet" and got refilled
+ * on the next tick. One request carries both.
+ */
+export interface RemoteListing {
+  documents: RemoteDoc[];
+  /** Empty against a hub older than the tombstone route — never null, because
+   *  "this hub cannot say" and "nothing was deleted" call for the same
+   *  behaviour: change nothing on disk. */
+  tombstones: RemoteTombstone[];
+}
+
 export interface RemoteDocDiff {
   /** Documents on both sides — the ones actually syncing. */
   shared: string[];
@@ -54,11 +77,11 @@ const LIST_TIMEOUT_MS = 6000;
  * reporting improvement, and making it load-bearing would trade a real feature
  * for a nicer message.
  */
-export async function fetchRemoteDocs(
+export async function fetchRemoteListing(
   hubUrl: string,
   token: string,
   fetchImpl: typeof fetch = fetch
-): Promise<RemoteDoc[] | null> {
+): Promise<RemoteListing | null> {
   try {
     const base = hubUrl.replace(/\/+$/, '');
     const res = await fetchImpl(`${base}/api/documents`, {
@@ -66,19 +89,64 @@ export async function fetchRemoteDocs(
       signal: AbortSignal.timeout(LIST_TIMEOUT_MS),
     });
     if (!res.ok) return null;
-    const body = (await res.json()) as { documents?: unknown };
+    const body = (await res.json()) as { documents?: unknown; tombstones?: unknown };
     if (!Array.isArray(body?.documents)) return null;
-    return body.documents
+    const documents = body.documents
       .filter(
         (d): d is RemoteDoc =>
           !!d && typeof (d as RemoteDoc).name === 'string' && (d as RemoteDoc).name.length > 0
       )
       .map((d) => ({ name: d.name, bytes: Number(d.bytes) || 0 }));
+    // A hub without the route omits the field entirely; a hostile one could send
+    // anything. Both land on "no deletions", which changes nothing on disk — the
+    // safe direction for a signal whose only effect is to REMOVE local files.
+    const tombstones = Array.isArray(body?.tombstones)
+      ? (body.tombstones as unknown[])
+          .filter(
+            (t): t is RemoteTombstone =>
+              !!t &&
+              typeof (t as RemoteTombstone).name === 'string' &&
+              (t as RemoteTombstone).name.length > 0
+          )
+          .map((t) => ({ name: t.name, deletedAt: Number(t.deletedAt) || 0 }))
+      : [];
+    return { documents, tombstones };
   } catch {
     return null;
   }
 }
 
+/**
+ * Tell the hub a document is gone (`DELETE`) or exists again (`POST`).
+ *
+ * BEST-EFFORT, LIKE EVERY OTHER HUB CALL HERE. A hub that is old, offline or
+ * refusing means the local delete still happened — the canvas is in `_trash/`
+ * and this peer has released it. What is lost is only the PROPAGATION, and the
+ * peer retries the statement on its next poll for anything it still sees on the
+ * hub but no longer has on disk. Returning false rather than throwing keeps a
+ * failed network call from turning a successful local delete into an error the
+ * user has to interpret.
+ */
+export async function stateDocumentGone(
+  hubUrl: string,
+  token: string,
+  docName: string,
+  opts: { revive?: boolean; fetchImpl?: typeof fetch } = {}
+): Promise<boolean> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  try {
+    const base = hubUrl.replace(/\/+$/, '');
+    const res = await fetchImpl(`${base}/api/documents/${encodeURIComponent(docName)}`, {
+      method: opts.revive ? 'POST' : 'DELETE',
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(LIST_TIMEOUT_MS),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Diff the hub's documents against the ones this peer syncs.
  *
@@ -146,6 +214,32 @@ export function slugFromDocName(docName: string): string | null {
   return ns ? ns[1].toLowerCase() : null;
 }
 
+/**
+ * The local slugs a tombstone set names — validated, deduplicated, safe.
+ *
+ * A tombstone is the one hub-supplied signal whose effect is to REMOVE work from
+ * a person's disk, so it runs through exactly the same name gate a pull does
+ * (`slugFromDocName`: whole-name match, no dots, no traversal, no extension
+ * smuggling) and anything that does not survive is dropped silently. A hub
+ * cannot name a file this way that it could not already have created.
+ *
+ * `known` is the set of slugs this peer actually holds; a tombstone for anything
+ * else is not an error, just nothing to do — that is the normal steady state
+ * once both sides have converged.
+ */
+export function tombstonedSlugs(
+  tombstones: readonly RemoteTombstone[],
+  known: Iterable<string>
+): string[] {
+  const have = new Set(known);
+  const out = new Set<string>();
+  for (const t of tombstones) {
+    const slug = slugFromDocName(t.name);
+    if (slug && have.has(slug)) out.add(slug);
+  }
+  return [...out].sort();
+}
+
 export interface PullTarget {
   slug: string;
   docName: string;

package/apps/studio/sync/status.ts

@@ -53,6 +53,22 @@ export interface SyncStatusPayload extends SyncStatusSnapshot {
    * payload as the doc counts so the Sync panel has one source, not two.
    */
   assets?: AssetPushProgress;
+  /**
+   * feature-sync-file-plane — Plane B's counts (additive; absent until the
+   * first flag-on file pull of a boot). `conflicts` names losers parked in
+   * `_trash/<rel>-conflict-<ts>` — the panel line points there, because a
+   * conflict a person cannot find is silent loss with extra steps.
+   */
+  files?: FilePlaneStatus;
+}
+
+export interface FilePlaneStatus {
+  /** Plane files present and equal after the last pass — the steady state. */
+  synced: number;
+  /** Cumulative files landed this boot. */
+  pulled: number;
+  /** Cumulative conflicts this boot (either winner); losers are in _trash/. */
+  conflicts: number;
 }
 
 export interface SyncStatusStoreOptions {
@@ -78,6 +94,9 @@ export interface SyncStatusStore {
    *  broadcast. Kept in the store (not the monitor): assets are a push lane,
    *  not a connection, and the monitor's state machine must not learn them. */
   updateAssets(progress: AssetPushProgress): void;
+  /** feature-sync-file-plane — merge Plane B counts + persist + broadcast.
+   *  Same reasoning as `updateAssets`: a lane, not a connection. */
+  updateFiles(files: FilePlaneStatus): void;
   /** Current payload (defensive copy). */
   get(): SyncStatusPayload;
 }
@@ -102,6 +121,7 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
   };
 
   let assets: AssetPushProgress | undefined;
+  let files: FilePlaneStatus | undefined;
 
   function payload(): SyncStatusPayload {
     return {
@@ -111,6 +131,7 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
       conflicts: conflicts.slice(),
       ...(opts.sharedDoc ? { sharedDoc: true } : {}),
       ...(assets ? { assets } : {}),
+      ...(files ? { files } : {}),
     };
   }
 
@@ -142,6 +163,10 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
       assets = progress;
       flush();
     },
+    updateFiles(next) {
+      files = next;
+      flush();
+    },
     get: payload,
   };
 }

package/apps/studio/sync/tombstone-apply.ts

@@ -0,0 +1,131 @@
+// Acting on a tombstone — the peer-side half of the delete lane.
+//
+// The hub states that a canvas is gone (`tombstones.mjs`); this is what a peer
+// does about it. One rule governs the whole file:
+//
+//   QUARANTINE, NEVER DELETE.
+//
+// This is the only code path where a HUB-SUPPLIED signal removes work from a
+// person's disk, and the hub is untrusted to peers (DDR-054). Moving the bundle
+// to `_trash/<slug>-deleted-<ts>/` is what makes that acceptable: a hub that is
+// hostile, buggy, or simply confused about which project it is costs the user a
+// trip to `_trash/`, never their work. The same posture, and the same directory,
+// `migrate-flat-fallback.ts` already established for a peer-driven move.
+//
+// WHY THE SIDECARS TRAVEL AND THE HISTORY DOES NOT. The lanes that ARE the
+// canvas — body, `.meta.json`, `.css`, `.annotations.svg` — move together, so
+// what lands in `_trash/` is a restorable canvas rather than a body stripped of
+// its annotations. `_history/<slug>/`, `_comments/`, `_canvas-state/` stay: they
+// are per-machine runtime state (DDR-115), regenerated or irrelevant, and
+// sweeping them would make a recoverable delete quietly lossy.
+
+import { existsSync, mkdirSync, renameSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Park ONE file in `_trash/<rel>-conflict-<ts>` — the file plane's LWW
+ * loser's parking spot (feature-sync-file-plane), generalized out of
+ * `quarantineCanvas` below: same posture (quarantine, never delete; never
+ * throw — a failed quarantine costs the overwrite, not the sync runtime),
+ * scoped to a single file rather than a canvas's lane bundle.
+ *
+ * Returns the design-root-relative destination, or null when nothing moved —
+ * and the CALLER must treat null as "do not overwrite": a conflict loser
+ * that could not be parked is a conflict loser that stays.
+ */
+export function quarantineFile(opts: {
+  designRoot: string;
+  /** Design-root-relative path of the file to park. */
+  rel: string;
+  now?: number;
+  log?: (line: string) => void;
+}): string | null {
+  const { designRoot, rel } = opts;
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const abs = path.join(designRoot, rel);
+  if (!existsSync(abs)) return null;
+  const trashedTo = `_trash/${rel}-conflict-${opts.now ?? Date.now()}`;
+  const trashAbs = path.join(designRoot, trashedTo);
+  try {
+    mkdirSync(path.dirname(trashAbs), { recursive: true });
+    renameSync(abs, trashAbs);
+  } catch (err) {
+    log(
+      `[sync/files] could not park ${rel} in _trash/: ${(err as Error).message} — keeping the local copy`
+    );
+    return null;
+  }
+  log(`[sync/files] conflict on ${rel} — the local copy moved to ${trashedTo}`);
+  return trashedTo;
+}
+
+export interface TombstoneMove {
+  slug: string;
+  /** Design-root-relative quarantine dir the canvas landed in. */
+  trashedTo: string;
+  /** Design-root-relative lanes that actually moved. */
+  moved: string[];
+}
+
+/** The absolute paths that make up one canvas on disk. */
+export interface CanvasLanes {
+  html: string;
+  meta?: string;
+  css?: string;
+  annotations?: string;
+}
+
+/**
+ * Move one canvas's lanes into `_trash/`, best-effort.
+ *
+ * Returns the move, or null when there was nothing on disk to move (already
+ * gone — the idempotent steady state once both peers have converged) or when the
+ * quarantine directory could not be made. NEVER THROWS: a failed quarantine must
+ * cost the deletion, not the sync runtime that called it.
+ *
+ * `now` is injectable so a test does not have to reason about wall-clock.
+ */
+export function quarantineCanvas(opts: {
+  designRoot: string;
+  slug: string;
+  lanes: CanvasLanes;
+  now?: number;
+  log?: (line: string) => void;
+}): TombstoneMove | null {
+  const { designRoot, slug, lanes } = opts;
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const present = [lanes.html, lanes.meta, lanes.css, lanes.annotations].filter(
+    (p): p is string => !!p && existsSync(p)
+  );
+  if (present.length === 0) return null;
+
+  const trashedTo = `_trash/${slug}-deleted-${opts.now ?? Date.now()}`;
+  const trashAbs = path.join(designRoot, trashedTo);
+  try {
+    mkdirSync(trashAbs, { recursive: true });
+  } catch (err) {
+    log(
+      `[sync/tombstone] could not quarantine ${slug}: ${(err as Error).message} — leaving it in place`
+    );
+    return null;
+  }
+
+  const moved: string[] = [];
+  for (const abs of present) {
+    try {
+      renameSync(abs, path.join(trashAbs, path.basename(abs)));
+      moved.push(path.relative(designRoot, abs));
+    } catch (err) {
+      // One stuck lane (an open handle on Windows, a permission quirk) must not
+      // abandon the lanes that CAN move — a half-moved canvas is still gone from
+      // the tree, and the remainder is named here so it can be found by hand.
+      log(
+        `[sync/tombstone] could not move ${path.basename(abs)} for ${slug}: ${(err as Error).message}`
+      );
+    }
+  }
+  if (moved.length === 0) return null;
+
+  log(`[sync/tombstone] ${slug} was deleted in the project — moved to ${trashedTo}/`);
+  return { slug, trashedTo, moved };
+}