@stigmer/react 3.2.3 → 3.3.0

package/src/datastore/__tests__/recordValues.test.ts

@@ -0,0 +1,359 @@
+// Tests for the client-side projection of the DD-004 canonical value
+// contract. The cases mirror the authoritative Go schema tests
+// (pkg/domain/datastore/schema) so a drift between projection and
+// enforcement shows up here first.
+
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import {
+  FieldDeclarationSchema,
+  FieldType,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/spec_pb";
+import { RecordConditionOp } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
+import {
+  buildUpdateFields,
+  coerceFieldValue,
+  formatFieldValue,
+  formatSystemTimestamp,
+  isListOperator,
+  isSortableField,
+  isValuelessOperator,
+  operatorsForField,
+  RESERVED_FIELD_NAMES,
+  SYSTEM_FIELD_OPERATORS,
+} from "../recordValues.js";
+
+function field(overrides: {
+  name?: string;
+  type: FieldType;
+  required?: boolean;
+  enumValues?: string[];
+}) {
+  return create(FieldDeclarationSchema, {
+    name: overrides.name ?? "f",
+    type: overrides.type,
+    required: overrides.required ?? false,
+    enumValues: overrides.enumValues ?? [],
+  });
+}
+
+describe("coerceFieldValue", () => {
+  it("passes explicit null through for every type (tri-state clear)", () => {
+    for (const type of [
+      FieldType.string,
+      FieldType.integer,
+      FieldType.number,
+      FieldType.bool,
+      FieldType.timestamp,
+      FieldType.date,
+      FieldType.time,
+      FieldType.json,
+    ]) {
+      expect(coerceFieldValue(field({ type }), null)).toEqual({ ok: true, value: null });
+    }
+  });
+
+  describe("string", () => {
+    it("accepts a plain string", () => {
+      expect(coerceFieldValue(field({ type: FieldType.string }), "hello")).toEqual({
+        ok: true,
+        value: "hello",
+      });
+    });
+
+    it("rejects non-strings", () => {
+      const r = coerceFieldValue(field({ name: "note", type: FieldType.string }), 5);
+      expect(r).toEqual({ ok: false, error: 'field "note" must be a string' });
+    });
+
+    it("enforces enum_values membership", () => {
+      const f = field({
+        name: "status",
+        type: FieldType.string,
+        enumValues: ["confirmed", "cancelled"],
+      });
+      expect(coerceFieldValue(f, "confirmed")).toEqual({ ok: true, value: "confirmed" });
+      expect(coerceFieldValue(f, "pending")).toEqual({
+        ok: false,
+        error: 'field "status" must be one of [confirmed cancelled]',
+      });
+    });
+  });
+
+  describe("integer", () => {
+    it("accepts integral numbers", () => {
+      expect(coerceFieldValue(field({ type: FieldType.integer }), 42)).toEqual({
+        ok: true,
+        value: 42,
+      });
+      expect(coerceFieldValue(field({ type: FieldType.integer }), -7)).toEqual({
+        ok: true,
+        value: -7,
+      });
+      expect(coerceFieldValue(field({ type: FieldType.integer }), 0)).toEqual({
+        ok: true,
+        value: 0,
+      });
+    });
+
+    it("rejects fractional, non-numeric, and unsafe values", () => {
+      const f = field({ name: "n", type: FieldType.integer });
+      expect(coerceFieldValue(f, 1.5)).toMatchObject({ ok: false });
+      expect(coerceFieldValue(f, "3")).toMatchObject({ ok: false });
+      expect(coerceFieldValue(f, Number.MAX_SAFE_INTEGER + 2)).toMatchObject({ ok: false });
+    });
+  });
+
+  describe("number", () => {
+    it("accepts finite numbers", () => {
+      expect(coerceFieldValue(field({ type: FieldType.number }), 3.14)).toEqual({
+        ok: true,
+        value: 3.14,
+      });
+    });
+
+    it("rejects non-numbers and non-finite values", () => {
+      const f = field({ name: "n", type: FieldType.number });
+      expect(coerceFieldValue(f, "3.14")).toMatchObject({ ok: false });
+      expect(coerceFieldValue(f, Number.POSITIVE_INFINITY)).toMatchObject({ ok: false });
+      expect(coerceFieldValue(f, Number.NaN)).toMatchObject({ ok: false });
+    });
+  });
+
+  describe("bool", () => {
+    it("accepts booleans and rejects everything else", () => {
+      const f = field({ name: "b", type: FieldType.bool });
+      expect(coerceFieldValue(f, true)).toEqual({ ok: true, value: true });
+      expect(coerceFieldValue(f, false)).toEqual({ ok: true, value: false });
+      expect(coerceFieldValue(f, "true")).toMatchObject({ ok: false });
+      expect(coerceFieldValue(f, 1)).toMatchObject({ ok: false });
+    });
+  });
+
+  describe("timestamp", () => {
+    const f = field({ name: "at", type: FieldType.timestamp });
+
+    it("accepts RFC 3339 UTC and offset forms", () => {
+      expect(coerceFieldValue(f, "2026-07-21T04:30:00Z")).toEqual({
+        ok: true,
+        value: "2026-07-21T04:30:00Z",
+      });
+      expect(coerceFieldValue(f, "2026-07-21T04:30:00.123Z")).toMatchObject({ ok: true });
+      expect(coerceFieldValue(f, "2026-07-21T10:00:00+05:30")).toMatchObject({ ok: true });
+    });
+
+    it("rejects date-only, missing zone, and garbage", () => {
+      expect(coerceFieldValue(f, "2026-07-21")).toMatchObject({ ok: false });
+      expect(coerceFieldValue(f, "2026-07-21T04:30:00")).toMatchObject({ ok: false });
+      expect(coerceFieldValue(f, "yesterday")).toMatchObject({ ok: false });
+      expect(coerceFieldValue(f, 1721536200)).toMatchObject({ ok: false });
+    });
+  });
+
+  describe("date", () => {
+    const f = field({ name: "day", type: FieldType.date });
+
+    it("accepts valid YYYY-MM-DD", () => {
+      expect(coerceFieldValue(f, "2026-07-21")).toEqual({ ok: true, value: "2026-07-21" });
+      expect(coerceFieldValue(f, "2024-02-29")).toMatchObject({ ok: true }); // leap day
+    });
+
+    it("rejects impossible dates and other shapes", () => {
+      expect(coerceFieldValue(f, "2026-02-30")).toMatchObject({ ok: false });
+      expect(coerceFieldValue(f, "2026-13-01")).toMatchObject({ ok: false });
+      expect(coerceFieldValue(f, "2023-02-29")).toMatchObject({ ok: false }); // not a leap year
+      expect(coerceFieldValue(f, "21-07-2026")).toMatchObject({ ok: false });
+      expect(coerceFieldValue(f, "2026-7-1")).toMatchObject({ ok: false }); // unpadded
+    });
+  });
+
+  describe("time", () => {
+    const f = field({ name: "slot", type: FieldType.time });
+
+    it("canonicalizes HH:MM to HH:MM:SS", () => {
+      expect(coerceFieldValue(f, "09:30")).toEqual({ ok: true, value: "09:30:00" });
+    });
+
+    it("passes HH:MM:SS through", () => {
+      expect(coerceFieldValue(f, "23:59:59")).toEqual({ ok: true, value: "23:59:59" });
+    });
+
+    it("rejects unpadded, out-of-range, and garbage input", () => {
+      expect(coerceFieldValue(f, "9:30")).toMatchObject({ ok: false }); // unpadded
+      expect(coerceFieldValue(f, "24:00")).toMatchObject({ ok: false });
+      expect(coerceFieldValue(f, "12:60")).toMatchObject({ ok: false });
+      expect(coerceFieldValue(f, "12:00:60")).toMatchObject({ ok: false });
+      expect(coerceFieldValue(f, "noon")).toMatchObject({ ok: false });
+    });
+  });
+
+  describe("json", () => {
+    it("passes any JSON value through untouched", () => {
+      const f = field({ type: FieldType.json });
+      const nested = { a: [1, "two", { three: true }] };
+      expect(coerceFieldValue(f, nested)).toEqual({ ok: true, value: nested });
+      expect(coerceFieldValue(f, [1, 2])).toMatchObject({ ok: true });
+      expect(coerceFieldValue(f, "plain")).toMatchObject({ ok: true });
+    });
+  });
+
+  it("rejects unspecified field types", () => {
+    expect(
+      coerceFieldValue(field({ type: FieldType.field_type_unspecified }), "x"),
+    ).toMatchObject({ ok: false });
+  });
+});
+
+describe("formatFieldValue", () => {
+  it("renders null/undefined as empty", () => {
+    expect(formatFieldValue(FieldType.string, null)).toBe("");
+    expect(formatFieldValue(FieldType.integer, undefined)).toBe("");
+  });
+
+  it("trims the stored timestamp's zero fraction", () => {
+    expect(formatFieldValue(FieldType.timestamp, "2026-07-21T04:30:00.000000000Z")).toBe(
+      "2026-07-21T04:30:00Z",
+    );
+    // Non-zero fractions carry information and stay.
+    expect(formatFieldValue(FieldType.timestamp, "2026-07-21T04:30:00.500000000Z")).toBe(
+      "2026-07-21T04:30:00.500000000Z",
+    );
+  });
+
+  it("stringifies json values compactly", () => {
+    expect(formatFieldValue(FieldType.json, { a: 1 })).toBe('{"a":1}');
+  });
+
+  it("renders scalars canonically", () => {
+    expect(formatFieldValue(FieldType.bool, true)).toBe("true");
+    expect(formatFieldValue(FieldType.integer, 42)).toBe("42");
+    expect(formatFieldValue(FieldType.date, "2026-07-21")).toBe("2026-07-21");
+  });
+
+  it("formats system timestamps the same way", () => {
+    expect(formatSystemTimestamp("2026-07-21T04:30:00.000000000Z")).toBe(
+      "2026-07-21T04:30:00Z",
+    );
+  });
+});
+
+describe("operator matrix", () => {
+  it("string fields get equality operators", () => {
+    expect(operatorsForField(field({ type: FieldType.string, required: true }))).toEqual([
+      RecordConditionOp.eq,
+      RecordConditionOp.neq,
+      RecordConditionOp.is_in,
+      RecordConditionOp.not_in,
+    ]);
+  });
+
+  it("bool fields get eq/neq only", () => {
+    expect(operatorsForField(field({ type: FieldType.bool, required: true }))).toEqual([
+      RecordConditionOp.eq,
+      RecordConditionOp.neq,
+    ]);
+  });
+
+  it("numeric and temporal fields get range operators", () => {
+    for (const type of [
+      FieldType.integer,
+      FieldType.number,
+      FieldType.timestamp,
+      FieldType.date,
+      FieldType.time,
+    ]) {
+      expect(operatorsForField(field({ type, required: true }))).toEqual([
+        RecordConditionOp.eq,
+        RecordConditionOp.neq,
+        RecordConditionOp.gt,
+        RecordConditionOp.gte,
+        RecordConditionOp.lt,
+        RecordConditionOp.lte,
+      ]);
+    }
+  });
+
+  it("json fields are not filterable — even optional ones get no null tests", () => {
+    expect(operatorsForField(field({ type: FieldType.json }))).toEqual([]);
+  });
+
+  it("optional fields additionally get null tests", () => {
+    const ops = operatorsForField(field({ type: FieldType.string, required: false }));
+    expect(ops).toContain(RecordConditionOp.is_null);
+    expect(ops).toContain(RecordConditionOp.not_null);
+  });
+
+  it("required fields never get null tests", () => {
+    const ops = operatorsForField(field({ type: FieldType.string, required: true }));
+    expect(ops).not.toContain(RecordConditionOp.is_null);
+    expect(ops).not.toContain(RecordConditionOp.not_null);
+  });
+
+  it("system fields mirror the server matrix", () => {
+    expect(SYSTEM_FIELD_OPERATORS.get("id")).toEqual([
+      RecordConditionOp.eq,
+      RecordConditionOp.is_in,
+    ]);
+    expect(SYSTEM_FIELD_OPERATORS.get("created_at")).toEqual([
+      RecordConditionOp.gt,
+      RecordConditionOp.gte,
+      RecordConditionOp.lt,
+      RecordConditionOp.lte,
+    ]);
+    expect(SYSTEM_FIELD_OPERATORS.get("updated_at")).toEqual(
+      SYSTEM_FIELD_OPERATORS.get("created_at"),
+    );
+    // Not filterable: attribution and ambient scope.
+    expect(SYSTEM_FIELD_OPERATORS.has("created_by")).toBe(false);
+    expect(SYSTEM_FIELD_OPERATORS.has("org")).toBe(false);
+    expect(SYSTEM_FIELD_OPERATORS.has("partition")).toBe(false);
+  });
+
+  it("classifies operator arity", () => {
+    expect(isValuelessOperator(RecordConditionOp.is_null)).toBe(true);
+    expect(isValuelessOperator(RecordConditionOp.not_null)).toBe(true);
+    expect(isValuelessOperator(RecordConditionOp.eq)).toBe(false);
+    expect(isListOperator(RecordConditionOp.is_in)).toBe(true);
+    expect(isListOperator(RecordConditionOp.not_in)).toBe(true);
+    expect(isListOperator(RecordConditionOp.eq)).toBe(false);
+  });
+});
+
+describe("isSortableField", () => {
+  it("declared non-json fields sort; json does not", () => {
+    expect(isSortableField(field({ type: FieldType.date }))).toBe(true);
+    expect(isSortableField(field({ type: FieldType.string }))).toBe(true);
+    expect(isSortableField(field({ type: FieldType.json }))).toBe(false);
+    expect(isSortableField(field({ type: FieldType.field_type_unspecified }))).toBe(false);
+  });
+});
+
+describe("buildUpdateFields", () => {
+  it("carries dirty values and explicit nulls, omits untouched fields", () => {
+    const payload = buildUpdateFields(
+      new Map<string, string | null>([
+        ["patient_phone", "+15550100"],
+        ["notes", null],
+      ]),
+    );
+    expect(payload).toEqual({ patient_phone: "+15550100", notes: null });
+    expect("slot_time" in payload).toBe(false);
+  });
+
+  it("produces an empty object for no edits", () => {
+    expect(buildUpdateFields(new Map())).toEqual({});
+  });
+});
+
+describe("RESERVED_FIELD_NAMES", () => {
+  it("matches the server's reserved set", () => {
+    expect([...RESERVED_FIELD_NAMES].sort()).toEqual([
+      "created_at",
+      "created_by",
+      "id",
+      "org",
+      "partition",
+      "updated_at",
+    ]);
+  });
+});

package/src/datastore/__tests__/schemaAndSyncViews.test.tsx

@@ -0,0 +1,142 @@
+// Render tests for the two Overview views: the schema view (spec for
+// structure — fields, constraints with authored messages, authorization
+// summary) and the sync report (status for health).
+
+import { describe, it, expect, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import {
+  DatastoreSpecSchema,
+  FieldType,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/spec_pb";
+import {
+  CollectionMaterializationState,
+  DatastoreStatusSchema,
+  DatastoreSyncOutcome,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/status_pb";
+import { CollectionSchemaView, formatSubject } from "../CollectionSchemaView";
+import { DatastoreSyncReport } from "../DatastoreSyncReport";
+
+afterEach(() => cleanup());
+
+describe("CollectionSchemaView", () => {
+  const spec = create(DatastoreSpecSchema, {
+    timezone: "Asia/Kolkata",
+    authorization: {
+      roles: [{ name: "admin" }, { name: "patient" }],
+      defaultRole: "patient",
+      bindings: [
+        {
+          subject: {
+            kind: { case: "channelSender", value: { senderKind: "whatsapp", value: "+15550100" } },
+          },
+          role: "admin",
+        },
+      ],
+    },
+    collections: [
+      {
+        name: "bookings",
+        description: "Confirmed appointments",
+        fields: [
+          { name: "slot_date", type: FieldType.date, required: true },
+          {
+            name: "status",
+            type: FieldType.string,
+            enumValues: ["confirmed", "cancelled"],
+            description: "Booking lifecycle",
+          },
+        ],
+        uniques: [
+          {
+            name: "one_confirmed_per_slot",
+            fields: ["slot_date"],
+            message: "that slot is already booked",
+          },
+        ],
+      },
+    ],
+  });
+
+  it("renders fields, enum values, and required markers", () => {
+    render(<CollectionSchemaView spec={spec} />);
+    expect(screen.getByText("slot_date")).toBeTruthy();
+    expect(screen.getByText(/confirmed \| cancelled/)).toBeTruthy();
+    expect(screen.getByText("Booking lifecycle")).toBeTruthy();
+  });
+
+  it("renders constraints with the operator's authored message verbatim", () => {
+    render(<CollectionSchemaView spec={spec} />);
+    expect(screen.getByText("one_confirmed_per_slot")).toBeTruthy();
+    expect(screen.getByText(/that slot is already booked/)).toBeTruthy();
+  });
+
+  it("summarizes the authorization block: roles, bindings, default_role, timezone", () => {
+    render(<CollectionSchemaView spec={spec} />);
+    // "admin" appears as a role chip and as the binding's role.
+    expect(screen.getAllByText("admin").length).toBeGreaterThan(0);
+    // "patient" appears as a role chip and as the default_role chip.
+    expect(screen.getAllByText("patient").length).toBeGreaterThan(0);
+    expect(screen.getByText("whatsapp:+15550100")).toBeTruthy();
+    expect(screen.getByText("Asia/Kolkata")).toBeTruthy();
+  });
+
+  it("states the deny-by-default posture when no default_role is set", () => {
+    const noDefault = create(DatastoreSpecSchema, {
+      authorization: { roles: [{ name: "admin" }] },
+      collections: [{ name: "c", fields: [{ name: "f", type: FieldType.string }] }],
+    });
+    render(<CollectionSchemaView spec={noDefault} />);
+    expect(screen.getByText(/unbound callers are denied/)).toBeTruthy();
+  });
+});
+
+describe("formatSubject", () => {
+  it("renders channel senders and principals plainly", () => {
+    expect(
+      formatSubject({
+        kind: { case: "channelSender", value: { senderKind: "whatsapp", value: "+1" } },
+      } as never),
+    ).toBe("whatsapp:+1");
+    expect(
+      formatSubject({
+        kind: { case: "principal", value: { kind: "identity_account", id: "ida_1" } },
+      } as never),
+    ).toBe("identity_account/ida_1");
+    expect(formatSubject(undefined)).toBe("unknown");
+  });
+});
+
+describe("DatastoreSyncReport", () => {
+  it("renders the outcome badge and per-collection counts", () => {
+    const status = create(DatastoreStatusSchema, {
+      lastSyncOutcome: DatastoreSyncOutcome.synced,
+      collections: [
+        {
+          name: "bookings",
+          state: CollectionMaterializationState.active,
+          recordCount: 214n,
+        },
+        {
+          name: "old_notes",
+          state: CollectionMaterializationState.removed,
+          recordCount: 3n,
+        },
+      ],
+    });
+    render(<DatastoreSyncReport status={status} />);
+    expect(screen.getByText("synced")).toBeTruthy();
+    expect(screen.getByText("214")).toBeTruthy();
+    expect(screen.getByText("active")).toBeTruthy();
+    expect(screen.getByText("removed")).toBeTruthy();
+  });
+
+  it("renders the rejected outcome", () => {
+    const status = create(DatastoreStatusSchema, {
+      lastSyncOutcome: DatastoreSyncOutcome.rejected,
+    });
+    render(<DatastoreSyncReport status={status} />);
+    expect(screen.getByText("rejected")).toBeTruthy();
+    expect(screen.getByText(/No collections have been synced yet/)).toBeTruthy();
+  });
+});

package/src/datastore/__tests__/useDatastoreDescription.test.tsx

@@ -0,0 +1,143 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import { DatastoreDescriptionSchema } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { useDatastoreDescription } from "../useDatastoreDescription";
+
+function createMockStigmer(overrides: {
+  describeDatastore?: (...args: unknown[]) => Promise<unknown>;
+} = {}) {
+  return {
+    datastore: {
+      describeDatastore:
+        overrides.describeDatastore ?? vi.fn().mockResolvedValue(null),
+    },
+  } as never;
+}
+
+function wrapper(client: unknown) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={null}>
+        <StigmerContext.Provider value={client as never}>
+          {children}
+        </StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  };
+}
+
+describe("useDatastoreDescription", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("fetches the description and passes org + datastore through", async () => {
+    const description = create(DatastoreDescriptionSchema, {
+      datastore: "clinic",
+      partitions: ["default", "dr-alt"],
+    });
+    const describeDatastore = vi.fn().mockResolvedValue(description);
+    const client = createMockStigmer({ describeDatastore });
+
+    const { result } = renderHook(() => useDatastoreDescription("acme", "clinic"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.description).toBe(description);
+    expect(describeDatastore).toHaveBeenCalledWith(
+      expect.objectContaining({ org: "acme", datastore: "clinic" }),
+    );
+  });
+
+  it("always offers the default partition even when the catalog is empty", async () => {
+    // The catalog materializes with the first record write; an empty
+    // datastore reports no partitions but "default" is always addressable.
+    const description = create(DatastoreDescriptionSchema, {
+      datastore: "clinic",
+      partitions: [],
+    });
+    const client = createMockStigmer({
+      describeDatastore: vi.fn().mockResolvedValue(description),
+    });
+
+    const { result } = renderHook(() => useDatastoreDescription("acme", "clinic"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.partitions).toEqual(["default"]);
+  });
+
+  it("prepends default when the catalog holds only named partitions", async () => {
+    const description = create(DatastoreDescriptionSchema, {
+      datastore: "clinic",
+      partitions: ["dr-alt"],
+    });
+    const client = createMockStigmer({
+      describeDatastore: vi.fn().mockResolvedValue(description),
+    });
+
+    const { result } = renderHook(() => useDatastoreDescription("acme", "clinic"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.partitions).toEqual(["default", "dr-alt"]);
+  });
+
+  it("does not duplicate default when the catalog already carries it", async () => {
+    const description = create(DatastoreDescriptionSchema, {
+      datastore: "clinic",
+      partitions: ["default", "dr-alt"],
+    });
+    const client = createMockStigmer({
+      describeDatastore: vi.fn().mockResolvedValue(description),
+    });
+
+    const { result } = renderHook(() => useDatastoreDescription("acme", "clinic"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.partitions).toEqual(["default", "dr-alt"]);
+  });
+
+  it("skips fetching when org or datastore is null", () => {
+    const describeDatastore = vi.fn();
+    const client = createMockStigmer({ describeDatastore });
+
+    const { result } = renderHook(() => useDatastoreDescription(null, "clinic"), {
+      wrapper: wrapper(client),
+    });
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.description).toBeNull();
+    expect(result.current.partitions).toEqual(["default"]);
+    expect(describeDatastore).not.toHaveBeenCalled();
+  });
+
+  it("surfaces PERMISSION_DENIED as error — the defensive denied-state branch", async () => {
+    // A reach-level denial must be catchable and rendered as the
+    // Records-tab denied panel, never a page-level failure.
+    const denial = new Error("unauthorized to use records in this datastore");
+    const client = createMockStigmer({
+      describeDatastore: vi.fn().mockRejectedValue(denial),
+    });
+
+    const { result } = renderHook(() => useDatastoreDescription("acme", "clinic"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.error?.message).toBe(
+      "unauthorized to use records in this datastore",
+    );
+    expect(result.current.description).toBeNull();
+  });
+});