@1agh/maude 0.53.0 → 0.53.2

package/apps/studio/test/canvas-build-sandbox.test.ts

@@ -0,0 +1,69 @@
+// Cloud Phase 27 — the sandbox child's environment.
+//
+// Diagnosed against a real cell: the canvas module 422'd with "Cannot find
+// native binding" while running the identical worker command by hand with a
+// clean environment worked. The difference was one inherited variable.
+
+import { describe, expect, test } from 'bun:test';
+
+import { workerEnv } from '../canvas-build-sandbox.ts';
+
+describe('workerEnv', () => {
+  test('a compiled binary’s VIRTUAL binding path is not handed to a child', () => {
+    const env = workerEnv({
+      PATH: '/bin',
+      NAPI_RS_NATIVE_LIBRARY_PATH: '/$bunfs/root/parser.linux-arm64-gnu.node',
+    } as NodeJS.ProcessEnv);
+    expect(env.NAPI_RS_NATIVE_LIBRARY_PATH).toBeUndefined();
+  });
+
+  test('a REAL binding path still is', () => {
+    const env = workerEnv({
+      PATH: '/bin',
+      NAPI_RS_NATIVE_LIBRARY_PATH: '/maude/node_modules/@oxc-parser/binding-linux-arm64-gnu',
+    } as NodeJS.ProcessEnv);
+    expect(env.NAPI_RS_NATIVE_LIBRARY_PATH).toBe(
+      '/maude/node_modules/@oxc-parser/binding-linux-arm64-gnu'
+    );
+  });
+
+  test('the child environment carries no secret — it parses tenant source', () => {
+    const env = workerEnv({
+      PATH: '/bin',
+      HUB_SECRET: 'nope',
+      AWS_SECRET_ACCESS_KEY: 'also-nope',
+      MAUDE_PROJECT_TOKEN_KEY: 'definitely-nope',
+    } as NodeJS.ProcessEnv);
+    expect(env.HUB_SECRET).toBeUndefined();
+    expect(env.AWS_SECRET_ACCESS_KEY).toBeUndefined();
+    expect(env.MAUDE_PROJECT_TOKEN_KEY).toBeUndefined();
+  });
+});
+
+// Cloud Phase 27 B2 — content-addressed media is immutable; everything else
+// revalidates. `no-store` is right on a laptop and is a re-download of every
+// photograph on every pan over the internet.
+import { cacheControlFor } from '../http.ts';
+
+describe('cacheControlFor', () => {
+  test('a content-addressed name is immutable — the name IS the content', () => {
+    for (const p of ['/x/assets/deadbeef.png', '/a/b/0123456789abcdef.mp4']) {
+      expect(cacheControlFor(p).cacheControl).toBe('public, max-age=31536000, immutable');
+      expect(cacheControlFor(p).addEtag).toBe(false);
+    }
+  });
+
+  test('an AUTHORED name revalidates — a designer edits hero.png in place', () => {
+    for (const p of ['/x/assets/hero.png', '/x/system/ds/colors_and_type.css', '/x/logos.svg']) {
+      expect(cacheControlFor(p).cacheControl).toBe('no-cache');
+      expect(cacheControlFor(p).addEtag).toBe(true);
+    }
+  });
+
+  test('a name that merely LOOKS hex-ish is not treated as content-addressed', () => {
+    // `deadbee` is 7 chars; `deadbeefs` has a non-hex char. Getting either
+    // wrong caches a mutable file for a year.
+    expect(cacheControlFor('/x/deadbee.png').cacheControl).toBe('no-cache');
+    expect(cacheControlFor('/x/deadbeefs.png').cacheControl).toBe('no-cache');
+  });
+});

package/apps/studio/test/canvas-origin-gate.test.ts

@@ -156,6 +156,11 @@ describe('canvas-origin gate — A1/A2 traversal + privilege containment', () =>
         '/_api/debug-bundle',
         '/_api/report',
         '/_api/report-fallback',
+        // …and the shell capture SPAWNS A PROCESS (screenshot.sh → a headless
+        // browser) and renders the whole project. Reachable from the canvas
+        // origin it would be a resource-exhaustion lever driven by untrusted
+        // canvas code, so it carries the same main-origin-only posture.
+        '/_api/shell-shot',
         // Stage F1 — the AssetPicker's asset-listing GET is a shell (main-origin)
         // concern; the untrusted canvas iframe must not enumerate project media.
         '/_api/assets',

package/apps/studio/test/canvas-url.test.ts

@@ -110,3 +110,29 @@ describe('canvasUrl — per-canvas design-system token resolution', () => {
     ).toBeNull();
   });
 });
