@1agh/maude 0.60.6 → 1.0.2

package/apps/studio/test/sync-hub-listing.test.ts

@@ -0,0 +1,46 @@
+// The hub's listing, and the one question the seed asks of it.
+//
+// THE FINDING (attacker seat, 2026-08-19, HIGH). The listing was indexed by
+// `slugFromDocName`, which strips `ws/<workspace>/<branch>/`, while
+// `diffRemoteDocs` — fed the SAME listing twelve lines later — compares full
+// document names. So a `hero` on `main` answered for another peer's `hero` on
+// `feat/x`: that peer's cold-start seed returned `defer-hub-state` forever,
+// logging that the hub's state was on its way, and the canvas never synced in
+// either direction. Peer tokens are commonly `scope: '*'`, so one listing spans
+// every namespace on the hub — no hostile hub required, one teammate reusing a
+// canvas name on another branch is the whole exploit.
+
+import { describe, expect, test } from 'bun:test';
+
+import { hubHolds, indexHubDocs } from '../sync/hub-listing.ts';
+
+describe('the hub listing index', () => {
+  test('a same-slug document in ANOTHER namespace does not answer for mine', () => {
+    const index = indexHubDocs([{ name: 'ws/acme/main/ui-hero', bytes: 2931 }]);
+    expect(hubHolds(index, 'ws/acme/feat-x/ui-hero')).toBe(false);
+    expect(hubHolds(index, 'ws/acme/main/ui-hero')).toBe(true);
+  });
+
+  test('a legacy flat name is its own key, not a match for a namespaced one', () => {
+    const index = indexHubDocs([{ name: 'ui-hero', bytes: 10 }]);
+    expect(hubHolds(index, 'ws/acme/main/ui-hero')).toBe(false);
+    expect(hubHolds(index, 'ui-hero')).toBe(true);
+  });
+
+  test('a row that exists but carries nothing is not state', () => {
+    // Deferring to an empty document would leave a canvas that never syncs in
+    // either direction — the document exists, and holds none of the work.
+    const index = indexHubDocs([{ name: 'ui-hero', bytes: 0 }, { name: 'ui-other' }]);
+    expect(hubHolds(index, 'ui-hero')).toBe(false);
+    expect(hubHolds(index, 'ui-other')).toBe(false);
+  });
+
+  test('an unnamed row is dropped rather than coerced into a blank key', () => {
+    const index = indexHubDocs([
+      { name: '', bytes: 5 },
+      { name: undefined as unknown as string, bytes: 5 },
+    ]);
+    expect(index.size).toBe(0);
+    expect(hubHolds(index, '')).toBe(false);
+  });
+});

package/apps/studio/test/sync-meta-codec.test.ts

@@ -16,6 +16,8 @@ import {
   META_LOCAL_KEYS,
   mergeSharedMetaIntoLocal,
   metaFromDoc,
+  normalizeSharedMeta,
+  repairSharedMeta,
 } from '../sync/codec.ts';
 
 describe('Gap 2 — meta codec: shared layout syncs, per-user keys stay local', () => {
@@ -121,3 +123,77 @@ describe('Gap 3 — css codec (opaque wholesale text)', () => {
     expect(applyCssToDoc(doc, '.x{ color: blue }')).toBe(true);
   });
 });
