ruact 0.0.4 → 0.0.6

data/vendor/javascript/ruact-server-functions-runtime/index.test.mjs

@@ -1,12 +1,14 @@
-// Story 8.1 — vitest suite for the real server-functions runtime.
+// Vitest suite for the route-driven server-functions runtime.
 //
-// Covers AC10 of Story 8.1: argument-shape branching (JSON vs FormData),
-// CSRF meta-tag injection, success vs. failure response handling, and
-// error wrapping. Uses `vi.fn()` to stub `fetch` — no real network.
+// Covers the shared mutation fetch core via `_makeServerFunction`: argument-
+// shape branching (JSON vs FormData), CSRF meta-tag injection, success vs.
+// failure response handling, error wrapping, and the useActionState two-arg
+// shape. Uses `vi.fn()` to stub `fetch` — no real network. Story 9.9 demolished
+// the v1 `_makeRef` accessor; these tests now exercise the same core through the
+// route-driven accessor (which `_makeRef` used to share verbatim).
 
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import {
-  _makeRef,
   _makeServerFunction,
   __RUNTIME_VERSION__,
   __internals,
@@ -15,6 +17,13 @@ import {
   revalidate,
 } from "./index.js";
 
+// Helper — a route-driven accessor targeting `POST /posts` (the canonical
+// mutation shape). The shared fetch core is identical regardless of verb/path,
+// so this stands in for the demolished `_makeRef("name")` in the core tests.
+function makePostFn() {
+  return _makeServerFunction({ method: "POST", path: "/posts", segments: [] });
+}
+
 let originalFetch;
 let originalDocument;
 
@@ -67,27 +76,27 @@ function mockMetaTag(token) {
   };
 }
 
