@oxyhq/services 28.0.0 → 29.0.0

package/src/ui/runtime/runtimeContext.tsx

@@ -0,0 +1,111 @@
+import { createContext, useContext } from 'react';
+import type { DeviceDirectory } from '@oxyhq/contracts';
+import type { DeviceContext, User } from '@oxyhq/core';
+import type { OxyRuntime } from './createOxyRuntime';
+import type { OxyRuntimeStatus } from './types';
+import { useRuntimeSelector, useRuntimeSnapshot } from './useRuntimeSnapshot';
+
+/**
+ * The runtime reference itself, as a context value that NEVER changes identity
+ * (ADR 0004).
+ *
+ * It is deliberately a second context beside the big `OxyContextState` one.
+ * That value is rebuilt whenever any of its fifty-odd members moves — a locale,
+ * a dialog opening — and every hook reading it re-renders with it. Hooks
+ * hanging off this one subscribe to the runtime with a selector instead, so
+ * only a change to what they actually selected wakes them. Retiring the wide
+ * context is Phase 8; this is what its replacements are built on.
+ */
+const OxyRuntimeHandleContext = createContext<OxyRuntime | null>(null);
+
+export const OxyRuntimeHandleProvider = OxyRuntimeHandleContext.Provider;
+
+const RUNTIME_MISSING_MESSAGE =
+  'useOxyRuntime() was called outside <OxyProvider>. Mount <OxyProvider clientId="…"> above this component.';
+
+export class OxyRuntimeMissingError extends Error {
+  readonly code = 'oxy_runtime_missing';
+
+  constructor() {
+    super(RUNTIME_MISSING_MESSAGE);
+    this.name = 'OxyRuntimeMissingError';
+  }
+}
+
+/** The runtime this provider owns. THROWS when no `<OxyProvider>` is mounted. */
+export function useOxyRuntime(): OxyRuntime {
+  const runtime = useContext(OxyRuntimeHandleContext);
+  if (runtime === null) {
+    throw new OxyRuntimeMissingError();
+  }
+  return runtime;
+}
+
+export interface ActiveAccount {
+  /**
+   * The human whose authentication backs the session — the audit actor. Equal
+   * to {@link ActiveAccount.account} unless a delegated context is active.
+   */
+  principal: User | null;
+  /** The account the session acts AS — what a profile header renders. */
+  account: User | null;
+  /** The resolved `principal acting as account` pair, when a directory is held. */
+  context: DeviceContext | null;
+  /** Whether the actor and the subject are different accounts. */
+  isDelegated: boolean;
+  status: OxyRuntimeStatus;
+}
+
+function selectActiveAccount(snapshot: {
+  principal: User | null;
+  account: User | null;
+  activeContext: DeviceContext | null;
+  status: OxyRuntimeStatus;
+}): ActiveAccount {
+  return {
+    principal: snapshot.principal,
+    account: snapshot.account,
+    context: snapshot.activeContext,
+    isDelegated: snapshot.activeContext?.isDelegated ?? false,
+    status: snapshot.status,
+  };
+}
+
+function activeAccountsEqual(a: ActiveAccount, b: ActiveAccount): boolean {
+  return (
+    a.principal === b.principal &&
+    a.account === b.account &&
+    a.context === b.context &&
+    a.isDelegated === b.isDelegated &&
+    a.status === b.status
+  );
+}
+
+/**
+ * Who this app is running as, with the actor and the subject kept apart.
+ *
+ * Unlike `useOxy()`, this re-renders only when one of those five facts moves —
+ * a locale change, a dialog opening or a session-list refresh does not reach it.
+ */
+export function useActiveAccount(): ActiveAccount {
+  return useRuntimeSelector(useOxyRuntime(), selectActiveAccount, activeAccountsEqual);
+}
+
+const selectDirectory = (snapshot: { device: DeviceDirectory | null }): DeviceDirectory | null =>
+  snapshot.device;
+
+/**
+ * The device directory — every principal on this device and the contexts each
+ * may act as (ADR 0002).
+ *
+ * `null` until something calls `runtime.refreshDirectory()`. A client that
+ * never asks for one never pays for the round trip.
+ */
+export function useDeviceDirectory(): DeviceDirectory | null {
+  return useRuntimeSelector(useOxyRuntime(), selectDirectory);
+}
+
+/** The whole runtime snapshot. Prefer a narrower hook where one exists. */
+export function useOxySnapshot(): ReturnType<OxyRuntime['getSnapshot']> {
+  return useRuntimeSnapshot(useOxyRuntime());
+}

