@oxyhq/services 26.2.0 → 27.0.0

package/src/ui/hooks/queries/__tests__/userCacheClear.test.ts

@@ -0,0 +1,301 @@
+/**
+ * userCache — DELIBERATE CLEARS vs sparse sources.
+ *
+ * `upsertCachedUser` refuses an empty incoming value so a sparse feed/post/list
+ * author can never blank a field the authoritative profile fetch stored. That is
+ * right for a projection and wrong for a user who just removed their picture,
+ * and the payload cannot tell the two apart: oxy-api's `formatUserResponse`
+ * emits a cleared field as `undefined`, which `JSON.stringify` drops, so a
+ * cleared avatar and an uncarried one arrive byte-identical. The caller declares
+ * the difference with `{ cleared: [...] }`.
+ *
+ * WHAT MAKES THIS SUITE NON-VACUOUS
+ * ---------------------------------
+ * Every assertion here is paired: the SAME incoming payload is upserted once
+ * WITHOUT `cleared` and once WITH it, and the two must disagree. A suite whose
+ * fixtures only ever passed `cleared` could not tell "the guard was removed"
+ * from "the clear works", which is the whole risk — dropping the guard would
+ * blank real avatars across every Oxy app. The `does not` half of each pair is
+ * what pins the guard; `userCache.test.ts` keeps its own anti-degradation
+ * coverage independently.
+ */
+
+import { QueryClient } from '@tanstack/react-query';
+import {
+  CLEARABLE_USER_FIELDS,
+  clearedFieldsFromAccountUpdate,
+  clearedFieldsFromProfileUpdate,
+  upsertCachedUser,
+  upsertCachedUsers,
+} from '../userCache';
+import type { CacheableUser, ClearableUserField } from '../userCache';
+import { queryKeys } from '../queryKeys';
+import { useAuthStore } from '../../../stores/authStore';
+
+function makeClient(): QueryClient {
+  return new QueryClient({ defaultOptions: { queries: { retry: false } } });
+}
+
+function readById(qc: QueryClient, id: string): CacheableUser | undefined {
+  return qc.getQueryData<CacheableUser>(queryKeys.users.detail(id));
+}
+
+function readByUsername(
+  qc: QueryClient,
+  username: string,
+  viewerId: string,
+): CacheableUser | undefined {
+  return qc.getQueryData<CacheableUser>(
+    queryKeys.users.byUsername(username, viewerId),
+  );
+}
+
+/** A warm, fully-populated entry — what an authoritative profile fetch stored. */
+function seedFullEntry(qc: QueryClient, viewerId = ''): void {
+  const full = {
+    id: 'u1',
+    username: 'alice',
+    name: { displayName: 'Alice A', first: 'Alice' },
+    avatar: 'file_old',
+    bio: 'old bio',
+    description: 'old description',
+    color: 'teal',
+    accountCategories: ['agency'],
+    _count: { followers: 10, following: 5 },
+  };
+  qc.setQueryData(queryKeys.users.detail('u1'), full);
+  qc.setQueryData(queryKeys.users.byUsername('alice', viewerId), {
+    ...full,
+    relationship: { isFollowing: true, followsYou: true },
+  });
+}
+
+/**
+ * The write response for an account that just emptied everything, in the shape
+ * oxy-api's `formatUserResponse` actually produces — MEASURED, not assumed:
+ *
+ *   {"id":"acc1","publicKey":"pk","username":"chan","name":{},"languages":[]}
+ *
+ * The two details that matter and are easy to get wrong: every cleared scalar is
+ * OMITTED (serialized as `undefined`, which `JSON.stringify` drops), while
+ * `name` survives as a PRESENT-but-EMPTY object. Writing this fixture as
+ * `{ id, username }` instead — with no `name` key — routes `mergeName` down its
+ * "incoming absent" branch and leaves the "incoming present, displayName empty"
+ * branch untested; mutation-testing caught exactly that. Nothing in this object
+ * says "cleared", which is the whole point.
+ */
+const clearedResponse: CacheableUser = { id: 'u1', username: 'alice', name: {} };
+
+/**
+ * The same clear expressed the way a caller echoing its own REQUEST would send
+ * it: `UserProfileUpdate` clears a display name with `''`. It must land on the
+ * same result as the response shape above.
+ */
+const clearedByEmptyString: CacheableUser = {
+  id: 'u1',
+  username: 'alice',
+  name: { displayName: '' },
+};
+
+beforeEach(() => {
+  useAuthStore.setState({ user: null });
+});
+
+describe('upsertCachedUser — a declared clear empties the field', () => {
+  it.each(
+    CLEARABLE_USER_FIELDS.filter(
+      (field): field is Exclude<ClearableUserField, 'name.displayName'> =>
+        field !== 'name.displayName',
+    ),
+  )('drops a stale `%s` only when the caller declares it cleared', (field) => {
+    // WITHOUT the declaration: the guard holds, the stored value survives.
+    const guarded = makeClient();
+    seedFullEntry(guarded);
+    upsertCachedUser(guarded, clearedResponse, '');
+    expect(readById(guarded, 'u1')?.[field]).toBeDefined();
+
+    // WITH it: the same payload now empties exactly that field.
+    const cleared = makeClient();
+    seedFullEntry(cleared);
+    upsertCachedUser(cleared, clearedResponse, '', { cleared: [field] });
+    expect(readById(cleared, 'u1')?.[field]).toBeUndefined();
+  });
+
+  // Three `name` shapes, because `mergeName` branches on them and a single
+  // fixture leaves one branch untested (mutation-verified): the measured
+  // response carries `name: {}`, a request echo carries `name: {displayName:''}`,
+  // and a caller passing a bare object carries no `name` key at all.
+  it.each([
+    ['present but empty (the measured oxy-api shape)', clearedResponse],
+    ['an explicit empty displayName (the request shape)', clearedByEmptyString],
+    ['no `name` key at all', { id: 'u1', username: 'alice' } as CacheableUser],
+  ])(
+    'drops a stale display name only when declared — incoming name %s',
+    (_label, incoming) => {
+      const guarded = makeClient();
+      seedFullEntry(guarded);
+      upsertCachedUser(guarded, incoming, '');
+      expect(readById(guarded, 'u1')?.name).toEqual({
+        displayName: 'Alice A',
+        first: 'Alice',
+      });
+
+      const cleared = makeClient();
+      seedFullEntry(cleared);
+      upsertCachedUser(cleared, incoming, '', {
+        cleared: ['name.displayName'],
+      });
+      // `first` is not what was cleared and must survive — a clear is per-field,
+      // not "drop the whole `name` object".
+      expect(readById(cleared, 'u1')?.name).toEqual({ first: 'Alice' });
+    },
+  );
+
+  it('never lets the "Unknown user" sentinel survive a declared display-name clear', () => {
+    // The ghost-author sentinel is not a real value, so it must not block the
+    // clear either — it is "empty" for this purpose, exactly as it is for the
+    // anti-degradation guard.
+    const qc = makeClient();
+    seedFullEntry(qc);
+    upsertCachedUser(
+      qc,
+      { id: 'u1', username: 'alice', name: { displayName: 'Unknown user' } },
+      '',
+      { cleared: ['name.displayName'] },
+    );
+    expect(readById(qc, 'u1')?.name).toEqual({ first: 'Alice' });
+  });
+
+  it('clears under the by-username key too, not just by-id', () => {
+    const qc = makeClient();
+    seedFullEntry(qc, 'viewer-1');
+    upsertCachedUser(qc, clearedResponse, 'viewer-1', { cleared: ['avatar'] });
+
+    expect(readByUsername(qc, 'alice', 'viewer-1')?.avatar).toBeUndefined();
+    expect(readById(qc, 'u1')?.avatar).toBeUndefined();
+  });
+
+  it('clears ONLY the declared fields, leaving every other one intact', () => {
+    const qc = makeClient();
+    seedFullEntry(qc);
+    upsertCachedUser(qc, clearedResponse, '', { cleared: ['avatar'] });
+
+    const entry = readById(qc, 'u1');
+    expect(entry?.avatar).toBeUndefined();
+    // Vacuity floor: if a clear were implemented as "drop everything absent
+    // from the payload", all of these would be gone too and the test above
+    // would still pass.
+    expect(entry?.bio).toBe('old bio');
+    expect(entry?.description).toBe('old description');
+    expect(entry?.color).toBe('teal');
+    expect(entry?.name).toEqual({ displayName: 'Alice A', first: 'Alice' });
+    expect(entry?._count).toEqual({ followers: 10, following: 5 });
+  });
+
+  it('never drops the viewer relationship, whatever is declared', () => {
+    // `relationship` is not declarable (it is absent from CLEARABLE_USER_FIELDS)
+    // and is server-derived, never user-emptied. Dropping it is the
+    // "Follows you tag vanishes" bug this module exists to prevent.
+    const qc = makeClient();
+    seedFullEntry(qc, 'viewer-1');
+    upsertCachedUser(qc, clearedResponse, 'viewer-1', {
+      cleared: [...CLEARABLE_USER_FIELDS],
+    });
+
+    expect(readByUsername(qc, 'alice', 'viewer-1')?.relationship).toEqual({
+      isFollowing: true,
+      followsYou: true,
+    });
+    expect(readByUsername(qc, 'alice', 'viewer-1')?.username).toBe('alice');
+  });
+});
+
+describe('upsertCachedUser — a declared clear never beats a real value', () => {
+  it('keeps a meaningful incoming value for a field declared cleared', () => {
+    // The server-COMPOSED display name case: clearing the EXPLICIT name makes
+    // oxy-api return the composed one, which must be stored rather than
+    // blanked. Same rule for every field: `cleared` lowers the guard, it does
+    // not force an erasure.
+    const qc = makeClient();
+    seedFullEntry(qc);
+
+    upsertCachedUser(
+      qc,
+      {
+        id: 'u1',
+        username: 'alice',
+        name: { displayName: 'Alice Anderson' },
+        avatar: 'file_new',
+      },
+      '',
+      { cleared: ['name.displayName', 'avatar'] },
+    );
+
+    expect(readById(qc, 'u1')?.name).toEqual({
+      displayName: 'Alice Anderson',
+      first: 'Alice',
+    });
+    expect(readById(qc, 'u1')?.avatar).toBe('file_new');
+  });
+
+  it('treats an explicit null and an empty string as cleared, not as values', () => {
+    // oxy-api omits a cleared field, but `UpdateAccountInput` clears with `null`
+    // and `UserProfileUpdate` clears with `''`, so a caller echoing its own
+    // request must land on the same result as one passing the response.
+    for (const empty of [null, '', '   ']) {
+      const qc = makeClient();
+      seedFullEntry(qc);
+      upsertCachedUser(qc, { id: 'u1', username: 'alice', avatar: empty }, '', {
+        cleared: ['avatar'],
+      });
+      expect(readById(qc, 'u1')?.avatar).toBeUndefined();
+    }
+  });
+
+  it('is a no-op on a cold slot (nothing stale to drop)', () => {
+    const qc = makeClient();
+    upsertCachedUser(qc, clearedResponse, '', { cleared: ['avatar'] });
+
+    expect(readById(qc, 'u1')).toMatchObject({ id: 'u1', username: 'alice' });
+    expect(readById(qc, 'u1')?.avatar).toBeUndefined();
+    // The cold-slot stale-seed contract still holds.
+    expect(qc.getQueryState(queryKeys.users.detail('u1'))?.dataUpdatedAt).toBe(0);
+  });
+});
+
+describe('upsertCachedUsers — the batch path stays guarded', () => {
+  it('takes no clear declaration and never empties a field', () => {
+    // A batch is a multi-user projection: exactly the sparse source the guard
+    // exists for. If it ever grows a `cleared` option this test should fail.
+    const qc = makeClient();
+    seedFullEntry(qc);
+
+    upsertCachedUsers(qc, [{ id: 'u1', username: 'alice', avatar: null }], '');
+
+    expect(readById(qc, 'u1')?.avatar).toBe('file_old');
+  });
+});
+
+describe('clearedFieldsFromProfileUpdate', () => {
+  it('names only fields the patch deliberately emptied', () => {
+    expect(
+      clearedFieldsFromProfileUpdate({ avatar: '', bio: '', name: { displayName: '' } }),
+    ).toEqual(['avatar', 'bio', 'name.displayName']);
+    expect(clearedFieldsFromProfileUpdate({ avatar: 'file_new', bio: 'hello' })).toEqual([]);
+    expect(clearedFieldsFromProfileUpdate({ color: null })).toEqual(['color']);
+  });
+});
+
+describe('clearedFieldsFromAccountUpdate', () => {
+  it('treats null clears on managed accounts like profile clears', () => {
+    expect(
+      clearedFieldsFromAccountUpdate({
+        avatar: null,
+        bio: null,
+        accountCategories: [],
+        name: { displayName: '' },
+      }),
+    ).toEqual(['avatar', 'bio', 'accountCategories', 'name.displayName']);
+    expect(clearedFieldsFromAccountUpdate({ bio: 'still here' })).toEqual([]);
+  });
+});

