@cosmicdrift/kumiko-server-runtime 0.329.0 → 0.330.0

package/src/__tests__/run-worker-app-boot.test.ts

@@ -1,183 +0,0 @@
-// Boot-mode + KMS-gate tests for runWorkerApp — no real Postgres/Redis
-// needed (like run-prod-app-env-source.test.ts): KUMIKO_DRY_RUN_ENV=boot
-// exits BEFORE any connection, and the KMS health gate runs BEFORE
-// createDbConnection/new Redis(...) — so neither path needs real infra.
-
-import { describe, expect, spyOn, test } from "bun:test";
-import type { KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
-import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
-import { runWorkerApp } from "../run-worker-app";
-import { makeProbeFeature, withClearedBootEnv } from "./boot-probe-fixture";
-
-const probeFeature = makeProbeFeature({
-  name: "worker-boot-probe",
-  table: "worker_boot_probe",
-});
-
-const DUMMY_ENV = {
-  DATABASE_URL: "postgres://smoke:smoke@127.0.0.1:1/smoke",
-  REDIS_URL: "redis://127.0.0.1:1",
-  JWT_SECRET: "smokesmokesmokesmokesmokesmokesmokesmoke",
-} as const;
-
-describe("runWorkerApp boot-mode", () => {
-  withClearedBootEnv();
-
-  test("KUMIKO_DRY_RUN_ENV=boot returns an inert handle without opening DB/Redis", async () => {
-    const logs: string[] = [];
-    const originalLog = console.log;
-    console.log = (...args: unknown[]) => {
-      logs.push(args.map(String).join(" "));
-    };
-    let handle: Awaited<ReturnType<typeof runWorkerApp>>;
-    try {
-      handle = await runWorkerApp({
-        features: [probeFeature],
-        migrations: false,
-        envSource: { ...DUMMY_ENV, KUMIKO_DRY_RUN_ENV: "boot" },
-      });
-    } finally {
-      console.log = originalLog;
-    }
-
-    expect(handle).toBeDefined();
-    expect(typeof handle.stop).toBe("function");
-    expect(logs.some((line) => line.includes("boot validation OK"))).toBe(true);
-    await handle.stop();
-  });
-
-  test("ensureTemporalPolyfill runs even in boot-mode — Temporal is defined right after boot validation", async () => {
-    // Regression pin for fw#1725: the bug that cost real time was a
-    // missing polyfill call. Boot-mode boots without running any job —
-    // this test only proves "the polyfill call happens"; the ordering-
-    // before-composeFeatures guarantee is covered by the integration
-    // test (run-worker-app.integration.test.ts) via a real job.
-    const originalLog = console.log;
-    console.log = () => {};
-    try {
-      const handle = await runWorkerApp({
-        features: [probeFeature],
-        migrations: false,
-        envSource: { ...DUMMY_ENV, KUMIKO_DRY_RUN_ENV: "boot" },
-      });
-      await handle.stop();
-    } finally {
-      console.log = originalLog;
-    }
-    expect(typeof (globalThis as { Temporal?: unknown }).Temporal).toBe("object");
-  });
-
-  test("unhealthy KMS aborts boot before any DB/Redis connection is opened", async () => {
-    let healthChecked = false;
-    const unhealthyKms: KmsAdapter = {
-      capabilities: { mode: "local-key" },
-      createKey: async () => {},
-      getKey: async () => {
-        throw new Error("unreachable");
-      },
-      eraseKey: async () => {},
-      health: async () => {
-        healthChecked = true;
-        return { ok: false, latencyMs: 3 };
-      },
-    };
-    const originalLog = console.log;
-    console.log = () => {};
-    try {
-      await expect(
-        runWorkerApp({
-          features: [probeFeature],
-          migrations: false,
-          kms: unhealthyKms,
-          envSource: { ...DUMMY_ENV },
-        }),
-      ).rejects.toThrow(/KMS health check failed/);
-    } finally {
-      console.log = originalLog;
-    }
-    expect(healthChecked).toBe(true);
-  });
-
-  test("validateBootOptions reaches validateBoot — an opt-in warning fires only when passed", async () => {
-    // Reach-the-boot proof, not an acceptance proof: the probe feature's
-    // single "anonymous" handler makes warnOnUniqueAccessRoles emit a
-    // warning naming that role, and validateBoot emits it only when the
-    // option arrives (fw#3080).
-    const originalLog = console.log;
-    console.log = () => {};
-    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
-    const roleWarnings = (): string[] =>
-      warnSpy.mock.calls
-        .map((call) => String(call[0]))
-        .filter((line) => line.includes('Access role "anonymous"'));
-    try {
-      const withOption = await runWorkerApp({
-        features: [probeFeature],
-        migrations: false,
-        validateBootOptions: { warnOnUniqueAccessRoles: true },
-        envSource: { ...DUMMY_ENV, KUMIKO_DRY_RUN_ENV: "boot" },
-      });
-      await withOption.stop();
-      expect(roleWarnings().length).toBeGreaterThan(0);
-
-      warnSpy.mockClear();
-      const withoutOption = await runWorkerApp({
-        features: [probeFeature],
-        migrations: false,
-        envSource: { ...DUMMY_ENV, KUMIKO_DRY_RUN_ENV: "boot" },
-      });
-      await withoutOption.stop();
-      expect(roleWarnings()).toEqual([]);
-    } finally {
-      warnSpy.mockRestore();
-      console.log = originalLog;
-    }
-  });
-
-  test("kmsSlots: a master key that exists only as ciphertext reaches the boot probe", async () => {
-    const encryptedFeature = defineFeature("worker-kms-probe", (r) => {
-      r.entity(
-        "note",
-        createEntity({
-          table: "worker_kms_probe_note",
-          fields: {
-            body: createTextField({ personal: false, reason: "test_fixture", encrypted: true }),
-          },
-        }),
-      );
-    });
-    const originalFetch = globalThis.fetch;
-    const originalLog = console.log;
-    const originalInfo = console.info;
-    globalThis.fetch = (async () =>
-      new Response(JSON.stringify({ plaintext: Buffer.alloc(32, 7).toString("base64") }), {
-        status: 200,
-      })) as unknown as typeof globalThis.fetch;
-    console.log = () => {};
-    console.info = () => {};
-    const env = {
-      ...DUMMY_ENV,
-      KUMIKO_DRY_RUN_ENV: "boot",
-      KUMIKO_SECRETS_MASTER_KEY_V1_CIPHERTEXT: "Y2lwaGVy",
-      PLATFORM_KEK_KMS_KEY_ID: "key-1",
-      PLATFORM_KEK_KMS_TOKEN: "token",
-    };
-    try {
-      await expect(
-        runWorkerApp({ features: [encryptedFeature], migrations: false, envSource: env }),
-      ).rejects.toThrow(/no usable master key/);
-
-      const handle = await runWorkerApp({
-        features: [encryptedFeature],
-        migrations: false,
-        envSource: env,
-        kmsSlots: ["KUMIKO_SECRETS_MASTER_KEY_V1"],
-      });
-      await handle.stop();
-    } finally {
-      globalThis.fetch = originalFetch;
-      console.log = originalLog;
-      console.info = originalInfo;
-    }
-  });
-});

package/src/__tests__/run-worker-app.integration.test.ts

@@ -1,218 +0,0 @@
-// runWorkerApp integration: boots the dedicated worker process against
-// real Postgres + Redis. Proves:
-//   - ensureTemporalPolyfill ran BEFORE the job executed (fw#1725: the
-//     bug that cost real time — without the polyfill, every job in the
-//     worker fails with "Temporal is not defined")
-//   - event-triggered jobs run end-to-end (afterCommit → BullMQ → handler)
-//   - the schema-drift gate aborts the boot on pending migrations
-//   - wireComponents gets db/redis/registry/dispatchSystemWrite/lifecycle
-//     and can register its own shutdown hooks
-
-import { afterEach, beforeAll, describe, expect, test } from "bun:test";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { createDbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
-import {
-  createArchivedStreamsTable,
-  createEventsTable,
-} from "@cosmicdrift/kumiko-framework/event-store";
-import {
-  createEventConsumerStateTable,
-  createProjectionStateTable,
-} from "@cosmicdrift/kumiko-framework/pipeline";
-import { unsafeEnsureEntityTable } from "@cosmicdrift/kumiko-framework/stack";
-import { waitFor } from "@cosmicdrift/kumiko-framework/testing";
-import postgres from "postgres";
-import * as z from "zod";
-import { makeDispatchSystemWrite } from "../extra-routes-deps";
-import { runWorkerApp, type WorkerAppHandle } from "../run-worker-app";
-
-const jobRuns: Array<{ note: string; temporalWasDefined: boolean }> = [];
-
-const workerProbeEntity = createEntity({
-  fields: { note: createTextField({ personal: false, reason: "test_fixture", required: true }) },
-  table: "worker_probes",
-});
-
-const workerProbeFeature = defineFeature("worker-probe", (r) => {
-  r.entity("probe", workerProbeEntity);
-  r.writeHandler({
-    name: "ping",
-    schema: z.object({ note: z.string() }),
-    access: { roles: ["SystemAdmin"] },
-    handler: async (event) => ({
-      isSuccess: true as const,
-      data: { note: (event.payload as { note: string }).note },
-    }),
-  });
-  // The job's only purpose: prove Temporal is already defined by the time
-  // the handler runs. Before fw#1725 there was no framework-side boot
-  // path for this — apps had to rebuild the polyfill call by hand
-  // (solon#42) and forgot it.
-  r.job(
-    "record-ping",
-    { trigger: { on: "worker-probe:write:ping" }, runIn: "worker" },
-    async (payload) => {
-      const temporalWasDefined =
-        typeof (globalThis as { Temporal?: unknown }).Temporal === "object";
-      // Touches the global directly — throws "Temporal is not defined" if the
-      // polyfill never ran, which is the exact failure mode fw#1725 reports.
-      Temporal.Now.instant();
-      jobRuns.push({
-        note: (payload as { note: string }).note,
-        temporalWasDefined,
-      });
-    },
-  );
-});
-
-const TENANT_ID = "00000000-0000-4000-8000-000000000002";
-const TEST_DB = `kumiko_runworker_${Date.now().toString(36)}`;
-const ADMIN_URL = process.env["TEST_DATABASE_URL"] ?? "";
-
-const tempDirs: string[] = [];
-let handles: WorkerAppHandle[] = [];
-
-beforeAll(async () => {
-  if (!ADMIN_URL) throw new Error("TEST_DATABASE_URL must be set");
-  const adminClient = postgres(ADMIN_URL.replace(/\/[^/]+$/, "/postgres"));
-  try {
-    await adminClient.unsafe(`CREATE DATABASE "${TEST_DB}"`);
-  } finally {
-    await adminClient.end();
-  }
-  const url = ADMIN_URL.replace(/\/[^/]+$/, `/${TEST_DB}`);
-  const { db, close } = createDbConnection(url);
-  try {
-    await createEventsTable(db);
-    await createArchivedStreamsTable(db);
-    await createProjectionStateTable(db);
-    await createEventConsumerStateTable(db);
-    await unsafeEnsureEntityTable(db, workerProbeEntity, "probe");
-  } finally {
-    await close();
-  }
-});
-
-afterEach(async () => {
-  for (const handle of handles) {
-    await handle.stop();
-  }
-  handles = [];
-  for (const dir of tempDirs) {
-    await rm(dir, { recursive: true, force: true });
-  }
-  tempDirs.length = 0;
-  jobRuns.length = 0;
-});
-
-async function boot(extra?: Partial<Parameters<typeof runWorkerApp>[0]>): Promise<WorkerAppHandle> {
-  const originalDbUrl = process.env["DATABASE_URL"];
-  process.env["DATABASE_URL"] = ADMIN_URL.replace(/\/[^/]+$/, `/${TEST_DB}`);
-  process.env["REDIS_URL"] = process.env["REDIS_URL"] ?? "redis://localhost:16379";
-  process.env["JWT_SECRET"] = "test-runworker-secret-32-chars-min!!";
-  try {
-    const handle = await runWorkerApp({
-      features: [workerProbeFeature],
-      migrations: false,
-      jobs: { queueNamePrefix: `test-worker-${Date.now().toString(36)}` },
-      ...(extra ?? {}),
-    });
-    handles.push(handle);
-    return handle;
-  } finally {
-    if (originalDbUrl !== undefined) process.env["DATABASE_URL"] = originalDbUrl;
-    else delete process.env["DATABASE_URL"];
-  }
-}
-
-async function pollFor<T>(probe: () => T | undefined): Promise<T> {
-  let result: T | undefined;
-  await waitFor(
-    () => {
-      result = probe();
-      return result !== undefined;
-    },
-    { delays: Array(80).fill(100) },
-  );
-  if (result === undefined) throw new Error("pollFor: timeout");
-  return result;
-}
-
-describe("runWorkerApp", () => {
-  test("boots against real Postgres/Redis — mode is worker, dispatcher available", async () => {
-    const handle = await boot();
-    expect(handle.entrypoint.mode).toBe("worker");
-    expect(handle.entrypoint.dispatcher).toBeDefined();
-  });
-
-  test("event-triggered job runs end-to-end with Temporal already defined (fw#1725 regression)", async () => {
-    const handle = await boot();
-    const dispatchSystemWrite = makeDispatchSystemWrite(handle.entrypoint.dispatcher);
-
-    const result = await dispatchSystemWrite({
-      handlerQn: "worker-probe:write:ping",
-      payload: { note: "hello-from-worker" },
-      tenantId: TENANT_ID as import("@cosmicdrift/kumiko-framework/engine").TenantId,
-    });
-    expect(result.isSuccess).toBe(true);
-
-    const run = await pollFor(() => jobRuns.find((r) => r.note === "hello-from-worker"));
-    expect(run.temporalWasDefined).toBe(true);
-  });
-
-  test("wireComponents receives db/redis/registry/dispatchSystemWrite/lifecycle and can register a shutdown hook", async () => {
-    let seenDeps: {
-      db: boolean;
-      redis: boolean;
-      registry: boolean;
-      dispatchSystemWrite: boolean;
-    } | null = null;
-    let shutdownHookRan = false;
-
-    const handle = await boot({
-      wireComponents: async (deps) => {
-        seenDeps = {
-          db: deps.db !== undefined,
-          redis: deps.redis !== undefined,
-          registry: deps.registry.features.has("worker-probe"),
-          dispatchSystemWrite: typeof deps.dispatchSystemWrite === "function",
-        };
-        deps.lifecycle.registerShutdownHook("test-component", async () => {
-          shutdownHookRan = true;
-        });
-      },
-    });
-
-    expect(seenDeps!).toEqual({
-      db: true,
-      redis: true,
-      registry: true,
-      dispatchSystemWrite: true,
-    });
-
-    await handle.stop();
-    handles = handles.filter((h) => h !== handle);
-    expect(shutdownHookRan).toBe(true);
-  });
-
-  test("Schema-Drift-Gate: pending migration aborts the boot before anything else initializes", async () => {
-    const driftDir = await mkdtemp(join(tmpdir(), "kumiko-worker-drift-boot-"));
-    tempDirs.push(driftDir);
-    await writeFile(
-      join(driftDir, "0001_pending.sql"),
-      `CREATE TABLE "worker_never_created_table" ("id" uuid PRIMARY KEY);`,
-    );
-    await writeFile(
-      join(driftDir, ".snapshot.json"),
-      JSON.stringify({
-        version: 1,
-        tables: [{ tableName: "worker_never_created_table", columns: [] }],
-      }),
-    );
-
-    await expect(boot({ migrations: { dir: driftDir } })).rejects.toThrow(/Schema drift detected/);
-  });
-});

package/src/__tests__/security-headers.test.ts

@@ -1,88 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { resolveSecurityHeaders, withSecurityHeaders } from "../security-headers";
-
-const okHandler = (_req: Request) => new Response("ok");
-const req = new Request("http://localhost/");
-
-describe("resolveSecurityHeaders", () => {
-  it("returns the four defaults without csp when unconfigured", () => {
-    const headers = new Map(resolveSecurityHeaders(undefined));
-    expect(headers.get("strict-transport-security")).toBe("max-age=31536000; includeSubDomains");
-    expect(headers.get("x-frame-options")).toBe("DENY");
-    expect(headers.get("x-content-type-options")).toBe("nosniff");
-    expect(headers.get("referrer-policy")).toBe("strict-origin-when-cross-origin");
-    expect(headers.has("content-security-policy")).toBe(false);
-  });
-
-  it("returns nothing when disabled", () => {
-    expect(resolveSecurityHeaders(false)).toEqual([]);
-  });
-
-  it("applies per-header overrides and opt-outs", () => {
-    const headers = new Map(
-      resolveSecurityHeaders({
-        hsts: "max-age=60",
-        frameOptions: false,
-        referrerPolicy: "no-referrer",
-        csp: "default-src 'self'",
-      }),
-    );
-    expect(headers.get("strict-transport-security")).toBe("max-age=60");
-    expect(headers.has("x-frame-options")).toBe(false);
-    expect(headers.get("x-content-type-options")).toBe("nosniff");
-    expect(headers.get("referrer-policy")).toBe("no-referrer");
-    expect(headers.get("content-security-policy")).toBe("default-src 'self'");
-  });
-});
-
-describe("withSecurityHeaders", () => {
-  it("sets defaults on every response", async () => {
-    const res = await withSecurityHeaders(okHandler, undefined)(req);
-    expect(res.headers.get("strict-transport-security")).toBe(
-      "max-age=31536000; includeSubDomains",
-    );
-    expect(res.headers.get("x-frame-options")).toBe("DENY");
-    expect(res.headers.get("x-content-type-options")).toBe("nosniff");
-    expect(res.headers.get("referrer-policy")).toBe("strict-origin-when-cross-origin");
-    expect(await res.text()).toBe("ok");
-  });
-
-  it("returns the handler unwrapped when disabled", () => {
-    expect(withSecurityHeaders(okHandler, false)).toBe(okHandler);
-  });
-
-  it("never overrides a header the response already set", async () => {
-    const handler = (_req: Request) =>
-      new Response("ok", {
-        headers: {
-          "content-security-policy": "default-src 'none'",
-          "x-frame-options": "SAMEORIGIN",
-        },
-      });
-    const res = await withSecurityHeaders(handler, { csp: "default-src 'self'" })(req);
-    expect(res.headers.get("content-security-policy")).toBe("default-src 'none'");
-    expect(res.headers.get("x-frame-options")).toBe("SAMEORIGIN");
-    expect(res.headers.get("x-content-type-options")).toBe("nosniff");
-  });
-
-  it("re-wraps responses with immutable headers", async () => {
-    const immutable = new Response("ok", { status: 201, statusText: "Created" });
-    Object.defineProperty(immutable, "headers", {
-      value: new Proxy(immutable.headers, {
-        get(target, prop) {
-          if (prop === "set") {
-            return () => {
-              throw new TypeError("immutable");
-            };
-          }
-          const value = Reflect.get(target, prop);
-          return typeof value === "function" ? value.bind(target) : value;
-        },
-      }),
-    });
-    const res = await withSecurityHeaders(() => immutable, undefined)(req);
-    expect(res.status).toBe(201);
-    expect(res.headers.get("x-content-type-options")).toBe("nosniff");
-    expect(await res.text()).toBe("ok");
-  });
-});

package/src/__tests__/session-boot-gate.test.ts

@@ -1,70 +0,0 @@
-import { describe, expect, spyOn, test } from "bun:test";
-import { assertSessionBootInvariants } from "../session-boot-gate";
-
-describe("assertSessionBootInvariants (#1372)", () => {
-  test("no auth → no throw", () => {
-    expect(() =>
-      assertSessionBootInvariants({
-        hasAuth: false,
-        sessionStoreProviderMounted: false,
-        mode: "prod",
-      }),
-    ).not.toThrow();
-  });
-
-  test("auth + sessionStore → no throw", () => {
-    expect(() =>
-      assertSessionBootInvariants({
-        hasAuth: true,
-        sessionStoreProviderMounted: true,
-        mode: "prod",
-      }),
-    ).not.toThrow();
-  });
-
-  test("prod: auth without sessionStore → BOOT ABORTED throw", () => {
-    expect(() =>
-      assertSessionBootInvariants({
-        hasAuth: true,
-        sessionStoreProviderMounted: false,
-        mode: "prod",
-      }),
-    ).toThrow(/BOOT ABORTED/);
-  });
-});
-
-// dev/prod split (#2027) — dev-server had no equivalent gate at all before
-// this: a forgotten sessions mount silently left session-list empty with no
-// signal. Mirrors assertPiiBootInvariants' dev/prod split (warn vs abort).
-describe("assertSessionBootInvariants — dev mode (#2027)", () => {
-  test("dev: auth without sessionStore → warns, does NOT throw", () => {
-    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
-    try {
-      expect(() =>
-        assertSessionBootInvariants({
-          hasAuth: true,
-          sessionStoreProviderMounted: false,
-          mode: "dev",
-        }),
-      ).not.toThrow();
-      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("sessionStore"));
-      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("[runDevApp]"));
-    } finally {
-      warnSpy.mockRestore();
-    }
-  });
-
-  test("dev: auth + sessionStore → no throw, no warn", () => {
-    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
-    try {
-      assertSessionBootInvariants({
-        hasAuth: true,
-        sessionStoreProviderMounted: true,
-        mode: "dev",
-      });
-      expect(warnSpy).not.toHaveBeenCalled();
-    } finally {
-      warnSpy.mockRestore();
-    }
-  });
-});

