@mandujs/core 0.21.0 → 0.22.1

package/src/resource/schema.ts

@@ -71,6 +71,36 @@ export interface ResourceOptions {
     defaultLimit?: number;
     maxLimit?: number;
   };
+  /**
+   * Opt-in DB persistence config (Phase 4c).
+   *
+   * When set, the resource generator emits an additional `<name>.repo.ts`
+   * artifact with typed CRUD backed by `@mandujs/core/db`, and the schema
+   * pipeline (`mandu db plan` / `computeSchemaGeneration`) includes this
+   * resource in migrations.
+   *
+   * The concrete shape lives in
+   * `@mandujs/core/resource/ddl/persistence-types` — imported lazily to
+   * keep `ResourceOptions` usable on runtimes without the DDL subsystem.
+   * Non-persistent resources simply omit this field (existing behavior).
+   *
+   * @example
+   * ```ts
+   * defineResource({
+   *   name: "post",
+   *   fields: { ... },
+   *   options: {
+   *     persistence: {
+   *       provider: "sqlite",
+   *       primaryKey: "id",
+   *       indexes: [{ name: "posts_user_idx", fields: ["userId"], unique: false }],
+   *       fieldOverrides: { id: { primary: true }, userId: { indexed: true } },
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  persistence?: import("./ddl/persistence-types").ExtendedResourcePersistence;
 }
 
 // ============================================

package/src/router/fs-scanner.ts

@@ -27,6 +27,7 @@ import {
   sortRoutesByPriority,
   getPatternShape,
 } from "./fs-patterns";
+import { mark, measure } from "../perf";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Scanner Class
@@ -55,6 +56,7 @@ export class FSScanner {
    * @returns 스캔 결과
    */
   async scan(rootDir: string): Promise<ScanResult> {
+    mark("router:scan");
     const startTime = Date.now();
     const routesDir = join(rootDir, this.config.routesDir);
 
@@ -87,6 +89,7 @@ export class FSScanner {
     // 통계 계산
     const stats = this.calculateStats(files, routes, Date.now() - startTime);
 
+    measure("router:scan", "router:scan");
     return {
       files,
       routes: sortRoutesByPriority(routes),

package/src/runtime/__tests__/error-boundary-redaction.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Phase 6.3: error-boundary stack redaction tests.
+ *
+ * Verifies the contract enforced by `redactErrorForBoundary()` in
+ * runtime/server.ts — user-land `error.tsx` receives full fidelity in
+ * dev and a trimmed view in prod, with a stable `digest` correlating
+ * the two. This is the defensive layer that keeps server-side stack
+ * frames from reaching the browser.
+ */
+
+import { describe, it, expect } from "bun:test";
+import {
+  redactErrorForBoundary,
+  computeErrorDigest,
+} from "../server";
+
+function buildFakeError(): Error {
+  // Build an error with a long, predictable stack so we can assert on frame
+  // count. The Node stack format starts with `Error: msg\n    at foo (...)`.
+  const e = new Error("boom");
+  e.stack = [
+    "Error: boom",
+    "    at level0 (/proj/src/a.ts:10:5)",
+    "    at level1 (/proj/src/a.ts:20:5)",
+    "    at level2 (/proj/src/b.ts:30:5)",
+    "    at level3 (/proj/src/b.ts:40:5)",
+    "    at level4 (/proj/src/c.ts:50:5)",
+    "    at level5 (/proj/src/c.ts:60:5)",
+  ].join("\n");
+  return e;
+}
+
+describe("redactErrorForBoundary() — dev mode (isDev=true)", () => {
+  it("returns the original Error unchanged", () => {
+    const original = buildFakeError();
+    const { error } = redactErrorForBoundary(original, true);
+    expect(error).toBe(original);
+    // Full stack preserved.
+    expect(error.stack).toContain("level5");
+  });
+
+  it("still produces a digest in dev", () => {
+    const original = buildFakeError();
+    const { digest } = redactErrorForBoundary(original, true);
+    expect(typeof digest).toBe("string");
+    expect(digest.length).toBe(8);
+  });
+});
+
+describe("redactErrorForBoundary() — prod mode (isDev=false)", () => {
+  it("returns a clone with preserved message", () => {
+    const original = buildFakeError();
+    const { error } = redactErrorForBoundary(original, false);
+    expect(error).not.toBe(original);
+    expect(error.message).toBe("boom");
+    expect(error.name).toBe("Error");
+  });
+
+  it("trims stack to header + top 3 frames", () => {
+    const original = buildFakeError();
+    const { error } = redactErrorForBoundary(original, false);
+    expect(typeof error.stack).toBe("string");
+    const lines = error.stack!.split("\n");
+    // Header + 3 frames = 4 lines.
+    expect(lines).toHaveLength(4);
+    expect(lines[0]).toBe("Error: boom");
+    expect(lines[1]).toContain("level0");
+    expect(lines[2]).toContain("level1");
+    expect(lines[3]).toContain("level2");
+    // Deeper frames are gone.
+    expect(error.stack).not.toContain("level3");
+    expect(error.stack).not.toContain("level4");
+    expect(error.stack).not.toContain("level5");
+  });
+
+  it("preserves .name on custom Error subclasses", () => {
+    class MyError extends Error {}
+    const custom = new MyError("hmm");
+    custom.name = "MyError";
+    const { error } = redactErrorForBoundary(custom, false);
+    expect(error.name).toBe("MyError");
+    expect(error.message).toBe("hmm");
+  });
+
+  it("handles errors with no stack gracefully", () => {
+    const noStack = new Error("bare");
+    noStack.stack = undefined;
+    const { error, digest } = redactErrorForBoundary(noStack, false);
+    expect(error.message).toBe("bare");
+    expect(error.stack).toBeUndefined();
+    expect(digest.length).toBe(8);
+  });
+});
+
+describe("computeErrorDigest()", () => {
+  it("produces the same digest for structurally identical errors", () => {
+    const a = new Error("same");
+    a.stack = "Error: same\n    at foo (/x:1:1)";
+    const b = new Error("same");
+    b.stack = "Error: same\n    at foo (/x:1:1)";
+    expect(computeErrorDigest(a)).toBe(computeErrorDigest(b));
+  });
+
+  it("produces a different digest when the message changes", () => {
+    const a = new Error("a");
+    a.stack = "Error: a\n    at foo (/x:1:1)";
+    const b = new Error("b");
+    b.stack = "Error: b\n    at foo (/x:1:1)";
+    expect(computeErrorDigest(a)).not.toBe(computeErrorDigest(b));
+  });
+
+  it("produces a different digest when the top frame changes", () => {
+    const a = new Error("same");
+    a.stack = "Error: same\n    at foo (/x:1:1)";
+    const b = new Error("same");
+    b.stack = "Error: same\n    at bar (/x:1:1)";
+    expect(computeErrorDigest(a)).not.toBe(computeErrorDigest(b));
+  });
+
+  it("returns an 8-char hex string", () => {
+    const d = computeErrorDigest(new Error("any"));
+    expect(d).toMatch(/^[0-9a-f]{8}$/);
+  });
+
+  it("handles Error with empty stack", () => {
+    const e = new Error("");
+    e.stack = "";
+    expect(computeErrorDigest(e)).toMatch(/^[0-9a-f]{8}$/);
+  });
+});
+
+describe("redactErrorForBoundary() ↔ computeErrorDigest() contract", () => {
+  it("dev digest equals prod digest for the same original error", () => {
+    // The digest must survive the redaction — same underlying event on
+    // client (redacted) and server logs (full) must be joinable.
+    const original = buildFakeError();
+    const dev = redactErrorForBoundary(original, true);
+    const prod = redactErrorForBoundary(original, false);
+    expect(dev.digest).toBe(prod.digest);
+  });
+});

package/src/runtime/__tests__/hdr-client.test.ts

@@ -0,0 +1,223 @@
+/**
+ * Phase 7.2 R1 Agent B — HDR client-side runtime tests.
+ *
+ * Coverage (pure unit — no DOM, no real WebSocket):
+ *   1. dispatchSlotRefetch returns false when no transport is
+ *      installed (the default "no-router" fallback).
+ *   2. setHDRTransport + dispatchSlotRefetch returns the transport's
+ *      `ok` flag so the caller can decide fallback vs. done.
+ *   3. A throwing transport never propagates; dispatchSlotRefetch
+ *      swallows + returns false so the HMR client stays alive.
+ *   4. Transport is isolated per test via _resetRegistryForTests().
+ *   5. HDRPayload shape round-trips through the transport (routeId,
+ *      slotPath, rebuildId, timestamp all preserved — no field is
+ *      silently dropped).
+ *
+ * References:
+ *   docs/bun/phase-7-2-team-plan.md §3 Agent B
+ *   packages/core/src/runtime/hmr-client.ts — setHDRTransport,
+ *     dispatchSlotRefetch, _resetRegistryForTests
+ */
+
+import { beforeEach, describe, expect, test } from "bun:test";
+import {
+  setHDRTransport,
+  dispatchSlotRefetch,
+  _resetRegistryForTests,
+} from "../hmr-client";
+import type { HDRPayload } from "../../bundler/hmr-types";
+
+describe("Phase 7.2 Agent B — dispatchSlotRefetch", () => {
+  beforeEach(() => {
+    _resetRegistryForTests();
+  });
+
+  test("[1] returns false when no transport is installed (default fallback)", async () => {
+    const payload: HDRPayload = {
+      type: "slot-refetch",
+      routeId: "home",
+      slotPath: "app/page.slot.ts",
+      rebuildId: 1,
+      timestamp: Date.now(),
+    };
+    const ok = await dispatchSlotRefetch(payload);
+    expect(ok).toBe(false);
+  });
+
+  test("[2] returns true when the installed transport resolves ok:true", async () => {
+    const received: HDRPayload[] = [];
+    setHDRTransport(async (p) => {
+      received.push(p);
+      return { ok: true };
+    });
+    const payload: HDRPayload = {
+      type: "slot-refetch",
+      routeId: "dashboard",
+      slotPath: "app/dashboard/page.slot.ts",
+      rebuildId: 7,
+      timestamp: 1234567890,
+    };
+    const ok = await dispatchSlotRefetch(payload);
+    expect(ok).toBe(true);
+    // Full payload passed through unchanged.
+    expect(received.length).toBe(1);
+    expect(received[0]).toEqual(payload);
+  });
+
+  test("[3] transport that throws does NOT propagate — dispatchSlotRefetch returns false", async () => {
+    setHDRTransport(async () => {
+      throw new Error("transport kaboom");
+    });
+    const payload: HDRPayload = {
+      type: "slot-refetch",
+      routeId: "home",
+      slotPath: "app/page.slot.ts",
+      rebuildId: 1,
+      timestamp: Date.now(),
+    };
+    // Must NOT reject. A thrown error in the transport is logged and
+    // the caller sees `false` so it can fall back to a full reload.
+    const ok = await dispatchSlotRefetch(payload);
+    expect(ok).toBe(false);
+  });
+
+  test("[4] transport resolves ok:false with reason — dispatch returns false", async () => {
+    setHDRTransport(async () => ({ ok: false, reason: "no-route" as const }));
+    const payload: HDRPayload = {
+      type: "slot-refetch",
+      routeId: "home",
+      slotPath: "app/page.slot.ts",
+      rebuildId: 1,
+      timestamp: Date.now(),
+    };
+    const ok = await dispatchSlotRefetch(payload);
+    expect(ok).toBe(false);
+  });
+
+  test("[5] _resetRegistryForTests restores default (no-transport) behavior", async () => {
+    setHDRTransport(async () => ({ ok: true }));
+    _resetRegistryForTests();
+    const payload: HDRPayload = {
+      type: "slot-refetch",
+      routeId: "home",
+      slotPath: "app/page.slot.ts",
+      rebuildId: 1,
+      timestamp: Date.now(),
+    };
+    const ok = await dispatchSlotRefetch(payload);
+    // After reset the default "no-router" transport is back.
+    expect(ok).toBe(false);
+  });
+
+  test("[6] two sequential dispatches with different payloads deliver each to transport", async () => {
+    const received: HDRPayload[] = [];
+    setHDRTransport(async (p) => {
+      received.push(p);
+      return { ok: true };
+    });
+    const a: HDRPayload = {
+      type: "slot-refetch",
+      routeId: "home",
+      slotPath: "app/page.slot.ts",
+      rebuildId: 1,
+      timestamp: 100,
+    };
+    const b: HDRPayload = {
+      type: "slot-refetch",
+      routeId: "dashboard",
+      slotPath: "app/dashboard/page.slot.ts",
+      rebuildId: 2,
+      timestamp: 200,
+    };
+    await dispatchSlotRefetch(a);
+    await dispatchSlotRefetch(b);
+    expect(received.length).toBe(2);
+    expect(received[0]!.routeId).toBe("home");
+    expect(received[1]!.routeId).toBe("dashboard");
+    expect(received[1]!.rebuildId).toBe(2);
+  });
+
+  test("[7] transport may observe the full HDRPayload — no fields lost", async () => {
+    const captured: HDRPayload[] = [];
+    setHDRTransport(async (p) => {
+      captured.push(p);
+      return { ok: true };
+    });
+    const payload: HDRPayload = {
+      type: "slot-refetch",
+      routeId: "nested-route-abc123",
+      slotPath: "app/deeply/nested/page.slot.ts",
+      rebuildId: 9999,
+      timestamp: 1_700_000_000_000,
+    };
+    await dispatchSlotRefetch(payload);
+    expect(captured.length).toBe(1);
+    const first = captured[0]!;
+    expect(first.type).toBe("slot-refetch");
+    expect(first.routeId).toBe(payload.routeId);
+    expect(first.slotPath).toBe(payload.slotPath);
+    expect(first.rebuildId).toBe(payload.rebuildId);
+    expect(first.timestamp).toBe(payload.timestamp);
+  });
+
+  test("[8] latest setHDRTransport wins (idempotent setter semantics)", async () => {
+    let firstCalled = 0;
+    let secondCalled = 0;
+    setHDRTransport(async () => {
+      firstCalled++;
+      return { ok: false, reason: "disabled" as const };
+    });
+    setHDRTransport(async () => {
+      secondCalled++;
+      return { ok: true };
+    });
+    const payload: HDRPayload = {
+      type: "slot-refetch",
+      routeId: "home",
+      slotPath: "app/page.slot.ts",
+      rebuildId: 1,
+      timestamp: Date.now(),
+    };
+    const ok = await dispatchSlotRefetch(payload);
+    expect(firstCalled).toBe(0);
+    expect(secondCalled).toBe(1);
+    expect(ok).toBe(true);
+  });
+
+  test("[9] transport that resolves with 'fetch-failed' reason — dispatch returns false", async () => {
+    setHDRTransport(async () => ({
+      ok: false,
+      reason: "fetch-failed" as const,
+    }));
+    const payload: HDRPayload = {
+      type: "slot-refetch",
+      routeId: "home",
+      slotPath: "app/page.slot.ts",
+      rebuildId: 1,
+      timestamp: Date.now(),
+    };
+    const ok = await dispatchSlotRefetch(payload);
+    expect(ok).toBe(false);
+  });
+
+  test("[10] HDRPayload slotPath with Windows backslashes is preserved verbatim", async () => {
+    // The helper does no normalization on the browser side — the
+    // server ships whatever string it put in the payload. Lock that
+    // contract so future changes don't introduce silent mutation.
+    const captured: HDRPayload[] = [];
+    setHDRTransport(async (p) => {
+      captured.push(p);
+      return { ok: true };
+    });
+    const payload: HDRPayload = {
+      type: "slot-refetch",
+      routeId: "home",
+      slotPath: "C:\\proj\\app\\page.slot.ts",
+      rebuildId: 1,
+      timestamp: Date.now(),
+    };
+    await dispatchSlotRefetch(payload);
+    expect(captured.length).toBe(1);
+    expect(captured[0]!.slotPath).toBe("C:\\proj\\app\\page.slot.ts");
+  });
+});

package/src/runtime/__tests__/http-errors.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Unit tests for the module-level HTTP error helpers (Phase 6.3).
+ *
+ * Companion to the ctx.unauthorized() / ctx.forbidden() / ctx.error()
+ * methods on ManduContext — those live in filling/context.ts. These
+ * standalone helpers must match ctx behavior for body shape while also
+ * covering the header-merging contract (WWW-Authenticate, custom headers).
+ */
+
+import { describe, it, expect } from "bun:test";
+import { unauthorized, forbidden, badRequest } from "../http-errors";
+
+async function readJson(res: Response): Promise<unknown> {
+  const clone = res.clone();
+  const text = await clone.text();
+  return text.length > 0 ? JSON.parse(text) : null;
+}
+
+describe("unauthorized()", () => {
+  it("returns 401 with the default WWW-Authenticate: Bearer header", async () => {
+    const res = unauthorized();
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate")).toBe("Bearer");
+    expect(await readJson(res)).toEqual({ error: "Unauthorized" });
+  });
+
+  it("includes the caller-provided message in the JSON body", async () => {
+    const res = unauthorized("login required");
+    expect(res.status).toBe(401);
+    expect(await readJson(res)).toEqual({ error: "login required" });
+  });
+
+  it("merges custom headers alongside WWW-Authenticate", async () => {
+    const res = unauthorized(undefined, { headers: { "x-custom": "1" } });
+    expect(res.status).toBe(401);
+    expect(res.headers.get("x-custom")).toBe("1");
+    expect(res.headers.get("WWW-Authenticate")).toBe("Bearer");
+    expect(res.headers.get("Content-Type")).toContain("application/json");
+  });
+
+  it("lets callers override WWW-Authenticate (e.g. Basic realm)", () => {
+    const res = unauthorized("Token expired", {
+      headers: { "WWW-Authenticate": 'Basic realm="app"' },
+    });
+    expect(res.headers.get("WWW-Authenticate")).toBe('Basic realm="app"');
+  });
+});
+
+describe("forbidden()", () => {
+  it("returns 403 with the default JSON body", async () => {
+    const res = forbidden();
+    expect(res.status).toBe(403);
+    expect(await readJson(res)).toEqual({ error: "Forbidden" });
+    expect(res.headers.get("Content-Type")).toContain("application/json");
+  });
+
+  it("carries the provided message", async () => {
+    const res = forbidden("role mismatch");
+    expect(res.status).toBe(403);
+    expect(await readJson(res)).toEqual({ error: "role mismatch" });
+  });
+
+  it("merges custom response headers", () => {
+    const res = forbidden("no", { headers: { "x-trace": "abc" } });
+    expect(res.headers.get("x-trace")).toBe("abc");
+    expect(res.status).toBe(403);
+  });
+});
+
+describe("badRequest()", () => {
+  it("string input produces { error: <string> }", async () => {
+    const res = badRequest("string-only");
+    expect(res.status).toBe(400);
+    expect(await readJson(res)).toEqual({ error: "string-only" });
+  });
+
+  it("object input with message + errors produces { error, errors }", async () => {
+    const res = badRequest({
+      message: "invalid",
+      errors: { email: ["required"] },
+    });
+    expect(res.status).toBe(400);
+    expect(await readJson(res)).toEqual({
+      error: "invalid",
+      errors: { email: ["required"] },
+    });
+  });
+
+  it("object input without errors omits the key (no `errors: undefined` leak)", async () => {
+    const res = badRequest({ message: "simple" });
+    const body = (await readJson(res)) as Record<string, unknown>;
+    expect(body).toEqual({ error: "simple" });
+    // Explicit: `errors` key must not appear at all — users pattern-match on presence.
+    expect(Object.prototype.hasOwnProperty.call(body, "errors")).toBe(false);
+  });
+
+  it("no-args call defaults to 'Bad Request'", async () => {
+    const res = badRequest();
+    expect(res.status).toBe(400);
+    expect(await readJson(res)).toEqual({ error: "Bad Request" });
+  });
+
+  it("merges custom headers on both string and object inputs", () => {
+    const resA = badRequest("x", { headers: { "x-a": "1" } });
+    expect(resA.headers.get("x-a")).toBe("1");
+
+    const resB = badRequest({ message: "y" }, { headers: { "x-b": "2" } });
+    expect(resB.headers.get("x-b")).toBe("2");
+  });
+
+  it("response content-type is application/json; charset=utf-8", () => {
+    const res = badRequest("z");
+    const ct = res.headers.get("Content-Type") ?? "";
+    expect(ct).toContain("application/json");
+    expect(ct).toContain("charset=utf-8");
+  });
+});

package/src/runtime/__tests__/not-found.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Unit tests for `notFound()` / `isNotFoundResponse()` (Phase 6.3).
+ *
+ * Mirrors the shape of the redirect() tests (see packages/core/tests/server/
+ * redirect-loader.test.ts). These stay local to the helper — integration
+ * coverage that exercises the full SSR pipeline lives in the server test
+ * at packages/core/tests/server/not-found-page.test.ts.
+ */
+
+import { describe, it, expect } from "bun:test";
+import {
+  notFound,
+  isNotFoundResponse,
+  NOT_FOUND_BRAND,
+} from "../not-found";
+import { redirect } from "../redirect";
+import { ManduFilling } from "../../filling/filling";
+import { ManduContext } from "../../filling/context";
+
+describe("notFound()", () => {
+  it("returns a Response with status 404", () => {
+    const res = notFound();
+    expect(res).toBeInstanceOf(Response);
+    expect(res.status).toBe(404);
+  });
+
+  it("carries the provided message in its body", async () => {
+    const res = notFound({ message: "Post not found" });
+    const body = await res.text();
+    expect(body).toBe("Post not found");
+  });
+
+  it("is recognized by isNotFoundResponse()", () => {
+    expect(isNotFoundResponse(notFound())).toBe(true);
+    expect(isNotFoundResponse(notFound({ message: "x" }))).toBe(true);
+  });
+
+  it("rejects a bare `new Response(null, { status: 404 })` (brand check)", () => {
+    const bare = new Response(null, { status: 404 });
+    expect(isNotFoundResponse(bare)).toBe(false);
+    // Double-check: something we know is 404 but not ours (e.g. upstream proxy)
+    const proxied = new Response("upstream 404", {
+      status: 404,
+      headers: { "Content-Type": "text/plain" },
+    });
+    expect(isNotFoundResponse(proxied)).toBe(false);
+  });
+
+  it("rejects a redirect() Response (notFound is a distinct brand)", () => {
+    expect(isNotFoundResponse(redirect("/foo"))).toBe(false);
+  });
+
+  it("rejects null / undefined / {} / primitives (type guard is strict)", () => {
+    expect(isNotFoundResponse(null)).toBe(false);
+    expect(isNotFoundResponse(undefined)).toBe(false);
+    expect(isNotFoundResponse({})).toBe(false);
+    expect(isNotFoundResponse("string")).toBe(false);
+    expect(isNotFoundResponse(404)).toBe(false);
+    expect(isNotFoundResponse(new Error("not a response"))).toBe(false);
+  });
+
+  it("status is always 404 regardless of the message", () => {
+    expect(notFound().status).toBe(404);
+    expect(notFound({ message: "a" }).status).toBe(404);
+    expect(notFound({ message: "" }).status).toBe(404); // empty still 404
+    expect(notFound({ message: "x".repeat(1000) }).status).toBe(404);
+  });
+
+  it("body is text/plain (not JSON) — explicit content-type contract", async () => {
+    const res = notFound({ message: "missing" });
+    const ct = res.headers.get("content-type") ?? "";
+    expect(ct).toContain("text/plain");
+    expect(ct).toContain("charset=utf-8");
+    // Body must be the literal message, not a JSON envelope.
+    expect(await res.text()).toBe("missing");
+  });
+
+  it("default body (no args) is the literal 'Not Found'", async () => {
+    const res = notFound();
+    expect(await res.text()).toBe("Not Found");
+  });
+
+  it("loader returning notFound() is picked up by isNotFoundResponse", async () => {
+    const filling = new ManduFilling();
+    filling.loader(() => notFound({ message: "post gone" }));
+
+    const ctx = new ManduContext(new Request("http://test/post/1"), { id: "1" });
+    const returned = await filling.executeLoader(ctx);
+    expect(isNotFoundResponse(returned)).toBe(true);
+    // And the body survived.
+    const body = await (returned as Response).text();
+    expect(body).toBe("post gone");
+  });
+
+  it("loader throwing notFound() is picked up the same way (Remix idiom)", async () => {
+    const filling = new ManduFilling();
+    filling.loader(() => {
+      throw notFound({ message: "thrown" });
+    });
+
+    const ctx = new ManduContext(new Request("http://test/x"), {});
+    let caught: unknown = null;
+    try {
+      await filling.executeLoader(ctx);
+    } catch (e) {
+      caught = e;
+    }
+    expect(isNotFoundResponse(caught)).toBe(true);
+    expect(await (caught as Response).text()).toBe("thrown");
+  });
+
+  it("integration simulation: loadPageData-like branch distinguishes return vs throw", async () => {
+    // Emulates the exact shape of the SSR pipeline's try/catch: `returned`
+    // and `thrown` both route through `isNotFoundResponse`. This is the
+    // contract the server integration relies on.
+    const returnCase = notFound({ message: "A" });
+    const throwCase = notFound({ message: "B" });
+
+    // Both must be recognised.
+    expect(isNotFoundResponse(returnCase)).toBe(true);
+    expect(isNotFoundResponse(throwCase)).toBe(true);
+
+    // And each preserves its own message (no shared mutable state).
+    expect(await returnCase.text()).toBe("A");
+    expect(await throwCase.text()).toBe("B");
+  });
+
+  it("accepts a call with no arguments and still produces a valid sentinel", () => {
+    const res = notFound();
+    expect(res).toBeInstanceOf(Response);
+    expect(res.status).toBe(404);
+    expect(isNotFoundResponse(res)).toBe(true);
+  });
+
+  it("exports NOT_FOUND_BRAND as a unique symbol keyed to the package", () => {
+    // The brand must be a Symbol.for() so multiple copies of @mandujs/core
+    // (e.g. monorepo duplication) agree on identity. If this changes we've
+    // broken cross-package detection — regression guard.
+    expect(typeof NOT_FOUND_BRAND).toBe("symbol");
+    expect(Symbol.keyFor(NOT_FOUND_BRAND)).toBe("@mandujs/core/not-found");
+  });
+
+  it("two separate notFound() calls produce independently-branded Responses", () => {
+    // WeakSet membership is per-instance — the brand on one must not
+    // leak to another. Important for test isolation.
+    const a = notFound();
+    const b = notFound();
+    expect(a).not.toBe(b);
+    expect(isNotFoundResponse(a)).toBe(true);
+    expect(isNotFoundResponse(b)).toBe(true);
+  });
+});