@1agh/maude 1.0.11 → 1.3.0

package/apps/studio/sync/journal-client.ts

@@ -86,6 +86,13 @@ function parseEntry(raw: unknown): JournalEntry | null {
  * Returns null when the hub is unreachable, refuses, or does not have the
  * route — the `fetchRemoteListing` posture: sync continues either way and we
  * ask again later. A null is never "nothing changed".
+ *
+ * It is also never "and there is nothing to learn from it". The cursor read
+ * shares the hub's per-label read bucket with the file pulls, so during a rate
+ * limit THIS is the request that meets the wall first — and collapsing that to
+ * a bare null is how issue #109 stayed invisible: a held plane and a
+ * quiet, ordinary, do-nothing pass are indistinguishable to the caller.
+ * `onRefused` hands the response to whoever can tell the difference.
  */
 export async function fetchJournal(opts: {
   hubUrl: string;
@@ -94,6 +101,8 @@ export async function fetchJournal(opts: {
   /** Send the epoch a cursor belongs to so a mismatch fails closed hub-side. */
   epoch?: string | null;
   fetchImpl?: typeof fetch;
+  /** Called with the response before a non-ok status becomes `null`. */
+  onRefused?: (res: Response) => void | Promise<void>;
 }): Promise<JournalPage | null> {
   const fetchImpl = opts.fetchImpl ?? fetch;
   const base = opts.hubUrl.replace(/\/+$/, '');
@@ -105,7 +114,10 @@ export async function fetchJournal(opts: {
       headers: { authorization: `Bearer ${opts.token}` },
       signal: AbortSignal.timeout(JOURNAL_TIMEOUT_MS),
     });
-    if (!res.ok) return null;
+    if (!res.ok) {
+      await opts.onRefused?.(res);
+      return null;
+    }
     const body = (await res.json()) as Record<string, unknown>;
     // The head and the epoch are the anchor the whole cursor protocol rests
     // on, and both arrive from a component DDR-054 calls untrusted. A

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

@@ -35,6 +35,7 @@ import path from 'node:path';
 import type * as Y from 'yjs';
 
 import { Y_TYPES } from '../collab/persistence.ts';
+import { atomicWrite } from './atomic-write.ts';
 import {
   annotationsEditAtFromDoc,
   applyAnnotationsToDoc,
@@ -49,11 +50,22 @@ import {
   Y_SYNC_TYPES,
 } from './codec.ts';
 import type { ColdStartAction } from './cold-start.ts';
-import { decideAnnotationsColdStart, decideColdStart, unionCommentsById } from './cold-start.ts';
-import { applyColdStart } from './cold-start-apply.ts';
+import {
+  decideAnnotationsColdStart,
+  decideColdStart,
+  decideCssColdStart,
+  isExactRepeat,
+  unionCommentsById,
+} from './cold-start.ts';
+import { applyColdStart, type ColdStartSnapshotReason } from './cold-start-apply.ts';
 import { hashBytes } from './echo-guard.ts';
 import type { SyncJournal } from './journal.ts';
 import { ORIGINS } from './origins.ts';
+import { collapseRepeatedModule, collapseRepeatedText } from './repeated-module.ts';
+import { rememberSeed } from './seed-repair.ts';
+import { mergeSource } from './source-merge.ts';
+import { lastValidSource, readRecoveryBody, saveRecoveryBody } from './source-recovery.ts';
+import { sourceError } from './source-validation.ts';
 
 export interface MigrateSeedPaths {
   html: string;
@@ -74,7 +86,7 @@ export interface MigrateSeedOptions {
   /** 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>;
+  snapshot?: (content: string, reason: ColdStartSnapshotReason) => Promise<string | null>;
   /**
    * Does the HUB hold state for this slug, per its last document listing?
    *
@@ -92,6 +104,13 @@ export interface MigrateSeedOptions {
    * does not have it", which is the pre-existing behaviour.
    */
   hubHasState?: (slug: string) => boolean;
+  /**
+   * A local candidate diverged from the hub body and could not be merged from
+   * their shared base. Neither side is overwritten: the caller hands `base` to
+   * the projection (`adoptBase`) so its write stays blocked with a visible
+   * conflict until a later save resolves it (audit 2026-09-13 P0 #1 / T2).
+   */
+  onHold?: (base: string) => void;
   /** DDR-102 — divergence notification, same contract as the agent's. */
   onConflict?: (info: {
     slug: string;
@@ -118,6 +137,10 @@ export type MigrateSeedResult =
   /** DDR-102 — divergence resolved newest-wins. */
   | 'conflict-local-wins'
   | 'conflict-hub-wins'
+  /** T2 — divergence resolved by a clean three-way merge from the saved base. */
+  | 'conflict-merged'
+  /** T2 — divergence that no merge could prove independent; both kept, held. */
+  | 'conflict-held'
   /** The replica is empty but the HUB is not — its state is still in flight.
    *  Seeding here is the F1 collision (see `hubHasState`), so this seed does
    *  nothing and lets the document arrive. */
@@ -141,11 +164,17 @@ export function docIsEmpty(doc: Y.Doc): boolean {
 export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeedResult> {
   const { slug, doc, paths } = opts;
 
-  const localHtml = readLocal(paths.html);
+  // A file already holding its module k× over (an earlier seed race) enters
+  // as ONE copy — adopting it as-is would plant the repeat in the project.
+  const readHtml = readLocal(paths.html);
+  const diskHtml = readHtml === null ? null : (collapseRepeatedModule(readHtml)?.unit ?? readHtml);
+  const localHtml =
+    diskHtml !== null && sourceError(paths.html, diskHtml) === null ? diskHtml : null;
   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 readCss = paths.css ? readLocal(paths.css) : null;
+  const localCss = readCss === null ? null : (collapseRepeatedText(readCss)?.unit ?? readCss);
 
   // 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
@@ -177,6 +206,7 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
 
     doc.transact(() => {
       if (localHtml) {
+        rememberSeed(doc, localHtml, localCss, ORIGINS.MIGRATION);
         if (applyHtmlToDoc(doc, localHtml, ORIGINS.MIGRATION)) {
           stampBodyEdit(doc, ORIGINS.MIGRATION);
         }
@@ -214,6 +244,16 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
   // boot — not spam) so non-body files keep their pre-cutover backup too.
   snapshotLocal(opts);
 
+  // Invalid hub source must reach the projector's quarantine unchanged. Never
+  // checkpoint it, elect it by timestamp, or merge a healthy local file into it
+  // merely because the connection restarted. A deliberate file edit can repair it.
+  if (
+    sourceError(paths.html, doc.getText(Y_SYNC_TYPES.html).toString()) !== null &&
+    !(localHtml && isExactRepeat(doc.getText(Y_SYNC_TYPES.html).toString(), localHtml))
+  ) {
+    return 'hub-wins';
+  }
+
   // Body resolution via the DDR-102 decision table.
   const docHtml = doc.getText(Y_SYNC_TYPES.html).toString();
   const decision = decideColdStart({
@@ -230,6 +270,7 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
    *  below (decideAnnotationsColdStart), independent of the body winner. */
   const rebuildBodyFromLocal = (): void => {
     doc.transact(() => {
+      if (docHtml === '' && localHtml) rememberSeed(doc, localHtml, localCss, ORIGINS.MIGRATION);
       if (applyHtmlToDoc(doc, localHtml as string, ORIGINS.MIGRATION)) {
         stampBodyEdit(doc, ORIGINS.MIGRATION);
       }
@@ -248,22 +289,61 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
   // fail-closed refusal, the conflict report, and crucially the
   // `recover-seed-dup` row this switch used to be missing — now lives in
   // exactly one place.
-  const applied = await applyColdStart({
-    slug,
-    decision,
-    localBody: localHtml,
-    docBody: docHtml,
-    takeHub: () => {
-      /* the projection materializes the doc; nothing to do here */
-    },
-    takeLocal: rebuildBodyFromLocal,
-    checkpointIdentity: (body) => opts.journal?.record(slug, { bodyHash: hashBytes(body) }),
-    logLabel: 'shared-doc',
-    ...(opts.snapshot ? { snapshot: opts.snapshot } : {}),
-    ...(opts.onConflict ? { onConflict: opts.onConflict } : {}),
-  });
-
-  const result: MigrateSeedResult = resultFor(applied.action, applied.bodyWinner);
+  // A DIVERGENCE WITH A KNOWN BASE IS NOT A COIN TOSS. Newest-wins keeps one
+  // side and snapshots the other — recoverable, but the peer's edit is gone
+  // from the canvas. When the projection saved the body both sides last agreed
+  // on (and the journal proves it is that body), merge from it exactly as a
+  // live save does; if the edits touch, hold both and let the projection keep
+  // the conflict visible. No base (older state) keeps DDR-102's table.
+  const journalHash = opts.journal?.get(slug)?.bodyHash ?? null;
+  const savedBase =
+    decision.action === 'conflict' && opts.historyDir && journalHash !== null
+      ? readRecoveryBody(opts.historyDir, paths.html, 'base')
+      : null;
+  const base = savedBase !== null && hashBytes(savedBase) === journalHash ? savedBase : null;
+  let applied: { action: ColdStartAction; bodyWinner: 'local' | 'hub' };
+  let result: MigrateSeedResult;
+  if (base !== null && localHtml !== null) {
+    const merged = mergeSource(base, localHtml, docHtml);
+    if (opts.snapshot) {
+      try {
+        await opts.snapshot(localHtml, 'pre-sync-local');
+        await opts.snapshot(docHtml, 'pre-sync-hub');
+      } catch {
+        /* best-effort — neither branch below overwrites a side it did not merge */
+      }
+    }
+    if (merged.ok && sourceError(paths.html, merged.merged) === null) {
+      doc.transact(() => {
+        if (applyHtmlToDoc(doc, merged.merged, ORIGINS.MIGRATION)) {
+          stampBodyEdit(doc, ORIGINS.MIGRATION);
+        }
+      }, ORIGINS.MIGRATION);
+      // The projection writes the merged body and checkpoints it.
+      result = 'conflict-merged';
+    } else {
+      opts.onHold?.(base);
+      result = 'conflict-held';
+    }
+    // The coupled lanes resolve per-lane against the hub, as on a hub-wins boot.
+    applied = { action: 'conflict', bodyWinner: 'hub' };
+  } else {
+    applied = await applyColdStart({
+      slug,
+      decision,
+      localBody: localHtml,
+      docBody: docHtml,
+      takeHub: () => {
+        /* the projection materializes the doc; nothing to do here */
+      },
+      takeLocal: rebuildBodyFromLocal,
+      checkpointIdentity: (body) => opts.journal?.record(slug, { bodyHash: hashBytes(body) }),
+      logLabel: 'shared-doc',
+      ...(opts.snapshot ? { snapshot: opts.snapshot } : {}),
+      ...(opts.onConflict ? { onConflict: opts.onConflict } : {}),
+    });
+    result = resultFor(applied.action, applied.bodyWinner);
+  }
 
   // ---- annotations: PER-LANE newest-wins (the 2026-08-14 eraser fix; the
   // same table as agent.ts reconcile). Under sharedDoc the collab room's
@@ -298,6 +378,38 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
     // annotations doc→file half and materializes it (persistJson).
   }
 
+  // ---- css: PER-LANE resolution (issue #114), the same table agent.ts uses.
+  // `rebuildBodyFromLocal` above already re-seeds css when the BODY winner was
+  // local; this block is what covers every other row — above all the exact-repeat
+  // collapse, which is how a `CSS × N` lane from a concurrent cold seed gets
+  // back to one copy on a hub-wins boot. It no-ops when the two sides already
+  // agree, so running after the body applier costs nothing.
+  if (paths.css) {
+    const docCssNow = doc.getText(Y_SYNC_TYPES.css).toString();
+    const cssDecision = decideCssColdStart({
+      local: localCss,
+      doc: docCssNow.length > 0 ? docCssNow : null,
+      journalHash: opts.journal?.get(slug)?.cssHash ?? null,
+      hash: hashBytes,
+      bodyWinner: applied.bodyWinner,
+    });
+    if (cssDecision.recoveredDuplication) {
+      // Warn, don't snapshot — see the note on the same branch in agent.ts
+      // reconcile. An exact integer repeat carries no unique bytes to recover,
+      // and snapshotting it hands a hostile hub an eviction lever against the
+      // `_history/` copies that DO.
+      console.warn(`[sync/${slug}] shared-doc cold-start css: ${cssDecision.reason}`);
+    }
+    if (cssDecision.winner === 'local' && localCss !== null) {
+      doc.transact(() => {
+        applyCssToDoc(doc, localCss, ORIGINS.MIGRATION);
+      }, ORIGINS.MIGRATION);
+      opts.journal?.record(slug, { cssHash: hashBytes(localCss) });
+    }
+    // winner 'hub' → nothing to write here: the projection materializes the
+    // doc's css to disk, exactly as it does for the body.
+  }
+
   // 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.
@@ -357,7 +469,23 @@ function snapshotLocal(opts: MigrateSeedOptions): void {
       opts.paths.css,
     ]) {
       if (p && existsSync(p)) {
-        copyFileSync(p, path.join(dir, path.basename(p)));
+        const target = path.join(dir, path.basename(p));
+        if (p === opts.paths.html) {
+          const current = readLocal(p);
+          // A body holding the same module twice over parses, but it is the
+          // corruption this snapshot exists to survive — never its "valid"
+          // copy, and never a reason to replace a healthy earlier snapshot.
+          const healthy = (body: string | null): body is string =>
+            !!body?.trim() &&
+            sourceError(p, body) === null &&
+            collapseRepeatedModule(body) === null;
+          const valid = healthy(current) ? current : lastValidSource(opts.historyDir, p);
+          if (valid && healthy(valid)) {
+            saveRecoveryBody(opts.historyDir, p, 'last-valid', valid);
+            const prior = readLocal(target);
+            if (!healthy(prior)) atomicWrite(target, valid);
+          }
+        } else copyFileSync(p, target);
       }
     }
   } catch {

package/apps/studio/sync/poke.ts

@@ -22,6 +22,8 @@ const MAX_POKE_BYTES = 512;
 export interface Poke {
   /** The hub's journal head at emit time. A hint, never an authority. */
   head: number;
+  /** Only document membership changed; do not scan or transfer the file plane. */
+  documents?: true;
 }
 
 /**
@@ -42,9 +44,9 @@ export function parsePoke(payload: unknown): Poke | null {
     return null;
   }
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
-  const frame = parsed as { t?: unknown; head?: unknown };
+  const frame = parsed as { t?: unknown; head?: unknown; documents?: unknown };
   if (frame.t !== 'files') return null;
   const head = frame.head;
   if (typeof head !== 'number' || !Number.isInteger(head) || head < 0) return null;
-  return { head };
+  return frame.documents === true ? { head, documents: true } : { head };
 }