package/src/ui/hooks/queries/userCache.ts

@@ -36,10 +36,38 @@
  *     never overwritten by a degraded/empty one (empty username, the
  *     `'Unknown user'` ghost-author sentinel, `null` avatar).
  *
+ * EXPRESSING A DELIBERATE CLEAR ("remove my picture")
+ * ---------------------------------------------------
+ * The anti-degradation rule above is right for a sparse source and wrong for a
+ * user who just emptied the field — and the two are NOT distinguishable from the
+ * payload. Measured against oxy-api's canonical serializer (`formatUserResponse`
+ * in `packages/api/src/utils/userTransform.ts`, which passes every field through
+ * `typeof value === 'string' ? value : undefined`): an account whose avatar,
+ * bio and display name were all just CLEARED serializes to
+ * `{"id":…,"publicKey":…,"username":…,"name":{},"languages":[]}` — byte-identical
+ * to the same account read as a sparse projection. There is no `null` and no
+ * `''` on the wire to key on. The information that a field was deliberately
+ * emptied exists ONLY at the call site that performed the write.
+ *
+ * So the caller declares it: `upsertCachedUser(qc, user, viewerId, { cleared:
+ * ['avatar'] })`. For a declared field an incoming EMPTY value means the field
+ * IS empty and the stale value is dropped; a MEANINGFUL incoming value still
+ * wins as usual (so `{ cleared: ['name.displayName'] }` on a personal account,
+ * where clearing the explicit name makes the server return the COMPOSED one,
+ * keeps the composed name rather than blanking it).
+ *
+ * A blanket "this source is authoritative, treat every absent field as cleared"
+ * flag was considered and rejected: because the two payloads are byte-identical,
+ * such a flag is an unverifiable promise about provenance, and the failure mode
+ * of getting it wrong is blanking real identity data in every Oxy app. Naming
+ * the fields states something the caller actually observed — which fields the
+ * user emptied — and bounds the damage to exactly those.
+ *
  * It is a cache write only — zero network, one `setQueryData` per key.
  */
 
