@geniee-inc/sfa-kit 1.8.0 → 1.10.0

package/GUIDE.md

@@ -18,7 +18,7 @@ The package ships built JavaScript and TypeScript declarations only. It contains
 
 ```ts
 import pkg from '@geniee-inc/sfa-kit/package.json';
-// pkg.version -> '1.8.0'
+// pkg.version -> '1.10.0'
 ```
 
 Two additional subpaths are available: `@geniee-inc/sfa-kit/signing` exposes bundle-signing utilities (`computeContentHash`, `computeSignature`, `createManifest`, `createManifestFromDirectory`) for Node.js environments, and `./package.json` exposes the manifest. Internal modules cannot be imported directly.
@@ -137,10 +137,23 @@ Returns `{ record: SfaRecord | null, isLoading, error, refetch }`.
 Fetches a paginated list of records. Supports cursor-based pagination (Keystone API).
 
 ```tsx
-import { useRecordList } from '@geniee-inc/sfa-kit';
-
-const { items, totalCount, hasMore, pageIndex, goToPage, isLoading, error } =
-  useRecordList('companies');
+import { useRecordList, FetchErrorState } from '@geniee-inc/sfa-kit';
+
+const {
+  items,
+  totalCount,
+  hasMore,
+  pageIndex,
+  goToPage,
+  status,
+  isLoading,
+  refetch,
+} = useRecordList('companies');
+
+// `items` describes the server only when the fetch succeeded. Render the
+// failure before the list, or a rate limit shows up as "0 records".
+if (status === 'error') return <FetchErrorState onRetry={refetch} />;
+if (isLoading) return <p>Loading...</p>;
 
 // With params
 const result = useRecordList('companies', {
@@ -150,6 +163,10 @@ const result = useRecordList('companies', {
 });
 ```
 
+**Starting position** — `offset` is a record position (`limit` 20 with `offset` 40 starts on page 2) and `cursor` names the same point opaquely. Both describe the _first_ page only: from there `goToPage` computes offsets from the page number and reuses the cursors the server hands back. Changing either starts a new query, so `status` reads `'loading'` with no items until the fetch from the new position settles.
+
+Against Keystone (`apiBase` pointing at the API directly) pagination is **cursor-only** — `records/query` takes no offset. Pages are reached in order: the first page needs no cursor, and each response carries the cursor for the next one. Asking to start at `offset > 0` without the cursor for that page fails with an explanatory error rather than quietly answering with the first page, so `status` reads `'error'` and the caller can retry or start from the beginning.
+
 **Filters** must use react-querybuilder shape with `combinator` and `rules`. The backend rejects any other format with a 422.
 
 ```tsx
@@ -164,6 +181,14 @@ const result = useRecordList('companies', {
 });
 ```
 
+**`status`** is the one field to branch on, and it always describes the query the hook is being asked about right now: `'idle'` (nothing will be fetched and nothing is known), `'loading'` (a fetch is in flight, or the query just changed and its fetch has not settled), `'success'` (the fetch for _this_ query completed and `items` came from the server), `'error'` (the fetch for _this_ query failed). Changing `collection`, `filter`, `sortBy`, `limit`, `offset` or `cursor` starts a new query: from that render on, `status` is `'loading'` and `items` is empty until the new fetch settles — the previous query's records, counts and error are never published as this query's answer. The client counts as part of the query: `SfaProvider` builds a new one whenever the access token, `organizationId`, `apiBase`, `mode` or `readOnly` change, so the same collection and filter can address a different organization. A failed fetch keeps the last successful `items` rather than emptying them, so an error never fabricates a zero — but it also means `items.length === 0` is only a real "the server has none" when `status === 'success'`.
+
+`refetch` retries what the reader was trying to reach: after a failed page turn it asks for the page that failed, not the one still on screen. `pageIndex` follows the records being displayed, so the two differ only while an error is showing; once a fetch succeeds they are the same again and `refetch` targets the current page.
+
+Disabling the hook, or clearing `collection`, discards any request still in flight: a response that lands after the caller stopped asking never becomes the result, and the `'loading'` a discarded refetch set does not outlive it — the hook goes back to how the query last ended.
+
+Returns `{ items, totalCount, hasMore, pageIndex, status, isLoading, error, refetch, goToPage }`.
+
 For cross-object queries (fetching child records of a parent), prefer `useRelatedRecords` which builds the filter automatically from describe metadata.
 
 ### useRelatedRecords
@@ -232,14 +257,18 @@ const { items, isLoading, error } = useRelatedRecords(
 );
 ```
 
-**Error handling:** If the relationship doesn't exist in the parent's metadata, the hook returns a `RelationNotFoundError` with an `availableTargets` list so the caller can self-correct.
+**Error handling:** `status` and `error` cover all three steps — a failed describe, a missing relationship, and a failed list fetch. If the relationship doesn't exist in the parent's metadata, `error` is a `RelationNotFoundError` with an `availableTargets` list so the caller can self-correct.
+
+Check `status` for **every** hook on the page, not just the first one. Each related-records hook fails independently: with several fetches firing on mount, one can hit a rate limit or a timeout while the others succeed, and the failed one renders as an empty section unless its own status is read.
 
-Returns `{ items, totalCount, hasMore, pageIndex, goToPage, isLoading, error, refetch, relationship }`.
+Returns `{ items, totalCount, hasMore, pageIndex, status, goToPage, isLoading, error, refetch, relationship }`.
 
 ### useDescribe
 
 Discovers object schema — fields, types, relationships, permissions. Use this to build dynamic UIs that adapt to any object.
 
+`object`, `isLoading` and `error` always describe the key passed right now, through the client in use right now. Changing either reports `isLoading` with a `null` object until the new fetch settles, so one object's metadata — or one organization's schema — is never attributed to another.
+
 ```tsx
 import { useDescribe } from '@geniee-inc/sfa-kit';
 
