@1agh/maude 0.29.0 → 0.31.0

package/apps/studio/sync/journal.ts

@@ -0,0 +1,190 @@
+// Per-machine sync journal — hub-sync cold-start safety (DDR-102).
+//
+// Records, per slug, the content hash of the LAST state this machine
+// successfully reconciled disk↔doc. It answers git's "do I have uncommitted
+// changes?" question for sync: a cold-start hub-wins overwrite of local disk
+// is allowed ONLY when hash(local) == journal hash (a clean fast-forward —
+// everything local was already synced, the hub is just ahead). Any other
+// combination is divergence and takes the conflict protocol (cold-start.ts:
+// dual snapshot + newest-wins).
+//
+// Per-machine, per-hub: the file lives at `<designRoot>/_state/sync-journal.json`
+// (`_state/` is already in the DDR-056 gitignore block) and carries the hub URL
+// it was recorded against. Relinking to a DIFFERENT hub invalidates every
+// entry — hashes recorded against one hub's docs say nothing about another's.
+//
+// Posture mirrors status.ts: best-effort, NEVER throws into the boot path. A
+// corrupt/unparseable file is treated as absent; the decision module then
+// degrades to the conservative "potential divergence" path, which is safe
+// (snapshot + newest-wins), never destructive. Hashes come exclusively from
+// `hashBytes` (echo-guard.ts) so the journal compares apples to apples with
+// the echo guard and the cold-start decision inputs.
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { atomicWrite } from './atomic-write.ts';
+
+/** Debounce window for persisting the journal to disk. */
+export const JOURNAL_FLUSH_MS = 1_000;
+
+export interface JournalEntry {
+  /** hashBytes() of the canvas body as last reconciled disk↔doc. */
+  bodyHash: string;
+  /** hashBytes() of the sibling .css, when one was reconciled. */
+  cssHash?: string;
+  /** ms epoch of the checkpoint. */
+  at: number;
+}
+
+interface JournalFileShape {
+  hubUrl: string | null;
+  updatedAt: number;
+  slugs: Record<string, JournalEntry>;
+}
+
+export interface SyncJournal {
+  /** Last-reconciled hashes for a slug, or null when never checkpointed. */
+  get(slug: string): JournalEntry | null;
+  /** Checkpoint a successful disk↔doc traversal. Lanes checkpoint
+   *  independently (body flush vs css flush), so omitted hashes MERGE with the
+   *  existing entry instead of clearing it. Schedules a debounced persist. */
+  record(slug: string, hashes: { bodyHash?: string; cssHash?: string }): void;
+  /** Relinked to a different hub → wipe every entry (hashes are per-hub). */
+  invalidateIfHubChanged(url: string): void;
+  /** Persist now (cancels the pending debounce). Best-effort. */
+  flush(): void;
+  /** Flush + cancel timers. */
+  stop(): void;
+  /** Test/inspection — number of slugs tracked. */
+  size(): number;
+}
+
+export interface LoadJournalOptions {
+  /** Override the persist debounce. Tests use 0 to persist synchronously. */
+  flushMs?: number;
+  now?: () => number;
+  /** Injected for tests — defaults to atomicWrite. */
+  writer?: (path: string, bytes: string) => void;
+}
+
+/** Absolute path of the journal file for a design root. */
+export function journalPath(designRoot: string): string {
+  return path.join(designRoot, '_state', 'sync-journal.json');
+}
+
+export function loadJournal(designRoot: string, opts: LoadJournalOptions = {}): SyncJournal {
+  const file = journalPath(designRoot);
+  const flushMs = opts.flushMs ?? JOURNAL_FLUSH_MS;
+  const now = opts.now ?? Date.now;
+  // atomicWrite mkdirs the parent (`_state/`) on demand, so no explicit mkdir.
+  const writer = opts.writer ?? ((p: string, bytes: string) => void atomicWrite(p, bytes));
+
+  let hubUrl: string | null = null;
+  let slugs: Record<string, JournalEntry> = {};
+  let dirty = false;
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+  let stopped = false;
+
+  // Load once at construction. Corrupt / unreadable / wrong-shape → absent.
+  try {
+    if (existsSync(file)) {
+      const parsed = JSON.parse(readFileSync(file, 'utf8')) as Partial<JournalFileShape>;
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        hubUrl = typeof parsed.hubUrl === 'string' ? parsed.hubUrl : null;
+        const rawSlugs = parsed.slugs;
+        if (rawSlugs && typeof rawSlugs === 'object' && !Array.isArray(rawSlugs)) {
+          for (const [slug, raw] of Object.entries(rawSlugs)) {
+            const e = raw as JournalEntry;
+            if (e && typeof e === 'object' && typeof e.bodyHash === 'string') {
+              slugs[slug] = {
+                bodyHash: e.bodyHash,
+                ...(typeof e.cssHash === 'string' ? { cssHash: e.cssHash } : {}),
+                at: typeof e.at === 'number' ? e.at : 0,
+              };
+            }
+          }
+        }
+      }
+    }
+  } catch {
+    /* corrupt journal → treat as absent; the decision module degrades safely */
+  }
+
+  function persist(): void {
+    if (!dirty) return;
+    dirty = false;
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    const payload: JournalFileShape = { hubUrl, updatedAt: now(), slugs };
+    try {
+      writer(file, `${JSON.stringify(payload, null, 2)}\n`);
+    } catch (err) {
+      // Best-effort: a failed persist must never throw into the sync hot path.
+      console.warn('[sync/journal] persist failed:', err instanceof Error ? err.message : err);
+    }
+  }
+
+  function schedulePersist(): void {
+    dirty = true;
+    if (stopped) return;
+    if (flushMs === 0) {
+      persist();
+      return;
+    }
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      persist();
+    }, flushMs);
+  }
+
+  return {
+    get(slug) {
+      return slugs[slug] ?? null;
+    },
+
+    record(slug, hashes) {
+      const prev = slugs[slug];
+      const cssHash = hashes.cssHash ?? prev?.cssHash;
+      slugs[slug] = {
+        // An entry created by a css-only checkpoint carries an empty bodyHash —
+        // it can never match a real body hash, so the decision module stays
+        // conservative (divergence path) until a body traversal checkpoints.
+        bodyHash: hashes.bodyHash ?? prev?.bodyHash ?? '',
+        ...(cssHash !== undefined ? { cssHash } : {}),
+        at: now(),
+      };
+      schedulePersist();
+    },
+
+    invalidateIfHubChanged(url) {
+      if (hubUrl === url) return;
+      if (hubUrl !== null) {
+        // Different hub than the one these hashes were recorded against — every
+        // entry is meaningless there. Wipe so the decision module stays
+        // conservative (divergence → snapshot) instead of false-fast-forwarding.
+        slugs = {};
+      }
+      hubUrl = url;
+      schedulePersist();
+    },
+
+    flush: persist,
+
+    stop() {
+      persist();
+      stopped = true;
+      if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+      }
+    },
+
+    size() {
+      return Object.keys(slugs).length;
+    },
+  };
+}

