@1agh/maude 0.60.7 → 1.0.3

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

@@ -0,0 +1,200 @@
+// The journal read client — Sync v2 Increment 2 (DDR-226 §5).
+//
+// One place that knows how to ask a hub "what changed since <seq>", and one
+// place that knows how to ask "do you even have a journal". Increment 2 uses
+// both for the cell child's heal path; Increment 3's pull engine uses the same
+// two functions rather than growing its own.
+//
+// EVERYTHING HERE IS UNTRUSTED INPUT. The hub is semi-trusted by design
+// (DDR-054): it may read and write synced state, and everything it says about
+// that state is a hint. So this module's job is not to fetch — it is to REFUSE.
+// A row whose shape is wrong is dropped; a `reanchor` is honoured rather than
+// argued with; a page that cannot be parsed is `null`, which every caller reads
+// as "ask again later", never as "nothing changed".
+//
+// FAIL CLOSED ON THE CURSOR. `{ reanchor: true }` is not an error and not an
+// empty page — it is the hub saying "your cursor is not in this log". Reading
+// it as "no changes" is exactly the shape that lets a stale peer believe it is
+// current, which is the failure DDR-214's ordering amendment exists to prevent.
+
+/** How long to wait for a journal page. Same figure as the manifest fetch. */
+const JOURNAL_TIMEOUT_MS = 6000;
+
+/**
+ * The hub's own published page ceiling, restated here.
+ *
+ * A receiver that trusts the sender to respect the sender's cap has no cap.
+ */
+const MAX_JOURNAL_PAGE = 2000;
+
+/** An epoch is a UUID-ish token; anything longer is not one. */
+const MAX_EPOCH_LEN = 128;
+
+/** How long to wait for `/health`. A capability probe must never hang a boot. */
+const HEALTH_TIMEOUT_MS = 4000;
+
+/** The shape a peer may act on. Anything else is dropped at parse time. */
+export interface JournalEntry {
+  seq: number;
+  path: string;
+  sha256: string | null;
+  size: number | null;
+  /** DISPLAY ONLY. Never an overwrite authority anywhere (F4). */
+  mtimeMs: number | null;
+  /** The hub's claimed class — a reporting hint; receivers re-classify. */
+  class: string;
+  deleted: boolean;
+}
+
+export interface JournalPage {
+  epoch: string | null;
+  head: number;
+  entries: JournalEntry[];
+  truncated: boolean;
+  /** The cursor is not in this log — re-anchor against a full compaction. */
+  reanchor: boolean;
+  reason?: string;
+  /** The hub sent more than its own published ceiling; the rest was dropped. */
+  overflowed?: true;
+}
+
+/** A designRoot-relative path shape a peer will turn into a real file. */
+const ENTRY_PATH_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,255}$/;
+
+function parseEntry(raw: unknown): JournalEntry | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const e = raw as Record<string, unknown>;
+  const seq = e.seq;
+  const p = e.path;
+  if (typeof seq !== 'number' || !Number.isInteger(seq) || seq <= 0) return null;
+  if (typeof p !== 'string' || !ENTRY_PATH_RE.test(p) || p.split('/').includes('..')) return null;
+  const sha = typeof e.sha256 === 'string' && /^[0-9a-f]{64}$/.test(e.sha256) ? e.sha256 : null;
+  return {
+    seq,
+    path: p,
+    sha256: sha,
+    size: typeof e.size === 'number' && Number.isFinite(e.size) ? e.size : null,
+    mtimeMs: typeof e.mtimeMs === 'number' && Number.isFinite(e.mtimeMs) ? e.mtimeMs : null,
+    class: typeof e.class === 'string' ? e.class.slice(0, 32) : '',
+    deleted: e.deleted === true,
+  };
+}
+
+/**
+ * Fetch one journal page.
+ *
+ * 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".
+ */
+export async function fetchJournal(opts: {
+  hubUrl: string;
+  token: string;
+  since?: number;
+  /** Send the epoch a cursor belongs to so a mismatch fails closed hub-side. */
+  epoch?: string | null;
+  fetchImpl?: typeof fetch;
+}): Promise<JournalPage | null> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const base = opts.hubUrl.replace(/\/+$/, '');
+  const params = new URLSearchParams();
+  params.set('since', String(Math.max(0, Math.trunc(opts.since ?? 0))));
+  if (opts.epoch) params.set('epoch', opts.epoch);
+  try {
+    const res = await fetchImpl(`${base}/api/journal?${params}`, {
+      headers: { authorization: `Bearer ${opts.token}` },
+      signal: AbortSignal.timeout(JOURNAL_TIMEOUT_MS),
+    });
+    if (!res.ok) 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
+    // fractional or negative head, or an unbounded epoch string, gets
+    // persisted into the ledger verbatim otherwise.
+    const rawHead = body?.head;
+    const head =
+      typeof rawHead === 'number' && Number.isInteger(rawHead) && rawHead >= 0 ? rawHead : 0;
+    const epoch =
+      typeof body?.epoch === 'string' && body.epoch.length > 0 && body.epoch.length <= MAX_EPOCH_LEN
+        ? body.epoch
+        : null;
+    if (body?.reanchor === true) {
+      return {
+        epoch,
+        head,
+        entries: [],
+        truncated: false,
+        reanchor: true,
+        ...(typeof body.reason === 'string' ? { reason: body.reason.slice(0, 120) } : {}),
+      };
+    }
+    // CAP THE PAGE at the hub's own published ceiling. An honest hub never
+    // exceeds it; a hostile one ignores its own cap, and every entry past this
+    // point becomes a ledger row on disk, a key in `_sync.json`, and a member
+    // of the union every future pass re-walks. One response should not be able
+    // to grow this machine's state without bound.
+    const rawEntries = Array.isArray(body?.entries) ? body.entries : [];
+    const overflowed = rawEntries.length > MAX_JOURNAL_PAGE;
+    const entries: JournalEntry[] = [];
+    for (const raw of rawEntries.slice(0, MAX_JOURNAL_PAGE)) {
+      const parsed = parseEntry(raw);
+      if (parsed !== null) entries.push(parsed);
+    }
+    return {
+      epoch,
+      head,
+      entries,
+      // An over-long page is treated as truncated, which is already the signal
+      // meaning "there is more; come back" — so the pass converges instead of
+      // silently believing it saw everything.
+      truncated: body?.truncated === true || overflowed,
+      reanchor: false,
+      ...(overflowed ? { overflowed: true } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What protocol features a hub advertises — the compat matrix's gate
+ * (DDR-226 §10, BINDING).
+ *
+ * Returns null when `/health` is unreachable or unparseable. A caller must
+ * treat BOTH null and a set without `ledger` as "this hub has no journal":
+ * attach no control channel, relax no polling, keep every legacy lane. The
+ * distinction between "an old hub that omits the field" and "a new hub with no
+ * checkout" matters for diagnostics, not for behaviour.
+ */
+export async function hubCapabilities(opts: {
+  hubUrl: string;
+  fetchImpl?: typeof fetch;
+  /**
+   * Cancel the probe when the caller goes away.
+   *
+   * A boot-time probe that outlives its runtime is a timer holding a dying
+   * process open and a promise resolving into torn-down state. The caller
+   * aborts this in `stop()`; without it the 4 s timeout alone decides.
+   */
+  signal?: AbortSignal;
+}): Promise<string[] | null> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const base = opts.hubUrl.replace(/\/+$/, '');
+  try {
+    const timeout = AbortSignal.timeout(HEALTH_TIMEOUT_MS);
+    const res = await fetchImpl(`${base}/health`, {
+      signal: opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout,
+    });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { capabilities?: unknown };
+    if (!Array.isArray(body?.capabilities)) return null;
+    return body.capabilities.filter((c): c is string => typeof c === 'string').slice(0, 32);
+  } catch {
+    return null;
+  }
+}
+
+/** Does this hub carry the journal file plane? */
+export function hasLedger(capabilities: string[] | null): boolean {
+  return Array.isArray(capabilities) && capabilities.includes('ledger');
+}

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

@@ -48,7 +48,9 @@ import {
   stampBodyEdit,
   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 { hashBytes } from './echo-guard.ts';
 import type { SyncJournal } from './journal.ts';
 import { ORIGINS } from './origins.ts';
@@ -73,6 +75,23 @@ export interface MigrateSeedOptions {
   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>;
+  /**
+   * Does the HUB hold state for this slug, per its last document listing?
+   *
+   * `docIsEmpty` asks the local replica, and an empty replica has two
+   * completely different meanings: "the hub has never seen this canvas" (adopt
+   * — the local file is the only copy) and "the hub's state has not landed in
+   * this replica YET" (do nothing — it is on its way). Adopting in the second
+   * case is the DDR-102 F1 concurrent cold-seed collision: both peers
+   * clear-and-rebuild their own replica from a file with the same bytes, and
+   * because the two runs carry different client ids the CRDT merge
+   * CONCATENATES them — the canvas ends up with its body twice on every peer.
+   *
+   * The listing is the only enumeration a peer has, so it is also the only way
+   * to tell the two cases apart before writing. Absent ⇒ treated as "the hub
+   * does not have it", which is the pre-existing behaviour.
+   */
+  hubHasState?: (slug: string) => boolean;
   /** DDR-102 — divergence notification, same contract as the agent's. */
   onConflict?: (info: {
     slug: string;
@@ -90,9 +109,19 @@ export type MigrateSeedResult =
   | 'empty'
   /** DDR-102 — doc held state but no body; local body seeded up in-place. */
   | 'body-seed-up'
+  /** DDR-102 F1 — the hub body was our local body repeated N≥2 times (a
+   *  concurrent cold-seed collision); local was re-applied so the codec's diff
+   *  deletes the duplicate. Before Increment 0 this decision had NO case in
+   *  this module's switch and fell through to `hub-wins`, keeping (and
+   *  materializing) the doubled body. */
+  | 'recover-seed-dup'
   /** DDR-102 — divergence resolved newest-wins. */
   | 'conflict-local-wins'
-  | 'conflict-hub-wins';
+  | 'conflict-hub-wins'
+  /** 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. */
+  | 'defer-hub-state';
 
 /** True when the shared doc holds no synced content for any of the five types. */
 export function docIsEmpty(doc: Y.Doc): boolean {
@@ -122,6 +151,26 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
   // 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)) {
+    // AN EMPTY REPLICA IS NOT AN EMPTY HUB. See `hubHasState` — on a cell the
+    // hub's workspace agent writes every document onto the checkout, so the
+    // studio child scans up a file whose document the hub already owns. Seeding
+    // from it doubles the body on every peer.
+    if (opts.hubHasState?.(slug)) {
+      // SNAPSHOT BEFORE STANDING ASIDE. Deferring means the local body never
+      // enters the doc — so when the hub's state does arrive, the projection
+      // writes it over this file with no `pre-sync-local` copy behind it and no
+      // conflict recorded, because both live in the non-empty branch this
+      // return skips. The adopt path it replaced could not lose the local body:
+      // it was inside the merge. One snapshot buys back the recoverability.
+      if (localHtml && opts.snapshot) {
+        try {
+          await opts.snapshot(localHtml, 'pre-sync-local');
+        } catch {
+          /* best-effort — history is a safety net, never a gate on syncing */
+        }
+      }
+      return 'defer-hub-state';
+    }
     const hasLocal =
       !!localHtml || !!localComments || !!localAnnotations || !!localMeta || !!localCss;
     if (!hasLocal) return 'empty';
@@ -175,8 +224,6 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
     docBodyEditAtMs: bodyEditAtFromDoc(doc),
   });
 
-  let result: MigrateSeedResult = 'hub-wins';
-
   /** Rebuild body (+ visually-coupled css) from local, in ONE MIGRATION
    *  transaction — one source per type, never a two-history merge.
    *  Annotations are deliberately NOT here any more: they resolve per-lane
@@ -194,69 +241,29 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
     });
   };
 
-  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;
-    }
-  }
+  // ONE application body, shared with agent.ts reconcile (DDR-226 Increment 0).
+  // `takeHub` is a genuine no-op here: under shared-doc the doc KEEPS its state
+  // and `projection.reconcile()` materializes it to disk (recording the journal
+  // checkpoint on its own write). Everything else — the dual snapshot, the
+  // 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);
 
   // ---- annotations: PER-LANE newest-wins (the 2026-08-14 eraser fix; the
   // same table as agent.ts reconcile). Under sharedDoc the collab room's
@@ -273,7 +280,7 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
       isEmpty: isEmptyAnnotationsSvg,
       localMtimeMs: localMtimeMs(paths.annotations),
       docEditAtMs: annotationsEditAtFromDoc(doc),
-      bodyWinner: result === 'body-seed-up' || result === 'conflict-local-wins' ? 'local' : 'hub',
+      bodyWinner: applied.bodyWinner,
     });
     if (annDecision.winner === 'local' && localAnnotations !== null) {
       console.warn(`[sync/${slug}] shared-doc cold-start annotations: ${annDecision.reason}`);
@@ -312,6 +319,31 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
 
 /* ---------------------------------------------------------------- helpers */
 
+/**
+ * Map the shared applier's verdict onto this module's public result string.
+ * Total over `ColdStartAction`, so a new row in the table surfaces here as a
+ * type error instead of silently reading as `hub-wins` (the exact shape of the
+ * `recover-seed-dup` bug this refactor fixed).
+ */
+function resultFor(action: ColdStartAction, bodyWinner: 'local' | 'hub'): MigrateSeedResult {
+  switch (action) {
+    case 'noop':
+    case 'materialize-hub':
+    case 'fast-forward-hub':
+      return 'hub-wins';
+    case 'seed-local-up':
+      return 'body-seed-up';
+    case 'recover-seed-dup':
+      return 'recover-seed-dup';
+    case 'conflict':
+      return bodyWinner === 'local' ? 'conflict-local-wins' : 'conflict-hub-wins';
+    default: {
+      const never: never = action;
+      throw new Error(`migrate-seed: unhandled cold-start action ${String(never)}`);
+    }
+  }
+}
+
 function snapshotLocal(opts: MigrateSeedOptions): void {
   if (!opts.historyDir) return;
   try {

package/apps/studio/sync/poke.ts

@@ -0,0 +1,50 @@
+// The poke frame's vocabulary, receiver side — Sync v2 Increment 2
+// (DDR-226 §4).
+//
+// A DELIBERATE TWIN of `apps/hub/src/files-ctl.mjs`'s `parsePoke`, for the same
+// reason `file-membership.ts` has a `.mjs` mirror: the hub image installs from
+// its own frozen lockfile and cannot import out of `apps/studio`, so the two
+// ends of a wire format live in two files. DDR-198's rule applies — a twin is
+// allowed only with a drift test that imports BOTH and asserts they agree. That
+// test is `apps/studio/test/sync-poke-parity.test.ts`; if you change the shape
+// here, change it there, and the test is what makes forgetting a red build.
+//
+// WHY THE FRAME IS THIS SMALL. Everything on this channel arrives from the hub,
+// which is untrusted to peers (DDR-054). A frame that carried a path would be a
+// path the hub chose; a frame that carried a hash would be a hash the hub chose.
+// So it carries neither. `head` is a HINT that something moved — the receiver
+// then asks through an authenticated, scope-filtered route and believes the
+// answer, not the doorbell.
+
+/** Max frame size. A doorbell has no reason to be long. */
+const MAX_POKE_BYTES = 512;
+
+export interface Poke {
+  /** The hub's journal head at emit time. A hint, never an authority. */
+  head: number;
+}
+
+/**
+ * Parse a control frame. Returns null for anything that is not exactly
+ * `{ t: 'files', head: <non-negative integer> }`.
+ *
+ * Extra properties are DROPPED rather than refused: a future hub adding a field
+ * must not silence the channel for an older peer (the additive-field rule the
+ * documents listing already follows). What is never accepted is a missing or
+ * malformed `head`, because that is the one value the receiver acts on.
+ */
+export function parsePoke(payload: unknown): Poke | null {
+  if (typeof payload !== 'string' || payload.length > MAX_POKE_BYTES) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  const frame = parsed as { t?: unknown; head?: unknown };
+  if (frame.t !== 'files') return null;
+  const head = frame.head;
+  if (typeof head !== 'number' || !Number.isInteger(head) || head < 0) return null;
+  return { head };
+}

package/apps/studio/sync/projection.ts

@@ -39,6 +39,7 @@ import {
   htmlFromDoc,
   mergeSharedMetaIntoLocal,
   metaFromDoc,
+  movedToFromDoc,
   stampAnnotationsEdit,
   stampBodyEdit,
 } from './codec.ts';
@@ -259,6 +260,13 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
 
   async function flush(): Promise<void> {
     if (!dirty || stopped) return;
+    // A RETIRED document is write-inert — its canvas moved to a new path in a
+    // new document, and materialising this one is how a moved canvas
+    // resurrected itself at its old path (see codec stampMovedTo).
+    if (movedToFromDoc(doc) !== null) {
+      dirty = false;
+      return;
+    }
     dirty = false;
     if (flushTimer) {
       clearTimeout(flushTimer);
@@ -301,6 +309,9 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
 
   function applyFromFs(evt: { path: string; bytes: Uint8Array; hash: string }): boolean {
     if (stopped) return false;
+    // Write-inert both ways — a local edit to a stale pre-move file must not
+    // revive the retired document (see codec stampMovedTo).
+    if (movedToFromDoc(doc) !== null) return false;
     // Echo of our own doc→file write — drop.
     if (opts.echoGuard?.consume(evt.path, evt.hash)) return false;
     // Circuit breaker — a file that won't parse can't spin the loop.
@@ -370,6 +381,8 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
 
   function reconcile(): void {
     if (stopped) return;
+    // A retired doc materialises NOTHING (see codec stampMovedTo).
+    if (movedToFromDoc(doc) !== null) return;
     // Materialize the converged doc to disk (html/css/meta). The *IfChanged
     // writers already guard against clobbering non-empty local with empty doc
     // values, so this is safe to run at cold start before the authoritative

package/apps/studio/sync/pull-budget.ts

@@ -0,0 +1,86 @@
+// F6 — the aggregate byte budget on every downward lane (Sync v2 Increment 0,
+// DDR-226 §9; the gap named in the Plane-B flip gate).
+//
+// Every pull lane already caps ONE file (`MAX_PULL_BYTES`) and the COUNT of
+// files per pass (`MAX_PULLS_PER_PASS` / `MAX_FILES_PER_PASS`). Nothing capped
+// the product. 200 files × 512 MB is 100 GB, and the hub decides both factors:
+// a hostile or merely broken hub could fill a person's disk one "legitimate"
+// pass at a time, and every individual transfer would pass every check.
+//
+// So the lanes share ONE budget object per pass. It is deliberately tiny and
+// leaf (no imports): a counter, a ceiling, and a single loud line when it is
+// reached — the "loud-cap convention" every other truncation in this codebase
+// follows, because a silent stop reads as "sync is broken" with no cause.
+//
+// The per-pass ceiling is not a quota: the remainder is simply the next pass's
+// work, exactly like the count caps. The CUMULATIVE per-hub accumulation quota
+// (a real quota, which refuses rather than defers) is Increment 4's job.
+
+/**
+ * How many bytes one downward pass may land, across all files in that pass.
+ *
+ * 2 GiB is far above any real project's per-poll delta (a converged project
+ * transfers zero) and far below "fills the disk while you are at lunch". A
+ * fresh link of a large project takes several passes — which is already how
+ * the count caps behave.
+ */
+export const MAX_PULL_BYTES_PER_PASS = 2 * 1024 * 1024 * 1024;
+
+export interface PullBudget {
+  /**
+   * Charge `bytes` against the budget.
+   *
+   * Returns false when this transfer would exceed the ceiling — the caller
+   * must NOT land it and should stop the pass (`exhausted()` is then true).
+   * A charge that fits is committed, so `take` is not a pure predicate.
+   */
+  take: (bytes: number) => boolean;
+  /** True once a `take` has been refused. */
+  exhausted: () => boolean;
+  /** Bytes committed so far this pass. */
+  spent: () => number;
+  /** Bytes still available. */
+  remaining: () => number;
+}
+
+export interface PullBudgetOptions {
+  /** Ceiling for this pass. Defaults to `MAX_PULL_BYTES_PER_PASS`. */
+  maxBytes?: number;
+  /** Log-line prefix — `sync/assets`, `sync/files`, … so the refusal names
+   *  which lane hit the wall. */
+  label: string;
+  log?: Pick<Console, 'warn'>;
+}
+
+/**
+ * One budget per pass. Never throws; refusing is a boolean, and the caller
+ * reports it the way it reports every other cap.
+ */
+export function createPullBudget(opts: PullBudgetOptions): PullBudget {
+  const max = opts.maxBytes ?? MAX_PULL_BYTES_PER_PASS;
+  const log = opts.log ?? console;
+  let spent = 0;
+  let hitTheWall = false;
+
+  return {
+    take(bytes: number): boolean {
+      // A negative/NaN size is a hub-supplied number: treat it as zero-cost
+      // rather than as a credit (it can never REFUND budget).
+      const cost = Number.isFinite(bytes) && bytes > 0 ? bytes : 0;
+      if (spent + cost > max) {
+        if (!hitTheWall) {
+          hitTheWall = true;
+          log.warn(
+            `[${opts.label}] pass byte budget reached — ${spent} B landed, refusing a further ${cost} B (ceiling ${max} B, DDR-226 F6). The rest is the next pass's work.`
+          );
+        }
+        return false;
+      }
+      spent += cost;
+      return true;
+    },
+    exhausted: () => hitTheWall,
+    spent: () => spent,
+    remaining: () => Math.max(0, max - spent),
+  };
+}