@@ -299,6 +328,63 @@ Access field values: `record.fields['company_name']?.value` for the raw value, `
 
 ## Error handling
 
+### Fetch errors are returned, not thrown
+
+Every data hook reports a failed fetch through its own `status` / `error`. Nothing throws, so `ErrorBoundary` does not see these — the page must branch on them itself. Skipping that check is the one mistake that is invisible in review: the page renders, with an empty list and a count of 0, and looks exactly like a record that genuinely has no children.
+
+Branch in this order, for **every** hook on the page:
+
+```tsx
+import {
+  useRelatedRecords,
+  FetchErrorState,
+  EmptyState,
+} from '@geniee-inc/sfa-kit';
+
+const { items, status, refetch } = useRelatedRecords(
+  'companies',
+  companyId,
+  'tasks'
+);
+
+// 1. Failure first: never fall through to a count or an empty list
+if (status === 'error')
+  return <FetchErrorState onRetry={refetch} message="タスクの取得に失敗" />;
+
+// 2. Nothing was fetched yet
+if (status === 'loading' || status === 'idle') return <p>Loading...</p>;
+
+// 3. Only now is an empty list a fact about the server
+if (items.length === 0) return <EmptyState message="タスクはありません" />;
+
+return (
+  <>
+    <h2>タスク ({items.length})</h2>
+    {items.map(task => (
+      <p key={task.record_id}>{task.title ?? task.record_id}</p>
+    ))}
+  </>
+);
+```
+
+Reading `items` before step 1 is what turns a rate limit into a confident `タスク (0)`. Each hook fails on its own, so one section can fail while the rest of the page renders normally — a shared `if (aError || bError)` at the top hides which one it was and blanks the sections that did load.
+
+Two components exist for the two states so they are never confused:
+
+### FetchErrorState
+
+The state for `status === 'error'`. Renders `⚠ 取得失敗` and, when given `onRetry`, a `再取得` link that refetches in place.
+
+```tsx
+<FetchErrorState onRetry={refetch} message="タスクの取得に失敗" />
+```
+
+Props: `{ onRetry?: () => void, message?: string, retryLabel?: string }`. Without `onRetry` no link is rendered — a dead control is worse than none.
+
+The server's error text is deliberately not shown: it is wording the reader cannot act on. Pages that need it still have `error` from the hook, and `RecordList` / `RecordView` report it through their `onError` prop.
+
+`refetch` retries whichever step failed. On `useRelatedRecords` that includes a failed describe: retrying only the list would do nothing, because without relationship metadata the list never ran.
+
 Two baseline components for resilient pages:
 
 ### ErrorBoundary
@@ -315,7 +401,7 @@ import { ErrorBoundary } from '@geniee-inc/sfa-kit';
 
 ### EmptyState
 
-Placeholder for pages with no data.
+Placeholder for pages with no data. Use it only once `status === 'success'` — before that an empty list means "not known", and "no data" states a fact the page never got back from the server.
 
 ```tsx
 import { EmptyState } from '@geniee-inc/sfa-kit';
@@ -383,6 +469,9 @@ Props:
 - `onRowClick` (optional) - `(record) => void` callback.
 - `showPagination` (optional) - Default true.
 - `params` (optional) - `{ limit?, offset?, sortBy?, sortOrder?, filter?, cursor? }`.
+- `errorMessage` (optional) - what to say when the fetch fails, e.g. `"タスクの取得に失敗"`. `RecordList` has nothing to fall back on, so on a page with several sections pass the label that section already displays — a failure then says which one it was. `collection` is never used for this: it is the object key the API is addressed with (`business_discussions`), not something to show a reader.
+
+`RecordView` takes the same prop and, without it, names its `title` — the label it already shows as the heading — so a page that passed `title="会社"` gets `⚠ 会社の取得に失敗` for free.
 
 ### FieldRenderer
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geniee-inc/sfa-kit",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "React hooks and components for building pages that connect to GENIEE SFA/CRM data.",
   "type": "module",
   "main": "./src/index.js",

package/src/index.d.ts

@@ -9,6 +9,7 @@ export type { EmbedContext } from './lib/auth/embed-protocol';
 export type { StandalonePreviewState, StandalonePreviewControls, } from './lib/auth/StandalonePreviewContext';
 export { useRecord } from './lib/hooks/useRecord';
 export { useRecordList } from './lib/hooks/useRecordList';
+export type { SfaListStatus } from './lib/hooks/useRecordList';
 export { useDescribe } from './lib/hooks/useDescribe';
 export { useObjectCatalog } from './lib/hooks/useObjectCatalog';
 export { useFieldTypes } from './lib/hooks/useFieldTypes';
@@ -25,6 +26,7 @@ export { RecordView } from './lib/components/RecordView';
 export { RecordList } from './lib/components/RecordList';
 export { ErrorBoundary } from './lib/components/ErrorBoundary';
 export { EmptyState } from './lib/components/EmptyState';
+export { FetchErrorState } from './lib/components/FetchErrorState';
 export type { SfaAuth, SfaApiMode, SfaClientConfig, SfaRecord, SfaListResponse, SfaListParams, SfaFieldValue, SfaFieldKind, SfaFieldValueMapping, FieldGroupSpec, FieldGroupLayout, SfaFieldDescriptor, SfaFieldOption, SfaRelationDescriptor, SfaObjectDetail, SfaObjectSummary, SfaObjectCatalog, SfaObjectPermissions, SfaObjectOrigin, SfaRelationshipKind, SfaCardinality, SfaDescribeResult, SfaFieldTypeDescriptor, SfaFieldTypeCatalog, SfaFilterOperator, SfaCreateOptions, SfaFieldError, } from './lib/provider/types';
 export type { SfaSession, AuthResult, OrganizationChoice, } from './lib/auth/types';
 export { buildRecordDetailUrl, resolveHostOrigin, } from './lib/navigation/record-detail-url';

package/src/index.js

@@ -19,5 +19,6 @@ export { RecordView } from './lib/components/RecordView';
 export { RecordList } from './lib/components/RecordList';
 export { ErrorBoundary } from './lib/components/ErrorBoundary';
 export { EmptyState } from './lib/components/EmptyState';
+export { FetchErrorState } from './lib/components/FetchErrorState';
 export { buildRecordDetailUrl, resolveHostOrigin, } from './lib/navigation/record-detail-url';
 export { useRecordDetailUrl } from './lib/hooks/useRecordDetailUrl';

package/src/lib/components/FetchErrorState.d.ts

@@ -0,0 +1,32 @@
+interface FetchErrorStateProps {
+    /** Runs the fetch again. Pass the hook's `refetch`. */
+    readonly onRetry?: () => void;
+    /** Label text after the warning mark. Override to name what failed. */
+    readonly message?: string;
+    readonly retryLabel?: string;
+}
+/**
+ * @description The state to render when a data hook reports
+ * `status === 'error'`. Says the fetch failed and offers a retry, so a rate
+ * limit or a dropped connection is never shown as an empty list.
+ *
+ * Do not use `EmptyState` for this: "no data" claims something the page
+ * never got back from the server, and gives the user nothing to act on.
+ *
+ * The underlying error is not shown: it is server wording the reader cannot
+ * act on. Pages that need it still have `error` from the hook, and
+ * RecordList / RecordView report it through their `onError` prop.
+ *
+ * ```tsx
+ * const { items, status, refetch } = useRelatedRecords(
+ *   'companies',
+ *   companyId,
+ *   'tasks'
+ * );
+ *
+ * if (status === 'error')
+ *   return <FetchErrorState onRetry={refetch} message="タスクの取得に失敗" />;
+ * ```
+ */
+export declare function FetchErrorState({ onRetry, message, retryLabel, }: FetchErrorStateProps): JSX.Element;
+export {};