+
+// Cloud Phase 27 (DDR-209) — the canvas origin's capability.
+//
+// In the cloud the canvas origin is a cookieless, cross-site hostname: a cookie
+// scoped widely enough to cover it would be readable by the untrusted canvas
+// content itself, which is the one thing the DDR-054 split exists to prevent.
+// So the capability rides in the URL. It reaches `cfg` through the `/_config`
+// projection — which silently dropped it once, and would have 401'd every
+// canvas iframe in production (see `config-projection.test.ts`).
+
+test('a canvas URL carries the capability when the server minted one', () => {
+  const url = canvasUrl('.design/ui/Home.tsx', {
+    designRel: '.design',
+    canvasOrigin: 'https://canvas.cloud.maude.sh/alligators',
+    canvasToken: 'cap-abc123',
+  });
+  expect(url.startsWith('https://canvas.cloud.maude.sh/alligators/_canvas-shell.html?')).toBe(true);
+  expect(new URL(url).searchParams.get('t')).toBe('cap-abc123');
+});
+
+test('a desktop URL is byte-identical to before — no capability, no query', () => {
+  // The loopback canvas origin needs none, so this must not change for the
+  // shell that has always worked.
+  const url = canvasUrl('.design/ui/Home.tsx', { designRel: '.design' });
+  expect(new URL(url, 'http://x').searchParams.has('t')).toBe(false);
+});

package/apps/studio/test/cloud-session-role.test.ts