-describe("Story 8.1 — _makeRef", () => {
+describe("runtime — accessor basics", () => {
   it("exports the runtime-version sentinel (placeholder __PLACEHOLDER__ is gone)", () => {
     expect(__RUNTIME_VERSION__).toBe(1);
   });
 
   it("returns a callable accessor", () => {
-    const ref = _makeRef("create_post");
+    const ref = makePostFn();
     expect(typeof ref).toBe("function");
   });
 });
 
-describe("Story 8.1 — JSON body branch", () => {
-  it("POSTs JSON.stringify(args) with Content-Type: application/json", async () => {
+describe("mutation core — JSON body branch", () => {
+  it("sends JSON.stringify(args) with Content-Type: application/json over the real path+verb", async () => {
     mockFetchOk({ ok: true });
     mockMetaTag(null);
 
-    await _makeRef("create_post")({ title: "Hi" });
+    await makePostFn()({ title: "Hi" });
 
     expect(globalThis.fetch).toHaveBeenCalledTimes(1);
     const [url, init] = globalThis.fetch.mock.calls[0];
-    expect(url).toBe("/__ruact/fn/create_post");
+    expect(url).toBe("/posts");
     expect(init.method).toBe("POST");
     expect(init.credentials).toBe("same-origin");
     expect(init.headers["Content-Type"]).toBe("application/json");
@@ -97,7 +106,7 @@ describe("Story 8.1 — JSON body branch", () => {
   it("treats undefined args as an empty JSON object {}", async () => {
     mockFetchOk({});
     mockMetaTag(null);
-    await _makeRef("categories")();
+    await makePostFn()();
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.body).toBe("{}");
@@ -106,7 +115,7 @@ describe("Story 8.1 — JSON body branch", () => {
   it("treats null args as an empty JSON object {}", async () => {
     mockFetchOk({});
     mockMetaTag(null);
-    await _makeRef("categories")(null);
+    await makePostFn()(null);
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.body).toBe("{}");
@@ -115,14 +124,14 @@ describe("Story 8.1 — JSON body branch", () => {
   it("resolves with parsed JSON for application/json responses", async () => {
     mockFetchOk({ id: 7 });
     mockMetaTag(null);
-    const result = await _makeRef("create_post")({ title: "x" });
+    const result = await makePostFn()({ title: "x" });
     expect(result).toEqual({ id: 7 });
   });
 
   it("attaches Accept: application/json header (re-run-2 #8 — host respond_to branching)", async () => {
     mockFetchOk({});
     mockMetaTag(null);
-    await _makeRef("create_post")({});
+    await makePostFn()({});
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.headers.Accept).toBe("application/json");
   });
@@ -138,7 +147,7 @@ describe("Story 8.1 — JSON body branch", () => {
     globalThis.fetch = vi.fn().mockResolvedValue(r);
     mockMetaTag(null);
 
-    const result = await _makeRef("ping")({});
+    const result = await makePostFn()({});
     expect(result).toBe("hello");
     expect(r.text).toHaveBeenCalled();
     expect(r.json).not.toHaveBeenCalled();
@@ -156,7 +165,7 @@ describe("Story 8.1 — JSON body branch", () => {
     globalThis.fetch = vi.fn().mockResolvedValue(r);
     mockMetaTag(null);
 
-    const result = await _makeRef("noop")({});
+    const result = await makePostFn()({});
     expect(result).toBeNull();
     expect(r.json).not.toHaveBeenCalled();
   });
@@ -172,7 +181,7 @@ describe("Story 8.1 — JSON body branch", () => {
     globalThis.fetch = vi.fn().mockResolvedValue(r);
     mockMetaTag(null);
 
-    const result = await _makeRef("noop")({});
+    const result = await makePostFn()({});
     expect(result).toBeNull();
   });
 
@@ -190,21 +199,21 @@ describe("Story 8.1 — JSON body branch", () => {
     globalThis.fetch = vi.fn().mockResolvedValue(r);
     mockMetaTag(null);
 
-    const result = await _makeRef("noop")({});
+    const result = await makePostFn()({});
     expect(result).toBeNull();
     expect(r.json).not.toHaveBeenCalled();
   });
 });
 
-describe("Story 8.1 — FormData branch", () => {
-  it("POSTs the FormData as-is with NO manual Content-Type header (browser sets boundary)", async () => {
+describe("mutation core — FormData branch", () => {
+  it("sends the FormData as-is with NO manual Content-Type header (browser sets boundary)", async () => {
     mockFetchOk({ ok: true });
     mockMetaTag(null);
 
     const fd = new FormData();
     fd.append("title", "From form");
 
-    await _makeRef("create_post")(fd);
+    await makePostFn()(fd);
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.body).toBe(fd);
@@ -212,12 +221,12 @@ describe("Story 8.1 — FormData branch", () => {
   });
 });
 
-describe("Story 8.1 — CSRF header injection", () => {
+describe("mutation core — CSRF header injection", () => {
   it("attaches X-CSRF-Token header when <meta name=\"csrf-token\"> is present", async () => {
     mockFetchOk({ ok: true });
     mockMetaTag("token-abc123");
 
-    await _makeRef("create_post")({ title: "x" });
+    await makePostFn()({ title: "x" });
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.headers["X-CSRF-Token"]).toBe("token-abc123");
@@ -227,7 +236,7 @@ describe("Story 8.1 — CSRF header injection", () => {
     mockFetchOk({ ok: true });
     mockMetaTag(null);
 
-    await _makeRef("create_post")({ title: "x" });
+    await makePostFn()({ title: "x" });
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.headers["X-CSRF-Token"]).toBeUndefined();
@@ -237,17 +246,17 @@ describe("Story 8.1 — CSRF header injection", () => {
     mockFetchOk({ ok: true });
     globalThis.document = undefined;
 
-    await expect(_makeRef("create_post")({ title: "x" })).resolves.toEqual({ ok: true });
+    await expect(makePostFn()({ title: "x" })).resolves.toEqual({ ok: true });
   });
 });
 
-describe("Story 8.1 — error responses", () => {
+describe("mutation core — error responses", () => {
   it("rejects with a structured Error on 4xx responses", async () => {
     mockFetchError(422, "validation failed");
     mockMetaTag(null);
 
-    await expect(_makeRef("create_post")({ title: "" })).rejects.toThrow(
-      /ruact action :create_post failed: 422 validation failed/,
+    await expect(makePostFn()({ title: "" })).rejects.toThrow(
+      /ruact action :\/posts failed: 422 validation failed/,
     );
   });
 
@@ -255,8 +264,8 @@ describe("Story 8.1 — error responses", () => {
     mockFetchError(500, "boom");
     mockMetaTag(null);
 
-    await expect(_makeRef("create_post")({})).rejects.toThrow(
-      /ruact action :create_post failed: 500 boom/,
+    await expect(makePostFn()({})).rejects.toThrow(
+      /ruact action :\/posts failed: 500 boom/,
     );
   });
 
@@ -264,13 +273,13 @@ describe("Story 8.1 — error responses", () => {
     globalThis.fetch = vi.fn().mockRejectedValue(new TypeError("Failed to fetch"));
     mockMetaTag(null);
 
-    await expect(_makeRef("create_post")({})).rejects.toThrow(
-      /ruact action :create_post request failed: Failed to fetch/,
+    await expect(makePostFn()({})).rejects.toThrow(
+      /ruact action :\/posts request failed: Failed to fetch/,
     );
   });
 });
 
-describe("Story 8.1 — Re-run-4 — RuactActionError carries status/body (#6)", () => {
+describe("mutation core — RuactActionError carries status/body", () => {
   it("rejects with a RuactActionError exposing status and parsed JSON body on 422", async () => {
     const r = {
       ok: false,
@@ -284,13 +293,13 @@ describe("Story 8.1 — Re-run-4 — RuactActionError carries status/body (#6)",
 
     let captured = null;
     try {
-      await _makeRef("create_post")({ title: "" });
+      await makePostFn()({ title: "" });
     } catch (err) {
       captured = err;
     }
     expect(captured).toBeInstanceOf(RuactActionError);
     expect(captured.status).toBe(422);
-    expect(captured.actionName).toBe("create_post");
+    expect(captured.actionName).toBe("/posts");
     expect(captured.body).toEqual({ errors: { title: ["can't be blank"] } });
   });
 
@@ -300,7 +309,7 @@ describe("Story 8.1 — Re-run-4 — RuactActionError carries status/body (#6)",
 
     let captured = null;
     try {
-      await _makeRef("create_post")({});
+      await makePostFn()({});
     } catch (err) {
       captured = err;
     }
@@ -310,7 +319,7 @@ describe("Story 8.1 — Re-run-4 — RuactActionError carries status/body (#6)",
   });
 });
 
-describe("Story 8.1 — Re-run-4 — +json structured-syntax-suffix media types (#7)", () => {
+describe("mutation core — +json structured-syntax-suffix media types", () => {
   it("parses application/problem+json as JSON (RFC 6838 §4.2.8)", async () => {
     const r = {
       ok: true,
@@ -322,7 +331,7 @@ describe("Story 8.1 — Re-run-4 — +json structured-syntax-suffix media types
     globalThis.fetch = vi.fn().mockResolvedValue(r);
     mockMetaTag(null);
 
-    const result = await _makeRef("noop")({});
+    const result = await makePostFn()({});
     expect(result).toEqual({ type: "about:blank", title: "ok" });
   });
 
@@ -337,24 +346,12 @@ describe("Story 8.1 — Re-run-4 — +json structured-syntax-suffix media types
     globalThis.fetch = vi.fn().mockResolvedValue(r);
     mockMetaTag(null);
 
-    const result = await _makeRef("noop")({});
+    const result = await makePostFn()({});
     expect(result).toEqual({ data: { id: "1" } });
   });
 });
 
-describe("Story 8.1 — Re-run-3 — URL encoding of name (#6)", () => {
-  it("encodeURIComponent's the name so a stray '/' cannot rewrite the path", async () => {
-    mockFetchOk({ ok: true });
-    mockMetaTag(null);
-
-    await _makeRef("../foo?x=1")({});
-
-    const [url] = globalThis.fetch.mock.calls[0];
-    expect(url).toBe("/__ruact/fn/..%2Ffoo%3Fx%3D1");
-  });
-});
-
-describe("Story 8.1 — Re-run-3 — Content-Type matching is case-insensitive (#5)", () => {
+describe("mutation core — Content-Type matching is case-insensitive", () => {
   it("parses JSON when Content-Type is `Application/JSON` (RFC 9110 — case-insensitive media type)", async () => {
     const r = {
       ok: true,
@@ -366,24 +363,24 @@ describe("Story 8.1 — Re-run-3 — Content-Type matching is case-insensitive (
     globalThis.fetch = vi.fn().mockResolvedValue(r);
     mockMetaTag(null);
 
-    const result = await _makeRef("noop")({});
+    const result = await makePostFn()({});
     expect(result).toEqual({ id: 42 });
   });
 });
 
-describe("Story 8.1 — Re-run-5 — fetch redirect: 'error' (#5)", () => {
+describe("mutation core — fetch redirect: 'error'", () => {
   it("sets redirect: 'error' on the fetch init so auth `redirect_to` failures surface as errors", async () => {
     mockFetchOk({ ok: true });
     mockMetaTag(null);
 
-    await _makeRef("create_post")({});
+    await makePostFn()({});
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.redirect).toBe("error");
   });
 });
 
-describe("Story 8.1 — Re-run-5 — configureRuactRuntime (#6)", () => {
+describe("mutation core — configureRuactRuntime", () => {
   afterEach(() => {
     configureRuactRuntime({ defaultHeaders: null });
   });
@@ -393,7 +390,7 @@ describe("Story 8.1 — Re-run-5 — configureRuactRuntime (#6)", () => {
     mockMetaTag(null);
     configureRuactRuntime({ defaultHeaders: { Authorization: "Bearer abc" } });
 
-    await _makeRef("create_post")({});
+    await makePostFn()({});
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.headers.Authorization).toBe("Bearer abc");
@@ -410,8 +407,8 @@ describe("Story 8.1 — Re-run-5 — configureRuactRuntime (#6)", () => {
       },
     });
 
-    await _makeRef("create_post")({});
-    await _makeRef("create_post")({});
+    await makePostFn()({});
+    await makePostFn()({});
 
     expect(globalThis.fetch.mock.calls[0][1].headers.Authorization).toBe("Bearer t1");
     expect(globalThis.fetch.mock.calls[1][1].headers.Authorization).toBe("Bearer t2");
@@ -428,7 +425,7 @@ describe("Story 8.1 — Re-run-5 — configureRuactRuntime (#6)", () => {
       },
     });
 
-    await _makeRef("create_post")({});
+    await makePostFn()({});
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.headers["X-CSRF-Token"]).toBe("real-csrf");
@@ -458,7 +455,7 @@ describe("Story 8.1 — Re-run-5 — configureRuactRuntime (#6)", () => {
       },
     });
 
-    await _makeRef("create_post")({});
+    await makePostFn()({});
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.headers.Accept).toBe("application/json");
@@ -483,7 +480,7 @@ describe("Story 8.1 — Re-run-5 — configureRuactRuntime (#6)", () => {
 
     const fd = new FormData();
     fd.append("title", "Hello");
-    await _makeRef("upload")(fd);
+    await makePostFn()(fd);
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.headers["Content-Type"]).toBeUndefined();
@@ -508,12 +505,12 @@ describe("Story 8.1 — __internals (test-only surface)", () => {
 // Story 8.2 — useActionState two-arg invocation
 // =============================================================================
 
-describe("Story 8.2 — _makeRef call-shape detection", () => {
+describe("Story 8.2 — call-shape detection (useActionState two-arg)", () => {
   it("fn() — zero args sends an empty JSON body (parity with Story 8.1 fn() shape)", async () => {
     mockFetchOk({});
     mockMetaTag(null);
 
-    await _makeRef("noop")();
+    await makePostFn()();
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.body).toBe("{}");
@@ -524,7 +521,7 @@ describe("Story 8.2 — _makeRef call-shape detection", () => {
     mockFetchOk({});
     mockMetaTag(null);
 
-    await _makeRef("create_post")({ title: "Hi" });
+    await makePostFn()({ title: "Hi" });
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.body).toBe(JSON.stringify({ title: "Hi" }));
@@ -536,7 +533,7 @@ describe("Story 8.2 — _makeRef call-shape detection", () => {
 
     const fd = new FormData();
     fd.append("title", "Hi");
-    await _makeRef("create_post")(fd);
+    await makePostFn()(fd);
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.body).toBe(fd);
@@ -550,7 +547,7 @@ describe("Story 8.2 — _makeRef call-shape detection", () => {
 
     const fd = new FormData();
     fd.append("title", "From form");
-    await _makeRef("create_post")({ message: "previous state" }, fd);
+    await makePostFn()({ message: "previous state" }, fd);
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.body).toBe(fd);
@@ -562,7 +559,7 @@ describe("Story 8.2 — _makeRef call-shape detection", () => {
     mockFetchOk({});
     mockMetaTag(null);
 
-    await _makeRef("create_post")({ message: "previous state" }, { title: "Hi" });
+    await makePostFn()({ message: "previous state" }, { title: "Hi" });
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.body).toBe(JSON.stringify({ title: "Hi" }));
@@ -576,16 +573,16 @@ describe("Story 8.2 — _makeRef call-shape detection", () => {
 
     const fd = new FormData();
     fd.append("title", "FD");
-    await _makeRef("create_post")(fd, { title: "obj" });
+    await makePostFn()(fd, { title: "obj" });
 
     const [, init] = globalThis.fetch.mock.calls[0];
     expect(init.body).toBe(fd);
   });
 
-  it("fn(a, b, c) — three or more args throws TypeError with a descriptive message", () => {
-    expect(() => _makeRef("create_post")(1, 2, 3)).toThrow(TypeError);
-    expect(() => _makeRef("create_post")(1, 2, 3)).toThrow(
-      /ruact action :create_post called with 3 arguments — expected 0, 1, or 2/,
+  it("fn(a, b, c) — three or more args rejects with a descriptive TypeError", async () => {
+    await expect(makePostFn()(1, 2, 3)).rejects.toThrow(TypeError);
+    await expect(makePostFn()(1, 2, 3)).rejects.toThrow(
+      /ruact server function POST \/posts called with 3 arguments — expected 0, 1, or 2/,
     );
   });
 
@@ -601,7 +598,7 @@ describe("Story 8.2 — _makeRef call-shape detection", () => {
     // Pre-Story-8.2 this would have thrown on JSON.stringify(circular). The
     // wire path never sees prevState, so circular references are harmless.
     await expect(
-      _makeRef("create_post")(circular, fd),
+      makePostFn()(circular, fd),
     ).resolves.not.toThrow();
 
     const [, init] = globalThis.fetch.mock.calls[0];

data/vendor/javascript/ruact-server-functions-runtime/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ruact-server-functions-runtime",
-  "version": "0.3.0",
-  "description": "Server-functions runtime for ruact gem (Stories 8.1 + 8.2 + 9.5). Provides `_makeRef(name)` / `_makeServerFunction(descriptor)` (mutations: POST/PUT/PATCH/DELETE with CSRF + JSON / FormData), `revalidate(path?)` (Flight refetch), and `_makeQuery(descriptor)` + `useQuery(ref, params?)` (reads: GET /q/<jsId>, CSRF-free, FR88 primitive params → { data, loading, error }).",
+  "version": "0.4.0",
+  "description": "Route-driven server-functions runtime for the ruact gem. Provides `_makeServerFunction(descriptor)` (mutations: POST/PUT/PATCH/DELETE with CSRF + JSON / FormData), `revalidate(path?)` (Flight refetch), and `_makeQuery(descriptor)` + `useQuery(ref, params?)` (reads: GET /q/<jsId>, CSRF-free, FR88 primitive params → { data, loading, error }; identical concurrent calls share one in-flight request).",
   "type": "module",
   "main": "index.js",
   "types": "./index.d.ts",

data/vendor/javascript/ruact-server-functions-runtime/usequery.test.mjs

@@ -15,6 +15,10 @@ let originalFetch;
 
 beforeEach(() => {
   originalFetch = globalThis.fetch;
+  // Story 9.6 — start every case from a clean in-flight registry so a test that
+  // deliberately leaves a request pending cannot leak a shared promise into the
+  // next one.
+  __internals.__resetQueryDedup();
 });
 
 afterEach(() => {
@@ -44,6 +48,39 @@ function mockFetchError(status, bodyText) {
   return response;
 }
 
+// Story 9.6 — a fetch stub that returns a PENDING promise so two hooks can both
+// be in-flight at once (the precondition for exercising dedup). The test
+// resolves it manually AFTER both hooks have mounted.
+function deferredFetch() {
+  let settle;
+  const fetchMock = vi.fn(
+    () =>
+      new Promise((resolve) => {
+        settle = resolve;
+      }),
+  );
+  globalThis.fetch = fetchMock;
+  return {
+    fetchMock,
+    resolveOk(jsonBody, { status = 200, contentType = "application/json" } = {}) {
+      settle({
+        ok: true,
+        status,
+        headers: { get: (n) => (n.toLowerCase() === "content-type" ? contentType : null) },
+        text: () => Promise.resolve(typeof jsonBody === "string" ? jsonBody : JSON.stringify(jsonBody)),
+      });
+    },
+    resolveError(status, bodyText) {
+      settle({
+        ok: false,
+        status,
+        headers: { get: () => "text/plain" },
+        text: () => Promise.resolve(bodyText),
+      });
+    },
+  };
+}
+
 describe("Story 9.5 — useQuery hook contract", () => {
   it("starts loading, then resolves to { data, loading: false, error: null }", async () => {
     const ref = vi.fn().mockResolvedValue({ items: [1, 2] });
@@ -179,3 +216,153 @@ describe("Story 9.5 — _makeQuery / buildQueryUrl wire format (FR88)", () => {
     expect(init.redirect).toBe("error");
   });
 });
+
+describe("Story 9.6 — useQuery in-flight request de-duplication", () => {
+  it("shares ONE network request across concurrent callers (same ref + same params) — AC1", async () => {
+    const deferred = deferredFetch();
+    const categories = _makeQuery({ path: "/q/categories", kind: "query" });
+
+    const a = renderHook(() => useQuery(categories, { q: "bo" }));
+    const b = renderHook(() => useQuery(categories, { q: "bo" }));
+
+    // Both hooks are in-flight: the second joined the first's request.
+    await waitFor(() => expect(deferred.fetchMock).toHaveBeenCalledTimes(1));
+
+    deferred.resolveOk([{ value: 1, label: "Books" }]);
+    await waitFor(() => expect(a.result.current.loading).toBe(false));
+    await waitFor(() => expect(b.result.current.loading).toBe(false));
+
+    // Still exactly one network call, and both callers got the same data.
+    expect(deferred.fetchMock).toHaveBeenCalledTimes(1);
+    expect(a.result.current.data).toEqual([{ value: 1, label: "Books" }]);
+    expect(b.result.current.data).toEqual([{ value: 1, label: "Books" }]);
+  });
+
+  it("propagates the SAME error instance to ALL sharers of an in-flight request — AC1", async () => {
+    const deferred = deferredFetch();
+    const search = _makeQuery({ path: "/q/search", kind: "query" });
+
+    const a = renderHook(() => useQuery(search, { q: "x" }));
+    const b = renderHook(() => useQuery(search, { q: "x" }));
+    await waitFor(() => expect(deferred.fetchMock).toHaveBeenCalledTimes(1));
+
+    deferred.resolveError(500, "boom");
+    await waitFor(() => expect(a.result.current.loading).toBe(false));
+    await waitFor(() => expect(b.result.current.loading).toBe(false));
+
+    expect(a.result.current.error).toBeInstanceOf(RuactActionError);
+    expect(a.result.current.error).toBe(b.result.current.error); // identical instance
+    expect(deferred.fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("collapses params that differ only in key ORDER onto one request — AC2", async () => {
+    const deferred = deferredFetch();
+    const search = _makeQuery({ path: "/q/search", kind: "query" });
+
+    renderHook(() => useQuery(search, { a: 1, b: 2 }));
+    renderHook(() => useQuery(search, { b: 2, a: 1 }));
+
+    await waitFor(() => expect(deferred.fetchMock).toHaveBeenCalledTimes(1));
+    // Give any stray second request a chance to fire before asserting once.
+    await Promise.resolve();
+    expect(deferred.fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("issues SEPARATE requests for different params — AC2", async () => {
+    const deferred = deferredFetch();
+    const search = _makeQuery({ path: "/q/search", kind: "query" });
+
+    renderHook(() => useQuery(search, { q: "a" }));
+    renderHook(() => useQuery(search, { q: "b" }));
+
+    await waitFor(() => expect(deferred.fetchMock).toHaveBeenCalledTimes(2));
+  });
+
+  it("does NOT dedup across distinct references with the same params — AC2 (keys off the reference)", async () => {
+    const deferred = deferredFetch();
+    const categories = _makeQuery({ path: "/q/categories", kind: "query" });
+    const search = _makeQuery({ path: "/q/search", kind: "query" });
+
+    renderHook(() => useQuery(categories, { q: "x" }));
+    renderHook(() => useQuery(search, { q: "x" }));
+
+    await waitFor(() => expect(deferred.fetchMock).toHaveBeenCalledTimes(2));
+  });
+
+  it("does NOT share an invalid-shape params call onto an in-flight no-param request (surfaces the error) — AC2", async () => {
+    const deferred = deferredFetch();
+    const categories = _makeQuery({ path: "/q/categories", kind: "query" });
+
+    // A no-param request is in flight (key "").
+    const noParams = renderHook(() => useQuery(categories));
+    await waitFor(() => expect(deferred.fetchMock).toHaveBeenCalledTimes(1));
+
+    // An invalid array-shaped params call must NOT join the "" request — it must
+    // invoke the reference, whose buildQueryUrl throws a TypeError.
+    const invalid = renderHook(() => useQuery(categories, [1, 2]));
+    await waitFor(() => expect(invalid.result.current.loading).toBe(false));
+
+    expect(invalid.result.current.error).toBeInstanceOf(TypeError);
+    expect(invalid.result.current.data).toBeUndefined();
+    // No new network call: buildQueryUrl threw before fetch, and it never shared.
+    expect(deferred.fetchMock).toHaveBeenCalledTimes(1);
+    expect(noParams.result.current.loading).toBe(true); // still in flight
+  });
+
+  it("issues a FRESH request on a mount AFTER the previous settled (in-flight only, no cache) — AC3", async () => {
+    mockFetchOk([{ value: 1 }]);
+    const categories = _makeQuery({ path: "/q/categories", kind: "query" });
+
+    const first = renderHook(() => useQuery(categories, { q: "bo" }));
+    await waitFor(() => expect(first.result.current.loading).toBe(false));
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    first.unmount();
+
+    // The previous request settled, so its registry entry is gone — a new mount
+    // with identical reference + params must refetch (no TTL / no SWR).
+    const second = renderHook(() => useQuery(categories, { q: "bo" }));
+    await waitFor(() => expect(second.result.current.loading).toBe(false));
+    expect(globalThis.fetch).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("Story 9.6 — canonicalParamsKey (dedup key derivation)", () => {
+  const { canonicalParamsKey } = __internals;
+
+  it("is order-independent ({a,b} === {b,a})", () => {
+    expect(canonicalParamsKey({ a: 1, b: 2 })).toBe(canonicalParamsKey({ b: 2, a: 1 }));
+  });
+
+  it("distinguishes different values", () => {
+    expect(canonicalParamsKey({ q: "a" })).not.toBe(canonicalParamsKey({ q: "b" }));
+  });
+
+  it("treats null / undefined / empty object as the same empty key", () => {
+    expect(canonicalParamsKey(null)).toBe("");
+    expect(canonicalParamsKey(undefined)).toBe("");
+    expect(canonicalParamsKey({})).toBe("");
+  });
+
+  it("skips undefined-valued keys (mirrors buildQueryUrl's wire omission)", () => {
+    expect(canonicalParamsKey({ q: "a", extra: undefined })).toBe(canonicalParamsKey({ q: "a" }));
+  });
+
+  it("distinguishes null from non-finite numbers (NaN / Infinity), which the wire sends differently", () => {
+    const asNull = canonicalParamsKey({ q: null });
+    const asNaN = canonicalParamsKey({ q: NaN });
+    const asInfinity = canonicalParamsKey({ q: Infinity });
+    expect(asNull).not.toBe(asNaN);
+    expect(asNaN).not.toBe(asInfinity);
+    expect(asNull).not.toBe(asInfinity);
+  });
+
+  it("distinguishes a null value (bare key) from the empty string (key=)", () => {
+    expect(canonicalParamsKey({ q: null })).not.toBe(canonicalParamsKey({ q: "" }));
+  });
+
+  it("returns null (non-shareable) for shapes buildQueryUrl rejects — array top level or array/object value", () => {
+    expect(canonicalParamsKey([1, 2])).toBe(null);
+    expect(canonicalParamsKey({ q: [1, 2] })).toBe(null);
+    expect(canonicalParamsKey({ q: { deep: 1 } })).toBe(null);
+  });
+});