package/src/lib/components/FetchErrorState.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { color, font, space, baseContainerStyle } from '../theme';
+/**
+ * @description The state to render when a data hook reports
+ * `status === 'error'`. Says the fetch failed and offers a retry, so a rate
+ * limit or a dropped connection is never shown as an empty list.
+ *
+ * Do not use `EmptyState` for this: "no data" claims something the page
+ * never got back from the server, and gives the user nothing to act on.
+ *
+ * The underlying error is not shown: it is server wording the reader cannot
+ * act on. Pages that need it still have `error` from the hook, and
+ * RecordList / RecordView report it through their `onError` prop.
+ *
+ * ```tsx
+ * const { items, status, refetch } = useRelatedRecords(
+ *   'companies',
+ *   companyId,
+ *   'tasks'
+ * );
+ *
+ * if (status === 'error')
+ *   return <FetchErrorState onRetry={refetch} message="タスクの取得に失敗" />;
+ * ```
+ */
+export function FetchErrorState({ onRetry, message = '取得失敗', retryLabel = '再取得', }) {
+    return (_jsxs("div", { style: styles.container, children: [_jsxs("p", { style: styles.message, role: "alert", children: [_jsx("span", { "aria-hidden": "true", children: "\u26A0" }), " ", message] }), onRetry && (_jsx("button", { type: "button", style: styles.retryLink, onClick: onRetry, children: retryLabel }))] }));
+}
+const styles = {
+    container: Object.assign(Object.assign({}, baseContainerStyle), { display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', padding: space.lg, textAlign: 'center' }),
+    message: {
+        fontSize: font.sizeMd,
+        fontWeight: font.weightMedium,
+        color: color.error,
+        margin: `0 0 ${space.sm}px`,
+    },
+    retryLink: {
+        padding: 0,
+        fontFamily: font.family,
+        fontSize: font.sizeMd,
+        color: color.primary,
+        backgroundColor: 'transparent',
+        border: 'none',
+        textDecoration: 'underline',
+        cursor: 'pointer',
+    },
+};

package/src/lib/components/RecordList.d.ts

@@ -12,9 +12,18 @@ interface RecordListProps {
     readonly showPagination?: boolean;
     readonly onRowClick?: (record: SfaRecord) => void;
     readonly onError?: (error: Error) => void;
+    /**
+     * What to say when the fetch fails. Defaults to a generic wording.
+     *
+     * NOTE: the component cannot name the records itself — `collection` is the
+     * object key the API is addressed with (`business_discussions`), not
+     * something to show a reader. A page with several sections should pass the
+     * label it already displays, so a failure says which section it was.
+     */
+    readonly errorMessage?: string;
 }
 /**
  * @description Fetches and displays a paginated list of SFA/CRM records as a table.
  */
-export declare function RecordList({ collection, columns, params, pageSize, showPagination, onRowClick, onError, }: RecordListProps): JSX.Element;
+export declare function RecordList({ collection, columns, params, pageSize, showPagination, onRowClick, onError, errorMessage, }: RecordListProps): JSX.Element;
 export {};

package/src/lib/components/RecordList.js

@@ -3,14 +3,15 @@ import { useEffect, useMemo, useRef } from 'react';
 import { useRecordList } from '../hooks/useRecordList';
 import { color, font, radius, space, baseContainerStyle, baseButtonStyle, } from '../theme';
 import { SFA_KIT_VERSION } from '../version';
+import { FetchErrorState } from './FetchErrorState';
 import { FieldRenderer } from './FieldRenderer';
 const MAX_AUTO_COLUMNS = 8;
 /**
  * @description Fetches and displays a paginated list of SFA/CRM records as a table.
  */
-export function RecordList({ collection, columns, params, pageSize = 20, showPagination = true, onRowClick, onError, }) {
+export function RecordList({ collection, columns, params, pageSize = 20, showPagination = true, onRowClick, onError, errorMessage, }) {
     const listParams = useMemo(() => (Object.assign(Object.assign({}, params), { limit: pageSize })), [params, pageSize]);
-    const { items, totalCount, hasMore, pageIndex, isLoading, error, goToPage } = useRecordList(collection, listParams);
+    const { items, totalCount, hasMore, pageIndex, status, isLoading, error, refetch, goToPage, } = useRecordList(collection, listParams);
     // Use a ref so inline onError callbacks don't re-fire the effect on
     // every parent render when error is present.
     const onErrorRef = useRef(onError);
@@ -20,8 +21,10 @@ export function RecordList({ collection, columns, params, pageSize = 20, showPag
         if (error)
             (_a = onErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onErrorRef, error);
     }, [error]);
-    if (error) {
-        return (_jsxs("div", { style: styles.container, children: [_jsx("div", { style: styles.error, children: error.message }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
+    // A failed fetch gets its own state with a retry, never the empty table:
+    // "0 records" would state something the server never answered.
+    if (status === 'error') {
+        return (_jsxs("div", { style: styles.container, children: [_jsx(FetchErrorState, { message: errorMessage, onRetry: refetch }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
     }
     const resolvedColumns = columns !== null && columns !== void 0 ? columns : autoDetectColumns(items);
     const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));
@@ -122,14 +125,6 @@ const styles = {
         fontSize: font.sizeSm,
         color: color.textMuted,
     },
-    error: {
-        padding: space.sm,
-        backgroundColor: color.errorLight,
-        border: `1px solid ${color.error}`,
-        borderRadius: radius.sm,
-        color: color.error,
-        fontSize: font.sizeMd,
-    },
     versionFooter: {
         textAlign: 'right',
         fontSize: font.sizeXs,

package/src/lib/components/RecordView.d.ts

@@ -6,9 +6,18 @@ interface RecordViewProps {
     readonly fields?: readonly string[];
     readonly fieldGroups?: readonly FieldGroupSpec[];
     readonly onError?: (error: Error) => void;
+    /**
+     * What to say when the fetch fails. Falls back to naming `title` when one is
+     * given, and to a generic wording otherwise.
+     *
+     * NOTE: `collection` is never used for this — it is the object key the API is
+     * addressed with, not something to show a reader. See RecordList, which has
+     * no title to fall back on and so needs this prop to name its section.
+     */
+    readonly errorMessage?: string;
 }
 /**
  * @description Fetches and displays a single SFA/CRM record in a label-value grid.
  */
-export declare function RecordView({ collection, recordId, title, fields, fieldGroups, onError, }: RecordViewProps): JSX.Element;
+export declare function RecordView({ collection, recordId, title, fields, fieldGroups, onError, errorMessage, }: RecordViewProps): JSX.Element;
 export {};

package/src/lib/components/RecordView.js

@@ -3,13 +3,14 @@ import { useEffect, useRef } from 'react';
 import { useRecord } from '../hooks/useRecord';
 import { color, font, radius, space, baseContainerStyle } from '../theme';
 import { SFA_KIT_VERSION } from '../version';
+import { FetchErrorState } from './FetchErrorState';
 import { FieldRenderer } from './FieldRenderer';
 /**
  * @description Fetches and displays a single SFA/CRM record in a label-value grid.
  */
-export function RecordView({ collection, recordId, title, fields, fieldGroups, onError, }) {
+export function RecordView({ collection, recordId, title, fields, fieldGroups, onError, errorMessage, }) {
     var _a;
-    const { record, isLoading, error } = useRecord(collection, recordId);
+    const { record, isLoading, error, refetch } = useRecord(collection, recordId);
     // Use a ref so inline onError callbacks don't re-fire the effect on
     // every parent render when error is present.
     const onErrorRef = useRef(onError);
@@ -20,7 +21,11 @@ export function RecordView({ collection, recordId, title, fields, fieldGroups, o
             (_a = onErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onErrorRef, error);
     }, [error]);
     if (error) {
-        return (_jsxs("div", { style: styles.container, children: [_jsx("div", { style: styles.error, children: error.message }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
+        // NOTE: `title` is the label the page already shows as the heading, so it
+        // names the record without exposing `collection` — the object key the API
+        // is addressed with. The derived heading is unavailable here: it reads the
+        // record, and on a failure there is none.
+        return (_jsxs("div", { style: styles.container, children: [_jsx(FetchErrorState, { message: errorMessage !== null && errorMessage !== void 0 ? errorMessage : (title ? `${title}の取得に失敗` : undefined), onRetry: refetch }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
     }
     if (isLoading || !record) {
         return (_jsxs("div", { style: styles.container, children: [_jsx("div", { style: styles.loading, children: "Loading..." }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
@@ -130,14 +135,6 @@ const styles = {
         color: color.textMuted,
         fontSize: font.sizeLg,
     },
-    error: {
-        padding: space.sm,
-        backgroundColor: color.errorLight,
-        border: `1px solid ${color.error}`,
-        borderRadius: radius.sm,
-        color: color.error,
-        fontSize: font.sizeMd,
-    },
     empty: {
         padding: space.lg,
         textAlign: 'center',

package/src/lib/hooks/useDescribe.d.ts

@@ -11,6 +11,11 @@ interface UseDescribeResult {
 /**
  * @description Fetches metadata for an object: fields, types, relationships, permissions.
  * The AI agent calls this to discover schema before rendering.
+ *
+ * `object`, `isLoading` and `error` always describe the `objectKey` being asked
+ * about right now, through the client in use right now. Until a fetch for that
+ * pair settles they read as loading, so one object's metadata — or one
+ * organization's — is never reported as another's.
  */
 export declare function useDescribe(objectKey: string, options?: UseDescribeOptions): UseDescribeResult;
 export {};

package/src/lib/hooks/useDescribe.js

@@ -3,6 +3,11 @@ import { useSfaClient } from '../provider/useSfaClient';
 /**
  * @description Fetches metadata for an object: fields, types, relationships, permissions.
  * The AI agent calls this to discover schema before rendering.
+ *
+ * `object`, `isLoading` and `error` always describe the `objectKey` being asked
+ * about right now, through the client in use right now. Until a fetch for that
+ * pair settles they read as loading, so one object's metadata — or one
+ * organization's — is never reported as another's.
  */
 export function useDescribe(objectKey, options) {
     var _a;
@@ -12,6 +17,18 @@ export function useDescribe(objectKey, options) {
     const [isLoading, setIsLoading] = useState(enabled && !!objectKey);
     const [error, setError] = useState(null);
     const fetchIdRef = useRef(0);
+    /**
+     * The key and client whose fetch has settled — succeeded or failed. The state
+     * below only describes objectKey once both match.
+     *
+     * NOTE: the client is part of it, for the reason spelled out in
+     * useRecordList — SfaProvider rebuilds it when the organization or token
+     * changes, so the same key can describe another organization's object.
+     */
+    const settledRef = useRef(null);
+    // What the metadata in state describes, so a failure can tell "keep what we
+    // have" from "what we have describes something else".
+    const loadedRef = useRef(null);
     const doFetch = useCallback(() => {
         if (!objectKey || !enabled)
             return;
@@ -23,18 +40,59 @@ export function useDescribe(objectKey, options) {
             .then(result => {
             if (fetchId !== fetchIdRef.current)
                 return;
+            // NOTE: refs before setState — see useRecordList for why.
+            settledRef.current = { client, objectKey };
+            loadedRef.current = { client, objectKey };
             setObject(result.object);
             setIsLoading(false);
         })
             .catch((err) => {
             if (fetchId !== fetchIdRef.current)
                 return;
+            // Read before writing: this is what the metadata in state describes.
+            const loaded = loadedRef.current;
+            const describesSameThing = loaded != null &&
+                loaded.client === client &&
+                loaded.objectKey === objectKey;
+            if (!describesSameThing)
+                loadedRef.current = null;
+            settledRef.current = { client, objectKey };
             setError(err instanceof Error ? err : new Error(String(err)));
             setIsLoading(false);
+            // Metadata for another key or organization must not survive: it would
+            // describe one object as if it were another. A failure on the same
+            // question keeps it, so a transient error does not blank a form that
+            // was already rendering.
+            if (loaded != null && !describesSameThing)
+                setObject(null);
         });
     }, [client, objectKey, enabled]);
     useEffect(() => {
+        // Invalidate anything still in flight before deciding what to do next.
+        // doFetch cannot do this itself: with no objectKey, or while disabled, it
+        // returns before reaching its own bump, so a response that lands after the
+        // caller stopped asking would still pass the id check and be recorded.
+        fetchIdRef.current += 1;
+        if (!objectKey || !enabled) {
+            // A discarded refetch would otherwise leave isLoading true with nothing
+            // to resolve it. The metadata already in hand still stands.
+            setIsLoading(false);
+            return;
+        }
         doFetch();
-    }, [doFetch]);
+    }, [doFetch, objectKey, enabled]);
+    // Until a fetch for the current key and client settles, the state describes
+    // what was asked before it.
+    const settled = settledRef.current;
+    if (settled == null ||
+        settled.client !== client ||
+        settled.objectKey !== objectKey) {
+        return {
+            object: null,
+            isLoading: enabled && !!objectKey,
+            error: null,
+            refetch: doFetch,
+        };
+    }
     return { object, isLoading, error, refetch: doFetch };
 }

package/src/lib/hooks/useRecordList.d.ts

@@ -2,11 +2,34 @@ import type { SfaListParams, SfaRecord } from '../provider/types';
 interface UseRecordListOptions {
     readonly enabled?: boolean;
 }
+/**
+ * @description Lifecycle of a list fetch. `items` only describes the server
+ * when this is `'success'`.
+ *
+ * - `idle`: nothing will be fetched and nothing is known — no collection, or
+ *   disabled before anything settled. A hook disabled *after* a successful
+ *   fetch keeps reporting `'success'`, because its `items` did come from the
+ *   server
+ * - `loading`: a fetch is in flight, or the query just changed and the fetch
+ *   for it has not settled yet
+ * - `success`: the last fetch for *this* query completed and `items` came
+ *   from the server
+ * - `error`: the last fetch for *this* query failed. `items` is the last
+ *   success of the same query, or empty when there was none
+ */
+export type SfaListStatus = 'idle' | 'loading' | 'success' | 'error';
 interface UseRecordListResult {
+    /**
+     * @description Records from the last successful fetch. An empty array is
+     * only meaningful when `status` is `'success'`: on `'idle'`, `'loading'`
+     * and `'error'` it means "not known", not "the server has none". Rendering
+     * it without checking `status` turns a failed fetch into a confident zero.
+     */
     readonly items: readonly SfaRecord[];
     readonly totalCount: number;
     readonly hasMore: boolean;
     readonly pageIndex: number;
+    readonly status: SfaListStatus;
     readonly isLoading: boolean;
     readonly error: Error | null;
     readonly refetch: () => void;

package/src/lib/hooks/useRecordList.js

@@ -1,20 +1,36 @@
 import { __awaiter } from "tslib";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useSfaClient } from '../provider/useSfaClient';
+/** Stable identity so an unanswered query never re-renders on a fresh array. */
+const NO_ITEMS = [];
 /**
  * @description Fetches a paginated list of records from the SFA/CRM API.
  */
 export function useRecordList(collection, params, options) {
-    var _a, _b;
+    var _a, _b, _c;
     const client = useSfaClient();
     const limit = (_a = params === null || params === void 0 ? void 0 : params.limit) !== null && _a !== void 0 ? _a : 20;
     const [items, setItems] = useState([]);
     const [totalCount, setTotalCount] = useState(0);
     const [hasMore, setHasMore] = useState(false);
-    // offset is a record offset, not a page number: pageIndex = floor(offset / limit)
-    const [pageIndex, setPageIndex] = useState((params === null || params === void 0 ? void 0 : params.offset) != null && limit > 0 ? Math.floor(params.offset / limit) : 0);
-    const enabled = (_b = options === null || options === void 0 ? void 0 : options.enabled) !== null && _b !== void 0 ? _b : true;
-    const [isLoading, setIsLoading] = useState(enabled && !!collection);
+    /**
+     * Where the caller asked the listing to start.
+     *
+     * `offset` is a record position, so the page it names is
+     * `floor(offset / limit)`. `cursor` addresses the same starting point
+     * opaquely and takes precedence over `offset` on the server. Both are only
+     * about the *first* page: from there the hook pages on its own, computing
+     * offsets from the page number and reusing cursors the server handed back.
+     */
+    const initialOffset = (_b = params === null || params === void 0 ? void 0 : params.offset) !== null && _b !== void 0 ? _b : 0;
+    const initialCursor = params === null || params === void 0 ? void 0 : params.cursor;
+    const initialPage = limit > 0 ? Math.floor(initialOffset / limit) : 0;
+    const [pageIndex, setPageIndex] = useState(initialPage);
+    const enabled = (_c = options === null || options === void 0 ? void 0 : options.enabled) !== null && _c !== void 0 ? _c : true;
+    // NOTE: the seed is never published. Until a fetch settles for the current
+    // query the reported status is derived below, so this only matters after the
+    // first settle — by which time a fetch has set it.
+    const [status, setStatus] = useState('idle');
     const [error, setError] = useState(null);
     const fetchId = useRef(0);
     const sortBy = params === null || params === void 0 ? void 0 : params.sortBy;
@@ -22,60 +38,220 @@ export function useRecordList(collection, params, options) {
     const filterKey = useMemo(() => ((params === null || params === void 0 ? void 0 : params.filter) ? JSON.stringify(params.filter) : ''), [params === null || params === void 0 ? void 0 : params.filter]);
     const filterRef = useRef(params === null || params === void 0 ? void 0 : params.filter);
     filterRef.current = params === null || params === void 0 ? void 0 : params.filter;
+    // What identifies the query, page navigation aside: paging stays within one
+    // query, but the position the caller starts from does not — the same
+    // collection and filter read from a different offset or cursor is a
+    // different question, and asking it has to start a new fetch.
+    const queryKey = useMemo(() => JSON.stringify({
+        collection,
+        limit,
+        sortBy,
+        sortOrder,
+        filterKey,
+        initialOffset,
+        initialCursor,
+    }), [
+        collection,
+        limit,
+        sortBy,
+        sortOrder,
+        filterKey,
+        initialOffset,
+        initialCursor,
+    ]);
+    /**
+     * Which client, query and page the records in state came from, so a failure
+     * can tell "keep what we have" from "what we have answers something else".
+     *
+     * NOTE: the client is part of the question. SfaProvider builds a new
+     * SfaClient whenever the accessToken, organizationId, apiBase, mode or
+     * readOnly change, so the same collection and filter can address a different
+     * organization. Comparing the query alone would publish one organization's
+     * records as the answer for another, and keep them through a failure.
+     */
+    const loadedRef = useRef(null);
+    // Which query last completed and how it ended, so a request discarded
+    // mid-flight can fall back to it instead of leaving 'loading' with nothing
+    // to resolve it. The query is part of it: falling back to how *another*
+    // query ended would present its outcome as this one's answer.
+    const settledRef = useRef(null);
+    // The page of the last request that failed, kept apart from pageIndex:
+    // pageIndex follows the records on screen, this follows what the reader was
+    // trying to reach. Without it, retrying after a failed page turn re-fetches
+    // the page already displayed — the error clears and the reader stays put.
+    const failedPageRef = useRef(null);
     // Track cursors for each page so goToPage can navigate backwards.
     const cursorMapRef = useRef(new Map());
     const doFetch = useCallback((page) => __awaiter(this, void 0, void 0, function* () {
+        var _a;
         if (!collection || !enabled)
             return;
         fetchId.current += 1;
         const currentFetchId = fetchId.current;
-        setIsLoading(true);
+        setStatus('loading');
         setError(null);
         try {
-            const cursor = cursorMapRef.current.get(page);
-            const result = yield client.list(collection, Object.assign({ limit, offset: page, sortBy,
+            // The caller's cursor and exact offset belong to the page they named.
+            // Every other page is reached with what the server handed back, or with
+            // an offset computed from the page number.
+            const cursor = (_a = cursorMapRef.current.get(page)) !== null && _a !== void 0 ? _a : (page === initialPage ? initialCursor : undefined);
+            const result = yield client.list(collection, Object.assign({ limit, 
+                // NOTE: offset is a record position, not a page number. Sending the
+                // page number asks for records 1..limit for page 1: it overlaps
+                // page 0 and comes back reporting pageIndex 0, so the list never
+                // advances. SfaClient derives pageIndex from this offset even when
+                // the server paginates by cursor, so the two have to agree.
+                offset: page === initialPage ? initialOffset : page * limit, sortBy,
                 sortOrder, filter: filterRef.current }, (cursor ? { cursor } : {})));
             if (currentFetchId === fetchId.current) {
+                // NOTE: the refs are written before the setState calls. Outside an
+                // event handler React 18 in legacy mode re-renders on every setState
+                // instead of batching, so a ref assigned afterwards is still stale
+                // in the renders those updates produce.
+                loadedRef.current = { client, queryKey, page: result.pageIndex };
+                settledRef.current = { client, queryKey, status: 'success' };
+                // Displayed page and target page are the same again
+                failedPageRef.current = null;
                 setItems(result.items);
                 setTotalCount(result.totalCount);
                 setHasMore(result.hasMore);
                 setPageIndex(result.pageIndex);
-                setIsLoading(false);
-                // Store cursor for the next page so goToPage can use it.
+                setStatus('success');
+                // Store cursors for adjacent pages so goToPage can navigate both ways.
                 if (result.nextCursor) {
                     cursorMapRef.current.set(page + 1, result.nextCursor);
                 }
+                if (page > 0 && result.prevCursor) {
+                    cursorMapRef.current.set(page - 1, result.prevCursor);
+                }
             }
         }
         catch (e) {
             if (currentFetchId === fetchId.current) {
+                settledRef.current = { client, queryKey, status: 'error' };
+                failedPageRef.current = page;
                 setError(e instanceof Error ? e : new Error(String(e)));
-                setItems([]);
-                setIsLoading(false);
+                setStatus('error');
+                const loaded = loadedRef.current;
+                // NOTE: compared against the captured client / queryKey rather than
+                // the render-time helper, so this closure depends only on values
+                // already in the dependency list below
+                const answersSameQuestion = loaded != null &&
+                    loaded.client === client &&
+                    loaded.queryKey === queryKey;
+                if (answersSameQuestion) {
+                    // Keep the records from the last successful fetch of this same
+                    // query. Emptying them would make a rate limit or a dropped
+                    // connection indistinguishable from "the server has no records",
+                    // and a caller that renders items without reading status would
+                    // show a confident zero. pageIndex goes back to the page those
+                    // records came from, so what it says matches what is on screen —
+                    // goToPage advanced it before the fetch failed. The page that
+                    // failed stays in failedPageRef, which is what refetch retries.
+                    setPageIndex(loaded.page);
+                }
+                else if (loaded != null) {
+                    // The records in state answer a different question (another
+                    // parent, another filter, another organization). Keeping them
+                    // would show one record's children — or one organization's data —
+                    // under another, so drop them and let status report them unknown.
+                    setItems([]);
+                    setTotalCount(0);
+                    setHasMore(false);
+                    loadedRef.current = null;
+                }
             }
         }
     }), 
+    // NOTE: queryKey is read inside but left out on purpose — it is a useMemo
+    // over exactly the values below, so it cannot change without one of them
+    // changing and recreating this callback. Anything added to queryKey's deps
+    // must be added here too, or the closure keeps a stale key.
     // eslint-disable-next-line react-hooks/exhaustive-deps -- filterKey triggers re-fetch when filter object changes
-    [client, collection, enabled, limit, sortBy, sortOrder, filterKey]);
+    [
+        client,
+        collection,
+        enabled,
+        limit,
+        sortBy,
+        sortOrder,
+        filterKey,
+        initialOffset,
+        initialCursor,
+        initialPage,
+    ]);
     useEffect(() => {
+        // Invalidate anything still in flight before deciding what to do next.
+        // doFetch cannot do this itself: while disabled or without a collection it
+        // returns before reaching its own bump, so a response that lands after the
+        // caller stopped asking would still pass the id check and be published.
+        fetchId.current += 1;
         cursorMapRef.current.clear();
-        setPageIndex(0);
-        doFetch(0);
-    }, [doFetch]);
+        // A new question has no failed page yet.
+        failedPageRef.current = null;
+        if (!collection) {
+            // Nothing to ask about, and the records in hand answer another
+            // collection — see the 'idle' contract on SfaListStatus.
+            setStatus('idle');
+            return;
+        }
+        if (!enabled) {
+            // A discarded refetch would otherwise leave 'loading' with nothing to
+            // resolve it. Fall back to how *this* query last ended — its records are
+            // still in hand. Nothing settled for it means nothing is known: idle.
+            // NOTE: compared against the captured client / queryKey rather than the
+            // render-time helper, so this effect depends only on what is already in
+            // its dependency list
+            const settled = settledRef.current;
+            const answersSameQuestion = settled != null &&
+                settled.client === client &&
+                settled.queryKey === queryKey;
+            // eslint-disable-next-line react-you-might-not-need-an-effect/no-pass-data-to-parent
+            setStatus(answersSameQuestion ? settled.status : 'idle');
+            return;
+        }
+        setPageIndex(initialPage);
+        doFetch(initialPage);
+    }, [doFetch, collection, enabled, client, queryKey, initialPage]);
     const goToPage = useCallback((page) => {
         setPageIndex(page);
         doFetch(page);
     }, [doFetch]);
     const refetch = useCallback(() => {
-        doFetch(pageIndex);
+        var _a;
+        // Retry what the reader was trying to reach. After a success the two are
+        // the same, so an ordinary refetch targets the page on screen.
+        doFetch((_a = failedPageRef.current) !== null && _a !== void 0 ? _a : pageIndex);
     }, [doFetch, pageIndex]);
+    /**
+     * The state above only answers `queryKey` once a fetch for it has settled:
+     * at mount nothing has, and right after the query changes it still holds the
+     * previous one's items, counts, error and status. Publishing those presents
+     * one query's answer as another's — the same lie as showing a failure as 0.
+     * Until this query settles, report only what is known.
+     */
+    const settled = settledRef.current;
+    const isSettledForCurrentQuery = settled != null &&
+        settled.client === client &&
+        settled.queryKey === queryKey;
+    const willFetch = enabled && !!collection;
+    const reported = isSettledForCurrentQuery
+        ? { items, totalCount, hasMore, status, error }
+        : {
+            items: NO_ITEMS,
+            totalCount: 0,
+            hasMore: false,
+            status: willFetch ? 'loading' : 'idle',
+            error: null,
+        };
     return {
-        items,
-        totalCount,
-        hasMore,
+        items: reported.items,
+        totalCount: reported.totalCount,
+        hasMore: reported.hasMore,
         pageIndex,
-        isLoading,
-        error,
+        status: reported.status,
+        isLoading: reported.status === 'loading',
+        error: reported.error,
         refetch,
         goToPage,
     };

package/src/lib/hooks/useRelatedRecords.d.ts

@@ -1,4 +1,5 @@
 import type { SfaRecord, SfaRelationDescriptor } from '../provider/types';
+import type { SfaListStatus } from './useRecordList';
 /** @description Parameters for narrowing, sorting, and filtering related records. */
 export interface UseRelatedRecordsParams {
     readonly limit?: number;
@@ -16,10 +17,20 @@ export interface UseRelatedRecordsOptions {
 }
 /** @description Return value of useRelatedRecords: paginated items, loading/error state, and the resolved relationship descriptor. */
 export interface UseRelatedRecordsResult {
+    /**
+     * @description Records from the last successful fetch. An empty array is
+     * only meaningful when `status` is `'success'` — see useRecordList.
+     */
     readonly items: readonly SfaRecord[];
     readonly totalCount: number;
     readonly hasMore: boolean;
     readonly pageIndex: number;
+    /**
+     * @description Lifecycle across all three steps (describe, relationship
+     * resolution, list fetch). `'error'` covers a failed describe, a missing
+     * relationship, and a failed list fetch.
+     */
+    readonly status: SfaListStatus;
     readonly isLoading: boolean;
     readonly error: Error | null;
     readonly refetch: () => void;

package/src/lib/hooks/useRelatedRecords.js

@@ -1,4 +1,4 @@
-import { useMemo, useRef } from 'react';
+import { useCallback, useMemo, useRef } from 'react';
 import { useDescribe } from './useDescribe';
 import { useRecordList } from './useRecordList';
 // ── Error ──
@@ -71,7 +71,7 @@ export function useRelatedRecords(parentCollection, parentId, relationTarget, pa
     // In the grandchild pattern the second hook's parentId starts as []
     // while the first hook fetches; starting describe early lets both
     // metadata calls overlap instead of running in sequence.
-    const { object: parentObject, isLoading: isParentDescribeLoading, error: parentDescribeError, } = useDescribe(parentCollection, {
+    const { object: parentObject, isLoading: isParentDescribeLoading, error: parentDescribeError, refetch: refetchParentDescribe, } = useDescribe(parentCollection, {
         enabled,
     });
     // Only trust parentObject while it matches the current collection;
@@ -94,7 +94,7 @@ export function useRelatedRecords(parentCollection, parentId, relationTarget, pa
         parentObjectMatches &&
         !isParentDescribeLoading &&
         !forwardRelationship;
-    const { object: childObject, isLoading: isChildDescribeLoading, error: childDescribeError, } = useDescribe(relationTarget, {
+    const { object: childObject, isLoading: isChildDescribeLoading, error: childDescribeError, refetch: refetchChildDescribe, } = useDescribe(relationTarget, {
         enabled: needsReverseLookup,
     });
     const childObjectMatches = (childObject === null || childObject === void 0 ? void 0 : childObject.key) === relationTarget;
@@ -213,14 +213,54 @@ export function useRelatedRecords(parentCollection, parentId, relationTarget, pa
             (recordList.isLoading || !listHasStartedRef.current));
     const describeError = parentDescribeError !== null && parentDescribeError !== void 0 ? parentDescribeError : (needsReverseLookup ? childDescribeError : null);
     const error = (_c = describeError !== null && describeError !== void 0 ? describeError : relationError) !== null && _c !== void 0 ? _c : recordList.error;
+    // Report the merged lifecycle, not just the list's. A failed describe or an
+    // unresolved relationship also leaves items empty, and a caller that reads
+    // items without status would render that as "no related records".
+    const status = (() => {
+        if (error)
+            return 'error';
+        if (isLoading)
+            return 'loading';
+        if (!listShouldBeActive)
+            return 'idle';
+        return recordList.status;
+    })();
+    // Retry whatever failed. The list is only enabled once a relationship is
+    // resolved, so while it is not, refetching the list issues no request at all
+    // and a retry control wired to it does nothing. Everything before the list
+    // comes from describe, so that is what gets retried — including
+    // RelationNotFoundError, which clears if the schema gains the relationship.
+    const refetchList = recordList.refetch;
+    const refetch = useCallback(() => {
+        if (relationship == null || parentDescribeError != null) {
+            refetchParentDescribe();
+            if (needsReverseLookup)
+                refetchChildDescribe();
+            return;
+        }
+        if (needsReverseLookup && childDescribeError != null) {
+            refetchChildDescribe();
+            return;
+        }
+        refetchList();
+    }, [
+        relationship,
+        parentDescribeError,
+        refetchParentDescribe,
+        needsReverseLookup,
+        childDescribeError,
+        refetchChildDescribe,
+        refetchList,
+    ]);
     return {
         items: recordList.items,
         totalCount: recordList.totalCount,
         hasMore: recordList.hasMore,
         pageIndex: recordList.pageIndex,
+        status,
         isLoading,
         error,
-        refetch: recordList.refetch,
+        refetch,
         goToPage: recordList.goToPage,
         relationship,
     };

package/src/lib/provider/SfaClient.d.ts

@@ -12,11 +12,18 @@ export declare class SfaClient implements SfaClientInterface {
     private readonly organizationId;
     private readonly onAuthError;
     readonly mode: SfaApiMode;
+    /** In-memory cache for describe results, keyed by objectKey. Stores Promises
+     *  so concurrent callers share a single in-flight request. */
+    private readonly describeCache;
     constructor(config: SfaClientConfig);
     private resolveBase;
     get(collection: string, recordId: string): Promise<SfaRecord>;
     list(collection: string, params?: SfaListParams): Promise<SfaListResponse>;
     describe(objectKey: string): Promise<SfaDescribeResult>;
+    /** Cached describe fetch. Returns a shared Promise so concurrent callers
+     *  for the same objectKey deduplicate into one HTTP request. On failure the
+     *  entry is evicted so the next caller retries. */
+    private describeObject;
     listObjects(): Promise<SfaObjectCatalog>;
     listFieldTypes(): Promise<SfaFieldTypeCatalog>;
     private assertDirectMode;
@@ -33,6 +40,12 @@ export declare class SfaClient implements SfaClientInterface {
      * another write landed first.
      */
     update(collection: string, recordId: string, fields: Record<string, unknown>, version: string): Promise<SfaRecord>;
+    /**
+     * @description Fetches describe metadata (with cache) and normalizes
+     * cardinality:"many" reference fields to arrays. Falls back to no-op if
+     * describe fails, so a broken metadata endpoint never blocks writes.
+     */
+    private applySchemaAwareNormalization;
     /**
      * @description Deletes a record with optimistic locking. Returns void on
      * success (204). Throws SfaConflictError on 412 if the record was modified

package/src/lib/provider/SfaClient.js

@@ -21,6 +21,9 @@ function timeoutSignal() {
  */
 export class SfaClient {
     constructor(config) {
+        /** In-memory cache for describe results, keyed by objectKey. Stores Promises
+         *  so concurrent callers share a single in-flight request. */
+        this.describeCache = new Map();
         this.apiBase = this.resolveBase(config.apiBase.replace(/\/+$/, ''), config.mode);
         this.auth = config.auth;
         this.mode = config.mode;
@@ -61,6 +64,16 @@ export class SfaClient {
             // offset is a record offset, not a page number: pageIndex = floor(offset / pageSize)
             const pageIndex = pageSize > 0 ? Math.floor(offset / pageSize) : 0;
             if (this.mode === 'direct') {
+                // Keystone paginates by cursor only: records/query takes no offset, so a
+                // later page can be reached only with the cursor that leads to it.
+                // Answering such a request with the first page while reporting the
+                // requested pageIndex would claim data the server never returned, so say
+                // it cannot be served instead.
+                if (offset > 0 && !(params === null || params === void 0 ? void 0 : params.cursor)) {
+                    throw new Error(`Cannot start at record ${offset}: this API paginates by cursor. ` +
+                        'Reach later pages with goToPage from the first one, or pass the ' +
+                        'cursor for the page you want.');
+                }
                 const body = {
                     limit: pageSize,
                 };
@@ -101,9 +114,25 @@ export class SfaClient {
     }
     describe(objectKey) {
         return __awaiter(this, void 0, void 0, function* () {
-            const raw = yield this.fetchGet(this.objectsPath(`/${enc(objectKey)}`));
-            return { object: normalizeObjectDetail(raw) };
+            const object = yield this.describeObject(objectKey);
+            return { object };
+        });
+    }
+    /** Cached describe fetch. Returns a shared Promise so concurrent callers
+     *  for the same objectKey deduplicate into one HTTP request. On failure the
+     *  entry is evicted so the next caller retries. */
+    describeObject(objectKey) {
+        const cached = this.describeCache.get(objectKey);
+        if (cached)
+            return cached;
+        const promise = this.fetchGet(this.objectsPath(`/${enc(objectKey)}`))
+            .then(raw => normalizeObjectDetail(raw))
+            .catch((err) => {
+            this.describeCache.delete(objectKey);
+            throw err;
         });
+        this.describeCache.set(objectKey, promise);
+        return promise;
     }
     listObjects() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -142,12 +171,13 @@ export class SfaClient {
     create(collection, fields, options) {
         return __awaiter(this, void 0, void 0, function* () {
             this.assertDirectMode();
+            const normalized = yield this.applySchemaAwareNormalization(collection, fields);
             const path = `/v1/objects/${enc(collection)}/records`;
             const extra = {};
             if (options === null || options === void 0 ? void 0 : options.idempotencyKey) {
                 extra['Idempotency-Key'] = options.idempotencyKey;
             }
-            const response = yield this.fetchWithBody('POST', path, { fields: normalizeWriteFields(fields) }, extra);
+            const response = yield this.fetchWithBody('POST', path, { fields: normalizeWriteFields(normalized) }, extra);
             const raw = yield response.json();
             return normalizeKeystoneRecord(raw);
         });
@@ -161,12 +191,32 @@ export class SfaClient {
         return __awaiter(this, void 0, void 0, function* () {
             this.assertDirectMode();
             this.assertRecordId(recordId);
+            const normalized = yield this.applySchemaAwareNormalization(collection, fields);
             const path = `/v1/objects/${enc(collection)}/records/${enc(recordId)}`;
-            const response = yield this.fetchWithBody('PATCH', path, { fields: normalizeWriteFields(fields) }, { 'If-Match': version });
+            const response = yield this.fetchWithBody('PATCH', path, { fields: normalizeWriteFields(normalized) }, { 'If-Match': version });
             const raw = yield response.json();
             return normalizeKeystoneRecord(raw);
         });
     }
+    /**
+     * @description Fetches describe metadata (with cache) and normalizes
+     * cardinality:"many" reference fields to arrays. Falls back to no-op if
+     * describe fails, so a broken metadata endpoint never blocks writes.
+     */
+    applySchemaAwareNormalization(collection, fields) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const detail = yield this.describeObject(collection);
+                return normalizeCardinalityFields(fields, detail.fields);
+            }
+            catch (_a) {
+                // Describe failed -- proceed without cardinality normalization.
+                // The write will either succeed (no many-cardinality fields in payload)
+                // or fail with the same 422 it would have before this feature.
+                return fields;
+            }
+        });
+    }
     /**
      * @description Deletes a record with optimistic locking. Returns void on
      * success (204). Throws SfaConflictError on 412 if the record was modified
@@ -293,6 +343,49 @@ function enc(segment) {
     return encodeURIComponent(segment);
 }
 // ── Keystone record normalization (direct mode) ──
+// ── Write-path normalization ──
+/** Field kinds whose values must be arrays when cardinality is 'many'. */
+const ARRAY_WRAPPABLE_KINDS = new Set([
+    'reference',
+    'user_reference',
+]);
+/**
+ * @description Wraps scalar values in arrays for fields whose schema declares
+ * cardinality:"many". Already-array values, null, and undefined are passed
+ * through unchanged. Runs *before* normalizeWriteFields so SfaFieldValue
+ * wrappers are still intact; when a wrapper is detected its inner `.value`
+ * is wrapped while the wrapper structure is preserved.
+ */
+function normalizeCardinalityFields(fields, descriptors) {
+    const manyFields = new Set();
+    for (const desc of descriptors) {
+        if (desc.cardinality === 'many' && ARRAY_WRAPPABLE_KINDS.has(desc.kind)) {
+            manyFields.add(desc.key);
+        }
+    }
+    if (manyFields.size === 0)
+        return fields;
+    const result = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (manyFields.has(key) && value != null && !Array.isArray(value)) {
+            if (isSfaFieldValue(value)) {
+                // Wrap the inner value; preserve the SfaFieldValue wrapper so the
+                // subsequent normalizeWriteFields step can still unwrap it.
+                const inner = value.value;
+                result[key] =
+                    inner != null && !Array.isArray(inner)
+                        ? Object.assign(Object.assign({}, value), { value: [inner] }) : value;
+            }
+            else {
+                result[key] = [value];
+            }
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
 /**
  * @description Converts a caller-supplied fields map into the raw values
  * expected by Keystone's RecordWrite body. If a value is already a raw value

package/src/lib/version.d.ts

@@ -1 +1 @@
-export declare const SFA_KIT_VERSION = "1.8.0";
+export declare const SFA_KIT_VERSION = "1.10.0";

package/src/lib/version.js

@@ -1,3 +1,3 @@
 // このファイルは libs/sfa-kit/scripts/sync-version.cjs が生成する。
 // 手で編集しないこと。バージョンを上げるときは libs/sfa-kit/package.json を変更する。
-export const SFA_KIT_VERSION = '1.8.0';
+export const SFA_KIT_VERSION = '1.10.0';