@1agh/maude 1.0.11 → 1.3.0

package/apps/studio/sync/presentation.ts

@@ -25,7 +25,9 @@ export type SyncPhase =
   | 'stalled'
   | 'refused'
   | 'offline'
-  | 'nothing-syncable';
+  | 'nothing-syncable'
+  /** The link works, but part of the project did not get through. */
+  | 'attention';
 
 /**
  * How long `connecting…` may honestly stay on screen with ZERO documents
@@ -71,6 +73,18 @@ export interface SyncStatusLike extends Partial<SyncStatusSnapshot> {
   tsxCount?: number;
   reason?: string;
   canvases?: number;
+  /**
+   * The other lanes `_sync.json` carries (`status.ts`): source-sync conflicts,
+   * the file plane, the asset push. Typed `unknown` on purpose — they are read
+   * off disk with no schema and validated below, never trusted.
+   */
+  conflicts?: unknown;
+  files?: unknown;
+  assets?: unknown;
+  /** Accepted-revisions save counters (plan T29) — validated below. */
+  accepted?: unknown;
+  /** An AI action open or held (plan T16) — validated below. */
+  aiAction?: unknown;
 }
 
 /** Hub-supplied text that reaches a UI. Bounded, never markup. */
@@ -143,6 +157,118 @@ function readCounts(
   return { synced: docs.synced, pending: docs.pending, rejected: docs.rejected };
 }
 