@@ -0,0 +1,131 @@
+// Cloud Phase 27 A3/A4 + C2/C4 (DDR-209) — the studio in a cell.
+//
+// The behaviour under test is the one that makes a cell multi-tenant-safe: in
+// workspace mode this process serves an owner and a viewer at the SAME TIME, so
+// "what may this request do" cannot come from a file on disk. It comes from the
+// proxy in front, per request, and in the absence of proof it is `viewer`.
+//
+// The local gate this replaces fails OPEN by design — `isHubReadOnly()` returns
+// false from its `catch`, and `projectReadOnly()` returns false when `linkedHub`
+// is unset. That is correct for a tool on your own laptop and is the whole
+// ballgame on the internet, which is why the no-header case below is the most
+// important assertion in the file.
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import type { Subprocess } from 'bun';
+
+import { bootServer, killProc, makeSandbox, nextPort } from './_helpers.ts';
+
+const procs: Subprocess[] = [];
+afterAll(async () => {
+  for (const p of procs) await killProc(p);
+});
+
+async function bootCell() {
+  const { root } = makeSandbox();
+  const port = nextPort();
+  const proc = await bootServer(root, port, {
+    MAUDE_WORKSPACE_MODE: '1',
+    // A dev checkout resolves Playwright (the E2E harness), which is a
+    // legitimate devDependency here and would otherwise fail the module half of
+    // the containment assert before workspace mode could be tested at all.
+    MAUDE_WORKSPACE_ALLOW_DEV_MODULES: '1',
+    HUB_DASHBOARD_URL: 'https://cloud.maude.sh',
+    MAUDE_PROJECT_NAME: 'Alligators',
+  });
+  procs.push(proc);
+  return { base: `http://localhost:${port}` };
+}
+
+describe('a cell resolves the role per request, and defaults to read-only', () => {
+  test('no injected role at all ⇒ read-only, and writes are refused', async () => {
+    const { base } = await bootCell();
+
+    const cfg = (await (await fetch(`${base}/_config`)).json()) as { readOnly?: boolean };
+    expect(cfg.readOnly).toBe(true);
+
+    const res = await fetch(`${base}/_api/edit-text`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ file: 'ui/Sample.tsx', id: 'x', text: 'y' }),
+    });
+    expect(res.status).toBe(403);
+    expect(((await res.json()) as { reason?: string }).reason).toBe('read-only');
+  });
+
+  test('a vouched editing role opens the same write', async () => {
+    const { base } = await bootCell();
+
+    const cfg = (await (
+      await fetch(`${base}/_config`, { headers: { 'x-maude-readonly': '0' } })
+    ).json()) as { readOnly?: boolean };
+    expect(cfg.readOnly).toBe(false);
+
+    const res = await fetch(`${base}/_api/edit-text`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-maude-readonly': '0' },
+      body: JSON.stringify({ file: 'ui/Sample.tsx', id: 'x', text: 'y' }),
+    });
+    // Whatever the handler makes of the payload, the GATE let it through — the
+    // read-only refusal is the specific thing that must not happen.
+    expect(res.status).not.toBe(403);
+  });
+
+  test('anything other than a positive `0` is read-only', async () => {
+    // The failure mode this rules out: a truthy-string check, where
+    // `x-maude-readonly: false` (a plausible thing for a future caller to send)
+    // reads as "not read-only".
+    const { base } = await bootCell();
+    for (const value of ['1', 'false', 'no', '', 'true', 'owner']) {
+      const cfg = (await (
+        await fetch(`${base}/_config`, { headers: { 'x-maude-readonly': value } })
+      ).json()) as { readOnly?: boolean };
+      expect(cfg.readOnly).toBe(true);
+    }
+  });
+
+  test('two requests to ONE process get two different answers', async () => {
+    // The actual multi-tenancy property, stated as a test: this is what a
+    // per-PROCESS config file cannot do, and it is why A3 exists.
+    const { base } = await bootCell();
+    const [viewer, member] = await Promise.all([
+      fetch(`${base}/_config`, { headers: { 'x-maude-readonly': '1' } }).then((r) => r.json()),
+      fetch(`${base}/_config`, { headers: { 'x-maude-readonly': '0' } }).then((r) => r.json()),
+    ]);
+    expect((viewer as { readOnly: boolean }).readOnly).toBe(true);
+    expect((member as { readOnly: boolean }).readOnly).toBe(false);
+  });
+});
+
+describe('the cloud shell states what it is', () => {
+  test('/_config carries the cloud block C2 and C4 render from', async () => {
+    const { base } = await bootCell();
+    const cfg = (await (await fetch(`${base}/_config`)).json()) as {
+      cloud?: { dashboardUrl?: string; projectName?: string };
+    };
+    expect(cfg.cloud).toBeTruthy();
+    expect(cfg.cloud?.dashboardUrl).toBe('https://cloud.maude.sh');
+    expect(cfg.cloud?.projectName).toBe('Alligators');
+  });
+
+  test('the canvas capability is echoed only when the proxy minted one', async () => {
+    const { base } = await bootCell();
+    const without = (await (await fetch(`${base}/_config`)).json()) as { canvasToken?: string };
+    expect(without.canvasToken).toBeUndefined();
+
+    const with_ = (await (
+      await fetch(`${base}/_config`, { headers: { 'x-maude-canvas-token': 'cap-123' } })
+    ).json()) as { canvasToken?: string };
+    expect(with_.canvasToken).toBe('cap-123');
+  });
+
+  test('a cell SERVES the canvas surfaces it used to 404 (DDR-209 A′1)', async () => {
+    const { base } = await bootCell();
+    // The shell is a static harness; the browser is what evaluates it. Before
+    // DDR-209 this was a hard 404 in workspace mode, which is precisely why
+    // Phase 25 had to hand-roll a second studio.
+    const shell = await fetch(`${base}/_canvas-shell.html`);
+    expect(shell.status).toBe(200);
+    expect(shell.headers.get('content-type')).toContain('text/html');
+  });
+});

package/apps/studio/test/cloud-shell-surfaces.test.ts

