@1agh/maude 1.0.11 → 1.3.0

package/apps/studio/sync/status.ts

@@ -14,11 +14,16 @@
 
 import type { AssetPushProgress } from './asset-push.ts';
 import type { SyncStatusSnapshot } from './connection-state.ts';
+import type { SeedProgress } from './seed-progress.ts';
 
 // `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 type ConflictKind =
+  | 'cold-start-hub-wins'
+  | 'cold-start-diverged'
+  | 'git-pull'
+  | 'body-rejected';
 
 export interface SyncConflict {
   slug: string;
@@ -32,6 +37,8 @@ export interface SyncConflict {
   /** 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;
+  /** #121 — source refused before materializing or importing. */
+  reason?: 'invalid-source' | 'local-edit' | 'history-failed' | 'merge-budget';
 }
 
 export interface SyncStatusPayload extends SyncStatusSnapshot {
@@ -41,6 +48,11 @@ export interface SyncStatusPayload extends SyncStatusSnapshot {
   canvases: number;
   /** Recent conflict notifications (most-recent-last, capped). */
   conflicts: SyncConflict[];
+  /**
+   * When the ConnectionMonitor last spoke, as distinct from when this payload
+   * was built (`updatedAt`). Additive — see the note in `payload()`.
+   */
+  connectionUpdatedAt?: number;
   /**
    * Phase 9.2 (DDR-064) — true when the unified single-shared-doc model is
    * active (MAUDE_SHARED_DOC). Lets `maude design status` + the browser banner
@@ -69,6 +81,28 @@ export interface SyncStatusPayload extends SyncStatusSnapshot {
    * panel and keeps a machine-local dismiss ack keyed on (id, hub url).
    */
   notices?: SyncNotice[];
+  /**
+   * Plan T29 — accepted revisions: what a person is waiting on. Additive;
+   * absent until the project saves through accepted revisions.
+   */
+  accepted?: AcceptedSaveStatus;
+  /**
+   * Plan T29 — cold open: ms from the runtime's start until every canvas was
+   * in step, and until the file plane first converged (media complete).
+   * Additive; each appears once it happens.
+   */
+  coldOpen?: { canvasesMs?: number; filesMs?: number };
+  /** Plan T29 — the newest accepted revision this checkout has written (vs the hub's head). */
+  appliedRevision?: number;
+  /** Plan T16 — an AI action open or held (unfinished). Absent when none. */
+  aiAction?: { state: 'open' | 'held'; label: string; canvases: string[]; since: number };
+}
+
+export interface AcceptedSaveStatus {
+  pending: number;
+  oldestPendingAt: number | null;
+  ackMs: { last: number | null; p95: number | null; n: number };
+  rejected: number;
 }
 
 export interface SyncNotice {
@@ -112,6 +146,25 @@ export interface FilePlaneStatus {
     /** One sentence, in the user's terms, about what is waiting and why. */
     detail: string;
   }[];
+  /**
+   * Files this lane could NOT move on the last pass — issue #109.
+   *
+   * `held` covers the breakers, which are deliberate refusals this machine
+   * made. This covers the other half: a transfer the hub refused, or a write
+   * that failed. It had no field at all, so ~200 refused assets rendered as a
+   * status bar reading `synced` and a person seeing broken images with no
+   * cause anywhere but a terminal they never open. Same disease `held` was
+   * added to cure, one lane over.
+   */
+  failed?: number;
+  /**
+   * The hub asked us to slow down and the WHOLE LANE is paused until `until`.
+   *
+   * Distinguished from `failed` because the answer is different: nothing is
+   * wrong, nothing is lost, and there is nothing to do but wait — which is
+   * exactly what a person cannot infer from a count of failures.
+   */
+  rateLimited?: { until: number; waiting: number };
   /**
    * THE DORUČENKA (DDR-226 §7) — per-path delivery state.
    *
@@ -126,6 +179,26 @@ export interface FilePlaneStatus {
    * as the thing to disagree with.
    */
   delivery?: Record<string, string>;
+  /**
+   * How many delivery rows were dropped from `delivery` by its cap.
+   *
+   * The map used to be unbounded — one entry per ledger row, so 2 961 keys for
+   * a real project, re-serialized into `_sync.json` AND broadcast over the
+   * WebSocket on EVERY status change, including 200 ms-throttled asset-progress
+   * emits. Same bounding shape `items`/`itemsTruncated` already uses.
+   */
+  deliveryTruncated?: number;
+  /**
+   * THE DENOMINATOR (feature-large-project-seed).
+   *
+   * Derived from the LEDGER rather than from per-pass results — see
+   * `seed-progress.ts` for why the per-pass counters read zero for twenty
+   * minutes while 2 961 rows changed underneath them. The raw counters above
+   * stay beside it deliberately: a panel derived from the same source it
+   * displays cannot be cross-checked, and DDR-214's lesson is that a status
+   * surface has to be falsifiable.
+   */
+  progress?: SeedProgress;
 }
 
 export interface SyncStatusStoreOptions {
@@ -139,6 +212,8 @@ export interface SyncStatusStoreOptions {
   broadcast?: (payload: SyncStatusPayload) => void;
   /** Max conflict notifications retained. Default 20. */
   maxConflicts?: number;
+  /** Floor between two writes/broadcasts. 0 disables coalescing (tests). */
+  flushIntervalMs?: number;
   now?: () => number;
 }
 
@@ -154,19 +229,35 @@ export interface SyncStatusStore {
   /** feature-sync-file-plane — merge Plane B counts + persist + broadcast.
    *  Same reasoning as `updateAssets`: a lane, not a connection. */
   updateFiles(files: FilePlaneStatus): void;
+  /** Plan T29 — accepted-revisions save counters. */
+  updateAccepted(next: AcceptedSaveStatus): void;
+  /** Plan T29 — the newest accepted revision written to this checkout. */
+  noteAppliedRevision(revision: number): void;
+  /** Plan T16 — the AI action stage (null clears it). */
+  updateAiAction(next: SyncStatusPayload['aiAction'] | null): void;
   /** Record a consent-class notice (A7) + persist + broadcast. Idempotent by
    *  `id` — the notice sites fire once per boot, and a repeat is a no-op
    *  rather than a duplicate row. */
   notice(notice: Omit<SyncNotice, 'at'>): void;
+  /** Remove a resolved source-sync warning; consent notices are untouched. */
+  clearSourceConflict(slug: string): void;
   /** Current payload (defensive copy). */
   get(): SyncStatusPayload;
 }
 
 const DEFAULT_MAX_CONFLICTS = 20;
 
+/** Floor between two status writes/broadcasts. Matches `asset-push.ts`'s own
+ *  `PROGRESS_INTERVAL_MS` — the lane that emits fastest sets the pace. */
+export const STATUS_FLUSH_MS = 200;
+
+/** Delivery rows one payload carries, actionable-first. See `deliveryTruncated`. */
+export const MAX_DELIVERY_ROWS = 300;
+
 export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusStore {
   const now = opts.now ?? Date.now;
   const maxConflicts = opts.maxConflicts ?? DEFAULT_MAX_CONFLICTS;
+  const flushIntervalMs = opts.flushIntervalMs ?? STATUS_FLUSH_MS;
   const conflicts: SyncConflict[] = [];
 
   let snapshot: SyncStatusSnapshot = {
@@ -183,22 +274,61 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
 
   let assets: AssetPushProgress | undefined;
   let files: FilePlaneStatus | undefined;
+  let accepted: AcceptedSaveStatus | undefined;
+  let aiAction: SyncStatusPayload['aiAction'] | undefined;
+  const bootAt = now();
+  const coldOpen: { canvasesMs?: number; filesMs?: number } = {};
+  let appliedRevision: number | undefined;
   const notices: SyncNotice[] = [];
 
   function payload(): SyncStatusPayload {
     return {
       ...snapshot,
+      // WHEN THIS PAYLOAD WAS BUILT, not when the connection monitor last
+      // spoke. `updatedAt` arrived here by spreading the monitor's snapshot,
+      // which only `update()` refreshes — so `updateFiles()` and
+      // `updateAssets()` flushed payloads carrying a stale timestamp ABOUT
+      // THEMSELVES. Measured at 130 s stale against a ledger that was current
+      // to within a second, on a file being rewritten continuously. A
+      // freshness stamp that lies is worse than none: it is what a person (and
+      // `maude design status`) uses to decide whether sync is alive at all.
+      updatedAt: now(),
+      // The monitor's own stamp, preserved under a name that says what it is,
+      // so nothing that depended on the old meaning silently changes meaning.
+      connectionUpdatedAt: snapshot.updatedAt,
       url: opts.url,
       canvases: opts.canvases,
       conflicts: conflicts.slice(),
       ...(opts.sharedDoc ? { sharedDoc: true } : {}),
       ...(assets ? { assets } : {}),
       ...(files ? { files } : {}),
+      ...(accepted ? { accepted } : {}),
+      ...(aiAction ? { aiAction } : {}),
+      ...(coldOpen.canvasesMs !== undefined || coldOpen.filesMs !== undefined
+        ? { coldOpen: { ...coldOpen } }
+        : {}),
+      ...(appliedRevision !== undefined ? { appliedRevision } : {}),
       ...(notices.length ? { notices: notices.slice() } : {}),
     };
   }
 
-  function flush(): void {
+  /**
+   * Write + broadcast, COALESCED.
+   *
+   * Every emit used to re-serialize the whole payload — including an unbounded
+   * per-path delivery map — to disk and to every open tab. During a seed the
+   * asset lane alone emits every 200 ms, and the file lane emits per pass, so
+   * the cost was paid continuously for a payload nobody could read that fast.
+   *
+   * `immediate` is not an optimisation escape hatch: conflicts, notices and
+   * terminal transitions are the events a person is waiting on, and delaying
+   * those by even a debounce window is the class of lie this file exists to
+   * avoid.
+   */
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+  let pendingFlush = false;
+
+  function emit(): void {
     const p = payload();
     try {
       opts.write(p);
@@ -212,28 +342,93 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
     }
   }
 
+  function flush(immediate = false): void {
+    if (flushIntervalMs <= 0) {
+      emit();
+      return;
+    }
+    if (!immediate && flushTimer !== null) {
+      pendingFlush = true;
+      return;
+    }
+    // An immediate flush jumps the queue but still OPENS the window — without
+    // that, every urgent write was followed by a free un-coalesced one, so a
+    // conflict during a seed re-admitted the whole burst it was jumping ahead of.
+    if (flushTimer !== null) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    pendingFlush = false;
+    emit();
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      // Only if something arrived while we were waiting — an idle store must
+      // not keep a timer alive forever.
+      if (pendingFlush) {
+        pendingFlush = false;
+        flush();
+      }
+    }, flushIntervalMs);
+    flushTimer.unref?.();
+  }
+
   return {
     update(next) {
+      const changed = snapshot.state !== next.state;
       snapshot = next;
-      flush();
+      const d = next.docs;
+      if (coldOpen.canvasesMs === undefined && d && d.synced > 0 && d.pending === 0) {
+        coldOpen.canvasesMs = now() - bootAt;
+      }
+      // A connection state CHANGE is the headline; a heartbeat is not.
+      flush(changed);
     },
     addConflict(conflict) {
       conflicts.push({ ...conflict, at: now() });
       if (conflicts.length > maxConflicts) conflicts.splice(0, conflicts.length - maxConflicts);
-      flush();
+      flush(true);
     },
     updateAssets(progress) {
       assets = progress;
       flush();
     },
+    noteAppliedRevision(revision) {
+      if (appliedRevision !== undefined && revision <= appliedRevision) return;
+      appliedRevision = revision;
+      flush();
+    },
+    updateAiAction(next) {
+      aiAction = next ?? undefined;
+      flush(true);
+    },
+    updateAccepted(next) {
+      const was = accepted;
+      accepted = next;
+      // Going from waiting to caught-up (or back) is news; a latency tick is not.
+      flush(
+        ((was?.pending ?? 0) === 0) !== (next.pending === 0) || next.rejected !== was?.rejected
+      );
+    },
     updateFiles(next) {
       files = next;
-      flush();
+      if (coldOpen.filesMs === undefined && next.progress?.phase === 'converged') {
+        coldOpen.filesMs = now() - bootAt;
+      }
+      // A finished or stalled seed is what a person is waiting to see; a
+      // mid-seed tick is not.
+      flush(next.progress?.phase === 'converged' || next.progress?.phase === 'blocked');
     },
     notice(next) {
       if (notices.some((n) => n.id === next.id)) return;
       notices.push({ ...next, at: now() });
-      flush();
+      flush(true);
+    },
+    clearSourceConflict(slug) {
+      const id = `source-conflict-${slug}`;
+      const index = notices.findIndex((n) => n.id === id);
+      if (index < 0) return;
+      notices.splice(index, 1);
+      flush(true);
     },
     get: payload,
   };