Relay Mutation Store Updates

5. Keep success honest — decide the refetch at the call site

onRequestClose(success: boolean) means the mutation succeeded. Pass it truthfully.

Do not pass false after a successful update to suppress a refetch. false already means "cancelled", so overloading it makes the two indistinguishable to the caller — anything the caller later wants to do on success (a toast, clearing a selection, closing a drawer) silently stops firing after updates. UserSettingModal currently does this; it is a bug to copy from, not a pattern.

The fragment prop is the discriminator. A setting modal that handles both paths takes a nullable *Frgmt — null means create, non-null means update. The caller passes that prop, so it can branch on it with no signature change: if (success && entityFrgmt === null) refetch(). Create adds a row the connection doesn't know about; update has already been patched into the store.

One instance serving both paths:

<ResourcePresetSettingModal
  resourcePresetFrgmt={editingResourcePreset}
  open={!!editingResourcePreset || isCreating}
  onRequestClose={(success) => {
    // read the fragment BEFORE the resets below; the handler closes over the
    // render-time value, so check first and reset after.
    if (success && !editingResourcePreset) {
      startRefetchTransition(() => updateResourcePresetsFetchKey());
    }
    setEditingResourcePreset(null);
    setIsCreating(false);
  }}
/>

When the caller renders separate instances for create and edit — as AdminUserManagement does with userSettingFrgmt={selectedUser} and ={null} — the branch collapses. Its edit path still keeps the refetch, for the §2 reason: the status-toggle payload returns only user { id }, so the changed fields never come back and there is nothing to patch. Fill the payload first if you want to drop that one.

If a caller genuinely cannot know, enrich the result rather than lying about success — ContainerRegistryEditorModal already passes onOk('create' | 'modify').

6. Create and delete: refetch

Refetch the list. Don't patch the connection.

Connection directives (@appendEdge, @deleteRecord) look like the tidy answer, but they break under pagination: appending to a page-sized connection pushes rows past the cursor boundary, so the client's idea of the list drifts from the server's. Add sorting and filtering — where the new row's position is decided server-side — and a client-side insert is simply guessing.

One component uses @appendEdge today (packages/backend.ai-ui/src/components/fragments/BAIImportArtifactModal.tsx). Treat it as an exception that predates this rule, not a pattern to copy.

7. When an update may refetch too

Create and delete are settled by §6. An update may also legitimately refetch when:

• The mutation has side effects on other entities the payload doesn't cover (e.g. changing a resource policy recomputes several users' quotas).
• Aggregates shown alongside the list (counts, totals, usage) are computed server-side.
• Bulk mutations where per-record payloads are impractical.

Leave a one-line reason in these cases. After an update, an unexplained refetch reads as the anti-pattern.

Enforcement

There is none — this skill and code review are the only guardrail, across ~149 updateFetchKey() call sites in react/src. A lint rule was considered and deliberately left out of scope (FR-3372). If that decision is revisited, the landing spot already exists: react/eslint.config.js uses no-restricted-syntax with an AST selector for the CSP <style> ban, and the onRequestClose={(success) => { if (success) updateFetchKey(); }} shape is matchable the same way.

Review Checklist

• No if (success) updateFetchKey() where the mutation was an update
• No refetch added because a changed field is a filter/orderBy property — stale-under-filter is accepted; the manual refresh covers re-evaluation
• Every update mutation payload selects the fields the UI reads
• Prefer spreading the consumer's fragment over hand-listing fields
• Schema checked (data/schema.graphql) before concluding a refetch is required
• Legacy ok/msg-only mutation → refetch kept, with a comment saying why
• success is passed truthfully; the refetch decision lives at the call site
• Create/delete refetch the list — no @appendEdge/@deleteRecord added
• A refetch after an update has a comment naming why the store can't be patched

Related

• .specs/FR-3372-refetch-after-mutation/spec.md — the remediation spec this skill distills
• FR-3170 — the audit epic; FR-3372 — this analysis