+const isCount = (n: unknown): n is number => typeof n === 'number' && Number.isInteger(n) && n >= 0;
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** What the non-document lanes say, validated. */
+interface LaneFacts {
+  /** A payload field we cannot read. Fail closed: never "synced". */
+  unreadable: boolean;
+  /** Canvases whose source change was refused and is waiting (#121 / T2). */
+  sourceSlugs: string[];
+  failedFiles: number;
+  tooLarge: number;
+  blockedOther: number;
+  /** Changes a breaker is holding for a person's decision. */
+  held: number;
+  failedMedia: number;
+  /** Files or media still moving on their own. */
+  moving:
+    | { delivered: number; tracked: number }
+    | { media: { done: number; total: number } }
+    | null;
+  paused: boolean;
+}
+
+/**
+ * Audit 2026-09-13 P0 #3 — "synced" is a claim about the whole project, not
+ * about the document sockets. The payload already carried refused source
+ * changes, failed files, a blocked seed and failed uploads; the summary read
+ * none of them and said "Synced … all 91 canvases" over all four.
+ */
+function readLanes(status: SyncStatusLike): LaneFacts {
+  const facts: LaneFacts = {
+    unreadable: false,
+    sourceSlugs: [],
+    failedFiles: 0,
+    tooLarge: 0,
+    blockedOther: 0,
+    held: 0,
+    failedMedia: 0,
+    moving: null,
+    paused: false,
+  };
+  const { conflicts, files, assets } = status;
+  if (conflicts !== undefined) {
+    if (!Array.isArray(conflicts)) facts.unreadable = true;
+    else {
+      for (const c of conflicts) {
+        // `body-rejected` is the only kind that stays until it is resolved
+        // (`clearSourceConflict`); cold-start notes record a decision made.
+        if (isRecord(c) && c.kind === 'body-rejected') {
+          facts.sourceSlugs.push(typeof c.slug === 'string' ? c.slug : '(unnamed)');
+        }
+      }
+    }
+  }
+  if (files !== undefined) {
+    if (!isRecord(files)) facts.unreadable = true;
+    else {
+      for (const key of ['synced', 'pulled', 'conflicts', 'pushed', 'failed'] as const) {
+        if (files[key] !== undefined && !isCount(files[key])) facts.unreadable = true;
+      }
+      if (isCount(files.failed)) facts.failedFiles = files.failed;
+      if (Array.isArray(files.held)) {
+        for (const h of files.held) facts.held += isRecord(h) && isCount(h.count) ? h.count : 1;
+      }
+      if (isRecord(files.rateLimited)) facts.paused = true;
+      const progress = files.progress;
+      if (isRecord(progress)) {
+        if (Array.isArray(progress.blocked)) {
+          for (const b of progress.blocked) {
+            if (!isRecord(b) || !isCount(b.count)) continue;
+            if (b.class === 'too-large') facts.tooLarge += b.count;
+            else facts.blockedOther += b.count;
+          }
+        }
+        if (progress.phase === 'paused') facts.paused = true;
+        if (
+          progress.phase === 'scanning' ||
+          progress.phase === 'seeding' ||
+          progress.phase === 'paused'
+        ) {
+          facts.moving =
+            isCount(progress.delivered) && isCount(progress.tracked)
+              ? {
+                  delivered: Math.min(progress.delivered, progress.tracked),
+                  tracked: progress.tracked,
+                }
+              : { delivered: 0, tracked: 0 };
+        }
+      } else if (progress !== undefined) facts.unreadable = true;
+    }
+  }
+  if (assets !== undefined) {
+    if (!isRecord(assets)) facts.unreadable = true;
+    else {
+      if (isCount(assets.failedCount)) facts.failedMedia = assets.failedCount;
+      else if (assets.failedCount !== undefined) facts.unreadable = true;
+      if (assets.finished === false && !facts.moving) {
+        facts.moving = {
+          media: {
+            done: isCount(assets.done) ? assets.done : 0,
+            total: isCount(assets.total) ? assets.total : 0,
+          },
+        };
+      }
+    }
+  }
+  return facts;
+}
+
+const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
 /**
  * Read a sync payload the way a person would.
  *
@@ -170,7 +296,26 @@ export function syncPresentation(
     status.startedAt > 0
       ? status.startedAt
       : null;
-  const stalled = (): SyncPresentation => {
+  /**
+   * @param credentialUnknown  Can an expired sign-in still be the cause?
+   *
+   * ONLY BLAME THE SIGN-IN WHEN THE SIGN-IN COULD BE THE PROBLEM (issue #118).
+   * This unconditionally told the person to reconnect the workspace because
+   * "the sign-in may have expired" — at call sites that have ALREADY proved
+   * `rejected === 0`, i.e. where the hub has refused exactly nothing and the
+   * credential is demonstrably fine. Naming a cause we have evidence against is
+   * worse than naming none: it sent the reporter to Resync, which re-handshakes
+   * every canvas against a hub that is not answering, times out the fresh
+   * monitor's grace window, and lands on `offline`. The product talked the
+   * person into making its own display worse.
+   *
+   * A rejection has its OWN branch (`phase: 'refused'`) and outranks this one,
+   * and it is the branch that may legitimately say "credential". Here we say
+   * what we actually know: the hub is not completing handshakes. Only the
+   * legacy no-`docs` payload, where refusals are unknowable, keeps the older
+   * hedge — and it is written as a possibility rather than a diagnosis.
+   */
+  const stalled = (credentialUnknown = false): SyncPresentation => {
     // `?? now` rather than a cast: every call site is behind `isStalled`, which
     // has already proved `startedAt` is a number — and a future one that isn't
     // reads "1 minute" instead of "NaN minutes".
@@ -180,7 +325,9 @@ export function syncPresentation(
       online: false,
       label: 'stalled',
       title: `Nothing has synced with ${project} in the ${min} minute${min === 1 ? '' : 's'} since Maude started trying.`,
-      next: 'Reconnect the workspace — the sign-in may have expired.',
+      next: credentialUnknown
+        ? 'Maude keeps retrying. If it persists, reconnect the workspace — the sign-in may have expired.'
+        : 'Maude keeps retrying — the workspace is reachable but is not completing handshakes.',
       names: [],
     };
   };