-import type { UserNameResponse } from "@oxyhq/contracts";
+import type { UserNameResponse, UserProfileUpdate } from "@oxyhq/contracts";
+import type { UpdateAccountInput } from "@oxyhq/core";
 import type { QueryClient } from "@tanstack/react-query";
 import { useAuthStore } from "../../stores/authStore";
 import { queryKeys } from "./queryKeys";
@@ -78,6 +106,108 @@ export interface CacheableUser {
 /** The degraded display-name sentinel (ghost-author rule). */
 const DEGRADED_DISPLAY_NAME = "Unknown user";
 
+/**
+ * The profile fields a user can genuinely EMPTY through a real Oxy write, and
+ * for which "empty" is a state every renderer already handles.
+ *
+ * Deliberately a closed list rather than "any field": a clear DELETES data from
+ * the cache, so the blast radius of a mistaken declaration is bounded here
+ * instead of resting on each call site. `username` is absent because an account
+ * always has one; `_count` and `relationship` are absent because they are
+ * server-derived, never user-emptied — and dropping a viewer `relationship` is
+ * the exact "Follows you vanishes" bug this module exists to prevent.
+ *
+ * Each entry is clearable through a shipped write path: `avatar`, `bio`,
+ * `description` and `name.displayName` via `UserProfileUpdate` (`''` clears) and
+ * `UpdateAccountInput` (`null` clears avatar/bio; `accountCategories: []`
+ * clears the ordered category list), and `color` via its nullable field.
+ */
+export const CLEARABLE_USER_FIELDS = [
+	"avatar",
+	"bio",
+	"description",
+	"color",
+	"accountCategories",
+	"name.displayName",
+] as const;
+
+/** A field nameable in {@link UpsertCachedUserOptions.cleared}. */
+export type ClearableUserField = (typeof CLEARABLE_USER_FIELDS)[number];
+
+/**
+ * Fields the caller deliberately emptied in a `PUT /users/me` patch. The wire
+ * response omits cleared scalars, so the cache needs this list to drop stale
+ * values immediately instead of waiting for a refetch that merges the same
+ * sparse payload.
+ */
+export function clearedFieldsFromProfileUpdate(
+	updates: UserProfileUpdate,
+): ClearableUserField[] {
+	const cleared: ClearableUserField[] = [];
+	if ("avatar" in updates && !isMeaningful(updates.avatar)) {
+		cleared.push("avatar");
+	}
+	if ("bio" in updates && !isMeaningful(updates.bio)) {
+		cleared.push("bio");
+	}
+	if ("description" in updates && !isMeaningful(updates.description)) {
+		cleared.push("description");
+	}
+	if ("color" in updates && updates.color === null) {
+		cleared.push("color");
+	}
+	if (
+		updates.name !== undefined &&
+		"displayName" in updates.name &&
+		!isMeaningful(updates.name.displayName)
+	) {
+		cleared.push("name.displayName");
+	}
+	return cleared;
+}
+
+/**
+ * Same contract as {@link clearedFieldsFromProfileUpdate} for managed-account
+ * `PATCH /accounts/:id` writes (`null` clears avatar/bio/category).
+ */
+export function clearedFieldsFromAccountUpdate(
+	input: UpdateAccountInput,
+): ClearableUserField[] {
+	const cleared: ClearableUserField[] = [];
+	if ("avatar" in input && !isMeaningful(input.avatar)) {
+		cleared.push("avatar");
+	}
+	if ("bio" in input && !isMeaningful(input.bio)) {
+		cleared.push("bio");
+	}
+	if (
+		"accountCategories" in input &&
+		Array.isArray(input.accountCategories) &&
+		input.accountCategories.length === 0
+	) {
+		cleared.push("accountCategories");
+	}
+	if (
+		input.name !== undefined &&
+		"displayName" in input.name &&
+		!isMeaningful(input.name.displayName)
+	) {
+		cleared.push("name.displayName");
+	}
+	return cleared;
+}
+
+/** Options for {@link upsertCachedUser}. */
+export interface UpsertCachedUserOptions {
+	/**
+	 * Fields the write that produced this user DELIBERATELY emptied. For each,
+	 * an incoming empty value stops meaning "this source does not carry it" and
+	 * starts meaning "it is empty" — so the stale value is dropped rather than
+	 * preserved. Everything not named here keeps the anti-degradation guard.
+	 */
+	cleared?: readonly ClearableUserField[];
+}
+
 /** A cache entry always carries a resolved string `id`. */
 type CachedUser = CacheableUser & { id: string; name?: UserNameResponse };
 
@@ -142,23 +272,55 @@ function normalizeIncoming(user: CacheableUser): CachedUser | null {
 	return cached.id ? cached : null;
 }
 
-/** Merge two `name` objects field-by-field, with anti-degradation on `displayName`. */
+/**
+ * Copy a name WITHOUT its `displayName`. The key must end up ABSENT rather than
+ * present-and-`undefined`: consumers render `name.displayName` directly and fall
+ * back to the handle when it is missing, and a present-but-undefined key also
+ * changes what a later merge sees.
+ */
+function omitDisplayName(name: UserNameResponse): UserNameResponse {
+	const result: UserNameResponse = {};
+	for (const [key, value] of Object.entries(name)) {
+		if (key !== "displayName") result[key] = value;
+	}
+	return result;
+}
+
+/**
+ * Merge two `name` objects field-by-field, with anti-degradation on
+ * `displayName`.
+ *
+ * `clearDisplayName` is the declared-clear escape hatch: the incoming value
+ * still wins whenever it is meaningful (an account that clears its explicit
+ * display name gets the server-COMPOSED one back, which must not be discarded),
+ * and only a genuinely empty incoming value drops the stored one.
+ *
+ * Both incoming shapes reach the clear, and they are separate branches: the
+ * measured oxy-api response carries `name` as a PRESENT-but-empty object, while
+ * a caller passing a bare user object may carry no `name` key at all.
+ */
 function mergeName(
 	existing: UserNameResponse | undefined,
 	incoming: UserNameResponse | undefined,
+	clearDisplayName: boolean,
 ): UserNameResponse | undefined {
-	if (incoming === undefined) return existing;
+	if (incoming === undefined) {
+		if (!clearDisplayName || existing === undefined) return existing;
+		return omitDisplayName(existing);
+	}
 	if (existing === undefined) return incoming;
 	const merged: UserNameResponse = { ...existing };
 	for (const [key, value] of Object.entries(incoming)) {
 		if (key === "displayName") continue;
 		if (isMeaningful(value)) merged[key] = value;
 	}
-	// Never let an empty / `'Unknown user'` displayName overwrite a real one.
+	// Never let an empty / `'Unknown user'` displayName overwrite a real one —
+	// unless the caller declared that the user cleared it.
 	if (isMeaningfulDisplayName(incoming.displayName)) {
 		merged.displayName = incoming.displayName;
+		return merged;
 	}
-	return merged;
+	return clearDisplayName ? omitDisplayName(merged) : merged;
 }
 
 /** Merge `_count` field-by-field so a partial count never replaces a fuller one. */
@@ -203,13 +365,22 @@ function mergeRelationship(
  * When `includeRelationship` is false (the viewer-independent by-id key), the
  * viewer-relative `relationship` field is never read, written, or preserved —
  * only the by-username key carries it (`useUserByUsername`).
+ *
+ * `cleared` names the fields the write deliberately emptied. It is applied
+ * AFTER the merge, because the merge loop can only ever COPY a meaningful value
+ * — an emptied field is absent from `incoming` (see the module docs: oxy-api
+ * omits it entirely) and would otherwise survive from `existing` untouched.
  */
 function mergeUsers(
 	existing: CachedUser,
 	incoming: CachedUser,
-	options?: { includeRelationship?: boolean },
+	options?: {
+		includeRelationship?: boolean;
+		cleared?: readonly ClearableUserField[];
+	},
 ): CachedUser {
 	const includeRelationship = options?.includeRelationship ?? true;
+	const cleared = options?.cleared;
 	const merged: CachedUser = { ...existing };
 	for (const [key, value] of Object.entries(incoming)) {
 		if (key === "name" || key === "_count" || key === "relationship") continue;
@@ -219,7 +390,11 @@ function mergeUsers(
 		}
 		if (isMeaningful(value)) merged[key] = value;
 	}
-	const name = mergeName(existing.name, incoming.name);
+	const name = mergeName(
+		existing.name,
+		incoming.name,
+		cleared?.includes("name.displayName") ?? false,
+	);
 	if (name !== undefined) merged.name = name;
 	const count = mergeCount(existing._count, incoming._count);
 	if (count !== undefined) merged._count = count;
@@ -232,6 +407,12 @@ function mergeUsers(
 	} else {
 		merged.relationship = undefined;
 	}
+	if (cleared) {
+		for (const field of cleared) {
+			if (field === "name.displayName") continue; // handled by `mergeName`.
+			if (!isMeaningful(incoming[field])) delete merged[field];
+		}
+	}
 	return merged;
 }
 
@@ -240,9 +421,15 @@ function upsertOneKey(
 	queryClient: QueryClient,
 	key: readonly unknown[],
 	incoming: CachedUser,
-	options: { includeRelationship: boolean },
+	options: {
+		includeRelationship: boolean;
+		cleared?: readonly ClearableUserField[];
+	},
 ): void {
-	const mergeOpts = { includeRelationship: options.includeRelationship };
+	const mergeOpts = {
+		includeRelationship: options.includeRelationship,
+		cleared: options.cleared,
+	};
 	const existing = queryClient.getQueryData<CacheableUser>(key);
 	if (existing === undefined) {
 		// Cold slot: seed the full incoming object, STALE, so react-query refetches
@@ -284,20 +471,27 @@ function resolveViewerId(viewerId?: string): string {
  * @param user        A `User`-shaped object (may be sparse).
  * @param viewerId    The active viewer id for the by-username key. Defaults to
  *                    the current auth-store user id.
+ * @param options     `cleared` names the fields the write deliberately emptied
+ *                    — the ONLY way "remove my picture" can propagate, since a
+ *                    cleared field and an uncarried one are byte-identical on
+ *                    the wire (see the module docs).
  */
 export function upsertCachedUser(
 	queryClient: QueryClient,
 	user: CacheableUser,
 	viewerId?: string,
+	options?: UpsertCachedUserOptions,
 ): void {
 	const incoming = normalizeIncoming(user);
 	if (!incoming) return;
+	const cleared = options?.cleared;
 
 	// By-id identity entry (read by `useUserById`). Not viewer-scoped — never store
 	// the viewer-relative `relationship` here or one viewer's follow state leaks
 	// into every other viewer's by-id cache entry.
 	upsertOneKey(queryClient, queryKeys.users.detail(incoming.id), incoming, {
 		includeRelationship: false,
+		cleared,
 	});
 
 	const username = incoming.username;
@@ -307,7 +501,10 @@ export function upsertCachedUser(
 		// the key through the SAME helper the hook uses so username normalization
 		// (`trim().toLowerCase()`) matches byte-for-byte.
 		const key = queryKeys.users.byUsername(username, resolveViewerId(viewerId));
-		upsertOneKey(queryClient, key, incoming, { includeRelationship: true });
+		upsertOneKey(queryClient, key, incoming, {
+			includeRelationship: true,
+			cleared,
+		});
 	}
 }
 
@@ -315,6 +512,10 @@ export function upsertCachedUser(
  * Batch merge-upsert many users at once (for a feed / list / search response).
  * Resolves the viewer id once and upserts each user cumulatively — a user that
  * appears twice merges both slices into the single cache entry.
+ *
+ * Takes NO `cleared`, deliberately: a batch is a multi-user projection, so it is
+ * exactly the sparse source the anti-degradation guard exists for, and one
+ * declaration could not be true of every user in the array anyway.
  */
 export function upsertCachedUsers(
 	queryClient: QueryClient,

package/src/ui/screens/AccountSettingsScreen.tsx

@@ -18,6 +18,10 @@ import { SettingsIcon } from '../components/SettingsIcon';
 import { useOxy } from '../context/OxyContext';
 import { useI18n } from '../hooks/useI18n';
 import { useSurfaceHeader } from '../hooks/useSurfaceHeader';
+import {
+  clearedFieldsFromAccountUpdate,
+  upsertCachedUser,
+} from '../hooks/queries/userCache';
 
 const DISPLAY_NAME_MAX = MAX_DISPLAY_NAME_LENGTH;
 const BIO_MAX = 160;
@@ -78,7 +82,11 @@ const AccountSettingsScreen: React.FC<BaseScreenProps> = ({ onClose, goBack, nav
   const updateMutation = useMutation({
     mutationKey: ['accounts', 'update', id],
     mutationFn: (input: UpdateAccountInput) => oxyServices.updateAccount(id, input),
-    onSuccess: () => {
+    onSuccess: (updatedNode, input) => {
+      const cleared = clearedFieldsFromAccountUpdate(input);
+      upsertCachedUser(queryClient, updatedNode.account, user?.id, {
+        cleared: cleared.length > 0 ? cleared : undefined,
+      });
       queryClient.invalidateQueries({ queryKey: ['accounts', 'detail', id] });
       queryClient.invalidateQueries({ queryKey: ['accounts'] });
       toast.success(t('accounts.settings.toasts.saved') || 'Account updated');