@oxy.so/services 1.0.0

package/src/ui/session/sharedDeviceCredentialStore.ts

@@ -0,0 +1,318 @@
+/**
+ * The platform half of the shared native DeviceSession credential.
+ *
+ * `@oxy.so/core` owns the rules (`sharedDeviceCredential.ts`: when to adopt, when
+ * to publish, and above all that an unreadable slot is never an empty one). This
+ * module owns only where the bytes live, which is genuinely different per
+ * platform:
+ *
+ *  - **iOS** — one `expo-secure-store` item in the approved Keychain Access Group
+ *    `group.so.oxy.shared`, under its OWN `keychainService`
+ *    ({@link IOS_DEVICE_SESSION_KEYCHAIN_SERVICE}). Every identity slot uses a
+ *    different service (`oxy_identity`, `oxy_identity_backup`,
+ *    `oxy_identity_mnemonic`) and the legacy cross-app identity keypair uses the
+ *    same group with NO service at all — so this item cannot alias any of them.
+ *    That separation is the point of the whole phase: the group-shared identity
+ *    key and the group-shared device-session credential are different secrets
+ *    with different blast radii and must not be conflated.
+ *  - **Android** — the signature-protected `OxyDeviceSession` broker (its own
+ *    EncryptedSharedPreferences file, its own ContentProvider, its own
+ *    `signature`-level permission). It carries a session credential; it can NOT
+ *    reach the identity keypair, which lives in a different file behind a
+ *    different provider.
+ *  - **web / anything else** — no shared slot. Each origin is its own device by
+ *    design, so the factory returns `null` and the cold boot simply omits the
+ *    lane.
+ *
+ * ## What is written here, and what is not
+ *
+ * Only `{deviceId, deviceSecret}`. No access token, no account id, no user id,
+ * and never any identity key material.
+ *
+ * ## Accessibility
+ *
+ * `WHEN_UNLOCKED_THIS_DEVICE_ONLY`: a device credential must not travel to
+ * another handset in an iCloud/encrypted backup restore — the restored device is
+ * a different device and has to establish its own session. It also keeps the item
+ * out of reach while the phone is locked, which is why a read can legitimately
+ * fail and why the `unavailable` verdict exists at all.
+ */
+import { Platform } from 'react-native';
+import { requireOptionalNativeModule } from 'expo-modules-core';
+import {
+  normalizeSharedDeviceSessionRead,
+  type SharedDeviceCredential,
+  type SharedDeviceCredentialRead,
+  type SharedDeviceCredentialStore,
+} from '@oxy.so/core';
+
+/**
+ * The iOS Keychain Access Group every official Oxy app declares in its
+ * entitlements. Shared with the identity slots — the group is the app-group
+ * boundary, not the secret's identity.
+ */
+export const IOS_KEYCHAIN_ACCESS_GROUP = 'group.so.oxy.shared';
+
+/**
+ * The iOS `keychainService` for the DEVICE SESSION credential. Deliberately
+ * distinct from every identity and recovery service; do not reuse one of those
+ * here, and do not drop it (an item written with no service shares the legacy
+ * identity slot's namespace inside the group).
+ */
+export const IOS_DEVICE_SESSION_KEYCHAIN_SERVICE = 'oxy_device_session';
+
+/** The single key holding the JSON-encoded `{deviceId, deviceSecret}` pair. */
+export const SHARED_DEVICE_SESSION_STORAGE_KEY = 'oxy_shared_device_session_v1';
+
+// Variable indirection so Metro's static analyzer never traces expo-secure-store
+// into the web bundle; the module is native-only and optional.
+const SECURE_STORE_MODULE = 'expo-secure-store';
+
+/**
+ * The subset of `expo-secure-store` this module needs. Unlike the adapter in
+ * `nativeSecureStorage.ts` it must pass OPTIONS — the access group and the
+ * dedicated service are the entire mechanism here, so an options-less wrapper
+ * would silently write a package-private item that no sibling app can see.
+ */
+interface KeychainGroupStore {
+  getItemAsync(key: string, options?: object): Promise<string | null>;
+  setItemAsync(key: string, value: string, options?: object): Promise<void>;
+  deleteItemAsync(key: string, options?: object): Promise<void>;
+  readonly WHEN_UNLOCKED_THIS_DEVICE_ONLY: number;
+}
+
+let keychainStorePromise: Promise<KeychainGroupStore | null> | null = null;
+
+function loadKeychainGroupStore(): Promise<KeychainGroupStore | null> {
+  if (!keychainStorePromise) {
+    const moduleName = SECURE_STORE_MODULE;
+    keychainStorePromise = import(moduleName)
+      .then((mod: Partial<KeychainGroupStore>) => {
+        if (
+          typeof mod.getItemAsync === 'function' &&
+          typeof mod.setItemAsync === 'function' &&
+          typeof mod.deleteItemAsync === 'function' &&
+          typeof mod.WHEN_UNLOCKED_THIS_DEVICE_ONLY === 'number'
+        ) {
+          return {
+            getItemAsync: mod.getItemAsync.bind(mod),
+            setItemAsync: mod.setItemAsync.bind(mod),
+            deleteItemAsync: mod.deleteItemAsync.bind(mod),
+            WHEN_UNLOCKED_THIS_DEVICE_ONLY: mod.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+          } satisfies KeychainGroupStore;
+        }
+        return null;
+      })
+      .catch(() => null);
+  }
+  return keychainStorePromise;
+}
+
+/** Parse the stored JSON into a credential, or `null` for anything malformed. */
+function parseStoredCredential(raw: string | null): SharedDeviceCredential | null {
+  if (!raw) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    return null;
+  }
+  const candidate = parsed as Record<string, unknown>;
+  if (
+    typeof candidate.deviceId !== 'string' ||
+    candidate.deviceId.length === 0 ||
+    typeof candidate.deviceSecret !== 'string' ||
+    candidate.deviceSecret.length === 0
+  ) {
+    return null;
+  }
+  return { deviceId: candidate.deviceId, deviceSecret: candidate.deviceSecret };
+}
+
+/**
+ * The iOS store: one keychain item in the shared access group.
+ *
+ * A THROWN read is `unavailable`, a `null` read is `absent`. That mapping is the
+ * whole safety contract — `expo-secure-store` returns `null` for a genuinely
+ * missing item and throws when the keychain itself refuses, and collapsing the
+ * two is what would let a locked phone look like a device that never had a
+ * session.
+ */
+function createKeychainGroupCredentialStore(): SharedDeviceCredentialStore {
+  const readOptions = {
+    keychainService: IOS_DEVICE_SESSION_KEYCHAIN_SERVICE,
+    keychainAccessGroup: IOS_KEYCHAIN_ACCESS_GROUP,
+  };
+
+  return {
+    read: async (): Promise<SharedDeviceCredentialRead> => {
+      const store = await loadKeychainGroupStore();
+      if (!store) {
+        return { state: 'unsupported' };
+      }
+      let raw: string | null;
+      try {
+        raw = await store.getItemAsync(SHARED_DEVICE_SESSION_STORAGE_KEY, readOptions);
+      } catch (error) {
+        return { state: 'unavailable', cause: error };
+      }
+      if (raw === null) {
+        return { state: 'absent' };
+      }
+      const credential = parseStoredCredential(raw);
+      if (!credential) {
+        // Something IS stored and we cannot read it. Reporting `absent` would
+        // authorise overwriting whatever a newer build put there.
+        return {
+          state: 'unavailable',
+          cause: new Error('shared device session item is present but not parseable'),
+        };
+      }
+      return { state: 'present', credential };
+    },
+
+    publish: async (credential): Promise<boolean> => {
+      const store = await loadKeychainGroupStore();
+      if (!store) {
+        return false;
+      }
+      const value = JSON.stringify(credential);
+      try {
+        await store.setItemAsync(SHARED_DEVICE_SESSION_STORAGE_KEY, value, {
+          ...readOptions,
+          keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+        });
+        // Read-back verify. A keychain write can resolve without the item having
+        // landed under the access group (a missing entitlement is the usual
+        // cause), and a phantom credential would send a fresh install into a mint
+        // that can never succeed.
+        return (await store.getItemAsync(SHARED_DEVICE_SESSION_STORAGE_KEY, readOptions)) === value;
+      } catch {
+        return false;
+      }
+    },
+
+    clear: async (): Promise<void> => {
+      const store = await loadKeychainGroupStore();
+      if (!store) {
+        return;
+      }
+      try {
+        await store.deleteItemAsync(SHARED_DEVICE_SESSION_STORAGE_KEY, readOptions);
+      } catch {
+        // Best-effort: the slot is a join point, not a source of truth.
+      }
+    },
+  };
+}
+
+/**
+ * The Android broker's JS surface. `read` returns an UNTRUSTED payload that
+ * {@link normalizeSharedDeviceSessionRead} narrows; `write` reports whether the
+ * native read-back confirmed the bytes.
+ */
+interface OxyDeviceSessionNativeModule {
+  read(): Promise<unknown>;
+  write(deviceId: string, deviceSecret: string): Promise<boolean>;
+  clear(): Promise<void>;
+}
+
+let brokerModule: OxyDeviceSessionNativeModule | null | undefined;
+
+/**
+ * Resolve the `OxyDeviceSession` broker, or `null` when it is not autolinked.
+ *
+ * `requireOptionalNativeModule` (a static import Metro always resolves) rather
+ * than a dynamic `import(moduleName)`: the latter compiles to `require(variable)`
+ * in the CJS build, which Metro cannot resolve inside a consuming app — it
+ * silently returns `null` there, which is exactly how the cross-app identity
+ * bridge broke once. Same reasoning as `backgroundSession.ts` next door.
+ */
+function loadBrokerModule(): OxyDeviceSessionNativeModule | null {
+  if (brokerModule === undefined) {
+    const native = requireOptionalNativeModule<Partial<OxyDeviceSessionNativeModule>>('OxyDeviceSession');
+    brokerModule =
+      native && typeof native.read === 'function' && typeof native.write === 'function' && typeof native.clear === 'function'
+        ? {
+            read: native.read.bind(native),
+            write: native.write.bind(native),
+            clear: native.clear.bind(native),
+          }
+        : null;
+  }
+  return brokerModule;
+}
+
+/**
+ * The Android store: the signature-protected `OxyDeviceSession` broker.
+ *
+ * The broker already answers with an explicit status, so the only work here is
+ * narrowing an UNTRUSTED payload — `normalizeSharedDeviceSessionRead` resolves
+ * anything it does not recognise to `unavailable`, never `absent`.
+ */
+function createBrokerCredentialStore(): SharedDeviceCredentialStore {
+  return {
+    read: async (): Promise<SharedDeviceCredentialRead> => {
+      const broker = loadBrokerModule();
+      if (!broker) {
+        return { state: 'unsupported' };
+      }
+      try {
+        return normalizeSharedDeviceSessionRead(await broker.read());
+      } catch (error) {
+        return { state: 'unavailable', cause: error };
+      }
+    },
+
+    publish: async (credential): Promise<boolean> => {
+      const broker = loadBrokerModule();
+      if (!broker) {
+        return false;
+      }
+      try {
+        // The broker read-back-verifies natively and returns the verdict.
+        return await broker.write(credential.deviceId, credential.deviceSecret);
+      } catch {
+        return false;
+      }
+    },
+
+    clear: async (): Promise<void> => {
+      const broker = loadBrokerModule();
+      if (!broker) {
+        return;
+      }
+      try {
+        await broker.clear();
+      } catch {
+        // Best-effort — see the iOS store.
+      }
+    },
+  };
+}
+
+/**
+ * The shared DeviceSession credential slot for this runtime, or `null` when
+ * there is none.
+ *
+ * The branch is on the PLATFORM, not on which module happens to load, because
+ * `expo-secure-store` loads perfectly well on Android — it would just quietly
+ * ignore `keychainAccessGroup` and read a package-private item, which looks
+ * exactly like an empty shared slot. This is the same iOS-vs-Android split
+ * `KeyManager` makes for the shared identity, for the same reason.
+ *
+ * Any other native platform gets the broker, which answers `unsupported` when
+ * the module is not linked — so the lane is simply off, which is the safe
+ * direction.
+ */
+export function createPlatformSharedDeviceCredentialStore(): SharedDeviceCredentialStore | null {
+  if (Platform.OS === 'web') {
+    return null;
+  }
+  return Platform.OS === 'ios' ? createKeychainGroupCredentialStore() : createBrokerCredentialStore();
+}