@@ -203,6 +350,54 @@ export function syncPresentation(
   const queued = status.queuedOps ?? 0;
   const queueNote = queued > 0 ? ` ${queued} local edit${queued === 1 ? '' : 's'} are queued.` : '';
   const unreachable = status.state === 'offline' || status.state === 'offline-long';
+  const lanes = readLanes(status);
+
+  /**
+   * Part of the project did not get through. `sourceOnly` is the ranking
+   * split: a refused source change never heals on its own, so it outranks an
+   * unreachable hub; a failed transfer may be the outage itself, so file and
+   * media problems rank below it.
+   */
+  const attention = (sourceOnly: boolean): SyncPresentation | null => {
+    const parts: string[] = [];
+    let items = 0;
+    const add = (n: number, text: string) => {
+      if (n <= 0) return;
+      parts.push(text);
+      items += n;
+    };
+    const src = lanes.sourceSlugs.length;
+    add(src, `${plural(src, 'source change')} ${src === 1 ? 'was' : 'were'} not applied`);
+    if (!sourceOnly) {
+      add(lanes.failedFiles, `${plural(lanes.failedFiles, 'file')} could not be delivered`);
+      add(
+        lanes.tooLarge,
+        `${plural(lanes.tooLarge, 'file')} ${lanes.tooLarge === 1 ? 'is' : 'are'} too large to sync`
+      );
+      add(
+        lanes.blockedOther,
+        `${plural(lanes.blockedOther, 'file')} ${lanes.blockedOther === 1 ? 'is' : 'are'} blocked`
+      );
+      add(
+        lanes.held,
+        `${plural(lanes.held, 'change')} ${lanes.held === 1 ? 'is' : 'are'} held for your decision`
+      );
+      add(lanes.failedMedia, `${plural(lanes.failedMedia, 'media upload')} failed`);
+    }
+    if (items === 0) return null;
+    return {
+      phase: 'attention',
+      online: false,
+      label: `${items} to review`,
+      title:
+        `${items === 1 ? 'A change needs' : `${items} changes need`} your attention in ${project}: ` +
+        `${parts.join('; ')}.` +
+        (unreachable ? ' The hub is also unreachable right now.' : '') +
+        queueNote,
+      next: 'Open the Sync panel to see what is waiting and why.',
+      names: shownNames(lanes.sourceSlugs),
+    };
+  };
   // Validated, not taken on trust — see `readCounts`. `null` means "unreadable",
   // which is deliberately NOT the same as "absent" (an old payload, handled
   // below) and must never reach the synced branch.
@@ -232,6 +427,14 @@ export function syncPresentation(
     };
   }
 
+  // A refused SOURCE change outranks an unreachable hub for the same reason a
+  // refusal does: it is sticky, and it is the part that needs a person.
+  // (With the hub reachable, the same sentence lists every other lane too.)
+  if (lanes.sourceSlugs.length > 0) {
+    const sourceAttention = attention(unreachable);
+    if (sourceAttention) return sourceAttention;
+  }
+
   // Otherwise an unreachable hub outranks every count. Whatever the documents
   // last said, nothing is moving — and "72 synced" over a dead socket is the
   // exact shape of lie this module exists to stop.
@@ -249,7 +452,7 @@ export function syncPresentation(
     };
   }
 