@@ -0,0 +1,90 @@
+// Surfaces a cloud tab must not offer — Cloud Phase 27, found by using it.
+//
+// The phase's rule is C1's: role shapes what is OFFERED, never what is VISIBLE.
+// That rule is about ROLES. A different question turned up the moment the real
+// studio actually ran in a browser: what about a control whose feature cannot
+// exist in THIS SHELL at all?
+//
+// Three answers, and the difference between them is the whole point:
+//
+//   the agent chat        ABSENT, WITH A NOTICE. It runs on your own Claude
+//                         subscription on your own machine (DDR-123). The
+//                         feature exists and you can have it — the menu row
+//                         stays, disabled, saying where. (C2)
+//
+//   "Sign in to Maude     ABSENT, SILENTLY. It offers to do the thing you have
+//    Cloud"               already done: you reached this tab THROUGH a Maude
+//                         account. There is nothing to explain.
+//
+//   AI generation /       ABSENT, SILENTLY. These configure ffmpeg, mlx-vlm, a
+//   Subtitles / Video     HuggingFace cache and your own provider keys — none
+//                         of which a browser tab has, and whose routes a cell
+//                         refuses by design (DDR-209 D1). Left in, they render
+//                         as a wall of `HTTP 404`, which is what the owner saw.
+//
+// Source-level assertions, because the menubar's dropdowns do not open under a
+// synthetic click and a test that cannot fail is worse than no test. What these
+// pin is exactly what would regress: someone re-introducing `TABS.map` or
+// dropping the gate on `<CloudBar />`.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const STUDIO = join(import.meta.dir, '..');
+const APP = readFileSync(join(STUDIO, 'client', 'app.jsx'), 'utf8');
+const SETTINGS = readFileSync(join(STUDIO, 'client', 'panels', 'SettingsPanel.jsx'), 'utf8');
+
+describe('the cloud shell offers nothing it cannot honour', () => {
+  test('the local-machine settings tabs are flagged, and only those three', () => {
+    const flagged = [
+      ...SETTINGS.matchAll(/\{ id: '([a-z-]+)', label: '[^']+', local: true \}/g),
+    ].map((m) => m[1]);
+    expect(flagged.sort()).toEqual(['ai-generation', 'subtitles', 'video']);
+  });
+
+  test('the tab rail renders the FILTERED list, not the raw table', () => {
+    // `TABS.map` is what shipped the wall of 404s.
+    expect(SETTINGS).toContain('{tabs.map((t) => (');
+    expect(SETTINGS).not.toContain('{TABS.map(');
+    // …and every keyboard path must walk the same list, or End/Home select a
+    // tab that is not on screen.
+    expect(SETTINGS).not.toMatch(/setTab\(TABS\[/);
+    expect(SETTINGS).toContain('const tabs = useMemo(');
+  });
+
+  test('a remembered tab this shell does not have cannot select nothing', () => {
+    // Open Video on the desktop, then open Settings in the cloud.
+    const init =
+      /const \[tab, setTab\] = useState\(\(\) => \{[\s\S]*?\}\);/.exec(SETTINGS)?.[0] ?? '';
+    expect(init).toContain('!(cloud && t.local)');
+  });
+
+  test('the cloud sign-in is not offered inside the cloud', () => {
+    expect(APP).toContain('{cloud ? null : <CloudBar />}');
+  });
+
+  test('every component that gates on the shell is actually GIVEN the flag', () => {
+    // The bug this exists for: three `cfg?.cloud` reads inside a component that
+    // never receives `cfg` — a ReferenceError at render, and a blank app.
+    for (const call of ['<Menubar', '<Sidebar', '<SettingsPanel']) {
+      const at = APP.indexOf(call);
+      expect(at).toBeGreaterThan(0);
+      const props = APP.slice(at, at + 900);
+      expect(props).toContain('cloud={cfg?.cloud ?? null}');
+    }
+  });
+
+  test('no component reaches for `cfg` where only the flag was passed', () => {
+    // `cfg` is a real variable at the top level, so a stray reference in a
+    // child component is a ReferenceError the bundler happily emits.
+    for (const fn of ['function Menubar({', 'function Sidebar({']) {
+      const start = APP.indexOf(fn);
+      expect(start).toBeGreaterThan(0);
+      // Bounded window: the component's own body, not the whole file.
+      const body = APP.slice(start, APP.indexOf('\nfunction ', start + 10));
+      expect(body).not.toMatch(/\bcfg\?\./);
+      expect(body).not.toMatch(/\bcfg\./);
+    }
+  });
+});

package/apps/studio/test/config-projection.test.ts

@@ -0,0 +1,104 @@
+// The `/_config` projection — Cloud Phase 27.
+//
+// WHAT WENT WRONG, TWICE IN ONE CHANGE.
+//
+// The server's `/_config` handler adds fields to the config it returns. The
+// client does NOT spread that response — it builds a new object naming each
+// field it wants (a deliberate choice: `/_config` and `/_index-data` race, and
+// a full replace would clobber `canvasDesignSystems`). So a field the server
+// starts returning arrives nowhere until somebody names it on the client too,
+// and NOTHING says so. Phase 27 added two and named neither:
+//
+//   `cloud`        → the cloud studio rendered without its "which project am I
+//                    in / how do I leave" chrome, silently.
+//   `canvasToken`  → every canvas iframe loaded the cookieless canvas origin
+//                    with no capability, so every canvas would have 401'd.
+//
+// Both shipped to production. The first was found by looking at the page; the
+// second had not been found at all.
+//
+// This test reads BOTH sides out of source and demands they agree. It is a
+// grep-gate, the same trade `scripts/check-containment.sh` makes, and it is
+// sound for the same reason: the shapes it matches are the ones both files have
+// had since they were written, and the "did the regex find anything" assertions
+// below are what stop it passing vacuously.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const STUDIO = join(import.meta.dir, '..');
+const HTTP_TS = readFileSync(join(STUDIO, 'http.ts'), 'utf8');
+const APP_JSX = readFileSync(join(STUDIO, 'client', 'app.jsx'), 'utf8');
+
+/**
+ * Fields the `/_config` handler adds ON TOP of the `...ctx.cfg` spread.
+ *
+ * The spread itself is not enumerable from source and does not need to be: it
+ * is the project's own config file, which the client already carries wholesale.
+ * The risk is in the COMPUTED fields — the ones the server decides per request.
+ */
+function serverComputedConfigFields(): string[] {
+  const start = HTTP_TS.indexOf("'/_config':");
+  expect(start).toBeGreaterThan(0);
+  // The handler is short; take to the end of its `Response.json({...})`.
+  const body = HTTP_TS.slice(start, start + 2000);
+  const end = body.indexOf('\n    // ');
+  const src = end > 0 ? body.slice(0, end) : body;
+
+  const fields = new Set<string>();
+  // `canvasOrigin: ctx.canvasOrigin,` / `readOnly: projectReadOnly(req),`
+  for (const m of src.matchAll(/^\s{8}([a-zA-Z][a-zA-Z0-9]*):\s/gm)) fields.add(m[1]);
+  // Conditionally-spread fields: `? { canvasToken: … }` / `? { cloud: { … } }`
+  for (const m of src.matchAll(/\?\s*\{\s*([a-zA-Z][a-zA-Z0-9]*):/g)) fields.add(m[1]);
+  return [...fields].sort();
+}
+
+/** Fields the client's `/_config` handler copies into `cfg`. */
+function clientProjectedFields(): string[] {
+  const start = APP_JSX.indexOf("fetch('/_config')");
+  expect(start).toBeGreaterThan(0);
+  const end = APP_JSX.indexOf('.catch(() => {});', start);
+  expect(end).toBeGreaterThan(start);
+  const src = APP_JSX.slice(start, end);
+  const fields = new Set<string>();
+  for (const m of src.matchAll(/^\s{10}([a-zA-Z][a-zA-Z0-9]*):\s/gm)) fields.add(m[1]);
+  return [...fields].sort();
+}
+
+describe('/_config projection', () => {
+  test('the scrape finds both sides — a regex that matches nothing approves everything', () => {
+    const server = serverComputedConfigFields();
+    const client = clientProjectedFields();
+    expect(server.length).toBeGreaterThanOrEqual(3);
+    expect(client.length).toBeGreaterThanOrEqual(5);
+    expect(server).toContain('readOnly');
+    expect(client).toContain('readOnly');
+  });
+
+  test('every field the server COMPUTES is named by the client', () => {
+    const client = new Set(clientProjectedFields());
+    const missing = serverComputedConfigFields().filter((f) => !client.has(f));
+    expect(missing).toEqual([]);
+  });
+
+  test('the two fields this gate was written for are both present', () => {
+    // Named explicitly as well as covered by the rule above, because these are
+    // the ones that actually shipped broken and a future refactor of the regex
+    // should not be able to quietly stop covering them.
+    const client = new Set(clientProjectedFields());
+    expect(client.has('canvasToken')).toBe(true);
+    expect(client.has('cloud')).toBe(true);
+  });
+
+  test('the client still MERGES rather than replaces', () => {
+    // The reason the projection is explicit in the first place: `/_config` and
+    // `/_index-data` race, and a full replace clobbers `canvasDesignSystems`
+    // (DDR-093). Anyone "simplifying" this into a spread of `data` must not
+    // also drop the functional merge.
+    const start = APP_JSX.indexOf("fetch('/_config')");
+    const src = APP_JSX.slice(start, APP_JSX.indexOf('.catch(() => {});', start));
+    expect(src).toContain('setCfg((prev) => ({');
+    expect(src).toContain('...prev,');
+  });
+});

package/apps/studio/test/read-only-gate.test.ts

@@ -128,3 +128,53 @@ describe('read-only gate — viewer role refuses project writes locally', () =>
     expect(r.status).not.toBe(403);
   }, 30000);
 });
+
+// ---------------------------------------------------------------------------
+// Cloud Phase 27 — the one write a viewer holds.
+//
+// The role matrix has said `viewer.comment === true` since Phase 25 C4 and the
+// People page promises it in those words. This list did not have it, so a
+// viewer's comment was allowed by the authority (the cell's proxy) and then
+// refused by the defence-in-depth layer behind it. Found by commenting as a
+// viewer against a real cell, not by reading either file.
+
+describe('a viewer may comment — the matrix says so, and so must this gate', () => {
+  test('comment + reply pass; annotate still does not', async () => {
+    const { base } = await boot('viewer');
+
+    const comment = await fetch(`${base}/_comments`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ file: 'ui/Sample.tsx', text: 'looks off to me' }),
+    });
+    expect(comment.status).not.toBe(403);
+
+    const reply = await fetch(`${base}/_api/comments/abc123/reply`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ text: 'agreed' }),
+    });
+    expect(reply.status).not.toBe(403);
+
+    // An annotation is drawn ON the design and versioned with it — the matrix
+    // files it with `edit`, and that distinction has to survive this change.
+    const annotate = await fetch(`${base}/_api/annotations`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ file: 'ui/Sample.tsx', svg: '<svg/>' }),
+    });
+    expect(annotate.status).toBe(403);
+  });
+
+  test('the reply pattern does not open the whole comment namespace', async () => {
+    const { base } = await boot('viewer');
+    for (const path of [
+      '/_api/comments/abc/delete',
+      '/_api/comments/abc/reply/../../edit-text',
+      '/_api/comments//reply',
+    ]) {
+      const res = await fetch(`${base}${path}`, { method: 'POST' });
+      expect(res.status).not.toBe(200);
+    }
+  });
+});