package/src/ui/runtime/types.ts

@@ -0,0 +1,110 @@
+import type { DeviceDirectory, DeviceSessionState } from '@oxyhq/contracts';
+import type { ClientSession, DeviceContext, User } from '@oxyhq/core';
+
+/**
+ * The runtime's coarse verdict about this device's session.
+ *
+ * `'booting'` is NOT "signed out but we are still looking": it is the honest
+ * "undetermined" that every readiness gate in the SDK exists to express, and it
+ * ends exactly once at the first cold-boot resolution. `'error'` is reserved for
+ * a resolved boot that produced no account AND recorded a failure — a failed
+ * sign-in against a signed-out device is `'signed_out'` with an `error`, because
+ * the device really is signed out.
+ */
+export type OxyRuntimeStatus = 'booting' | 'authenticated' | 'signed_out' | 'error';
+
+/**
+ * Whether a bearer usable for private calls is planted right now.
+ *
+ * `'refreshing'` covers both halves of the gap the SDK already tracked with two
+ * separate booleans: a bearer that is present but whose readiness gate is shut
+ * (a commit in flight), and an authenticated account whose bearer has been
+ * invalidated and is being re-minted. Both mean the same thing to a caller —
+ * wait, do not treat this as signed out.
+ */
+export type OxyTokenStatus = 'missing' | 'refreshing' | 'ready' | 'error';
+
+export interface OxyRuntimeError {
+  message: string;
+  code: string;
+}
+
+/**
+ * The ONE observable state of an `OxyRuntime` (ADR 0004).
+ *
+ * Frozen and referentially stable: a new object is published only when
+ * something actually changed, so `useSyncExternalStore` can compare by identity
+ * and a selector over an unchanged field never re-renders.
+ *
+ * Every field is either a fact the runtime owns or a pure derivation of one.
+ * There is no second writable store: `sessions`, `activeSessionId`, `status`
+ * and `tokenStatus` are computed by the one snapshot builder, so two of them can
+ * never disagree about the same device.
+ */
+export interface OxyRuntimeSnapshot {
+  status: OxyRuntimeStatus;
+
+  /**
+   * The device DIRECTORY (ADR 0002) — principals and the contexts each may act
+   * as. `null` until something asks for one; the flat lane never pays for it.
+   */
+  device: DeviceDirectory | null;
+
+  /**
+   * The flat, server-authoritative device state. Kept beside {@link device}
+   * because it is what the compatibility projections below are derived from,
+   * and because the two describe the same device at the same `revision`.
+   */
+  deviceState: DeviceSessionState | null;
+
+  /** The active `principal acting as account` pair, when a directory is held. */
+  activeContext: DeviceContext | null;
+
+  /**
+   * The human whose authentication backs the session — the audit actor.
+   *
+   * Equal to {@link account} on a device with no directory and on any
+   * non-delegated context: the flat lane cannot tell the two apart, and saying
+   * so by making them the same object is more honest than leaving this `null`.
+   */
+  principal: User | null;
+
+  /** The account the session acts AS — what a profile header renders. */
+  account: User | null;
+
+  tokenStatus: OxyTokenStatus;
+
+  /**
+   * Whether the first cold boot has concluded. Monotonic: once `true` it never
+   * reverts, so a later transient signed-out state is never mistaken for
+   * "still booting".
+   */
+  authResolved: boolean;
+
+  /** A context activation / account switch is in flight. */
+  switching: boolean;
+
+  error: OxyRuntimeError | null;
+
+  // ── Compatibility projections ────────────────────────────────────────────
+  // Derived, never separately written. They exist because every app still
+  // renders the flat session list; Phase 7 moves them onto the directory.
+
+  sessions: ClientSession[];
+  activeSessionId: string | null;
+
+  /** A sign-in / sign-out operation is in flight. */
+  isLoading: boolean;
+
+  /** The local display/bookkeeping storage has resolved. */
+  storageReady: boolean;
+
+  /** A bearer is planted on the client instance right now. */
+  hasAccessToken: boolean;
+
+  /**
+   * The commit gate. Shut while a session commit is mid-flight so a consumer
+   * cannot fire a private call between the token landing and the projection.
+   */
+  tokenReady: boolean;
+}