-  if (unreadable) {
+  if (unreadable || lanes.unreadable) {
     // A payload we cannot read is not a payload that says everything is fine.
     return {
       phase: 'connecting',
@@ -265,7 +468,11 @@ export function syncPresentation(
     // Pre-DDR-102 payload: `state` is all there is. Report it as the weaker
     // evidence it is, rather than promoting it to a document-level claim.
     const online = status.state === 'online' || status.flash === 'synced';
-    if (!online && isStalled) return stalled();
+    // Pre-DDR-102 payload — no per-document counts, so a refusal cannot be
+    // ruled out and the credential hedge stays.
+    if (!online && isStalled) return stalled(true);
+    const laneAttention = online ? attention(false) : null;
+    if (laneAttention) return laneAttention;
     return {
       phase: online ? 'synced' : 'connecting',
       online,
@@ -292,6 +499,25 @@ export function syncPresentation(
     };
   }
 
+  // Needs a person, so it outranks work that will finish by itself.
+  const laneAttention = attention(false);
+  if (laneAttention) return laneAttention;
+
+  // Plan T16 — an AI edit that did not finish is kept on this device, not
+  // shared. It is the person's decision, so it reads as attention.
+  const ai = readAiAction(status.aiAction);
+  if (ai?.state === 'held') {
+    const n = ai.canvases;
+    return {
+      phase: 'attention',
+      online: true,
+      label: 'AI edit held',
+      title: `An unfinished AI edit to ${n} canvas${n === 1 ? '' : 'es'} is kept on this device — it is not shared with ${project} yet.`,
+      next: 'Open the Sync panel to publish it as it stands or discard it.',
+      names: [],
+    };
+  }
+
   if (docs.pending > 0) {
     // Zero settled yet is a different fact from some settled: one is a
     // handshake in flight, the other is visible progress.
@@ -309,6 +535,61 @@ export function syncPresentation(
     };
   }
 
+  // Every canvas is in step, but files or media are still moving: that is
+  // syncing, not synced. The denominator is the ledger's (seed-progress.ts).
+  if (lanes.moving) {
+    const m = lanes.moving;
+    const detail =
+      'media' in m
+        ? `uploading media (${m.media.done} of ${m.media.total})`
+        : m.tracked > 0
+          ? `files ${m.delivered} of ${m.tracked} delivered`
+          : 'checking project files';
+    return {
+      phase: 'syncing',
+      online: true,
+      label:
+        'media' in m ? 'media ↑' : m.tracked > 0 ? `${m.delivered}/${m.tracked} files` : 'files…',
+      title:
+        `Syncing with ${project} — all ${total} canvas${total === 1 ? '' : 'es'} in step, ${detail}.` +
+        (lanes.paused ? ' Paused while the hub asks us to wait.' : '') +
+        queueNote,
+      next: 'Nothing to do — this continues on its own.',
+      names: [],
+    };
+  }
+
+  // Plan T29 — accepted revisions: "synced" documents only mean the replica is
+  // current. A change still waiting for the project's durable answer is saved
+  // on this device, not yet shared — so it is Saving, never Saved.
+  if (ai?.state === 'open') {
+    return {
+      phase: 'syncing',
+      online: true,
+      label: 'AI editing',
+      title: `An AI edit is in progress — its changes are shared with ${project} together when it finishes.`,
+      next: null,
+      names: [],
+    };
+  }
+  const acceptedPending = readAcceptedPending(status.accepted);
+  if (acceptedPending) {
+    const ageS = acceptedPending.oldestPendingAt
+      ? Math.max(0, Math.round((Date.now() - acceptedPending.oldestPendingAt) / 1000))
+      : 0;
+    return {
+      phase: 'syncing',
+      online: true,
+      label: `saving ${acceptedPending.pending}`,
+      title:
+        `Saving ${acceptedPending.pending} change${acceptedPending.pending === 1 ? '' : 's'} to ${project}` +
+        (ageS >= 10 ? ` — the oldest has waited ${ageS} s.` : '.') +
+        ' They are kept on this device until the project confirms them.',
+      next: ageS >= 60 ? 'Maude keeps trying. If this persists, check your connection.' : null,
+      names: [],
+    };
+  }
+
   // Clamped and validated for the same reason as the doc counts: `count` is
   // read off disk, and "1000000000 came down from the project" is not a
   // sentence this module should be capable of producing. The ceiling is `total`
@@ -336,3 +617,28 @@ export function syncPresentation(
     names: pulledCount > 0 ? shownNames(status.pulled?.names) : [],
   };
 }
+
+/** `status.accepted`, validated — it is read off disk like every other count. */
+function readAcceptedPending(
+  raw: unknown
+): { pending: number; oldestPendingAt: number | null } | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const r = raw as { pending?: unknown; oldestPendingAt?: unknown };
+  const pending = r.pending;
+  if (typeof pending !== 'number' || !Number.isInteger(pending) || pending <= 0 || pending > 1e6)
+    return null;
+  const at = r.oldestPendingAt;
+  return {
+    pending,
+    oldestPendingAt: typeof at === 'number' && Number.isFinite(at) && at > 0 ? at : null,
+  };
+}
+
+/** `status.aiAction`, validated — never trusted off disk. */
+function readAiAction(raw: unknown): { state: 'open' | 'held'; canvases: number } | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const r = raw as { state?: unknown; canvases?: unknown };
+  if (r.state !== 'open' && r.state !== 'held') return null;
+  const canvases = Array.isArray(r.canvases) ? Math.min(r.canvases.length, 10_000) : 0;
+  return { state: r.state, canvases };
+}