@ogygie/ui 0.0.0-stage → 0.17.0

package/src/failures.test.ts

@@ -0,0 +1,31 @@
+/**
+ * @intent Proves the structural reading of a thrown value (spec ogygie-ui
+ * B1): an OgygieFailure yields its payload and status whatever module built
+ * it; a plain Error yields its message; 401 and 403 read as access denied.
+ */
+import { describe, expect, it } from "vitest";
+import { OgygieFailure, ogygieError } from "@ogygie/core/errors";
+import { failureOf, isAccessDenied, messageOf, statusOf } from "./failures.js";
+
+const payload = ogygieError({ code: "WORKSPACE_ACCESS_DENIED", message: "Not a member of this workspace.", file: null, cause: "membership absent", suggestedFix: "Switch workspace." });
+
+describe("failures", () => {
+  it("lit une OgygieFailure par sa forme, pas par sa classe", () => {
+    const lookalike = { error: payload, httpStatus: 403 };
+    expect(failureOf(lookalike)).toEqual(payload);
+    expect(statusOf(lookalike)).toBe(403);
+    expect(isAccessDenied(lookalike)).toBe(true);
+    expect(failureOf(new OgygieFailure(payload, 401))).toEqual(payload);
+    expect(isAccessDenied(new OgygieFailure(payload, 401))).toBe(true);
+    expect(isAccessDenied(new OgygieFailure(payload, 409))).toBe(false);
+  });
+
+  it("dégrade une erreur quelconque à son message", () => {
+    expect(failureOf(new Error("boom"))).toBeNull();
+    expect(statusOf(new Error("boom"))).toBeNull();
+    expect(messageOf(new Error("boom"))).toBe("boom");
+    expect(messageOf("plain")).toBe("plain");
+    expect(messageOf(new OgygieFailure(payload, 403))).toBe(payload.message);
+    expect(failureOf({ error: { code: "x" } })).toBeNull();
+  });
+});

package/src/failures.ts

@@ -0,0 +1,39 @@
+/**
+ * @intent Reads a thrown value the way a screen needs it: the OgygieError
+ * payload and the HTTP status of an `OgygieFailure` (`@ogygie/core/errors`),
+ * found STRUCTURALLY — the payload re-validated against its schema — never
+ * through `instanceof`. A product may hold two copies of the core for a
+ * moment (an upgrade in flight, a nested install): an instance check would
+ * then mask a perfectly good failure as "unknown error", and the banner would
+ * lose the code and the suggested fix, the only two things a reader can act
+ * on. Anything else degrades to its message.
+ */
+import { OgygieErrorSchema, type OgygieError } from "@ogygie/core/errors";
+
+/** The OgygieError a failure carries, or null when the thrown value is not one. */
+export function failureOf(error: unknown): OgygieError | null {
+  if (typeof error !== "object" || error === null || !("error" in error)) return null;
+  const parsed = OgygieErrorSchema.safeParse((error as { error: unknown }).error);
+  return parsed.success ? parsed.data : null;
+}
+
+/** The HTTP status a failure carries, or null when the thrown value is not an OgygieFailure. */
+export function statusOf(error: unknown): number | null {
+  if (typeof error !== "object" || error === null || !("httpStatus" in error)) return null;
+  const status = (error as { httpStatus: unknown }).httpStatus;
+  return typeof status === "number" ? status : null;
+}
+
+/** 401 or 403: the caller is not allowed, which a screen shows as an explanation, never as a failure to load. */
+export function isAccessDenied(error: unknown): boolean {
+  const status = statusOf(error);
+  return status === 401 || status === 403;
+}
+
+/** The sentence a banner shows for ANY thrown value: the payload's message, an Error's message, or the value itself. */
+export function messageOf(error: unknown): string {
+  const failure = failureOf(error);
+  if (failure !== null) return failure.message;
+  if (error instanceof Error) return error.message;
+  return String(error);
+}

package/src/fetch-contract.test.ts