+
+describe('a duplicated meta lane — the shape two peers publishing at once leaves', () => {
+  // Meta is a WHOLE VALUE in a Y.Text, written delete-all + insert-all. Two
+  // peers inserting the same string into an empty lane produce two inserts Yjs
+  // has no reason to merge, and the result — `{"a":1}{"a":1}` — is not empty
+  // and not parseable. Every consumer ran it through JSON.parse and bailed, so
+  // a canvas silently lost its title, kind and design-system binding on every
+  // machine that synced the project afterwards.
+  //
+  // Observed live on nine canvases at once, all created on the same laptop.
+
+  const ONE = '{"kind":"web","title":"Home"}';
+
+  function docWith(text: string): Y.Doc {
+    const d = new Y.Doc();
+    d.getText('meta').insert(0, text);
+    return d;
+  }
+
+  test('normalizeSharedMeta collapses identical copies to one', () => {
+    expect(normalizeSharedMeta(ONE + ONE)).toBe(ONE);
+    expect(normalizeSharedMeta(ONE + ONE + ONE)).toBe(ONE);
+  });
+
+  test('a single value passes through untouched', () => {
+    expect(normalizeSharedMeta(ONE)).toBe(ONE);
+  });
+
+  test('empty stays null — that is a real answer, not a broken one', () => {
+    expect(normalizeSharedMeta('')).toBeNull();
+    expect(normalizeSharedMeta(null)).toBeNull();
+  });
+
+  test('it repairs only what it can PROVE — differing copies stay null', () => {
+    // Two DIFFERENT values concatenated is not a duplication; it is a
+    // disagreement, and picking one would be inventing a winner. Null routes it
+    // to "the doc has no usable opinion", where local meta seeds instead.
+    expect(normalizeSharedMeta('{"title":"A"}{"title":"B"}')).toBeNull();
+    expect(normalizeSharedMeta('not json at all')).toBeNull();
+    expect(normalizeSharedMeta('[1,2]')).toBeNull();
+  });
+
+  test('a value CONTAINING "}{" is not mistaken for a seam', () => {
+    // Each segment must itself parse as a complete object, so a brace pair
+    // inside a string cannot manufacture a false split.
+    const tricky = JSON.stringify({ title: 'a}{b' });
+    expect(normalizeSharedMeta(tricky)).toBe(tricky);
+  });
+
+  test('metaFromDoc hands consumers the single value', () => {
+    expect(metaFromDoc(docWith(ONE + ONE))).toBe(ONE);
+  });
+
+  test('repairSharedMeta collapses the lane in place', () => {
+    const d = docWith(ONE + ONE);
+    expect(repairSharedMeta(d)).toBe(true);
+    expect(d.getText('meta').toString()).toBe(ONE);
+    // Idempotent — a repaired lane is not repaired again, so this cannot churn.
+    expect(repairSharedMeta(d)).toBe(false);
+  });
+
+  test('repair leaves an unrepairable lane exactly as it found it', () => {
+    const d = docWith('{"title":"A"}{"title":"B"}');
+    expect(repairSharedMeta(d)).toBe(false);
+    expect(d.getText('meta').toString()).toBe('{"title":"A"}{"title":"B"}');
+  });
+
+  test('applying the same meta over a duplicated lane is a no-op, not a rewrite', () => {
+    // Comparing against the literal text would see a difference every pass and
+    // rewrite forever.
+    const d = docWith(ONE + ONE);
+    expect(applyMetaToDoc(d, ONE)).toBe(false);
+  });
+});

package/apps/studio/test/sync-move-retirement.test.ts