package/apps/studio/sync/migrate-seed.ts

@@ -1,5 +1,5 @@
 // One-time authoritative seed for the shared-doc cutover — Phase 9.2 (DDR-064
-// Task 9). The fix for Risk 1 (the duplication-on-merge trap).
+// Task 9), cold-start resolution upgraded by DDR-102.
 //
 // The trap (dmonad-confirmed, discuss.yjs.dev/t/.../2538): if a shared doc is
 // populated from TWO independent sources — the local file-seed (room.seed
@@ -12,22 +12,24 @@
 // This module is that decision, run ONCE per canvas at cutover, AFTER the
 // provider's first sync (so the doc already holds hub state if the hub had any):
 //
-//   - hub HAD state (doc non-empty)  → HUB WINS. Leave the doc; the projection
-//     materializes hub state to disk. Local divergent files are snapshotted to
-//     `_history/` first (rollback) then overwritten by the room persist.
-//   - hub was EMPTY (doc empty)      → ADOPT. Clear+rebuild the doc from the
-//     local files inside `transact(fn, MIGRATION)` (the apply* codecs already
-//     delete-then-insert, so this is a true rebuild, not an append). The
-//     provider then pushes it up as the canonical first version.
+//   - hub EMPTY (doc empty)            → ADOPT. Clear+rebuild the doc from the
+//     local files inside `transact(fn, MIGRATION)`.
+//   - hub HAD state, body resolution   → the DDR-102 decision table
+//     (cold-start.ts): identical → keep; journal-matched local → fast-forward
+//     (hub keeps); empty local → materialize; divergence → dual snapshot +
+//     NEWEST-WINS — winner `local` rebuilds the body from disk inside ONE
+//     MIGRATION transaction (one source per type, never a CRDT merge of two
+//     histories); winner `hub` keeps the doc.
+//   - comments under a non-empty doc   → id-union (plain array rebuild from
+//     merged JSON via the delete-then-insert codec — NOT a CRDT merge, so the
+//     duplication trap stays closed; same-id entries keep the doc's version).
 //