@@ -0,0 +1,121 @@
+/**
+ * @intent Proves the one fetch path of a front (spec ogygie-ui B1): an answer
+ * on its contract is served parsed; an OgygieError body comes back as an
+ * OgygieFailure UNTOUCHED with its status; a network throw, a non-JSON answer
+ * and an answer off its contract speak the same language (NETWORK_ERROR,
+ * CONTRACT_BROKEN); the JSON content type travels only with a body; the
+ * product's `onFailure` sees every refusal before it is thrown.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+import { OgygieFailure, ogygieError } from "@ogygie/core/errors";
+import { createContractFetcher, fetchContract, jsonBody } from "./fetch-contract.js";
+
+const OutputSchema = z.object({ items: z.array(z.object({ code: z.string() })) });
+
+function answering(status: number, body: string, headers: Record<string, string> = {}) {
+  const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
+  const fetchImpl = vi.fn(async (url: string, init?: RequestInit) => {
+    calls.push({ url, init });
+    return new Response(body, { status, headers: { "content-type": "application/json", ...headers } });
+  });
+  return { fetchImpl, calls };
+}
+
+async function failureOf(promise: Promise<unknown>): Promise<OgygieFailure> {
+  try {
+    await promise;
+  } catch (thrown) {
+    if (thrown instanceof OgygieFailure) return thrown;
+    throw new Error(`expected an OgygieFailure, got ${String(thrown)}`);
+  }
+  throw new Error("expected a refusal");
+}
+
+describe("fetchContract", () => {
+  it("ÉTANT DONNÉ une réponse conforme au contrat QUAND on la lit ALORS elle est servie parsée", async () => {
+    const { fetchImpl, calls } = answering(200, JSON.stringify({ items: [{ code: "a" }] }));
+    const fetch = createContractFetcher({ fetchImpl });
+    await expect(fetch("/api/items", OutputSchema)).resolves.toEqual({ items: [{ code: "a" }] });
+    expect(calls[0]?.url).toBe("/api/items");
+    expect(new Headers(calls[0]?.init?.headers).get("content-type")).toBeNull();
+  });
+
+  it("ÉTANT DONNÉ un corps QUAND on écrit ALORS le content-type JSON l'accompagne, et lui seul", async () => {
+    const { fetchImpl, calls } = answering(201, JSON.stringify({ items: [] }));
+    const fetch = createContractFetcher({ fetchImpl });
+    await fetch("/api/items", OutputSchema, { method: "POST", ...jsonBody({ code: "a" }) });
+    const headers = new Headers(calls[0]?.init?.headers);
+    expect(headers.get("content-type")).toBe("application/json");
+    expect(calls[0]?.init?.method).toBe("POST");
+    expect(calls[0]?.init?.body).toBe('{"code":"a"}');
+  });
+
+  it("ÉTANT DONNÉ un statut d'erreur avec un corps OgygieError QUAND on lit ALORS la failure porte ce corps intact et le statut", async () => {
+    const payload = ogygieError({
+      code: "GRADE_IN_USE",
+      message: "The row is still referenced.",
+      file: null,
+      cause: "3 holders",
+      suggestedFix: "Move the holders first.",
+    });
+    const { fetchImpl } = answering(409, JSON.stringify(payload));
+    const failure = await failureOf(createContractFetcher({ fetchImpl })("/api/items/a", OutputSchema, { method: "DELETE" }));
+    expect(failure.httpStatus).toBe(409);
+    expect(failure.error).toEqual(payload);
+  });
+
+  it("ÉTANT DONNÉ un corps d'erreur réduit à code et message QUAND on lit ALORS la failure le complète sans le perdre", async () => {
+    const { fetchImpl } = answering(400, JSON.stringify({ code: "VALIDATION_FAILED", message: "The request does not satisfy the contract." }));
+    const failure = await failureOf(createContractFetcher({ fetchImpl })("/api/items", OutputSchema));
+    expect(failure.error.code).toBe("VALIDATION_FAILED");
+    expect(failure.error.suggestedFix).toBe("");
+    expect(failure.httpStatus).toBe(400);
+  });
+
+  it("ÉTANT DONNÉ un statut d'erreur sans corps OgygieError QUAND on lit ALORS NETWORK_ERROR porte le statut dans details", async () => {
+    const { fetchImpl } = answering(502, "<html>bad gateway</html>", { "content-type": "text/html" });
+    const failure = await failureOf(createContractFetcher({ fetchImpl })("/api/items", OutputSchema));
+    expect(failure.error.code).toBe("CONTRACT_BROKEN");
+    expect(failure.httpStatus).toBe(502);
+    const { fetchImpl: jsonImpl } = answering(502, JSON.stringify({ oops: true }));
+    const jsonFailure = await failureOf(createContractFetcher({ fetchImpl: jsonImpl })("/api/items", OutputSchema));
+    expect(jsonFailure.error.code).toBe("NETWORK_ERROR");
+    expect(jsonFailure.error.details).toEqual({ status: 502 });
+  });
+
+  it("ÉTANT DONNÉ un réseau qui lève QUAND on lit ALORS NETWORK_ERROR 503, jamais une rejection nue", async () => {
+    const fetchImpl = vi.fn(async () => {
+      throw new TypeError("Failed to fetch");
+    });
+    const failure = await failureOf(createContractFetcher({ fetchImpl })("/api/items", OutputSchema));
+    expect(failure.error.code).toBe("NETWORK_ERROR");
+    expect(failure.httpStatus).toBe(503);
+    expect(failure.error.cause).toContain("Failed to fetch");
+  });
+
+  it("ÉTANT DONNÉ une réponse 200 hors contrat QUAND on lit ALORS CONTRACT_BROKEN nomme le chemin fautif", async () => {
+    const { fetchImpl } = answering(200, JSON.stringify({ items: [{ code: 12 }] }));
+    const failure = await failureOf(createContractFetcher({ fetchImpl })("/api/items", OutputSchema));
+    expect(failure.error.code).toBe("CONTRACT_BROKEN");
+    expect(failure.error.cause).toContain("items.0.code");
+  });
+
+  it("ÉTANT DONNÉ un onFailure du produit QUAND une lecture est refusée ALORS il la voit avant qu'elle soit levée", async () => {
+    const seen: OgygieFailure[] = [];
+    const { fetchImpl } = answering(401, JSON.stringify(ogygieError({ code: "AUTH_REQUIRED", message: "A valid session is required.", file: null, cause: "no cookie", suggestedFix: "Sign in." })));
+    const fetch = createContractFetcher({ fetchImpl, onFailure: (failure) => seen.push(failure) });
+    await failureOf(fetch("/api/items", OutputSchema));
+    expect(seen.map((failure) => failure.error.code)).toEqual(["AUTH_REQUIRED"]);
+  });
+
+  it("le fetcher par défaut passe par globalThis.fetch", async () => {
+    const spy = vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response(JSON.stringify({ items: [] }), { status: 200 }));
+    try {
+      await expect(fetchContract("/api/items", OutputSchema)).resolves.toEqual({ items: [] });
+      expect(spy).toHaveBeenCalledTimes(1);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});

package/src/fetch-contract.ts

@@ -0,0 +1,157 @@
+/**
+ * @intent The ONE fetch path of an Ogygie front (D39): a relative `/api/...`
+ * call whose answer is RE-VALIDATED against the Zod contract the API
+ * declares. Failures speak one language — an OgygieError body comes back as
+ * an `OgygieFailure` of the core, untouched (code, cause, suggestedFix, the
+ * HTTP status beside it); a network failure, a non-JSON answer or an answer
+ * off its contract become NETWORK_ERROR / CONTRACT_BROKEN failures — never a
+ * raw rejection, never a shape nobody expected flowing into a screen.
+ *
+ * The transport is an injected effect (`fetchImpl`, principle 5): a test
+ * passes a fake, a product passes nothing and gets `globalThis.fetch`. What a
+ * product does on a given failure — redirect to its sign-in on 401, log — is
+ * its decision, declared once through `onFailure` when it CREATES its
+ * fetcher; the default fetcher decides nothing.
+ *
+ * Why not `@ogygie/core/client`? That module derives operations from the
+ * manifest; this one serves the screens written before that derivation
+ * reaches them (every existing product), and the generated `queries.gen.ts`
+ * of the next lot — one call, one URL, one schema.
+ */
+import type { z } from "zod";
+import { OgygieErrorSchema, OgygieFailure, ogygieError, type OgygieError } from "@ogygie/core/errors";
+
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+
+export interface ContractFetcherOptions {
+  /** The network effect. Defaults to `globalThis.fetch`, bound. */
+  fetchImpl?: FetchLike;
+  /** Called with EVERY failure before it is thrown — the product's one place to react (a 401 → its sign-in). */
+  onFailure?: (failure: OgygieFailure) => void;
+}
+
+export type ContractFetcher = <TSchema extends z.ZodType>(
+  url: string,
+  schema: TSchema,
+  init?: RequestInit,
+) => Promise<z.infer<TSchema>>;
+
+/**
+ * An OgygieError body is the api SPEAKING: it comes back untouched. A body
+ * with at least a code and a message is completed (a product whose error
+ * handler predates `details` or `timestamp` still names its codes); anything
+ * else is a NETWORK_ERROR carrying the status and the start of the body.
+ */
+function failurePayloadOf(body: unknown, status: number, url: string): OgygieError {
+  const strict = OgygieErrorSchema.safeParse(body);
+  if (strict.success) return strict.data;
+  if (typeof body === "object" && body !== null) {
+    const candidate = body as Record<string, unknown>;
+    const lenient = OgygieErrorSchema.safeParse({
+      ogygie: true,
+      details: {},
+      timestamp: new Date(0).toISOString(),
+      file: null,
+      cause: "",
+      suggestedFix: "",
+      ...candidate,
+    });
+    if (lenient.success) return lenient.data;
+  }
+  return ogygieError({
+    code: "NETWORK_ERROR",
+    message: `The api answered ${status} without an OgygieError body.`,
+    file: null,
+    cause: `${url} answered ${status} with ${JSON.stringify(body).slice(0, 200)}`,
+    suggestedFix: "Find what answered (gateway? proxy? an api without its error handler?) — every Ogygie failure carries an OgygieError body.",
+    details: { status },
+  });
+}
+
+export function createContractFetcher(options: ContractFetcherOptions = {}): ContractFetcher {
+  const fetchImpl: FetchLike = options.fetchImpl ?? ((url, init) => globalThis.fetch(url, init));
+  const refuse = (failure: OgygieFailure): never => {
+    options.onFailure?.(failure);
+    throw failure;
+  };
+
+  return async (url, schema, init) => {
+    let response: Response;
+    try {
+      response = await fetchImpl(url, {
+        ...init,
+        headers: {
+          accept: "application/json",
+          // JSON content type ONLY when there is a body: Fastify refuses an
+          // empty body announced as JSON, which silently broke every verb that
+          // sends nothing (astorg-ai-pdlc, 2026-09).
+          ...(init?.body === undefined || init.body === null ? {} : { "content-type": "application/json" }),
+          ...(init?.headers ?? {}),
+        },
+      });
+    } catch (thrown) {
+      return refuse(
+        new OgygieFailure(
+          ogygieError({
+            code: "NETWORK_ERROR",
+            message: `The call to ${url} never reached the api.`,
+            file: null,
+            cause: `fetch threw ${String(thrown)}`,
+            suggestedFix: "Check that the api answers on this path (dev proxy up? offline?) — the front never invents a fallback answer.",
+          }),
+          503,
+        ),
+      );
+    }
+
+    const rawBody = await response.text();
+    let body: unknown = undefined;
+    if (rawBody.trim() !== "") {
+      try {
+        body = JSON.parse(rawBody) as unknown;
+      } catch (thrown) {
+        return refuse(
+          new OgygieFailure(
+            ogygieError({
+              code: "CONTRACT_BROKEN",
+              message: `The answer of ${url} is not JSON.`,
+              file: null,
+              cause: `status ${response.status}, body starting with ${JSON.stringify(rawBody.slice(0, 80))} (${String(thrown)})`,
+              suggestedFix: "Find what really answered on this path (a proxy error page? an html fallback?) — the declared output schema promises JSON.",
+            }),
+            response.status,
+          ),
+        );
+      }
+    }
+
+    if (!response.ok) {
+      return refuse(new OgygieFailure(failurePayloadOf(body, response.status, url), response.status));
+    }
+
+    const parsed = schema.safeParse(body);
+    if (!parsed.success) {
+      return refuse(
+        new OgygieFailure(
+          ogygieError({
+            code: "CONTRACT_BROKEN",
+            message: `The answer of ${url} violates the contract this screen reads.`,
+            file: null,
+            cause: parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join(" ; "),
+            suggestedFix: "The API and the front disagree on a contract: align the answer with the schema, or amend the contract on both sides in the same PR.",
+          }),
+          response.status,
+        ),
+      );
+    }
+    return parsed.data;
+  };
+}
+
+/** The fetcher a product uses when it has nothing to decide on failures. */
+export const fetchContract: ContractFetcher = createContractFetcher();
+
+/** A JSON body for a write: `fetchContract(url, Schema, { method: "POST", ...jsonBody(input) })`. */
+export function jsonBody(body: unknown): Pick<RequestInit, "body"> {
+  return { body: JSON.stringify(body) };
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @intent Root entry point of `@ogygie/ui` (D39): the dependency-light socle
+ * every Ogygie front imports — the screen states, the error and empty
+ * surfaces, the inline editor, the contract fetcher and the shapes a body
+ * receives. It pulls React, zod and the core, nothing else: the three patterns
+ * that carry an optional peer live behind their own entry points —
+ * `@ogygie/ui/data-table`, `@ogygie/ui/contract-form`,
+ * `@ogygie/ui/variance-chart` — so a product that installs none of them never
+ * resolves them.
+ */
+export { EmptyState, type EmptyStateProps } from "./EmptyState.js";
+export { ErrorBanner, type ErrorBannerProps } from "./ErrorBanner.js";
+export { ScreenState, Skeleton, type ScreenStateProps, type StateCopy } from "./ScreenState.js";
+export { EditableText, type EditableTextProps } from "./EditableText.js";
+export { CharacterCount } from "./CharacterCount.js";
+export {
+  createContractFetcher,
+  fetchContract,
+  jsonBody,
+  type ContractFetcher,
+  type ContractFetcherOptions,
+  type FetchLike,
+} from "./fetch-contract.js";
+export { failureOf, isAccessDenied, messageOf, statusOf } from "./failures.js";
+export {
+  failedQuery,
+  idleMutation,
+  pendingQuery,
+  readyQuery,
+  type MutationLike,
+  type QueryLike,
+} from "./query-like.js";

package/src/published-contract.test.ts

@@ -0,0 +1,84 @@
+/**
+ * @intent Guards what this package PUBLISHES (D39, same family as the studio's
+ * and the MCP server's contract tests): every entry point resolves to a source
+ * file under a shipped folder; the ROOT entry pulls none of the optional peers
+ * (a product that installs none of them must still import it); the three
+ * heavy patterns each sit behind their own entry point; the optional peers are
+ * declared optional; the version is the lockstep's.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const packageRoot = new URL("../", import.meta.url);
+const packageJson: {
+  version: string;
+  exports?: Record<string, string>;
+  files?: string[];
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+} = JSON.parse(readFileSync(new URL("package.json", packageRoot), "utf8"));
+const corePackageJson: { version: string } = JSON.parse(readFileSync(new URL("../ogygie-core/package.json", packageRoot), "utf8"));
+
+const OPTIONAL_PEERS = ["@tanstack/react-table", "react-hook-form", "recharts"];
+
+/** Every relative module a source file imports, transitively, under src/. */
+function importsOf(relativePath: string, seen = new Set<string>()): Set<string> {
+  if (seen.has(relativePath)) return seen;
+  seen.add(relativePath);
+  const source = readFileSync(new URL(relativePath, packageRoot), "utf8");
+  for (const match of source.matchAll(/from\s+"([^"]+)"/g)) {
+    const specifier = match[1] ?? "";
+    if (specifier.startsWith("./")) {
+      const target = specifier.replace(/\.js$/, "");
+      const directory = relativePath.slice(0, relativePath.lastIndexOf("/") + 1);
+      const candidates = [`${directory}${target.slice(2)}.ts`, `${directory}${target.slice(2)}.tsx`];
+      const existing = candidates.find((candidate) => existsSync(new URL(candidate, packageRoot)));
+      if (existing !== undefined) importsOf(existing, seen);
+    } else {
+      seen.add(`pkg:${specifier}`);
+    }
+  }
+  return seen;
+}
+
+describe("@ogygie/ui — contrat du paquet publié", () => {
+  it("chaque point d'entrée vit sous un dossier LIVRÉ et existe", () => {
+    const shippedRoots = (packageJson.files ?? []).map((entry) => entry.replace(/\/$/, ""));
+    const targets = Object.values(packageJson.exports ?? {});
+    expect(targets.length).toBeGreaterThan(0);
+    for (const target of targets) {
+      expect(shippedRoots).toContain(target.replace(/^\.\//, "").split("/")[0] ?? "");
+      expect(existsSync(new URL(target, packageRoot))).toBe(true);
+    }
+  });
+
+  it("le point d'entrée racine ne tire AUCUN peer optionnel", () => {
+    const reached = importsOf(packageJson.exports?.["."] ?? "./src/index.ts");
+    const externals = [...reached].filter((entry) => entry.startsWith("pkg:")).map((entry) => entry.slice(4));
+    for (const peer of OPTIONAL_PEERS) {
+      expect(externals.some((external) => external === peer || external.startsWith(`${peer}/`))).toBe(false);
+    }
+  });
+
+  it("les trois patterns lourds ont chacun leur point d'entrée, et leur peer est déclaré optionnel", () => {
+    expect(packageJson.exports?.["./data-table"]).toBe("./src/DataTable.tsx");
+    expect(packageJson.exports?.["./contract-form"]).toBe("./src/ContractForm.tsx");
+    expect(packageJson.exports?.["./variance-chart"]).toBe("./src/VarianceChart.tsx");
+    for (const peer of OPTIONAL_PEERS) {
+      expect(packageJson.peerDependencies?.[peer]).toBeDefined();
+      expect(packageJson.peerDependenciesMeta?.[peer]?.optional).toBe(true);
+    }
+    expect(packageJson.peerDependenciesMeta?.["react"]).toBeUndefined();
+  });
+
+  it("@ogygie/core est une DÉPENDANCE, jamais un peer : un peer qui monte ferait monter le lockstep en majeur (FAILURES.md 2026-10-18)", () => {
+    expect(packageJson.dependencies?.["@ogygie/core"]).toBeDefined();
+    expect(packageJson.peerDependencies?.["@ogygie/core"]).toBeUndefined();
+  });
+
+  it("la version est celle du lockstep (= @ogygie/core)", () => {
+    expect(packageJson.version).toBe(corePackageJson.version);
+  });
+});

package/src/query-like.ts

@@ -0,0 +1,50 @@
+/**
+ * @intent The two shapes a screen BODY receives instead of a hook (D39): the
+ * subset of a TanStack Query result it branches on (`QueryLike`) and the
+ * subset of a mutation result it acts through (`MutationLike`). A body typed
+ * on these renders without a QueryClient, a router or the network — the form
+ * the first product found on its own (every screen of the dtd app of
+ * astorg-ai-pdlc), lifted here so a generated container and a written body
+ * speak the same types. `UseQueryResult` and `UseMutationResult` are
+ * structurally assignable to them: a container passes its hooks' results as
+ * they are. The three fixtures at the end are what a body test builds its
+ * states from, so every product test spells them the same way.
+ */
+
+/** A read result shaped like a subset of `UseQueryResult`: only what a body branches on. Pending = no data and no error yet. */
+export interface QueryLike<TData> {
+  data: TData | undefined;
+  error: unknown;
+}
+
+/**
+ * A write result shaped like a subset of `UseMutationResult`: only what a
+ * body acts through. `variables` lets a body tell WHICH row is being written
+ * (one inactive cell, never the whole grid).
+ */
+export interface MutationLike<TVariables, TData = unknown> {
+  mutate: (variables: TVariables, options?: { onSuccess?: (data: TData) => void }) => void;
+  variables?: TVariables | undefined;
+  isPending: boolean;
+  error: unknown;
+}
+
+/** A mutation that never writes — what a read-only body receives, and what a test passes when writes are out of its scope. */
+export function idleMutation<TVariables, TData = unknown>(): MutationLike<TVariables, TData> {
+  return { mutate: () => undefined, variables: undefined, isPending: false, error: null };
+}
+
+/** The loading state of a read: nothing served yet, nothing failed. */
+export function pendingQuery<TData>(): QueryLike<TData> {
+  return { data: undefined, error: null };
+}
+
+/** The failed state of a read: the error a container would have received. */
+export function failedQuery(error: unknown): QueryLike<never> {
+  return { data: undefined, error };
+}
+
+/** The served state of a read. */
+export function readyQuery<TData>(data: TData): QueryLike<TData> {
+  return { data, error: null };
+}