package/src/ui/runtime/useRuntimeSnapshot.ts

@@ -0,0 +1,52 @@
+import { useCallback, useRef, useSyncExternalStore } from 'react';
+import type { OxyRuntime } from './createOxyRuntime';
+import type { OxyRuntimeSnapshot } from './types';
+
+/**
+ * Subscribe to the whole runtime snapshot.
+ *
+ * The runtime publishes a frozen object only when a fact actually changed, so
+ * identity comparison is exact: a locale change, a dialog opening or an
+ * unrelated query settling does not wake anything subscribed here.
+ */
+export function useRuntimeSnapshot(runtime: OxyRuntime): OxyRuntimeSnapshot {
+  return useSyncExternalStore(runtime.subscribe, runtime.getSnapshot, runtime.getSnapshot);
+}
+
+/**
+ * Subscribe to one derived value of the runtime snapshot.
+ *
+ * The selection is cached against the snapshot it was computed from, which is
+ * what makes a selector returning a fresh object (`{user, isAuthenticated}`)
+ * safe here: `useSyncExternalStore` calls `getSnapshot` several times per
+ * commit and would otherwise see a new object every call and loop.
+ *
+ * `selector` must be stable — hoist it to module scope or wrap it in
+ * `useCallback`. An inline arrow re-subscribes on every render.
+ */
+export function useRuntimeSelector<T>(
+  runtime: OxyRuntime,
+  selector: (snapshot: OxyRuntimeSnapshot) => T,
+  isEqual?: (a: T, b: T) => boolean,
+): T {
+  const cache = useRef<{ snapshot: OxyRuntimeSnapshot; value: T } | null>(null);
+
+  const getSelection = useCallback((): T => {
+    const snapshot = runtime.getSnapshot();
+    const cached = cache.current;
+    if (cached !== null && cached.snapshot === snapshot) {
+      return cached.value;
+    }
+    const value = selector(snapshot);
+    if (cached !== null && isEqual?.(cached.value, value) === true) {
+      // Same value under the caller's equality: keep the PREVIOUS reference so a
+      // structurally-equal recomputation does not read as a change.
+      cache.current = { snapshot, value: cached.value };
+      return cached.value;
+    }
+    cache.current = { snapshot, value };
+    return value;
+  }, [runtime, selector, isEqual]);
+
+  return useSyncExternalStore(runtime.subscribe, getSelection, getSelection);
+}

package/src/ui/server.ts

@@ -34,7 +34,6 @@ export const ProfileScreen = noopComponent;
 
 // Stores (return empty objects)
 export const useAuthStore = noopHook;