package/apps/studio/test/report-proxy.test.ts

@@ -0,0 +1,125 @@
+// Regression test for issue-report-a-bug-http-500 (RCA:
+// .ai/logs/rca/issue-report-a-bug-http-500.md). `/_api/report` proxies the
+// dialog's multipart body to `MAUDE_REPORT_URL`. A bare `fetch(endpoint, …)`
+// call inside http.ts silently resolved to this module's OWN same-named
+// fall-through handler instead of the global `fetch` — the request never left
+// the machine, and the route mirrored a bogus local 500 back to the client.
+// These tests boot a real server pointed at a real stub upstream, so a
+// reintroduced shadow (or any other break in the proxy hop) fails loudly
+// instead of only being caught by a mocked-upstream unit test.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+
+import { bootServer, killProc, makeSandbox, nextPort } from './_helpers.ts';
+
+async function bootStubUpstream(
+  handler: (req: Request) => Response | Promise<Response>
+): Promise<{ url: string; stop: () => void; received: () => number }> {
+  let received = 0;
+  const server = Bun.serve({
+    port: 0,
+    fetch: async (req) => {
+      received += 1;
+      return handler(req);
+    },
+  });
+  return {
+    url: `http://127.0.0.1:${server.port}`,
+    stop: () => server.stop(true),
+    received: () => received,
+  };
+}
+
+describe('/_api/report proxy hop', () => {
+  test('forwards the multipart body verbatim and mirrors a successful upstream response', async () => {
+    const { root } = makeSandbox();
+    let capturedBytes = 0;
+    let capturedHasReportPart = false;
+    const upstream = await bootStubUpstream(async (req) => {
+      const form = await req.formData();
+      capturedHasReportPart = typeof form.get('report') === 'string';
+      // Multipart parsing consumed the body — approximate "did real bytes
+      // arrive" by re-serializing what FormData kept.
+      capturedBytes = [...form.values()].reduce(
+        (n, v) => n + (typeof v === 'string' ? v.length : (v as Blob).size),
+        0
+      );
+      return Response.json({ ok: true, issueNumber: 1, issueUrl: 'https://example.com/issues/1' });
+    });
+
+    const port = nextPort();
+    const proc = await bootServer(root, port, { MAUDE_REPORT_URL: `${upstream.url}/report` });
+    try {
+      const form = new FormData();
+      form.set(
+        'report',
+        JSON.stringify({ schema: 'maude-report/v1', description: 'test', reportId: 'r-0123abcd' })
+      );
+      form.append('screenshot', new Blob([new Uint8Array([1, 2, 3, 4])]), 'shot.png');
+
+      const res = await fetch(`http://localhost:${port}/_api/report`, {
+        method: 'POST',
+        body: form,
+      });
+      expect(res.status).toBe(200);
+      const json = await res.json();
+      expect(json).toEqual({ ok: true, issueNumber: 1, issueUrl: 'https://example.com/issues/1' });
+
+      expect(upstream.received()).toBe(1);
+      expect(capturedHasReportPart).toBe(true);
+      expect(capturedBytes).toBeGreaterThan(0);
+    } finally {
+      await killProc(proc);
+      upstream.stop();
+    }
+  });
+
+  test('an unreachable upstream yields 502 with a JSON error, not a bare 500', async () => {
+    const { root } = makeSandbox();
+    const port = nextPort();
+    // Nothing listens on this port — the fetch itself must fail/timeout.
+    const proc = await bootServer(root, port, { MAUDE_REPORT_URL: 'http://127.0.0.1:1/report' });
+    try {
+      const form = new FormData();
+      form.set(
+        'report',
+        JSON.stringify({ schema: 'maude-report/v1', description: 'test', reportId: 'r-0123abcd' })
+      );
+      const res = await fetch(`http://localhost:${port}/_api/report`, {
+        method: 'POST',
+        body: form,
+      });
+      expect(res.status).toBe(502);
+      const json = await res.json();
+      expect(json).toEqual({ error: 'report service unreachable' });
+    } finally {
+      await killProc(proc);
+    }
+  });
+});
+
+describe('no bare `fetch(` call sites in http.ts', () => {
+  test('every fetch call is either the global fetch (qualified) or a local handler name', () => {
+    const src = readFileSync(new URL('../http.ts', import.meta.url), 'utf8');
+    // A bare `fetch(` immediately preceded by a word-boundary and NOT preceded
+    // by a `.` (member access) or `function ` (declaration) would silently
+    // resolve to this file's own same-named fall-through handler instead of
+    // the global — exactly the bug this test guards against. `handleFallthrough`
+    // is the current, unambiguous name; this assertion also fails if the
+    // handler is ever renamed back to something call-site-ambiguous.
+    const bareFetchCalls = [...src.matchAll(/(?<![.\w])fetch\(/g)];
+    const lines = src.split('\n');
+    // Skip: comment lines (mentioning `fetch(` in prose is fine) and the one
+    // legitimate bare occurrence — the type-signature parameter name
+    // `fetch(req: Request): Promise<Response>;` in the `Api`-shaped interface,
+    // which is a declaration, not a call.
+    const offendingLines = bareFetchCalls
+      .map((m) => src.slice(0, m.index).split('\n').length)
+      .map((line) => ({ line, text: lines[line - 1] ?? '' }))
+      .filter(({ text }) => !/^\s*(\/\/|\*)/.test(text))
+      .filter(({ text }) => !/^\s*fetch\(req: Request\): Promise<Response>;/.test(text));
+
+    expect(offendingLines).toEqual([]);
+  });
+});