@@ -0,0 +1,231 @@
+// The MOVE protocol — a moved canvas retires its old document (stampMovedTo).
+//
+// Before this existed, moving a canvas minted a new slug + new document and
+// the OLD document simply lived on: the hub kept materialising it at the old
+// path, every peer's cold start saw "doc has a body, disk has no file" and
+// resurrected it, and the canvas came back as a duplicate on every machine.
+// Observed live: `shoj` moved into a folder left BOTH paths on both machines
+// and two documents on the hub.
+//
+// What is pinned here:
+//   1. the stamp round-trips and is idempotent;
+//   2. a retired doc is WRITE-INERT in every direction, for both disk
+//      handlers (agent and projection) — no doc→file materialise, no
+//      file→doc revival;
+//   3. retirement is an explicit statement, never inferred from emptiness —
+//      an un-stamped doc behaves exactly as before.
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as Y from 'yjs';
+
+import { createCanvasSyncAgent } from '../sync/agent.ts';
+import { applyHtmlToDoc, htmlFromDoc, movedToFromDoc, stampMovedTo } from '../sync/codec.ts';
+import { createEchoGuard, hashBytes } from '../sync/echo-guard.ts';
+import { createDocProjection } from '../sync/projection.ts';
+
+function tempDir(): string {
+  return mkdtempSync(join(tmpdir(), 'sync-retire-'));
+}
+
+describe('the stamp', () => {
+  test('round-trips, with where the canvas went', () => {
+    const doc = new Y.Doc();
+    expect(movedToFromDoc(doc)).toBe(null);
+    expect(stampMovedTo(doc, 'ui/folder/screen.tsx')).toBe(true);
+    expect(movedToFromDoc(doc)).toBe('ui/folder/screen.tsx');
+  });
+
+  test('is idempotent — restamping the same target writes nothing', () => {
+    const doc = new Y.Doc();
+    stampMovedTo(doc, 'ui/a/b.tsx');
+    let updates = 0;
+    doc.on('update', () => updates++);
+    expect(stampMovedTo(doc, 'ui/a/b.tsx')).toBe(false);
+    expect(updates).toBe(0);
+  });
+
+  test('crosses the wire like any syncMeta', () => {
+    const a = new Y.Doc();
+    const b = new Y.Doc();
+    a.on('update', (u: Uint8Array) => Y.applyUpdate(b, u));
+    stampMovedTo(a, 'ui/x.tsx');
+    expect(movedToFromDoc(b)).toBe('ui/x.tsx');
+  });
+});
+
+describe('a retired doc is write-inert — the agent', () => {
+  test('doc→file: a peer update on a retired doc lands nothing on disk', async () => {
+    const dir = tempDir();
+    try {
+      const doc = new Y.Doc();
+      const paths = {
+        html: join(dir, 'screen.html'),
+        comments: join(dir, '_comments', 'screen.json'),
+        annotations: join(dir, 'screen.annotations.svg'),
+      };
+      const agent = createCanvasSyncAgent({
+        slug: 'screen',
+        doc,
+        paths,
+        echoGuard: createEchoGuard(),
+        flushMs: 0,
+      });
+      agent.start();
+
+      stampMovedTo(doc, 'ui/moved/screen.tsx');
+      applyHtmlToDoc(doc, '<main>ghost</main>');
+      await agent.flush();
+
+      // The resurrection: this file appearing is exactly the bug.
+      expect(existsSync(paths.html)).toBe(false);
+      agent.stop();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('file→doc: a local edit to a stale pre-move file does not revive the doc', () => {
+    const dir = tempDir();
+    try {
+      const doc = new Y.Doc();
+      const paths = {
+        html: join(dir, 'screen.html'),
+        comments: join(dir, '_comments', 'screen.json'),
+        annotations: join(dir, 'screen.annotations.svg'),
+      };
+      const agent = createCanvasSyncAgent({
+        slug: 'screen',
+        doc,
+        paths,
+        echoGuard: createEchoGuard(),
+        flushMs: 0,
+      });
+      agent.start();
+      stampMovedTo(doc, 'ui/moved/screen.tsx');
+
+      const bytes = new TextEncoder().encode('<main>stale local edit</main>');
+      const applied = agent.applyFromFs({
+        path: paths.html,
+        bytes,
+        hash: hashBytes('<main>stale local edit</main>'),
+      });
+
+      expect(applied).toBe(false);
+      expect(htmlFromDoc(doc)).toBe('');
+      agent.stop();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('reconcile materialises nothing from a retired doc', async () => {
+    const dir = tempDir();
+    try {
+      const doc = new Y.Doc();
+      applyHtmlToDoc(doc, '<main>content from before the move</main>');
+      stampMovedTo(doc, 'ui/moved/screen.tsx');
+      const paths = {
+        html: join(dir, 'screen.html'),
+        comments: join(dir, '_comments', 'screen.json'),
+        annotations: join(dir, 'screen.annotations.svg'),
+      };
+      const agent = createCanvasSyncAgent({
+        slug: 'screen',
+        doc,
+        paths,
+        echoGuard: createEchoGuard(),
+        flushMs: 0,
+      });
+      agent.start();
+      await agent.reconcile();
+
+      expect(existsSync(paths.html)).toBe(false);
+      agent.stop();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('and the CONTROL: without the stamp, the very same doc materialises', async () => {
+    // The guard must be the stamp, not some accident of the harness.
+    const dir = tempDir();
+    try {
+      const doc = new Y.Doc();
+      applyHtmlToDoc(doc, '<main>live</main>');
+      const paths = {
+        html: join(dir, 'screen.html'),
+        comments: join(dir, '_comments', 'screen.json'),
+        annotations: join(dir, 'screen.annotations.svg'),
+      };
+      const agent = createCanvasSyncAgent({
+        slug: 'screen',
+        doc,
+        paths,
+        echoGuard: createEchoGuard(),
+        flushMs: 0,
+      });
+      agent.start();
+      await agent.reconcile();
+
+      expect(readFileSync(paths.html, 'utf8')).toBe('<main>live</main>');
+      agent.stop();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('a retired doc is write-inert — the projection', () => {
+  test('doc→file reconcile + flush land nothing', async () => {
+    const dir = tempDir();
+    try {
+      const doc = new Y.Doc();
+      applyHtmlToDoc(doc, '<main>ghost</main>');
+      stampMovedTo(doc, 'ui/moved/screen.tsx');
+      const proj = createDocProjection({
+        slug: 'screen',
+        doc,
+        paths: { html: join(dir, 'screen.tsx') },
+        flushMs: 0,
+      });
+      proj.start();
+      proj.reconcile();
+      await proj.flush();
+
+      expect(existsSync(join(dir, 'screen.tsx'))).toBe(false);
+      proj.stop();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('file→doc refuses too', () => {
+    const dir = tempDir();
+    try {
+      const doc = new Y.Doc();
+      stampMovedTo(doc, 'ui/moved/screen.tsx');
+      const abs = join(dir, 'screen.tsx');
+      writeFileSync(abs, '<main>stale</main>');
+      const proj = createDocProjection({
+        slug: 'screen',
+        doc,
+        paths: { html: abs },
+        flushMs: 0,
+      });
+      proj.start();
+      const applied = proj.applyFromFs({
+        path: abs,
+        bytes: new TextEncoder().encode('<main>stale</main>'),
+        hash: hashBytes('<main>stale</main>'),
+      });
+      expect(applied).toBe(false);
+      expect(htmlFromDoc(doc)).toBe('');
+      proj.stop();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/apps/studio/test/sync-panel-surface.test.ts

@@ -131,3 +131,23 @@ describe('the Resync control', () => {
     expect(PANEL).toMatch(/cloud = null,/);
   });
 });
+
+describe('a held breaker is visible, because a log line is not a surface', () => {
+  // The finding: `deleteHeld` / `firstAnchorHeld` / `reanchorHeld` shipped
+  // with no consumer at all — declared, assigned, and read by nothing. So the
+  // breakers the release leans on had their entire output in a dev-server
+  // console, on a product whose premise (DDR-177) is that the user never opens
+  // a terminal. A hold that nobody can see is a stall, not a safety control.
+  test('the panel renders every hold the status carries', () => {
+    expect(PANEL).toContain('files.held');
+    expect(PANEL).toMatch(/data-testid=\{`sync-held-\$\{h\.kind\}`\}/);
+  });
+
+  test('it says nothing was removed — the reassurance IS the message', () => {
+    expect(PANEL).toContain('nothing was removed');
+  });
+
+  test('it names the files, so a person can judge whether it was deliberate', () => {
+    expect(PANEL).toMatch(/h\.paths/);
+  });
+});

package/apps/studio/test/sync-path-pull.test.ts

@@ -115,7 +115,7 @@ function makeCtx(canvasGroups?: DevServerConfig['canvasGroups']): Context {
  * from the listing.
  */
 function hubDocProviderFactory(
-  seed: Record<string, { body: string; path?: string; css?: string }>,
+  seed: Record<string, { body: string; path?: string; css?: string; movedTo?: string }>,
   docs?: Map<string, Y.Doc>
 ) {
   return (args: { documentName: string; document?: Y.Doc }): SyncProvider => {
@@ -126,6 +126,7 @@ function hubDocProviderFactory(
       doc.transact(() => {
         doc.getText('html').insert(0, entry.body);
         if (entry.path) doc.getMap('syncMeta').set('path', entry.path);
+        if (entry.movedTo) doc.getMap('syncMeta').set('movedTo', entry.movedTo);
         if (entry.css) doc.getText('css').insert(0, entry.css);
       }, 'hub');
     }
@@ -233,6 +234,71 @@ describe('a peer with an empty design root pulls the project down whole', () =>
   });
 });
 
+describe('a refused path ends the pull — it does not redirect it', () => {
+  // `canvasSlugFromRel` is lossy: `ui/Desk A.tsx` flattens to `ui-desk_a`, and
+  // the provisional target derived back from that slug is `ui/desk_a.tsx` — a
+  // DIFFERENT file. So when the document's own path was refused (here: the file
+  // is already on this disk, which is what `admitPullTarget` protects), falling
+  // through left the descriptor on the provisional target and the reconcile
+  // wrote the canvas there. The peer then held the canvas twice, both copies
+  // flattening to one slug — a collision, which takes the canvas out of sync on
+  // that machine entirely. Observed on a live cell for every canvas whose name
+  // contains a space.
+  test('a document whose path already exists locally writes no slug-shaped ghost', async () => {
+    const SPACED_REL = 'ui/Desk A.tsx';
+    const SPACED_SLUG = 'ui-desk_a';
+    const LOCAL = 'export default () => <main>the copy already here</main>;\n';
+    hubListing([{ name: `ws/acme/main/${SPACED_SLUG}`, bytes: BODY.length }]);
+    const ctx = makeCtx();
+    mkdirSync(join(ctx.paths.designRoot, 'ui'), { recursive: true });
+    // Present, but out of the sync set — a `syncable: false` sidecar, the TSX
+    // sandbox gate, or (on a cell) a file the hub's own workspace agent wrote.
+    writeFileSync(join(ctx.paths.designRoot, SPACED_REL), LOCAL);
+    writeFileSync(
+      join(ctx.paths.designRoot, 'ui', 'Desk A.meta.json'),
+      JSON.stringify({ syncable: false })
+    );
+    const runtime = createSyncRuntime(ctx, {
+      providerFactory: hubDocProviderFactory({
+        [SPACED_SLUG]: { body: BODY, path: SPACED_REL },
+      }),
+    });
+    await runtime?.start();
+    await runtime?.stop();
+
+    expect(existsSync(join(ctx.paths.designRoot, 'ui', 'desk_a.tsx'))).toBe(false);
+    // And the file that WAS there is kept, byte for byte.
+    expect(readFileSync(join(ctx.paths.designRoot, SPACED_REL), 'utf8')).toBe(LOCAL);
+  });
+});
+
+describe('a PULLED document may not talk itself out of being retired', () => {
+  // THE FINDING (attacker seat, 2026-08-19, HIGH). The self-stamp repair exists
+  // for the machine that performed a move, whose canvas descriptor came from its
+  // own disk scan. A PULLED canvas has no such descriptor: its path is the
+  // provisional one derived from the document NAME — which the hub chose. Since
+  // the hub also writes `movedTo`, it would control both sides of the "it moved
+  // to where it already is" comparison, and a repair would become a write to a
+  // path `resolvePulledTarget` and `admitPullTarget` never approved. That is the
+  // resurrection primitive the retirement release exists to deny.
+  test('a hub-named document whose movedTo equals its own provisional path is NOT written', async () => {
+    const SLUG = 'ui-evil';
+    hubListing([{ name: SLUG, bytes: BODY.length }]);
+    const ctx = makeCtx();
+    const runtime = createSyncRuntime(ctx, {
+      providerFactory: hubDocProviderFactory({
+        // Both halves chosen by the hub: the name fixes the provisional target
+        // `ui/evil.tsx`, and the stamp claims the canvas moved exactly there.
+        [SLUG]: { body: BODY, movedTo: 'ui/evil.tsx' },
+      }),
+    });
+    await runtime?.start();
+    await runtime?.stop();
+
+    expect(existsSync(join(ctx.paths.designRoot, 'ui', 'evil.tsx'))).toBe(false);
+  });
+});
+
 describe('boot runs the flat-fallback quarantine BEFORE the scan (fix 4)', () => {
   test('a pre-fix-5 flat twin is in _trash by the time the runtime settles', async () => {
     const ctx = makeCtx();

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

@@ -0,0 +1,169 @@
+// F6 — the aggregate per-pass byte budget on the downward lanes (Sync v2
+// Increment 0, DDR-226 §9).
+//
+// The gap the Plane-B flip gate named: every lane capped ONE file and the COUNT
+// of files, nothing capped the product. 200 × 512 MB = 100 GB, and the hub
+// chooses both factors. These tests pin that a pass stops on bytes, that it
+// stops LOUDLY, and — the part that matters for an untrusted hub — that a
+// manifest UNDERSTATING a file's size buys no extra transfer.
+
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { pullFiles } from '../sync/file-pull.ts';
+import { createPullBudget, MAX_PULL_BYTES_PER_PASS } from '../sync/pull-budget.ts';
+
+const silent = { log: () => {}, warn: () => {} };
+
+describe('createPullBudget', () => {
+  test('commits what fits and refuses what does not', () => {
+    const b = createPullBudget({ maxBytes: 100, label: 't', log: silent });
+    expect(b.take(60)).toBe(true);
+    expect(b.spent()).toBe(60);
+    expect(b.remaining()).toBe(40);
+    expect(b.take(50)).toBe(false);
+    expect(b.spent()).toBe(60); // a refused charge is not committed
+    expect(b.exhausted()).toBe(true);
+  });
+
+  test('an exact fit is allowed', () => {
+    const b = createPullBudget({ maxBytes: 100, label: 't', log: silent });
+    expect(b.take(100)).toBe(true);
+    expect(b.exhausted()).toBe(false);
+    expect(b.remaining()).toBe(0);
+    expect(b.take(1)).toBe(false);
+  });
+
+  test('a negative or NaN size can never refund budget', () => {
+    const b = createPullBudget({ maxBytes: 100, label: 't', log: silent });
+    expect(b.take(-1_000_000)).toBe(true);
+    expect(b.take(Number.NaN)).toBe(true);
+    expect(b.spent()).toBe(0);
+    expect(b.take(101)).toBe(false);
+  });
+
+  test('the wall is named exactly once, and loudly', () => {
+    const warns: string[] = [];
+    const b = createPullBudget({
+      maxBytes: 10,
+      label: 'sync/files',
+      log: { warn: (m: string) => warns.push(m) },
+    });
+    b.take(20);
+    b.take(20);
+    expect(warns).toHaveLength(1);
+    expect(warns[0]).toContain('[sync/files]');
+    expect(warns[0]).toContain('byte budget');
+    expect(warns[0]).toContain('next pass');
+  });
+
+  test('the default ceiling is the documented 2 GiB', () => {
+    expect(MAX_PULL_BYTES_PER_PASS).toBe(2 * 1024 * 1024 * 1024);
+    const b = createPullBudget({ label: 't', log: silent });
+    expect(b.remaining()).toBe(MAX_PULL_BYTES_PER_PASS);
+  });
+});
+
+describe('file-pull honours the pass budget', () => {
+  const manifest = (files: { path: string; size: number; sha256: string }[]) =>
+    ({
+      files: files.map((f) => ({
+        path: f.path,
+        sha256: f.sha256,
+        size: f.size,
+        mtimeMs: Date.now(),
+        class: 'inert-media',
+      })),
+    }) as const;
+
+  const sha = async (bytes: Uint8Array) =>
+    Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)))
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+
+  test('charges from the manifest BEFORE the request — an over-budget batch costs no transfer', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'pull-budget-files-'));
+    try {
+      mkdirSync(join(dir, 'assets'), { recursive: true });
+      const bytes = new Uint8Array(400);
+      const hash = await sha(bytes);
+      const fetched: string[] = [];
+      const fetchImpl = (async (url: string) => {
+        const u = String(url);
+        if (u.endsWith('/api/files')) {
+          return new Response(
+            JSON.stringify(
+              manifest([
+                { path: 'assets/a.png', size: 400, sha256: hash },
+                { path: 'assets/b.png', size: 400, sha256: hash },
+                { path: 'assets/c.png', size: 400, sha256: hash },
+              ])
+            ),
+            { status: 200 }
+          );
+        }
+        fetched.push(u);
+        return new Response(bytes, { status: 200 });
+      }) as unknown as typeof fetch;
+
+      const out = await pullFiles({
+        designRoot: dir,
+        hubUrl: 'https://hub.example',
+        token: () => 't',
+        allowCodeModules: false,
+        fetchImpl,
+        log: silent,
+        maxPassBytes: 900,
+      });
+
+      expect(out.pulled).toHaveLength(2);
+      expect(out.budgetExhausted).toBe(true);
+      // The third file was never even requested — the manifest priced it.
+      expect(fetched).toHaveLength(2);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('a manifest that UNDERSTATES a size buys no extra transfer', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'pull-budget-files-lie-'));
+    try {
+      mkdirSync(join(dir, 'assets'), { recursive: true });
+      const big = new Uint8Array(5_000);
+      const hash = await sha(big);
+      const fetchImpl = (async (url: string) => {
+        const u = String(url);
+        if (u.endsWith('/api/files')) {
+          return new Response(
+            JSON.stringify(
+              // Declares 1 byte; sends 5,000.
+              manifest([{ path: 'assets/lie.png', size: 1, sha256: hash }])
+            ),
+            { status: 200 }
+          );
+        }
+        return new Response(big, { status: 200 });
+      }) as unknown as typeof fetch;
+
+      const out = await pullFiles({
+        designRoot: dir,
+        hubUrl: 'https://hub.example',
+        token: () => 't',
+        allowCodeModules: false,
+        fetchImpl,
+        log: silent,
+        maxPassBytes: 1_000,
+      });
+
+      expect(out.pulled).toEqual([]);
+      expect(out.budgetExhausted).toBe(true);
+      expect(out.failed[0]?.reason).toContain('declared 1 B, sent 5000 B');
+      // And crucially: nothing landed on disk.
+      expect(readdirSync(join(dir, 'assets'))).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});