-// Idempotent: re-running with hub state present is a no-op (doc already holds
-// it); re-running an adopt rebuilds from the same files → byte-identical, no
-// duplicate items. The companion guard is the room's seed being disabled for
-// pinned (provider-attached) slugs under sharedDoc (see collab/index.ts
-// `shouldSeed`), so the file-seed can never re-introduce duplicate items after
-// this runs.
-
-import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+// Idempotent: re-running with hub state present and no divergence is a no-op;
+// re-running an adopt rebuilds from the same files → byte-identical.
+// The companion guard is the room's seed being disabled for pinned
+// (provider-attached) slugs under sharedDoc (see collab/index.ts `shouldSeed`).
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 
 import type * as Y from 'yjs';
@@ -39,8 +41,13 @@ import {
   applyCssToDoc,
   applyHtmlToDoc,
   applyMetaToDoc,
+  bodyEditAtFromDoc,
+  stampBodyEdit,
   Y_SYNC_TYPES,
 } from './codec.ts';
+import { decideColdStart, unionCommentsById } from './cold-start.ts';
+import { hashBytes } from './echo-guard.ts';
+import type { SyncJournal } from './journal.ts';
 import { ORIGINS } from './origins.ts';
 
 export interface MigrateSeedPaths {
@@ -56,11 +63,33 @@ export interface MigrateSeedOptions {
   doc: Y.Doc;
   paths: MigrateSeedPaths;
   /** `_history/<slug>/` (or any dir) — when set, local files are snapshotted
-   *  here before a hub-wins overwrite, for rollback. Best-effort. */
+   *  here (the legacy `pre-shared-doc-migration/` whole-set copy) before any
+   *  doc-keeps-state path can overwrite them via the projection. Best-effort. */
   historyDir?: string;
+  /** DDR-102 — per-machine journal; gates fast-forward vs conflict. */
+  journal?: SyncJournal;
+  /** DDR-102 — body snapshot writer (history.ts), same contract as the agent's. */
+  snapshot?: (content: string, reason: 'pre-sync-local' | 'pre-sync-hub') => Promise<string | null>;
+  /** DDR-102 — divergence notification, same contract as the agent's. */
+  onConflict?: (info: {
+    slug: string;
+    kind: 'cold-start-diverged';
+    winner?: 'local' | 'hub';
+    snapshots?: { local?: string; hub?: string };
+    /** DDR-102 fail-closed (F1) — local snapshot didn't land; hub-wins refused. */
+    snapshotFailed?: boolean;
+  }) => void;
 }
 
-export type MigrateSeedResult = 'hub-wins' | 'local-adopt' | 'empty';
+export type MigrateSeedResult =
+  | 'hub-wins'
+  | 'local-adopt'
+  | 'empty'
+  /** DDR-102 — doc held state but no body; local body seeded up in-place. */
+  | 'body-seed-up'
+  /** DDR-102 — divergence resolved newest-wins. */
+  | 'conflict-local-wins'
+  | 'conflict-hub-wins';
 
 /** True when the shared doc holds no synced content for any of the five types. */
 export function docIsEmpty(doc: Y.Doc): boolean {
@@ -77,42 +106,163 @@ export function docIsEmpty(doc: Y.Doc): boolean {
  * Run the one-time authoritative seed. Returns which source won so the caller
  * can log / surface a conflict. Safe to call on every boot (idempotent).
  */
-export function migrateSeed(opts: MigrateSeedOptions): MigrateSeedResult {
-  const { doc, paths } = opts;
-
-  // Hub had canonical state → it wins. The doc already holds it; the projection
-  // will materialize it to disk. Snapshot any divergent local files first so the
-  // overwrite is recoverable.
-  if (!docIsEmpty(doc)) {
-    snapshotLocal(opts);
-    return 'hub-wins';
-  }
+export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeedResult> {
+  const { slug, doc, paths } = opts;
 
-  // Hub was empty → adopt local. Build the doc from the local files ONCE, inside
-  // a single MIGRATION transaction. The apply* codecs delete-then-insert, so
-  // this is a clear+rebuild (re-running is a no-op once content matches).
   const localHtml = readLocal(paths.html);
   const localComments = readLocal(paths.comments);
   const localAnnotations = readLocal(paths.annotations);
   const localMeta = paths.meta ? readLocal(paths.meta) : null;
   const localCss = paths.css ? readLocal(paths.css) : null;
 
-  const hasLocal =
-    !!localHtml || !!localComments || !!localAnnotations || !!localMeta || !!localCss;
-  if (!hasLocal) return 'empty';
+  // Hub was empty → adopt local. Build the doc from the local files ONCE, inside
+  // a single MIGRATION transaction. The apply* codecs delete-then-insert, so
+  // this is a clear+rebuild (re-running is a no-op once content matches).
+  if (docIsEmpty(doc)) {
+    const hasLocal =
+      !!localHtml || !!localComments || !!localAnnotations || !!localMeta || !!localCss;
+    if (!hasLocal) return 'empty';
+
+    doc.transact(() => {
+      if (localHtml) {
+        if (applyHtmlToDoc(doc, localHtml, ORIGINS.MIGRATION)) {
+          stampBodyEdit(doc, ORIGINS.MIGRATION);
+        }
+      }
+      if (localComments) {
+        const parsed = tryParseJsonArray(localComments);
+        if (parsed) applyCommentsToDoc(doc, parsed, ORIGINS.MIGRATION);
+      }
+      if (localAnnotations) applyAnnotationsToDoc(doc, localAnnotations, ORIGINS.MIGRATION);
+      if (paths.meta && localMeta) applyMetaToDoc(doc, localMeta, ORIGINS.MIGRATION);
+      if (paths.css && localCss) applyCssToDoc(doc, localCss, ORIGINS.MIGRATION);
+    }, ORIGINS.MIGRATION);
+
+    // DDR-102 — the adopt is a disk→doc traversal: checkpoint it.
+    if (localHtml) {
+      opts.journal?.record(slug, {
+        bodyHash: hashBytes(localHtml),
+        ...(localCss ? { cssHash: hashBytes(localCss) } : {}),
+      });
+    }
+    return 'local-adopt';
+  }
+
+  // Hub had state. Legacy whole-set safety copy (fixed dir, overwritten per
+  // boot — not spam) so non-body files keep their pre-cutover backup too.
+  snapshotLocal(opts);
+
+  // Body resolution via the DDR-102 decision table.
+  const docHtml = doc.getText(Y_SYNC_TYPES.html).toString();
+  const decision = decideColdStart({
+    localBody: localHtml,
+    docBody: docHtml,
+    journalHash: opts.journal?.get(slug)?.bodyHash ?? null,
+    localMtimeMs: localMtimeMs(paths.html),
+    docBodyEditAtMs: bodyEditAtFromDoc(doc),
+  });
+
+  let result: MigrateSeedResult = 'hub-wins';
+
+  /** Rebuild body (+ visually-coupled css/annotations) from local, in ONE
+   *  MIGRATION transaction — one source per type, never a two-history merge. */
+  const rebuildBodyFromLocal = (): void => {
+    doc.transact(() => {
+      if (applyHtmlToDoc(doc, localHtml as string, ORIGINS.MIGRATION)) {
+        stampBodyEdit(doc, ORIGINS.MIGRATION);
+      }
+      if (paths.css && localCss !== null) applyCssToDoc(doc, localCss, ORIGINS.MIGRATION);
+      if (localAnnotations !== null) {
+        applyAnnotationsToDoc(doc, localAnnotations, ORIGINS.MIGRATION);
+      }
+    }, ORIGINS.MIGRATION);
+    opts.journal?.record(slug, {
+      bodyHash: hashBytes(localHtml as string),
+      ...(localCss !== null ? { cssHash: hashBytes(localCss) } : {}),
+    });
+  };
+
+  switch (decision.action) {
+    case 'noop':
+      // Identical (or both empty) — checkpoint identity so the next boot
+      // fast-forwards even if the hub then moves ahead.
+      if (localHtml !== null && localHtml === docHtml && docHtml !== '') {
+        opts.journal?.record(slug, { bodyHash: hashBytes(docHtml) });
+      }
+      break;
+    case 'materialize-hub':
+    case 'fast-forward-hub':
+      // Keep the doc; the projection materializes it to disk (and records the
+      // journal checkpoint on its write).
+      break;
+    case 'seed-local-up':
+      // Doc holds state for OTHER types but no body — seed the local body up.
+      rebuildBodyFromLocal();
+      result = 'body-seed-up';
+      break;
+    case 'conflict': {
+      const snapshots: { local?: string; hub?: string } = {};
+      let snapshotAttempted = false;
+      if (opts.snapshot) {
+        snapshotAttempted = true;
+        try {
+          const localTs = await opts.snapshot(localHtml as string, 'pre-sync-local');
+          if (localTs) snapshots.local = localTs;
+          const hubTs = await opts.snapshot(docHtml, 'pre-sync-hub');
+          if (hubTs) snapshots.hub = hubTs;
+        } catch {
+          /* swallowed below — the missing snapshot ref drives the fail-closed guard */
+        }
+      }
+      // DDR-102 fail-closed (security F1): a hub-wins resolution keeps the doc
+      // (hub) state, which projection.reconcile() then materializes to disk —
+      // OVERWRITING local. If the local snapshot didn't land, rebuild the body
+      // from local instead so the projection writes local back (a no-op on
+      // disk) and nothing is lost. Gated on `snapshotAttempted` so a
+      // snapshot-less standalone call keeps plain newest-wins.
+      const localSnapshotMissing = snapshotAttempted && !snapshots.local;
+      let winner = decision.winner;
+      if (winner === 'hub' && localSnapshotMissing) {
+        winner = 'local';
+        console.error(
+          `[sync/${slug}] shared-doc cold-start divergence: hub won newest-wins but the local snapshot FAILED — REFUSING to overwrite local (DDR-102 fail-closed). Rebuilding the doc from local; resolve the _history/ write failure to restore newest-wins.`
+        );
+      }
+      if (winner === 'local') {
+        rebuildBodyFromLocal();
+        result = 'conflict-local-wins';
+      } else {
+        result = 'conflict-hub-wins';
+      }
+      console.warn(`[sync/${slug}] shared-doc cold-start divergence — ${decision.reason}`);
+      opts.onConflict?.({
+        slug,
+        kind: 'cold-start-diverged',
+        winner,
+        ...(snapshots.local || snapshots.hub ? { snapshots } : {}),
+        ...(localSnapshotMissing ? { snapshotFailed: true } : {}),
+      });
+      break;
+    }
+  }
 
-  doc.transact(() => {
-    if (localHtml) applyHtmlToDoc(doc, localHtml, ORIGINS.MIGRATION);
-    if (localComments) {
-      const parsed = tryParseJsonArray(localComments);
-      if (parsed) applyCommentsToDoc(doc, parsed, ORIGINS.MIGRATION);
+  // Comments id-union (DDR-102): rebuild from merged JSON via the
+  // delete-then-insert codec — same-id entries keep the doc's version, so the
+  // duplication trap stays closed; local-only comments survive.
+  if (localComments) {
+    const parsed = tryParseJsonArray(localComments);
+    if (parsed && parsed.length > 0) {
+      const docList = doc.getArray(Y_TYPES.comments).toArray();
+      const merged = unionCommentsById(docList, parsed);
+      if (merged.length !== docList.length) {
+        doc.transact(() => {
+          applyCommentsToDoc(doc, merged, ORIGINS.MIGRATION);
+        }, ORIGINS.MIGRATION);
+      }
     }
-    if (localAnnotations) applyAnnotationsToDoc(doc, localAnnotations, ORIGINS.MIGRATION);
-    if (paths.meta && localMeta) applyMetaToDoc(doc, localMeta, ORIGINS.MIGRATION);
-    if (paths.css && localCss) applyCssToDoc(doc, localCss, ORIGINS.MIGRATION);
-  }, ORIGINS.MIGRATION);
+  }
 
-  return 'local-adopt';
+  return result;
 }
 
 /* ---------------------------------------------------------------- helpers */
@@ -147,6 +297,14 @@ function readLocal(p: string): string | null {
   }
 }
 
+function localMtimeMs(p: string): number | null {
+  try {
+    return statSync(p).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
 // Proto-pollution-safe (DDR-054 §2g), mirroring the agent + projection comments
 // parse — a planted local `_comments/<slug>.json` must not seed dangerous keys
 // during adopt.

package/apps/studio/sync/projection.ts

@@ -42,8 +42,10 @@ import {
   MAX_META_BYTES,
   mergeSharedMetaIntoLocal,
   metaFromDoc,
+  stampBodyEdit,
 } from './codec.ts';
 import { type EchoGuard, hashBytes } from './echo-guard.ts';
+import type { SyncJournal } from './journal.ts';
 import { ORIGINS } from './origins.ts';
 
 export const PROJECT_FLUSH_MS = 800;
@@ -78,6 +80,9 @@ export interface DocProjectionOptions {
   flushMs?: number;
   /** Circuit-breaker threshold (consecutive parse failures per path). */
   maxStrikes?: number;
+  /** DDR-102 — per-machine sync journal; every successful disk↔doc body/css
+   *  traversal checkpoints here (same discipline as the agent). Optional. */
+  journal?: SyncJournal;
 }
 
 export interface DocProjection {
@@ -177,6 +182,7 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
     recordEcho(paths.html, next);
     writer(paths.html, next);
     lastHtml = next;
+    opts.journal?.record(slug, { bodyHash: hashBytes(next) }); // DDR-102 checkpoint
   }
 
   function writeCssIfChanged(): void {
@@ -188,6 +194,7 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
     if (!withinCap(paths.css, next, MAX_CSS_BYTES)) return;
     recordEcho(paths.css, next);
     writer(paths.css, next);
+    opts.journal?.record(slug, { cssHash: hashBytes(next) }); // DDR-102 checkpoint
   }
 
   function writeMetaIfChanged(): void {
@@ -257,14 +264,26 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
 
     if (evt.path === paths.html) {
       clearStrike(evt.path);
-      const changed = applyHtmlToDoc(doc, str, importOrigin);
-      if (changed) lastHtml = htmlFromDoc(doc);
+      // Body import + syncMeta stamp in ONE transaction (same FILE_IMPORT
+      // origin) — peers get a single update carrying the newest-wins stamp.
+      let changed = false;
+      doc.transact(() => {
+        changed = applyHtmlToDoc(doc, str, importOrigin);
+        if (changed) stampBodyEdit(doc, importOrigin);
+      }, importOrigin);
+      if (changed) {
+        lastHtml = htmlFromDoc(doc);
+        opts.journal?.record(slug, { bodyHash: evt.hash }); // DDR-102 checkpoint
+      }
       return changed;
     }
     if (paths.css && evt.path === paths.css) {
       clearStrike(evt.path);
       const changed = applyCssToDoc(doc, str, importOrigin);
-      if (changed) lastCss = str;
+      if (changed) {
+        lastCss = str;
+        opts.journal?.record(slug, { cssHash: evt.hash }); // DDR-102 checkpoint
+      }
       return changed;
     }
     if (paths.meta && evt.path === paths.meta) {

package/apps/studio/sync/status.ts

@@ -14,12 +14,23 @@
 
 import type { SyncStatusSnapshot } from './connection-state.ts';
 
-export type ConflictKind = 'cold-start-hub-wins' | 'git-pull';
+// `cold-start-hub-wins` stays in the union for OLD payload readers (additive
+// evolution — the NoSyncablePayload discriminator pattern); new conflicts are
+// recorded as `cold-start-diverged` with the DDR-102 winner + snapshot refs.
+export type ConflictKind = 'cold-start-hub-wins' | 'cold-start-diverged' | 'git-pull';
 
 export interface SyncConflict {
   slug: string;
   kind: ConflictKind;
   at: number;
+  /** DDR-102 — which side the newest-wins resolution kept. */
+  winner?: 'local' | 'hub';
+  /** DDR-102 — ISO timestamps of the `_history/<slug>/` snapshots taken before
+   *  resolution (`/design:rollback` recovery). */
+  snapshots?: { local?: string; hub?: string };
+  /** DDR-102 fail-closed (F1) — the local snapshot didn't land, so a hub-wins
+   *  overwrite was refused (local kept). Surfaces the degraded `_history/` write. */
+  snapshotFailed?: boolean;
 }
 
 export interface SyncStatusPayload extends SyncStatusSnapshot {
@@ -55,7 +66,7 @@ export interface SyncStatusStore {
   /** Merge a fresh ConnectionMonitor snapshot + persist + broadcast. */
   update(snapshot: SyncStatusSnapshot): void;
   /** Record a conflict notification + persist + broadcast. */
-  addConflict(conflict: { slug: string; kind: ConflictKind }): void;
+  addConflict(conflict: Omit<SyncConflict, 'at'>): void;
   /** Current payload (defensive copy). */
   get(): SyncStatusPayload;
 }
@@ -105,8 +116,8 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
       snapshot = next;
       flush();
     },
-    addConflict({ slug, kind }) {
-      conflicts.push({ slug, kind, at: now() });
+    addConflict(conflict) {
+      conflicts.push({ ...conflict, at: now() });
       if (conflicts.length > maxConflicts) conflicts.splice(0, conflicts.length - maxConflicts);
       flush();
     },