@1agh/maude 1.0.11 → 1.2.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

@@ -49,8 +49,13 @@ 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,
+  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';
@@ -74,7 +79,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?
    *
@@ -298,6 +303,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.

package/apps/studio/sync/presentation.ts

@@ -170,7 +170,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 +199,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: [],
     };
   };
@@ -265,7 +286,9 @@ 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);
     return {
       phase: online ? 'synced' : 'connecting',
       online,

package/apps/studio/sync/retry-after.ts

@@ -0,0 +1,169 @@
+// What a refusal MEANS — shared by every sync lane that talks to a hub.
+//
+// This module exists because the lesson had to be learned twice. The
+// 2026-08-11 RCA (alligators, 182 assets, ~5 moved per boot) taught the asset
+// push lane that a 429 is not a failure but an instruction: the hub says when
+// to come back, so come back then, and keep enough of the body to tell "rate
+// limit exceeded" from a Cloudflare error page. All of it lived as private
+// constants inside `asset-push.ts`.
+//
+// So when the journal file plane (DDR-226) became the ONE lane for project
+// files, it inherited none of it — `HTTP ${res.status}` and nothing else. A
+// 429 read as an ordinary error, the pass fired its remaining requests into a
+// closed door, and because the cursor only advances on a clean pass the very
+// next tick re-requested the identical set. The retries were what kept the
+// bucket empty. Issue #109: every asset of a linked project refused, forever,
+// while the status bar said `synced` and a person saw broken images.
+//
+// One copy, imported by both lanes, so there is no third time.
+
+/** Longest single pause a hub can ask for. Matches the hub's rate-limit
+ *  window (60 s) — a `Retry-After` larger than that is either a typo or a hub
+ *  we should not be blocking a boot sweep on. */
+export const MAX_RETRY_DELAY_MS = 60_000;
+
+/** Where an absent/unparsable `Retry-After` lands. Old hubs (pre-fix) send a
+ *  bare 429 with no header, and their window is the same 60 s. */
+export const DEFAULT_RETRY_DELAY_MS = 60_000;
+
+/**
+ * Shortest pause a hub can talk us into.
+ *
+ * The clamp above stops a hub asking for a pause so long it bricks the lane.
+ * This is the other end of the same argument, and it is the one that matters:
+ * the header is hub-controlled, `Retry-After: 0.001` parses as a perfectly
+ * valid millisecond, and a hold of one millisecond is not a hold. A hub that
+ * refuses everything and asks us straight back would put us into the issue-#109
+ * storm again — a refusal loop at full poll rate — with the client believing it
+ * was being obedient the whole time.
+ */
+export const MIN_RETRY_DELAY_MS = 1_000;
+
+/** How much of an error body reaches a `reason`. Enough to tell "rate limit
+ *  exceeded" from a Cloudflare error page — the distinction the 2026-08-11 RCA
+ *  had to reconstruct from edge logs because the client kept only a status. */
+export const ERROR_SNIPPET_CHARS = 80;
+
+/** How much of an error body we will READ to produce those characters.
+ *  Bounded on purpose: the body comes from a component DDR-054 calls
+ *  untrusted, and `await res.text()` on a body that never ends is a heap fill
+ *  dressed as diagnostics. */
+const MAX_SNIPPET_READ_BYTES = 8 * 1024;
+
+/**
+ * `Retry-After: <seconds>` → ms, clamped.
+ *
+ * Only the delta-seconds form is parsed; the HTTP-date form is not something
+ * our hub emits, and guessing at clock skew to support it would make the
+ * pause less predictable, not more.
+ */
+export function retryAfterMs(header: string | null | undefined): number {
+  const secs = Number(String(header ?? '').trim());
+  if (!Number.isFinite(secs) || secs <= 0) return DEFAULT_RETRY_DELAY_MS;
+  // Clamped at BOTH ends — the ceiling stops a hub bricking the lane, the
+  // floor stops one talking us out of pausing at all.
+  return Math.min(Math.max(secs * 1000, MIN_RETRY_DELAY_MS), MAX_RETRY_DELAY_MS);
+}
+
+/** Read at most `MAX_SNIPPET_READ_BYTES` of a body, then hang up. */
+async function readBounded(res: Response): Promise<string> {
+  const body = res.body;
+  if (!body?.getReader) {
+    // No stream to cap (a fixture `Response`, an older polyfill). The text is
+    // still bounded on the way out by `ERROR_SNIPPET_CHARS`.
+    try {
+      return (await res.text()).slice(0, MAX_SNIPPET_READ_BYTES);
+    } catch {
+      return '';
+    }
+  }
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (total < MAX_SNIPPET_READ_BYTES) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        chunks.push(value);
+        total += value.byteLength;
+      }
+    }
+  } catch {
+    /* a body we cannot read tells us nothing — the status still does */
+  } finally {
+    void reader.cancel().catch(() => {});
+  }
+  const joined = new Uint8Array(total);
+  let at = 0;
+  for (const c of chunks) {
+    joined.set(c, at);
+    at += c.byteLength;
+  }
+  return new TextDecoder().decode(joined);
+}
+
+/**
+ * Why a request was refused, in words — status PLUS a bounded snippet of the
+ * body. The hub says `{"error":"rate limit exceeded"}`; an edge that never
+ * reached the hub says HTML. Those are different bugs and the Sync panel
+ * should not make a person read logs to tell them apart.
+ *
+ * The body is hub-supplied ⇒ untrusted (DDR-054): control characters stripped,
+ * whitespace collapsed, hard length cap, and it only ever renders as text.
+ */
+export async function failureReason(res: Response): Promise<string> {
+  const snippet = (await readBounded(res))
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping them is the point.
+    .replace(/[\u0000-\u001f\u007f]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, ERROR_SNIPPET_CHARS);
+  return snippet ? `HTTP ${res.status} — ${snippet}` : `HTTP ${res.status}`;
+}
+
+/** A refusal that names a WALL rather than a fault: the hub is willing, just
+ *  not now. Every lane that can hit one reports it in this shape. */
+export interface RateLimited {
+  rateLimited: true;
+  /** How long the hub asked us to wait, already clamped. */
+  retryAfterMs: number;
+}
+
+/** Is this response the hub telling us to slow down? */
+export function isRateLimited(res: Pick<Response, 'status'>): boolean {
+  return res.status === 429;
+}
+
+/**
+ * Is this response BACKPRESSURE — the peer is willing, just not right now?
+ *
+ * Wider than `isRateLimited`, and the two are deliberately both exported:
+ * a 429 has one precise meaning that other call sites depend on, while this is
+ * the question the transfer lanes actually want to ask.
+ *
+ * Two cases:
+ *   - 429, always. It has one meaning even bare, and `retryAfterMs` supplies a
+ *     sane default when the header is missing.
+ *   - 503 or 502 that CARRIES a `Retry-After`. The header is the peer saying
+ *     "come back at this time", which is precisely what distinguishes a busy
+ *     peer from a broken one.
+ *
+ * THE HEADER IS THE DISCRIMINATOR, and it is doing real work rather than being
+ * a formality. A cell that is starting answers `503 Retry-After: <n>` (see
+ * `cell-do.mjs` `#resolveStorageCredentials`), and firing this pass's whole
+ * request budget into that window is how a slow start becomes a failed one.
+ * A cell that genuinely cannot obtain storage answers a BARE 503 — a broken
+ * deployment, not a wall — and that one must stay an ordinary refusal so the
+ * request ceiling bounds it and the failure surfaces per file.
+ *
+ * Treating every 5xx as backpressure would erase exactly that distinction and
+ * make a broken hub look like a busy one, forever.
+ */
+export function isBackpressure(res: Pick<Response, 'status'> & { headers?: Headers }): boolean {
+  if (res.status === 429) return true;
+  if (res.status === 503 || res.status === 502) {
+    return Boolean(res.headers?.get?.('retry-after'));
+  }
+  return false;
+}

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