-export const useAccountStore = noopHook;
 
 // Toast (noop)
 export const toast = Object.assign(

package/src/ui/session/__tests__/authStore.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Which apps mirror their device credential into the device-wide shared slot.
+ *
+ * The mirror is what makes a later-installed official app able to JOIN this
+ * device's session instead of asking for the Commons identity key. It runs on
+ * native, in `'account'` mode only — the identity vault is excluded so that a
+ * background persist inside the vault can never change which session five other
+ * apps boot into.
+ */
+import type { AuthStateStore } from '@oxyhq/core';
+
+const CRED_STATE = { sessionId: 'sess-1', userId: 'user-1', deviceId: 'dev-1', deviceSecret: 'ds-1' };
+
+/** Track every credential handed to the shared slot by the store under test. */
+function makeSharedSpy() {
+  const published: { deviceId: string; deviceSecret: string }[] = [];
+  return {
+    published,
+    store: {
+      read: async () => ({ state: 'absent' as const }),
+      publish: async (credential: { deviceId: string; deviceSecret: string }) => {
+        published.push(credential);
+        return true;
+      },
+      clear: async () => undefined,
+    },
+  };
+}
+
+/**
+ * Build the platform store with the native seams stubbed. `jest.resetModules()`
+ * + `require` rather than `jest.isolateModules` for the same reason as
+ * `sharedDeviceCredentialStore.test.ts`: a factory registered inside an isolate
+ * leaked into the next one.
+ */
+function loadAuthStore(
+  os: 'ios' | 'android' | 'web',
+  sessionMode: 'account' | 'identity',
+  shared: ReturnType<typeof makeSharedSpy>,
+): AuthStateStore {
+  jest.resetModules();
+  jest.doMock('../sharedDeviceCredentialStore', () => ({
+    createPlatformSharedDeviceCredentialStore: () => (os === 'web' ? null : shared.store),
+  }));
+  const rn = require('react-native') as { Platform: { OS: string } };
+  rn.Platform.OS = os;
+  // `authStore` selects web-vs-native with `isReactNative()`, which reads
+  // `navigator.product` — NOT `Platform.OS`. Setting only the latter leaves it on
+  // the web branch, where nothing mirrors and every case passes for the wrong
+  // reason.
+  Object.defineProperty(globalThis.navigator, 'product', {
+    value: os === 'web' ? 'Gecko' : 'ReactNative',
+    configurable: true,
+  });
+  const mod = require('../authStore') as typeof import('../authStore');
+  return mod.createPlatformAuthStateStore({ sessionMode });
+}
+
+afterEach(() => {
+  jest.dontMock('../sharedDeviceCredentialStore');
+  Object.defineProperty(globalThis.navigator, 'product', { value: 'Gecko', configurable: true });
+  jest.resetModules();
+});
+
+describe('createPlatformAuthStateStore', () => {
+  test('an ordinary native app publishes its credential to the shared slot', async () => {
+    const shared = makeSharedSpy();
+    const store = loadAuthStore('android', 'account', shared);
+    await store.save(CRED_STATE);
+    expect(shared.published).toEqual([{ deviceId: 'dev-1', deviceSecret: 'ds-1' }]);
+  });
+
+  test('the identity vault does NOT publish', async () => {
+    // The vault's credential is a perfectly valid device credential, so this is a
+    // deliberate abstention, not an impossibility: publishing it would let every
+    // ordinary app on the device join the vault's session as a side effect of the
+    // vault persisting a token.
+    const shared = makeSharedSpy();
+    const store = loadAuthStore('android', 'identity', shared);
+    await store.save(CRED_STATE);
+    expect(shared.published).toEqual([]);
+  });
+
+  test('web has no shared slot to publish into', async () => {
+    const shared = makeSharedSpy();
+    const store = loadAuthStore('web', 'account', shared);
+    await store.save(CRED_STATE);
+    expect(shared.published).toEqual([]);
+  });
+});

package/src/ui/session/__tests__/sharedDeviceCredentialStore.test.ts

@@ -0,0 +1,289 @@
+/**
+ * The platform half of the shared DeviceSession credential.
+ *
+ * `@oxyhq/core` owns and tests the RULES; what is pinned here is the mapping from
+ * each platform's failure shapes onto them — and that mapping is where the
+ * dangerous mistake lives. `expo-secure-store` returns `null` for a missing item
+ * and THROWS when the keychain refuses; the Android broker answers with an
+ * explicit status. Collapsing either failure into "absent" is what would let a
+ * locked device look like one that never had a session.
+ */
+import type { SharedDeviceCredentialStore } from '@oxyhq/core';
+
+const CRED = { deviceId: 'dev-shared', deviceSecret: 'ds-shared' };
+const STORAGE_KEY = 'oxy_shared_device_session_v1';
+
+/** A minimal in-memory `expo-secure-store` that records the options it was given. */
+function makeSecureStoreMock() {
+  const items = new Map<string, string>();
+  const calls: { key: string; options?: Record<string, unknown> }[] = [];
+  let readError: Error | null = null;
+  let writeError: Error | null = null;
+  /** When set, `setItemAsync` resolves but nothing lands — the phantom-write case. */
+  let swallowWrites = false;
+  return {
+    items,
+    calls,
+    setReadError: (error: Error | null) => {
+      readError = error;
+    },
+    setWriteError: (error: Error | null) => {
+      writeError = error;
+    },
+    setSwallowWrites: (value: boolean) => {
+      swallowWrites = value;
+    },
+    module: {
+      WHEN_UNLOCKED_THIS_DEVICE_ONLY: 3,
+      getItemAsync: async (key: string, options?: Record<string, unknown>) => {
+        calls.push({ key, options });
+        if (readError) {
+          throw readError;
+        }
+        return items.get(key) ?? null;
+      },
+      setItemAsync: async (key: string, value: string, options?: Record<string, unknown>) => {
+        calls.push({ key, options });
+        if (writeError) {
+          throw writeError;
+        }
+        if (!swallowWrites) {
+          items.set(key, value);
+        }
+      },
+      deleteItemAsync: async (key: string, options?: Record<string, unknown>) => {
+        calls.push({ key, options });
+        items.delete(key);
+      },
+    },
+  };
+}
+
+type BrokerModule = {
+  read(): Promise<unknown>;
+  write(deviceId: string, deviceSecret: string): Promise<boolean>;
+  clear(): Promise<void>;
+};
+
+/**
+ * Load the module fresh, with `Platform.OS` set and both native seams mocked.
+ *
+ * Two things here are load-bearing and were each got wrong first:
+ *
+ *  - `jest.resetModules()` + `require`, NOT `jest.isolateModules`. The module
+ *    memoises its keychain and broker handles at module scope, so it must be
+ *    re-required per case — and with `isolateModules` a mock factory registered
+ *    in one block leaked into the next block's module, so a test's own mock was
+ *    silently ignored and its assertions read the PREVIOUS test's store.
+ *  - `Platform.OS` is set on the instance in the CURRENT registry. A reset hands
+ *    out a fresh `react-native` mock whose `OS` is back to its `'web'` default,
+ *    so mutating an instance captured earlier leaves the code under test on the
+ *    web branch and every platform assertion passes vacuously.
+ */
+function loadStore(
+  os: 'ios' | 'android' | 'web',
+  seams: { secureStore?: ReturnType<typeof makeSecureStoreMock>; broker?: BrokerModule | null } = {},
+): SharedDeviceCredentialStore | null {
+  jest.resetModules();
+  jest.doMock('expo-modules-core', () => ({
+    requireOptionalNativeModule: () => seams.broker ?? null,
+    requireNativeModule: () => {
+      throw new Error('not available');
+    },
+  }));
+  // NOT `{ virtual: true }`: a virtual mock is keyed to the directory of the
+  // file that declared it, so one declared here would be invisible to the module
+  // under test two directories up — it would silently keep resolving
+  // `unsupported`. `expo-secure-store` is installed in the workspace, so the
+  // ordinary mock registers against its real resolved path. With no mock given,
+  // model the module being ABSENT.
+  const secureStoreModule = seams.secureStore?.module;
+  jest.doMock('expo-secure-store', () => {
+    if (!secureStoreModule) {
+      throw new Error("Cannot find module 'expo-secure-store'");
+    }
+    return secureStoreModule;
+  });
+  const rn = require('react-native') as { Platform: { OS: string } };
+  rn.Platform.OS = os;
+  const mod = require('../sharedDeviceCredentialStore') as typeof import('../sharedDeviceCredentialStore');
+  return mod.createPlatformSharedDeviceCredentialStore();
+}
+
+afterEach(() => {
+  jest.dontMock('expo-modules-core');
+  jest.dontMock('expo-secure-store');
+  jest.resetModules();
+});
+
+describe('createPlatformSharedDeviceCredentialStore', () => {
+  test('web has no shared slot at all', () => {
+    // Each web origin is its own device by design; there is nothing to join.
+    expect(loadStore('web')).toBeNull();
+    // Positive control: `null` must mean "web", not "the harness never reached
+    // the platform branch" — the failure mode this whole harness had once.
+    expect(loadStore('android', { broker: null })).not.toBeNull();
+    expect(loadStore('ios')).not.toBeNull();
+  });
+
+  test('iOS uses the keychain, not the Android broker', async () => {
+    // The branch is on the platform because `expo-secure-store` LOADS on Android
+    // too — it would just ignore the access group and read a package-private
+    // item, which is indistinguishable from an empty shared slot.
+    const secureStore = makeSecureStoreMock();
+    const broker: BrokerModule = {
+      read: jest.fn(async () => ({ status: 'present', ...CRED })),
+      write: jest.fn(async () => true),
+      clear: jest.fn(async () => undefined),
+    };
+    const store = loadStore('ios', { secureStore, broker });
+    await store?.read();
+    expect(broker.read).not.toHaveBeenCalled();
+    expect(secureStore.calls.length).toBeGreaterThan(0);
+  });
+
+  test('Android uses the broker, not the keychain', async () => {
+    const secureStore = makeSecureStoreMock();
+    const broker: BrokerModule = {
+      read: jest.fn(async () => ({ status: 'absent' })),
+      write: jest.fn(async () => true),
+      clear: jest.fn(async () => undefined),
+    };
+    const store = loadStore('android', { secureStore, broker });
+    await expect(store?.read()).resolves.toEqual({ state: 'absent' });
+    expect(broker.read).toHaveBeenCalled();
+    expect(secureStore.calls).toHaveLength(0);
+  });
+});
+
+describe('iOS keychain-group slot', () => {
+  test('a missing item is absent; a THROWN read is unavailable', async () => {
+    const secureStore = makeSecureStoreMock();
+    const store = loadStore('ios', { secureStore });
+
+    await expect(store?.read()).resolves.toEqual({ state: 'absent' });
+
+    secureStore.setReadError(new Error('User interaction is not allowed'));
+    const locked = await store?.read();
+    // The pair that must never be confused. `absent` authorises seeding the slot.
+    expect(locked?.state).toBe('unavailable');
+  });
+
+  test('an unparseable item is unavailable, never absent', async () => {
+    const secureStore = makeSecureStoreMock();
+    secureStore.items.set(STORAGE_KEY, 'not-json-at-all');
+    const store = loadStore('ios', { secureStore });
+    // Something IS stored. Reporting absent would authorise overwriting whatever
+    // a newer build put there.
+    expect((await store?.read())?.state).toBe('unavailable');
+  });
+
+  test('reads and writes carry the dedicated service AND the access group', async () => {
+    const secureStore = makeSecureStoreMock();
+    const store = loadStore('ios', { secureStore });
+    await store?.publish(CRED);
+
+    // Without `keychainAccessGroup` the item is package-private and no sibling
+    // app can ever join. Without the dedicated `keychainService` it shares the
+    // legacy shared-IDENTITY namespace inside the group — the exact conflation
+    // this phase exists to end.
+    for (const call of secureStore.calls) {
+      expect(call.options).toMatchObject({
+        keychainService: 'oxy_device_session',
+        keychainAccessGroup: 'group.so.oxy.shared',
+      });
+    }
+    expect(secureStore.calls.length).toBeGreaterThan(0);
+  });
+
+  test('the item is written device-only so it never rides an OS backup to a new handset', async () => {
+    const secureStore = makeSecureStoreMock();
+    const store = loadStore('ios', { secureStore });
+    await store?.publish(CRED);
+    const write = secureStore.calls.find((c) => c.options?.keychainAccessible !== undefined);
+    expect(write?.options?.keychainAccessible).toBe(secureStore.module.WHEN_UNLOCKED_THIS_DEVICE_ONLY);
+  });
+
+  test('a publish round-trips and reads back as present', async () => {
+    const secureStore = makeSecureStoreMock();
+    const store = loadStore('ios', { secureStore });
+    await expect(store?.publish(CRED)).resolves.toBe(true);
+    await expect(store?.read()).resolves.toEqual({ state: 'present', credential: CRED });
+  });
+
+  test('a write that silently does not land reports false', async () => {
+    // A keychain write can resolve without the item landing under the access
+    // group (a missing entitlement is the usual cause). A phantom credential
+    // would send a fresh install into a mint that can never succeed.
+    const secureStore = makeSecureStoreMock();
+    secureStore.setSwallowWrites(true);
+    const store = loadStore('ios', { secureStore });
+    await expect(store?.publish(CRED)).resolves.toBe(false);
+  });
+
+  test('a throwing write reports false rather than propagating', async () => {
+    const secureStore = makeSecureStoreMock();
+    secureStore.setWriteError(new Error('keychain error -34018'));
+    const store = loadStore('ios', { secureStore });
+    await expect(store?.publish(CRED)).resolves.toBe(false);
+  });
+
+  test('the slot is unsupported when expo-secure-store is not installed', async () => {
+    const store = loadStore('ios');
+    // No `expo-secure-store` mock registered → the dynamic import rejects.
+    expect((await store?.read())?.state).toBe('unsupported');
+  });
+});
+
+describe('Android broker slot', () => {
+  test('narrows a present payload', async () => {
+    const store = loadStore('android', {
+      broker: { read: async () => ({ status: 'present', ...CRED }), write: async () => true, clear: async () => undefined },
+    });
+    await expect(store?.read()).resolves.toEqual({ state: 'present', credential: CRED });
+  });
+
+  test('an explicit unavailable status stays unavailable', async () => {
+    const store = loadStore('android', {
+      broker: {
+        read: async () => ({ status: 'unavailable', reason: 'GeneralSecurityException' }),
+        write: async () => true,
+        clear: async () => undefined,
+      },
+    });
+    expect((await store?.read())?.state).toBe('unavailable');
+  });
+
+  test('a THROWN broker call is unavailable, never absent', async () => {
+    const store = loadStore('android', {
+      broker: {
+        read: async () => {
+          throw new Error('binder transaction failed');
+        },
+        write: async () => true,
+        clear: async () => undefined,
+      },
+    });
+    expect((await store?.read())?.state).toBe('unavailable');
+  });
+
+  test('an unrecognised payload from an older sibling is unavailable, never absent', async () => {
+    const store = loadStore('android', {
+      broker: { read: async () => ({ ok: true }), write: async () => true, clear: async () => undefined },
+    });
+    expect((await store?.read())?.state).toBe('unavailable');
+  });
+
+  test('the slot is unsupported when the native module is not linked', async () => {
+    const store = loadStore('android', { broker: null });
+    expect((await store?.read())?.state).toBe('unsupported');
+    await expect(store?.publish(CRED)).resolves.toBe(false);
+  });
+
+  test('publish forwards the broker’s own read-back verdict', async () => {
+    const unverified = loadStore('android', {
+      broker: { read: async () => ({ status: 'absent' }), write: async () => false, clear: async () => undefined },
+    });
+    await expect(unverified?.publish(CRED)).resolves.toBe(false);
+  });
+});