package/src/__tests__/session-wiring.test.ts

@@ -1,16 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { shouldWireProdSessions } from "../session-wiring";
-
-describe("shouldWireProdSessions — secure-by-default (#1372)", () => {
-  it("wires when auth + sessionStore provider mounted", () => {
-    expect(shouldWireProdSessions(true, true)).toBe(true);
-  });
-
-  it("does not wire without auth", () => {
-    expect(shouldWireProdSessions(false, true)).toBe(false);
-  });
-
-  it("does not wire without sessionStore provider", () => {
-    expect(shouldWireProdSessions(true, false)).toBe(false);
-  });
-});

package/src/__tests__/try-hono-first.test.ts

@@ -1,108 +0,0 @@
-// Pure-function pin for tryHonoFirst. Trivial but load-bearing: drift
-// between dev (createKumikoServer) and prod (runProdApp) has already
-// caused a bug before (legal-pages worked in prod but not in dev). Both
-// now use this helper — if the semantics change (e.g. "matched" treating
-// other 4xx differently than 404), both paths MUST update in sync.
-//
-// kumiko-framework#2435: "matched" used to depend ONLY on the status code
-// (404 = no match) — that masked any matched route's deliberate 404 as the
-// SPA shell with status 200. The contract now: a router-miss is ONLY a 404
-// that ADDITIONALLY carries NO_ROUTE_MATCH_HEADER_NAME (set by buildServer's
-// app.notFound(), see framework/api/server.ts). A plain 404 without the
-// marker counts as matched — the route answered deliberately.
-
-import { describe, expect, test } from "bun:test";
-import { NO_ROUTE_MATCH_HEADER_NAME } from "@cosmicdrift/kumiko-framework/api";
-import { type HonoLikeApp, stripNoRouteMatchHeader, tryHonoFirst } from "../try-hono-first";
-
-function makeApp(response: Response): HonoLikeApp {
-  return { fetch: () => response };
-}
-
-function makeAsyncApp(response: Response): HonoLikeApp {
-  return { fetch: async () => response };
-}
-
-function routerMissResponse(): Response {
-  return new Response("Not Found", {
-    status: 404,
-    headers: { [NO_ROUTE_MATCH_HEADER_NAME]: "1" },
-  });
-}
-
-describe("tryHonoFirst", () => {
-  test("matched=true on 200 (a Hono route handled it)", async () => {
-    const app = makeApp(new Response("ok", { status: 200 }));
-    const res = await tryHonoFirst(app, new Request("http://test/foo"));
-    expect(res.matched).toBe(true);
-    expect(res.response.status).toBe(200);
-  });
-
-  test("matched=false on a router-miss (404 + NO_ROUTE_MATCH_HEADER_NAME — caller falls back to the SPA)", async () => {
-    const app = makeApp(routerMissResponse());
-    const res = await tryHonoFirst(app, new Request("http://test/unknown"));
-    expect(res.matched).toBe(false);
-    // response is still returned — caller can use the 404 as a last-resort
-    // safety net if the SPA fallback doesn't deliver anything either.
-    expect(res.response.status).toBe(404);
-  });
-
-  test("matched=true for a matched route that deliberately answers 404 (no marker — bug #2435)", async () => {
-    // The actual bug: file-derivatives' public-variant route matches and
-    // answers `c.text("not found", 404)` for default-deny — NOT a
-    // router-miss. Without the marker header this used to be
-    // misinterpreted as "no match" and the caller would have served the
-    // SPA shell with status 200 instead of passing the real 404 through.
-    const app = makeApp(new Response("not found", { status: 404 }));
-    const res = await tryHonoFirst(app, new Request("http://test/files/x/thumb"));
-    expect(res.matched).toBe(true);
-    expect(res.response.status).toBe(404);
-  });
-
-  test("matched=true on 401/403/500 (Hono answered — no SPA fallback)", async () => {
-    // Bug pin: matched may ONLY be false on a router-miss. When Hono
-    // returns 401 (auth required), the route was clearly found and
-    // deliberately rejected — an SPA fallback would override that and
-    // redirect the user into the SPA instead of showing the 401 message.
-    for (const status of [401, 403, 422, 500] as const) {
-      const app = makeApp(new Response(null, { status }));
-      const res = await tryHonoFirst(app, new Request("http://test/x"));
-      expect(res.matched, `status ${status} should be matched`).toBe(true);
-    }
-  });
-
-  test("accepts both sync and async fetch (Hono variation)", async () => {
-    // Hono.app.fetch returns Response | Promise<Response> depending on the
-    // handler mix. createApiEntrypoint's apiHandler does the same. The
-    // helper must accept both.
-    const sync = await tryHonoFirst(
-      makeApp(new Response("s", { status: 200 })),
-      new Request("http://t/"),
-    );
-    const asyncRes = await tryHonoFirst(
-      makeAsyncApp(new Response("a", { status: 200 })),
-      new Request("http://t/"),
-    );
-    expect(sync.matched).toBe(true);
-    expect(asyncRes.matched).toBe(true);
-  });
-
-  test("strips NO_ROUTE_MATCH_HEADER_NAME from the returned response (never leaks to the client)", async () => {
-    const app = makeApp(routerMissResponse());
-    const res = await tryHonoFirst(app, new Request("http://test/unknown"));
-    expect(res.response.headers.has(NO_ROUTE_MATCH_HEADER_NAME)).toBe(false);
-  });
-});
-
-describe("stripNoRouteMatchHeader", () => {
-  test("removes the header when present", () => {
-    const res = stripNoRouteMatchHeader(routerMissResponse());
-    expect(res.headers.has(NO_ROUTE_MATCH_HEADER_NAME)).toBe(false);
-  });
-
-  test("is a no-op when the header is absent", () => {
-    const res = stripNoRouteMatchHeader(new Response("ok", { status: 200 }));
-    expect(res.status).toBe(200);
-    expect(res.headers.has(NO_ROUTE_MATCH_HEADER_NAME)).toBe(false);
-  });
-});