@@ -0,0 +1,218 @@
+// How far the file plane has got — derived from the LEDGER, which is the one
+// thing that stayed correct.
+//
+// THE PROBLEM THIS SOLVES. During two real runs against an 8.8 GB project the
+// status payload reported `files: {synced: 0, pushed: 0, pulled: 0}` for twenty
+// minutes while 2 961 ledger rows changed underneath it. The counters were not
+// broken so much as mis-sourced: `sync/index.ts` derived them from PER-PASS
+// results, and a pass where nothing converges is legitimately all zeros. The
+// ledger, meanwhile, was current to within a second the whole time and nothing
+// read it.
+//
+// And even correct counters could not answer the question a seed actually
+// raises. `synced`, `pushed`, `pulled` are numerators with no denominator, so
+// no surface could say "1 412 of 2 961" — only "1 412", which is
+// indistinguishable from "1 412 and finished".
+//
+// A LEAF MODULE, like `limits.ts`, and for the same reason: `status.ts` will
+// import this, and this must never import back. It takes ledger rows and
+// returns a shape. No disk, no clock beyond what it is handed, no I/O.
+
+import type { DeliveryState, LedgerRow } from './file-ledger.ts';
+
+/** Why nothing is moving, when nothing is moving. */
+export type BlockedClass = 'too-large' | 'quota' | 'unreachable' | 'refused';
+
+export type SeedPhase =
+  /** Walking the tree; the denominator is not final yet. */
+  | 'scanning'
+  /** Moving files, with work outstanding. */
+  | 'seeding'
+  /** A wall we are waiting out — a rate limit, a quota, an unreachable peer. */
+  | 'paused'
+  /** Outstanding work that no amount of waiting will move on its own. */
+  | 'blocked'
+  /** Nothing outstanding. */
+  | 'converged';
+
+export interface SeedProgress {
+  phase: SeedPhase;
+  /** Rows in scope — THE DENOMINATOR the old counters never had. */
+  tracked: number;
+  /** Rows in a terminal-good state. */
+  delivered: number;
+  /** `tracked - delivered - blocked`, floored at 0. */
+  remaining: number;
+  /** Bytes still to move, as far as the ledger knows. Best-effort. */
+  bytesRemaining: number;
+  /** Outstanding rows no retry will clear on its own, by class. */
+  blocked: { class: BlockedClass; count: number }[];
+  /** Which ceiling ended the last pass, when one did. */
+  passCapped?: 'requests' | 'files' | 'bytes';
+  /** null until a real throughput sample exists — NEVER a guess. */
+  etaMs: number | null;
+  /** When this seed was first observed to have outstanding work. */
+  startedAt: number | null;
+}
+
+/**
+ * States that mean "this file is where it needs to be".
+ *
+ * `on-hub` counts. A stricter bar (`durable`, `everywhere`) would be more
+ * truthful about replication but would make the denominator un-completable for
+ * a project whose hub has not finished mirroring — a progress bar that never
+ * reaches the end is worse than one that reaches it slightly early, and the
+ * mirroring state has its own surface.
+ */
+const DELIVERED: ReadonlySet<DeliveryState> = new Set<DeliveryState>([
+  'on-hub',
+  'durable',
+  'at-peer',
+  'ui-healed',
+  'everywhere',
+]);
+
+/** States that will not move again without something changing. */
+const BLOCKED: ReadonlySet<DeliveryState> = new Set<DeliveryState>([
+  'refused',
+  'referenced-but-unoffered',
+]);
+
+export interface SeedProgressInput {
+  rows: Record<string, LedgerRow>;
+  now: number;
+  /** The lane is holding until this instant, if it is. */
+  pausedUntil?: number | null;
+  /** Why it is holding — carried through to the phase and the wording. */
+  pauseCause?: 'hub-asked' | 'unreachable' | 'quota' | null;
+  /** Set when the last pass stopped on a ceiling rather than on the work. */
+  passCapped?: 'requests' | 'files' | 'bytes';
+  /** True while the first scan of this boot has not finished. */
+  scanning?: boolean;
+  /** Previous result, for `startedAt` continuity and the throughput sample. */
+  previous?: SeedProgress | null;
+  /** Bytes delivered since `previous` was computed, if the caller knows. */
+  deliveredSince?: { bytes: number; ms: number } | null;
+}
+
+/**
+ * Fold the ledger into one progress shape.
+ *
+ * Total and pure. Every field is derivable from the rows plus what the caller
+ * observed; nothing is inferred from a wall clock this function reads itself.
+ */
+export function computeSeedProgress(input: SeedProgressInput): SeedProgress {
+  const { rows, now } = input;
+  let tracked = 0;
+  let delivered = 0;
+  let bytesRemaining = 0;
+  const blockedCounts = new Map<BlockedClass, number>();
+
+  for (const row of Object.values(rows)) {
+    tracked += 1;
+    const state = row.state;
+    if (state && DELIVERED.has(state)) {
+      delivered += 1;
+      continue;
+    }
+    if (state && BLOCKED.has(state)) {
+      const cls = classifyBlocked(row);
+      blockedCounts.set(cls, (blockedCounts.get(cls) ?? 0) + 1);
+      continue;
+    }
+    // Outstanding. `size` is the stat cache, so it is what we know rather than
+    // what is true — a row we have never stat'd contributes nothing, which is
+    // why `bytesRemaining` is documented as best-effort rather than exact.
+    if (Number.isFinite(row.size)) bytesRemaining += row.size as number;
+  }
+
+  const blocked = [...blockedCounts.entries()]
+    .map(([cls, count]) => ({ class: cls, count }))
+    .sort((a, b) => b.count - a.count);
+  const blockedTotal = blocked.reduce((n, b) => n + b.count, 0);
+  const remaining = Math.max(0, tracked - delivered - blockedTotal);
+
+  const paused =
+    typeof input.pausedUntil === 'number' && Number.isFinite(input.pausedUntil)
+      ? input.pausedUntil > now
+      : false;
+
+  const phase: SeedPhase = input.scanning
+    ? 'scanning'
+    : paused
+      ? 'paused'
+      : remaining > 0
+        ? 'seeding'
+        : blockedTotal > 0
+          ? 'blocked'
+          : 'converged';
+
+  return {
+    phase,
+    tracked,
+    delivered,
+    remaining,
+    bytesRemaining,
+    blocked,
+    ...(input.passCapped ? { passCapped: input.passCapped } : {}),
+    etaMs: estimateEta(bytesRemaining, input.deliveredSince ?? null),
+    startedAt: resolveStartedAt(input, remaining, now),
+  };
+}
+
+/**
+ * An ETA, or `null`.
+ *
+ * NULL UNTIL THERE IS A REAL SAMPLE, and that restraint is the point. During
+ * the 2026-09-03 investigation a two-second throughput sample read as "4 MB/s,
+ * about ten minutes left" and was reported to a person as such; the sustained
+ * rate was ~270 kB/s of retry traffic and the true answer was "never". A
+ * fabricated ETA does not merely mislead, it stops people looking.
+ *
+ * So: no sample, no number. And a sample of zero delivered bytes is not a
+ * slow rate, it is no information at all.
+ */
+function estimateEta(
+  bytesRemaining: number,
+  sample: { bytes: number; ms: number } | null
+): number | null {
+  if (!sample || sample.bytes <= 0 || sample.ms <= 0) return null;
+  const bytesPerMs = sample.bytes / sample.ms;
+  if (!Number.isFinite(bytesPerMs) || bytesPerMs <= 0) return null;
+  const ms = bytesRemaining / bytesPerMs;
+  if (!Number.isFinite(ms)) return null;
+  // A week is not an estimate, it is a way of saying we do not know.
+  return ms > 7 * 24 * 3_600_000 ? null : Math.round(ms);
+}
+
+/** Keep the original start across ticks; clear it once there is nothing left. */
+function resolveStartedAt(input: SeedProgressInput, remaining: number, now: number): number | null {
+  if (remaining <= 0) return null;
+  const prev = input.previous?.startedAt;
+  return typeof prev === 'number' && Number.isFinite(prev) ? prev : now;
+}
+
+/**
+ * Which wall this row is behind.
+ *
+ * FROM THE ROW'S OWN `blockedClass`, which the writer set at the moment it
+ * refused. The first version matched on `row.reason` and claimed in this very
+ * comment that the matching was "never on hub-supplied text" — which was wrong
+ * by one hop: `reason` can be a `failureReason()` string embedding a bounded
+ * snippet of a hub error body, so a hostile hub answering with a body
+ * containing "too big" could steer how its own refusals were labelled. Only
+ * cosmetic, and only in the panel, but a classifier a peer can influence is not
+ * a classifier.
+ *
+ * The string fallback stays for rows written before the field existed — bounded
+ * to our own sentences, and it degrades to `refused`, which is the honest
+ * answer when we do not know.
+ */
+function classifyBlocked(row: LedgerRow): BlockedClass {
+  if (row.blockedClass) return row.blockedClass;
+  const reason = (row.reason ?? '').toLowerCase();
+  if (reason.startsWith('too big')) return 'too-large';
+  if (reason.startsWith("this project's upload allowance")) return 'quota';
+  if (reason.startsWith('could not reach')) return 'unreachable';
+  return 'refused';
+}