package/src/ui/session/tokenTransport.ts

@@ -0,0 +1,70 @@
+import { logger, type OxyServices, type TokenTransport } from '@oxy.so/core';
+import type { DeviceSessionState } from '@oxy.so/contracts';
+
+/**
+ * Platform `TokenTransport` for `SessionClient` (device-first model).
+ *
+ * `ensureActiveToken` is the fallback the client uses when a `session_state`
+ * push arrived WITHOUT an embedded `activeToken` and the planted bearer does not
+ * already belong to the state's active account. It mints one through the ONE
+ * unified single-flight the scheduler, the request-time preflight, and the 401
+ * retry all use — `oxyServices.httpService.refreshAccessToken(...)` — which runs
+ * the installed refresh handler (present the persisted zero-cookie `deviceId` +
+ * `deviceSecret` at `POST /session/device/token`, which mints for the device's
+ * CURRENT active account). Routing through the SAME entry point means this lane
+ * can never double-rotate the device secret against the others: it has NO
+ * private single-flight of its own.
+ *
+ * The short-circuit compares the planted bearer's ACCOUNT against
+ * `state.activeAccountId`, not mere token presence: a bearer for the PREVIOUS
+ * account (an account switch) must still mint the new account's token — skipping
+ * on presence alone would leave a subscriber observing the new active account
+ * under the old account's bearer (the account-switch 404 race).
+ *
+ * A failure is logged and swallowed: this method must never throw out (it runs
+ * inside the socket state handler).
+ *
+ * `getPinnedAccountId` is the identity-bound escape hatch. Converging the bearer
+ * on `state.activeAccountId` is precisely what an identity-bound client must
+ * never do — its token is minted for the PINNED account by the cold boot /
+ * re-mint lane. `SessionClient` already bypasses the transport entirely while
+ * pinned; this guard is the services-side half of that contract, so no future
+ * wiring can reintroduce the convergence from this end.
+ */
+export function createTokenTransport(
+  oxyServices: OxyServices,
+  getPinnedAccountId?: () => string | null,
+): TokenTransport {
+  return {
+    async ensureActiveToken(state: DeviceSessionState): Promise<void> {
+      if ((getPinnedAccountId?.() ?? null) !== null) {
+        return;
+      }
+      try {
+        // Skip the mint ONLY when the planted bearer already identifies the
+        // active account. `getCurrentUserId()` decodes the bearer's `userId`/`id`
+        // (null when absent/opaque), directly comparable to the account id.
+        const activeAccountId = state.activeAccountId;
+        if (activeAccountId !== null && oxyServices.getCurrentUserId() === activeAccountId) {
+          return;
+        }
+      } catch (error) {
+        logger.warn('ensureActiveToken: bearer-account check threw', { component: 'TokenTransport' }, error);
+      }
+
+      try {
+        // The shared HttpService single-flight coalesces concurrent callers onto
+        // one in-flight mint; no local `inFlightMint` guard is needed.
+        const token = await oxyServices.httpService.refreshAccessToken('preflight');
+        if (!token) {
+          logger.debug('ensureActiveToken: refresh produced no session', {
+            component: 'TokenTransport',
+            deviceId: state.deviceId,
+          });
+        }
+      } catch (error) {
+        logger.warn('ensureActiveToken: refresh failed', { component: 'TokenTransport' }, error);
+      }
+    },
+  };
+}

package/src/ui/session/useBackgroundSessionSync.ts

@@ -0,0 +1,92 @@
+/**
+ * Keeps the native background credential in step with the session, so an app
+ * enables background authentication with one prop and writes no session code of
+ * its own.
+ *
+ * See `./backgroundSession` for what the credential is and why it is separate
+ * from the rotating device secret.
+ */
+import { useEffect } from 'react';
+import { AppState } from 'react-native';
+import type { OxyServices } from '@oxy.so/core';
+import {
+  clearBackgroundSession,
+  isBackgroundSessionSupported,
+  syncBackgroundSession,
+} from './backgroundSession';
+
+export interface UseBackgroundSessionSyncInput {
+  /** `OxyProviderProps.backgroundSession`. */
+  enabled: boolean;
+  oxyServices: OxyServices;
+  /** The signed-in account, or `null` when signed out. */
+  userId: string | null;
+  /** Whether a bearer is available yet — provisioning needs one. */
+  canUsePrivateApi: boolean;
+}
+
+/**
+ * An effect is the right shape here, unusually for this codebase: the work is a
+ * side effect on native storage, and it has to react both to an identity change
+ * (a value) and to the app being foregrounded (a subscription). There is no
+ * derived-state or React Query formulation of "write a credential to the
+ * keystore when the user changes or the app comes back".
+ *
+ * Re-runs on identity change, which is what makes sign-out and account switching
+ * work: `syncBackgroundSession` clears a credential belonging to anyone other
+ * than `userId` before it does any network work.
+ */
+export function useBackgroundSessionSync({
+  enabled,
+  oxyServices,
+  userId,
+  canUsePrivateApi,
+}: UseBackgroundSessionSyncInput): void {
+  useEffect(() => {
+    if (!isBackgroundSessionSupported()) {
+      return;
+    }
+
+    if (!enabled) {
+      // An app that leaves the feature off must not keep a credential THIS app
+      // provisioned earlier. The store is package-scoped (see
+      // OxyBackgroundSessionStore), so this cannot revoke a sibling Oxy app's
+      // credential under the shared UID.
+      void clearBackgroundSession();
+      return;
+    }
+
+    // A run that is superseded (unmount, or another identity change) must not
+    // write the credential it was about to write.
+    let current = true;
+    // Deliberately NOT caught. `syncBackgroundSession` already handles every
+    // runtime failure internally and throws for exactly one thing: an installed
+    // `@oxy.so/core` too old to provision. That is a dependency mistake which must
+    // surface, so it is allowed to reject — adding a `.catch()` here would put it
+    // back behind the silence it was moved out of.
+    const run = () => {
+      void syncBackgroundSession({
+        oxyServices,
+        userId,
+        canUsePrivateApi,
+        isCurrent: () => current,
+      });
+    };
+
+    run();
+    const subscription = AppState.addEventListener('change', (state) => {
+      if (state === 'active') {
+        run();
+      }
+    });
+
+    return () => {
+      current = false;
+      subscription.remove();
+      // Deliberately NOT clearing here. Unmount is the app closing, which is
+      // precisely when the credential has to survive — clearing on teardown
+      // would defeat the entire feature. Revocation happens on sign-out (via a
+      // `userId` of null), on the server, or when the credential expires.
+    };
+  }, [enabled, oxyServices, userId, canUsePrivateApi]);
+}

package/src/ui/stores/__tests__/followStore.test.ts

@@ -0,0 +1,181 @@
+/**
+ * followStore — tri-state seed, micro-batched resolution, and optimistic
+ * mutation tests.
+ *
+ * Covers the follow-system efficiency overhaul:
+ *  - `setFollowStatuses` seeds only-if-absent (never clobbers a definite value)
+ *  - `resolveFollowStatuses` coalesces every UNKNOWN id requested in one tick
+ *    into a SINGLE `getFollowStatuses` call, and skips known/seeded ids
+ *  - `toggleFollowUser` writes optimistically BEFORE the await and rolls back on
+ *    error
+ */
+
+import type { OxyServices, FollowMutationResult } from '@oxy.so/core';
+import { useFollowStore } from '../followStore';
+
+// A microtask + macrotask flush: `resolveFollowStatuses` schedules its bulk call
+// via `queueMicrotask`, and the mocked `getFollowStatuses` resolves on the
+// microtask queue, so a single macrotask turn drains both.
+const flush = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+interface FollowServicesMock {
+  getFollowStatuses: jest.Mock<Promise<Record<string, boolean>>, [string[]]>;
+  followUser: jest.Mock<Promise<FollowMutationResult>, [string]>;
+  unfollowUser: jest.Mock<Promise<FollowMutationResult>, [string]>;
+  getCurrentUserId: jest.Mock<string | null, []>;
+}
+
+const makeServices = (): { mock: FollowServicesMock; services: OxyServices } => {
+  const mock: FollowServicesMock = {
+    getFollowStatuses: jest.fn(async (ids: string[]) =>
+      Object.fromEntries(ids.map((id) => [id, false])),
+    ),
+    followUser: jest.fn(async () => ({ message: 'ok' })),
+    unfollowUser: jest.fn(async () => ({ message: 'ok' })),
+    getCurrentUserId: jest.fn(() => 'viewer-1'),
+  };
+  return { mock, services: mock as unknown as OxyServices };
+};
+
+beforeEach(() => {
+  useFollowStore.getState().resetFollowState();
+});
+
+afterEach(async () => {
+  // Drain any pending micro-batch so module-level state never leaks between tests.
+  await flush();
+});
+
+describe('setFollowStatuses (seed-only-if-absent)', () => {
+  it('seeds absent ids and never clobbers an existing definite value', () => {
+    const store = useFollowStore.getState();
+    store.setFollowStatuses({ u1: true });
+    store.setFollowStatuses({ u1: false, u2: true });
+
+    expect(useFollowStore.getState().followingUsers).toEqual({ u1: true, u2: true });
+  });
+});
+
+describe('resolveFollowStatuses (micro-batched)', () => {
+  it('coalesces every id requested in one tick into a SINGLE call', async () => {
+    const { mock, services } = makeServices();
+    mock.getFollowStatuses.mockImplementation(async (ids) =>
+      Object.fromEntries(ids.map((id) => [id, id === 'u1'])),
+    );
+
+    const store = useFollowStore.getState();
+    store.resolveFollowStatuses(['u1', 'u2'], services);
+    store.resolveFollowStatuses(['u3'], services);
+
+    await flush();
+
+    expect(mock.getFollowStatuses).toHaveBeenCalledTimes(1);
+    expect(mock.getFollowStatuses).toHaveBeenCalledWith(['u1', 'u2', 'u3']);
+    expect(useFollowStore.getState().followingUsers).toEqual({ u1: true, u2: false, u3: false });
+  });
+
+  it('skips ids whose status is already known/seeded', async () => {
+    const { mock, services } = makeServices();
+    const store = useFollowStore.getState();
+    store.setFollowStatuses({ u1: false }); // seeded → must NOT re-fetch
+
+    store.resolveFollowStatuses(['u1', 'u2'], services);
+    await flush();
+
+    expect(mock.getFollowStatuses).toHaveBeenCalledTimes(1);
+    expect(mock.getFollowStatuses).toHaveBeenCalledWith(['u2']);
+    // The seeded false is preserved; u2 resolved.
+    expect(useFollowStore.getState().followingUsers).toEqual({ u1: false, u2: false });
+  });
+
+  it('performs NO call when every requested id is already known', async () => {
+    const { mock, services } = makeServices();
+    const store = useFollowStore.getState();
+    store.setFollowStatuses({ u1: true, u2: false });
+
+    store.resolveFollowStatuses(['u1', 'u2'], services);
+    await flush();
+
+    expect(mock.getFollowStatuses).not.toHaveBeenCalled();
+  });
+});
+
+describe('toggleFollowUser (optimistic)', () => {
+  it('writes the new value BEFORE the await and reconciles on success', async () => {
+    const { mock, services } = makeServices();
+    let resolveFollow: (value: FollowMutationResult) => void = () => {};
+    mock.followUser.mockReturnValueOnce(
+      new Promise<FollowMutationResult>((resolve) => { resolveFollow = resolve; }),
+    );
+
+    const store = useFollowStore.getState();
+    const pending = store.toggleFollowUser('u1', services, false);
+
+    // Optimistic write happened synchronously, before the network resolved.
+    expect(useFollowStore.getState().followingUsers.u1).toBe(true);
+    expect(useFollowStore.getState().loadingUsers.u1).toBe(true);
+
+    resolveFollow({ message: 'ok', counts: { followers: 10, following: 3 } });
+    const accepted = await pending;
+
+    expect(accepted).toBe(true);
+
+    expect(useFollowStore.getState().followingUsers.u1).toBe(true);
+    expect(useFollowStore.getState().loadingUsers.u1).toBe(false);
+    // Counts from the response were applied.
+    expect(useFollowStore.getState().followerCounts.u1).toBe(10);
+    expect(useFollowStore.getState().followingCounts['viewer-1']).toBe(3);
+  });
+
+  it('rolls back to the prior definite value on error', async () => {
+    const { mock, services } = makeServices();
+    mock.followUser.mockRejectedValueOnce(new Error('boom'));
+
+    const store = useFollowStore.getState();
+    store.setFollowStatuses({ u1: false });
+
+    const accepted = await store.toggleFollowUser('u1', services, false);
+
+    expect(accepted).toBe(false);
+    expect(useFollowStore.getState().followingUsers.u1).toBe(false);
+    expect(useFollowStore.getState().loadingUsers.u1).toBe(false);
+    expect(useFollowStore.getState().errors.u1).toBe('boom');
+  });
+
+  it('rolls back to UNKNOWN when there was no prior value', async () => {
+    const { mock, services } = makeServices();
+    mock.followUser.mockRejectedValueOnce(new Error('nope'));
+
+    const store = useFollowStore.getState();
+    const accepted = await store.toggleFollowUser('u1', services, false);
+
+    expect(accepted).toBe(false);
+    // The key is removed → back to UNKNOWN (tri-state), not a definite false.
+    expect(Object.prototype.hasOwnProperty.call(useFollowStore.getState().followingUsers, 'u1')).toBe(false);
+  });
+});
+
+describe('resetFollowState', () => {
+  it('clears store data and in-flight micro-batch coordination', async () => {
+    const { mock, services } = makeServices();
+    let resolveBatch: ((value: Record<string, boolean>) => void) | undefined;
+    mock.getFollowStatuses.mockImplementation(
+      () => new Promise<Record<string, boolean>>((resolve) => { resolveBatch = resolve; }),
+    );
+
+    const store = useFollowStore.getState();
+    store.resolveFollowStatuses(['u1'], services);
+    store.setFollowingStatus('u2', true);
+
+    store.resetFollowState();
+
+    expect(useFollowStore.getState().followingUsers).toEqual({});
+    expect(useFollowStore.getState().fetchingUsers).toEqual({});
+
+    resolveBatch?.({ u1: true });
+    await flush();
+
+    // A late batch must not repopulate a store that was reset.
+    expect(useFollowStore.getState().followingUsers).toEqual({});
+  });
+});

package/src/ui/stores/__tests__/resetSessionScopedStores.test.ts

@@ -0,0 +1,23 @@
+import { useFollowStore } from '../followStore';
+import { UNKNOWN_FOLLOW_STATUS, useFollowTargetStore } from '../followTargetStore';
+import { resetSessionScopedStores } from '../resetSessionScopedStores';
+
+describe('resetSessionScopedStores', () => {
+  beforeEach(() => {
+    useFollowStore.getState().resetFollowState();
+    useFollowTargetStore.getState().reset();
+  });
+
+  it('clears legacy follow state and the v2 follow-target cache', () => {
+    useFollowStore.getState().setFollowingStatus('user-1', true);
+    useFollowTargetStore.getState().setStatus('target-1', {
+      ...UNKNOWN_FOLLOW_STATUS,
+      effectiveState: 'following',
+    });
+
+    resetSessionScopedStores();
+
+    expect(useFollowStore.getState().followingUsers['user-1']).toBeUndefined();
+    expect(useFollowTargetStore.getState().statuses['target-1']).toBeUndefined();
+  });
+});