@fias/arche-sdk 2.28.0 → 2.30.0

package/dist/hooks.test.js

@@ -68,8 +68,16 @@ function createMockBridge() {
         getCurrentPath: jest.fn().mockReturnValue('/'),
         getTextModels: jest.fn().mockReturnValue(null),
         onTextModelsUpdate: jest.fn().mockReturnValue(() => { }),
+        getHolder: jest.fn().mockReturnValue(null),
+        onHolderReady: jest.fn().mockReturnValue(() => { }),
         onThemeUpdate: jest.fn().mockReturnValue(() => { }),
+        onAccessUpdate: jest.fn().mockReturnValue(() => { }),
         onNavigationUpdate: jest.fn().mockReturnValue(() => { }),
+        getChrome: jest.fn().mockReturnValue(null),
+        hasChromeSupport: jest.fn().mockReturnValue(false),
+        onChromeUpdate: jest.fn().mockReturnValue(() => { }),
+        setChrome: jest.fn(),
+        navigateHost: jest.fn(),
         onStepNavigationUpdate: jest.fn().mockReturnValue(() => { }),
         registerPreviewState: jest.fn().mockReturnValue(() => { }),
         onSubscriptionEvent: jest.fn().mockReturnValue(() => { }),
@@ -242,6 +250,66 @@ describe('SDK hooks', () => {
             });
         });
     });
+    describe('useFiasChrome', () => {
+        const HOST_STATE = {
+            focusMode: true,
+            focusModeAvailable: true,
+            sidebarAvailable: true,
+            sidebarCollapsed: false,
+            hostExpandedBar: true,
+            hostExpandButton: false,
+        };
+        it('is inert and unsupported before init / on an older host, and still renders', () => {
+            const { useFiasChrome } = require('./hooks');
+            const chrome = useFiasChrome();
+            expect(chrome.supported).toBe(false);
+            expect(chrome.focusMode).toBe(false);
+            expect(chrome.focusModeAvailable).toBe(false);
+            expect(chrome.sidebarAvailable).toBe(false);
+            expect(chrome.hostExpandedBar).toBe(true);
+            expect(mockBridge.onChromeUpdate).toHaveBeenCalled();
+        });
+        it('spreads the host state and reports supported once delivered', () => {
+            mockBridge.getChrome.mockReturnValue(HOST_STATE);
+            mockBridge.hasChromeSupport.mockReturnValue(true);
+            const { useFiasChrome } = require('./hooks');
+            const chrome = useFiasChrome();
+            expect(chrome.supported).toBe(true);
+            expect(chrome.focusMode).toBe(true);
+            expect(chrome.hostExpandButton).toBe(false);
+        });
+        it('TAKES THE CHROME OVER on mount — the host drops its default expand button', () => {
+            const { useFiasChrome } = require('./hooks');
+            useFiasChrome();
+            expect(mockBridge.setChrome).toHaveBeenCalledWith({ hostExpandButton: false });
+        });
+        it('setters send one-field chrome_set patches; navigation uses the closed enum', () => {
+            const { useFiasChrome } = require('./hooks');
+            const chrome = useFiasChrome();
+            chrome.setFocusMode(true);
+            expect(mockBridge.setChrome).toHaveBeenCalledWith({ focusMode: true });
+            chrome.setSidebarCollapsed(true);
+            expect(mockBridge.setChrome).toHaveBeenCalledWith({ sidebarCollapsed: true });
+            chrome.setHostExpandedBar(false);
+            expect(mockBridge.setChrome).toHaveBeenCalledWith({ hostExpandedBar: false });
+            chrome.goToFiasHome();
+            expect(mockBridge.navigateHost).toHaveBeenCalledWith('home');
+            chrome.goToWorktop();
+            expect(mockBridge.navigateHost).toHaveBeenCalledWith('worktop');
+            chrome.openAssistant();
+            expect(mockBridge.openAssistant).toHaveBeenCalled();
+        });
+        it('cleanup unsubscribes from chrome updates', () => {
+            const unsubscribe = jest.fn();
+            mockBridge.onChromeUpdate.mockReturnValue(unsubscribe);
+            const { useFiasChrome } = require('./hooks');
+            useFiasChrome();
+            // The LAST captured cleanup is the takeover effect's (none) or the
+            // subscription's — walk the captured one if present.
+            capturedEffectCleanup?.();
+            expect(unsubscribe).toHaveBeenCalled();
+        });
+    });
     describe('hook return identity', () => {
         // These two returns MUST be memoized. The natural way to consume them is
         // `useEffect(() => { void storage.readFile(...) }, [storage])`, and a
@@ -763,6 +831,366 @@ describe('SDK hooks', () => {
             expect(useTextModels()).toEqual([]);
         });
     });
+    describe('useFiasHolder', () => {
+        it('returns the init-payload workspace and subscribes for its arrival', () => {
+            const { useFiasHolder } = require('./hooks');
+            const holder = { type: 'org', role: 'member' };
+            mockBridge.getHolder.mockReturnValue(holder);
+            expect(useFiasHolder()).toEqual(holder);
+            expect(mockBridge.onHolderReady).toHaveBeenCalled();
+        });
+        it('returns null before init', () => {
+            const { useFiasHolder } = require('./hooks');
+            mockBridge.getHolder.mockReturnValue(null);
+            expect(useFiasHolder()).toBeNull();
+        });
+    });
+    describe('useFiasWorkspaces().openForWorkspace', () => {
+        it('asks for the acting workspace by flag, never by id', async () => {
+            const { useFiasWorkspaces } = require('./hooks');
+            const ws = { workspaceId: 'ws_1', displayName: 'Acme', role: 'member', holderBacked: true };
+            mockBridge.request.mockResolvedValue(output({ workspace: ws }));
+            await expect(useFiasWorkspaces().openForWorkspace()).resolves.toEqual(ws);
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'create', { forActingHolder: true }));
+        });
+    });
+    // ADR-034 phase 0b. The real-render cases (stale answers across workspace
+    // switches, the render before effects run, refetch) live in
+    // use-fias-access.render.test.tsx, which CI runs through the package's
+    // `test:render` script; these mock React and run under the root config.
+    describe('useFiasAccess', () => {
+        const settle = () => new Promise((r) => setTimeout(r, 0));
+        const setCalls = () => mockSetState.mock.calls.map((c) => c[0]);
+        it('asks the workspaces entity for my_access with the workspace id', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const access = { mode: 'tier', workspaceId: 'ws_1', tier: 'member', expiresAt: null };
+            mockBridge.request.mockResolvedValue(output({ access }));
+            useFiasAccess('ws_1');
+            await settle();
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'my_access', { workspaceId: 'ws_1' }));
+            expect(setCalls()).toContainEqual({ workspaceId: 'ws_1', access, error: null });
+        });
+        it.each(['NOT_A_MEMBER', 'WORKSPACE_NOT_FOUND'])('%s becomes tier: null', async (code) => {
+            const { useFiasAccess } = require('./hooks');
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            mockBridge.request.mockRejectedValue(new FiasBridgeError('refused', code));
+            useFiasAccess('ws_1');
+            await settle();
+            expect(setCalls()).toContainEqual({
+                workspaceId: 'ws_1',
+                access: { mode: 'tier', workspaceId: 'ws_1', tier: null, expiresAt: null },
+                error: null,
+            });
+        });
+        it('surfaces any other failure as an error', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            mockBridge.request.mockRejectedValue(new FiasBridgeError('slow down', 'RATE_LIMIT'));
+            useFiasAccess('ws_1');
+            await settle();
+            expect(setCalls()).toContainEqual({
+                workspaceId: 'ws_1',
+                access: null,
+                error: expect.objectContaining({ code: 'RATE_LIMIT' }),
+            });
+        });
+        it('asks nothing without a workspace', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const state = useFiasAccess(null);
+            await settle();
+            expect(mockBridge.request).not.toHaveBeenCalled();
+            expect(state).toMatchObject({ access: null, isLoading: false, error: null });
+        });
+        it('asks again when the host says the person’s access changed (ADR-034)', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const access = { mode: 'tier', workspaceId: 'ws_1', tier: 'member', expiresAt: null };
+            mockBridge.request.mockResolvedValue(output({ access }));
+            useFiasAccess('ws_1');
+            await settle();
+            expect(mockBridge.request).toHaveBeenCalledTimes(1);
+            const listener = mockBridge.onAccessUpdate.mock.calls[0][0];
+            listener();
+            await settle();
+            expect(mockBridge.request).toHaveBeenCalledTimes(2);
+        });
+        it('a failed background refetch keeps the answer it had', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            const access = { mode: 'tier', workspaceId: 'ws_1', tier: 'member', expiresAt: null };
+            mockBridge.request.mockResolvedValueOnce(output({ access }));
+            useFiasAccess('ws_1');
+            await settle();
+            mockSetState.mockClear();
+            mockBridge.request.mockRejectedValueOnce(new FiasBridgeError('slow down', 'RATE_LIMIT'));
+            const subscriptions = mockBridge.onAccessUpdate.mock.calls;
+            subscriptions[subscriptions.length - 1][0]();
+            await settle();
+            // No blanking answer was written, and nothing flipped to loading.
+            expect(setCalls()).not.toContainEqual(expect.objectContaining({ access: null }));
+            expect(setCalls()).not.toContain(true);
+        });
+        it('window focus asks again at most once per 30 s', async () => {
+            const listeners = {};
+            const win = {
+                addEventListener: jest.fn((type, fn) => (listeners[type] = fn)),
+                removeEventListener: jest.fn(),
+            };
+            globalThis.window = win;
+            try {
+                const { useFiasAccess } = require('./hooks');
+                const access = { mode: 'tier', workspaceId: 'ws_1', tier: 'member', expiresAt: null };
+                mockBridge.request.mockResolvedValue(output({ access }));
+                useFiasAccess('ws_1');
+                await settle();
+                expect(mockBridge.request).toHaveBeenCalledTimes(1);
+                listeners.focus();
+                await settle();
+                expect(mockBridge.request).toHaveBeenCalledTimes(1);
+                const now = Date.now();
+                jest.spyOn(Date, 'now').mockReturnValue(now + 31000);
+                listeners.focus();
+                await settle();
+                expect(mockBridge.request).toHaveBeenCalledTimes(2);
+            }
+            finally {
+                delete globalThis.window;
+                jest.restoreAllMocks();
+            }
+        });
+        it('opens the host’s access sheet with no input, and asks again only if it changed', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const access = { mode: 'tier', workspaceId: 'ws_1', tier: 'member', expiresAt: null };
+            mockBridge.request.mockResolvedValue(output({ access }));
+            const state = useFiasAccess('ws_1');
+            await settle();
+            mockBridge.request.mockClear();
+            mockBridge.request.mockResolvedValueOnce({ changed: false });
+            await expect(state.openAccessDialog()).resolves.toEqual({ changed: false });
+            expect(mockBridge.request).toHaveBeenCalledWith('client_entity_invoke', { entityId: 'ent_intg_app_access_dialog_00000', input: {} }, expect.any(Number));
+            expect(mockBridge.request).toHaveBeenCalledTimes(1);
+            mockBridge.request.mockResolvedValueOnce({ changed: true });
+            mockBridge.request.mockResolvedValue(output({ access }));
+            await expect(state.openAccessDialog()).resolves.toEqual({ changed: true });
+            await settle();
+            expect(mockBridge.request).toHaveBeenCalledTimes(3);
+        });
+        it('a host without the sheet (an older Fias) is ACCESS_UNAVAILABLE, not a bare bridge error', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            mockBridge.request.mockResolvedValue(output({ access: null }));
+            const state = useFiasAccess('ws_1');
+            await settle();
+            mockBridge.request.mockRejectedValueOnce(new FiasBridgeError('no client-side executor registered', 'BRIDGE_ERROR'));
+            await expect(state.openAccessDialog()).rejects.toMatchObject({ code: 'ACCESS_UNAVAILABLE' });
+        });
+        it('an older dev harness without the sheet is ACCESS_UNAVAILABLE too', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            mockBridge.request.mockResolvedValue(output({ access: null }));
+            const state = useFiasAccess('ws_1');
+            await settle();
+            mockBridge.request.mockRejectedValueOnce(new FiasBridgeError('client_entity_invoke: no client-side executor for ent_intg_app_access_dialog_00000 in the dev harness', 'BRIDGE_ERROR'));
+            await expect(state.openAccessDialog()).rejects.toMatchObject({ code: 'ACCESS_UNAVAILABLE' });
+        });
+        it('any other bridge error (e.g. a missing permission) passes through unchanged', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            mockBridge.request.mockResolvedValue(output({ access: null }));
+            const state = useFiasAccess('ws_1');
+            await settle();
+            mockBridge.request.mockRejectedValueOnce(new FiasBridgeError('Permission denied: data:workspace not granted', 'BRIDGE_ERROR'));
+            await expect(state.openAccessDialog()).rejects.toMatchObject({
+                code: 'BRIDGE_ERROR',
+                message: 'Permission denied: data:workspace not granted',
+            });
+        });
+        it('the sheet’s refusal is a typed error', async () => {
+            const { useFiasAccess } = require('./hooks');
+            mockBridge.request.mockResolvedValue(output({ access: null }));
+            const state = useFiasAccess('ws_1');
+            await settle();
+            mockBridge.request.mockResolvedValueOnce({
+                error: { code: 'NOT_IN_WORKSPACE', message: 'Personal' },
+            });
+            await expect(state.openAccessDialog()).rejects.toMatchObject({ code: 'NOT_IN_WORKSPACE' });
+        });
+    });
+    describe('useCreativeLibrary().pick (ADR-035 D8)', () => {
+        const PICKED = {
+            item: { itemId: 'vci_' + 'a'.repeat(32), kind: 'style', name: 'Ink', version: 2 },
+        };
+        it('asks the host’s picker for a kind, waiting on the person', async () => {
+            const { useCreativeLibrary } = require('./hooks');
+            mockBridge.request.mockResolvedValue(PICKED);
+            await expect(useCreativeLibrary().pick({ kind: 'style' })).resolves.toEqual(PICKED);
+            const [op, payload, timeout] = mockBridge.request.mock.calls[0];
+            expect(op).toBe('client_entity_invoke');
+            expect(payload).toEqual({ entityId: entity_ops_1.CREATIVE_PICKER_ENTITY_ID, input: { kind: 'style' } });
+            expect(timeout).toBeGreaterThanOrEqual(5 * 60 * 1000);
+        });
+        it('sends nothing when no kind is asked, and passes a closed sheet through', async () => {
+            const { useCreativeLibrary } = require('./hooks');
+            mockBridge.request.mockResolvedValue({ canceled: true });
+            await expect(useCreativeLibrary().pick()).resolves.toEqual({ canceled: true });
+            expect(mockBridge.request.mock.calls[0][1]).toEqual({
+                entityId: entity_ops_1.CREATIVE_PICKER_ENTITY_ID,
+                input: {},
+            });
+        });
+        it('turns a refusal result into a typed error', async () => {
+            const { useCreativeLibrary } = require('./hooks');
+            mockBridge.request.mockResolvedValue({
+                error: { code: 'SHEET_BUSY', message: 'Another request is waiting' },
+            });
+            await expect(useCreativeLibrary().pick()).rejects.toMatchObject({ code: 'SHEET_BUSY' });
+        });
+        it('a host with no picker answers PICKER_UNAVAILABLE', async () => {
+            const { useCreativeLibrary } = require('./hooks');
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            mockBridge.request.mockRejectedValue(new FiasBridgeError('no client-side executor registered for x', 'BRIDGE_ERROR'));
+            await expect(useCreativeLibrary().pick()).rejects.toMatchObject({
+                code: 'PICKER_UNAVAILABLE',
+            });
+        });
+    });
+    describe('useFiasConnections', () => {
+        it('lists through the connections entity', async () => {
+            const { useFiasConnections } = require('./hooks');
+            const accounts = [{ connectionId: 'conn_1', provider: 'x', status: 'active' }];
+            mockBridge.request.mockResolvedValue(output({ connections: accounts }));
+            await expect(useFiasConnections().list()).resolves.toEqual(accounts);
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.CONNECTIONS_ENTITY_ID, 'list'));
+        });
+        it('connects through the client-side entity, waiting on the person', async () => {
+            const { useFiasConnections } = require('./hooks');
+            mockBridge.request.mockResolvedValue({ connectionId: 'conn_1', provider: 'x' });
+            await expect(useFiasConnections().connect('x')).resolves.toEqual({
+                connectionId: 'conn_1',
+                provider: 'x',
+            });
+            const [op, payload, timeout] = mockBridge.request.mock.calls[0];
+            expect(op).toBe('client_entity_invoke');
+            expect(payload).toEqual({
+                entityId: entity_ops_1.CONNECTIONS_CONNECT_ENTITY_ID,
+                input: { provider: 'x' },
+            });
+            expect(timeout).toBeGreaterThanOrEqual(5 * 60 * 1000);
+        });
+        it('turns a refusal result into a typed error', async () => {
+            const { useFiasConnections } = require('./hooks');
+            mockBridge.request.mockResolvedValue({
+                error: { code: 'PERMISSION_DENIED', message: 'no connections:use' },
+            });
+            await expect(useFiasConnections().connect('x')).rejects.toMatchObject({
+                code: 'PERMISSION_DENIED',
+            });
+        });
+        it('releases its own access', async () => {
+            const { useFiasConnections } = require('./hooks');
+            mockBridge.request.mockResolvedValue(output({ released: true }));
+            await useFiasConnections().release('conn_1');
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.CONNECTIONS_ENTITY_ID, 'release', { connectionId: 'conn_1' }));
+        });
+    });
+    describe('the outward guard round-trip (ADR-029 §4)', () => {
+        const PACT = `pact_${'a'.repeat(32)}`;
+        const publish = { connectionId: 'conn_1', posts: [{ text: 'Hi' }] };
+        it('a confirmation answer asks the host, then re-sends the identical call naming the approval', async () => {
+            const { useFiasX } = require('./hooks');
+            mockBridge.request
+                .mockResolvedValueOnce({ output: null, confirmationRequired: { pendingActionId: PACT } })
+                .mockResolvedValueOnce({ approved: true })
+                .mockResolvedValueOnce(output({ posts: [{ postId: '1', url: 'u' }], complete: true }));
+            await expect(useFiasX().publishPost(publish)).resolves.toEqual({
+                posts: [{ postId: '1', url: 'u' }],
+                complete: true,
+            });
+            const [first, confirm, resend] = mockBridge.request.mock.calls;
+            expect(first).toEqual(entityOp(entity_ops_1.X_ENTITY_ID, 'publish_post', publish));
+            expect(confirm[0]).toBe('client_entity_invoke');
+            expect(confirm[1]).toEqual({
+                entityId: entity_ops_1.ACTION_CONFIRMATION_ENTITY_ID,
+                input: { pendingActionId: PACT },
+            });
+            expect(confirm[2]).toBeGreaterThanOrEqual(5 * 60 * 1000);
+            expect(resend[0]).toBe('entity_invoke');
+            expect(resend[1]).toEqual({
+                entityId: entity_ops_1.X_ENTITY_ID,
+                payload: { op: 'publish_post', ...publish },
+                pendingActionId: PACT,
+            });
+            // The approved call acts outside Fias and may take a while; it is not cut at the default.
+            expect(resend[2]).toBeGreaterThanOrEqual(60 * 1000);
+        });
+        it('a decline rejects with USER_DECLINED and sends nothing more', async () => {
+            const { useFiasX } = require('./hooks');
+            mockBridge.request
+                .mockResolvedValueOnce({ output: null, confirmationRequired: { pendingActionId: PACT } })
+                .mockResolvedValueOnce({ approved: false });
+            await expect(useFiasX().publishPost(publish)).rejects.toMatchObject({
+                code: 'USER_DECLINED',
+            });
+            expect(mockBridge.request).toHaveBeenCalledTimes(2);
+        });
+        it("the host's refusal is a typed error", async () => {
+            const { useFiasLinkedIn } = require('./hooks');
+            mockBridge.request
+                .mockResolvedValueOnce({ output: null, confirmationRequired: { pendingActionId: PACT } })
+                .mockResolvedValueOnce({ error: { code: 'CONFIRM_UNAVAILABLE', message: 'no host' } });
+            await expect(useFiasLinkedIn().publishPost({ connectionId: 'conn_1', text: 'Hi' })).rejects.toMatchObject({ code: 'CONFIRM_UNAVAILABLE' });
+        });
+    });
+    describe('useFiasSchedules (ADR-029 §5)', () => {
+        it('schedules one call, approved first, and lists and cancels its own', async () => {
+            const { useFiasSchedules } = require('./hooks');
+            const PACT = `pact_${'b'.repeat(32)}`;
+            const fireAt = new Date('2030-01-01T09:00:00Z');
+            const payload = { connectionId: 'conn_1', posts: [{ text: 'Later' }] };
+            mockBridge.request
+                .mockResolvedValueOnce({ output: null, confirmationRequired: { pendingActionId: PACT } })
+                .mockResolvedValueOnce({ approved: true })
+                .mockResolvedValueOnce(output({ scheduleId: 's1', fireAt: fireAt.toISOString() }));
+            await expect(useFiasSchedules().schedule({
+                entityId: entity_ops_1.X_ENTITY_ID,
+                verb: 'publish_post',
+                payload,
+                fireAt,
+            })).resolves.toEqual({ scheduleId: 's1', fireAt: fireAt.toISOString() });
+            // The Date is sent as ISO, and the re-send names the approval.
+            expect(mockBridge.request.mock.calls[0]).toEqual(entityOp(entity_ops_1.SCHEDULED_INVOCATIONS_ENTITY_ID, 'schedule', {
+                entityId: entity_ops_1.X_ENTITY_ID,
+                verb: 'publish_post',
+                payload,
+                fireAt: fireAt.toISOString(),
+            }));
+            expect(mockBridge.request.mock.calls[2][1]).toMatchObject({ pendingActionId: PACT });
+            mockBridge.request.mockResolvedValueOnce(output({ schedules: [{ scheduleId: 's1' }] }));
+            await expect(useFiasSchedules().list()).resolves.toEqual([{ scheduleId: 's1' }]);
+            expect(mockBridge.request).toHaveBeenLastCalledWith(...entityOp(entity_ops_1.SCHEDULED_INVOCATIONS_ENTITY_ID, 'list', {}));
+            mockBridge.request.mockResolvedValueOnce(output({ schedules: [] }));
+            await useFiasSchedules().list({ limit: 100, scheduleIds: ['s1'] });
+            expect(mockBridge.request).toHaveBeenLastCalledWith(...entityOp(entity_ops_1.SCHEDULED_INVOCATIONS_ENTITY_ID, 'list', { limit: 100, scheduleIds: ['s1'] }));
+            mockBridge.request.mockResolvedValueOnce(output({ cancelled: true }));
+            await useFiasSchedules().cancel('s1');
+            expect(mockBridge.request).toHaveBeenLastCalledWith(...entityOp(entity_ops_1.SCHEDULED_INVOCATIONS_ENTITY_ID, 'cancel', { scheduleId: 's1' }));
+        });
+    });
+    describe('useFiasX / useFiasLinkedIn reads', () => {
+        it('unwrap each read through its entity verb', async () => {
+            const { useFiasX, useFiasLinkedIn } = require('./hooks');
+            mockBridge.request.mockResolvedValueOnce(output({ users: [{ id: '1' }] }));
+            await expect(useFiasX().searchUsers('conn_1', 'acme')).resolves.toEqual([{ id: '1' }]);
+            expect(mockBridge.request).toHaveBeenLastCalledWith(...entityOp(entity_ops_1.X_ENTITY_ID, 'search_users', { connectionId: 'conn_1', query: 'acme' }));
+            mockBridge.request.mockResolvedValueOnce(output({ organizations: [{ id: '2' }] }));
+            await expect(useFiasLinkedIn().searchOrganizations('conn_1', 'acme')).resolves.toEqual([
+                { id: '2' },
+            ]);
+            expect(mockBridge.request).toHaveBeenLastCalledWith(...entityOp(entity_ops_1.LINKEDIN_ENTITY_ID, 'search_organizations', {
+                connectionId: 'conn_1',
+                query: 'acme',
+            }));
+        });
+    });
     describe('NLLB translation entity', () => {
         it('exposes the NLLB_LANGUAGES picker list keyed by FLORES code', () => {
             const { NLLB_LANGUAGES } = require('./hooks');
@@ -1049,6 +1477,7 @@ describe('SDK hooks', () => {
                 __esModule: true,
                 getBridge: () => mockSingletonBridge,
                 FiasBridge: jest.fn(),
+                FiasBridgeError: jest.requireActual('./bridge').FiasBridgeError,
                 resetBridge: jest.fn(),
             }));
             jest.doMock('react', () => require('react'));
@@ -1174,6 +1603,136 @@ describe('SDK hooks', () => {
             expect(second.url).toBe('https://example.com/new');
             expect(mockBridge.request).toHaveBeenCalledTimes(2);
         });
+        it('a changed access answer forgets cached download URLs (ADR-034)', async () => {
+            const { useVaultDocuments, useFiasAccess } = freshHooks();
+            const api = useVaultDocuments();
+            mockBridge.request.mockResolvedValueOnce({
+                url: 'https://example.com/minted-under-old-access',
+                expiresAt: Date.now() + 10 * 60000,
+            });
+            await api.getDownloadUrl('file_c');
+            const answer = (permissions) => ({
+                output: {
+                    access: {
+                        mode: 'roles',
+                        workspaceId: 'ws_1',
+                        tier: 'member',
+                        expiresAt: null,
+                        roles: [],
+                        permissions,
+                    },
+                },
+            });
+            const settle = () => new Promise((r) => setTimeout(r, 0));
+            mockBridge.request.mockResolvedValueOnce(answer(['ledger.read']));
+            useFiasAccess('ws_1');
+            await settle();
+            // The same answer again keeps the cache…
+            mockBridge.request.mockResolvedValueOnce(answer(['ledger.read']));
+            const subscriptions = mockBridge.onAccessUpdate.mock.calls;
+            const listener = subscriptions[subscriptions.length - 1][0];
+            listener();
+            await settle();
+            mockBridge.request.mockClear();
+            await api.getDownloadUrl('file_c');
+            expect(mockBridge.request).not.toHaveBeenCalled();
+            // …a different one does not.
+            mockBridge.request.mockResolvedValueOnce(answer([]));
+            listener();
+            await settle();
+            mockBridge.request.mockClear();
+            mockBridge.request.mockResolvedValueOnce({
+                url: 'https://example.com/fresh',
+                expiresAt: Date.now() + 10 * 60000,
+            });
+            await expect(api.getDownloadUrl('file_c')).resolves.toMatchObject({
+                url: 'https://example.com/fresh',
+            });
+        });
+        it('losing the workspace (NOT_A_MEMBER) forgets cached download URLs too (ADR-034)', async () => {
+            const { useVaultDocuments, useFiasAccess } = freshHooks();
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            const api = useVaultDocuments();
+            mockBridge.request.mockResolvedValueOnce({
+                url: 'https://example.com/old',
+                expiresAt: Date.now() + 10 * 60000,
+            });
+            await api.getDownloadUrl('file_d');
+            const settle = () => new Promise((r) => setTimeout(r, 0));
+            mockBridge.request.mockResolvedValueOnce({
+                output: { access: { mode: 'tier', workspaceId: 'ws_1', tier: 'member', expiresAt: null } },
+            });
+            useFiasAccess('ws_1');
+            await settle();
+            mockBridge.request.mockRejectedValueOnce(new FiasBridgeError('gone', 'NOT_A_MEMBER'));
+            const subscriptions = mockBridge.onAccessUpdate.mock.calls;
+            subscriptions[subscriptions.length - 1][0]();
+            await settle();
+            mockBridge.request.mockClear();
+            mockBridge.request.mockResolvedValueOnce({
+                url: 'https://example.com/new',
+                expiresAt: Date.now() + 10 * 60000,
+            });
+            await expect(api.getDownloadUrl('file_d')).resolves.toMatchObject({
+                url: 'https://example.com/new',
+            });
+        });
+        it('a remounted access hook still forgets the caches — on no access, and on a changed answer', async () => {
+            const { useVaultDocuments, useFiasAccess } = freshHooks();
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            const api = useVaultDocuments();
+            const settle = () => new Promise((r) => setTimeout(r, 0));
+            const cacheUrl = async (documentId, url) => {
+                mockBridge.request.mockResolvedValueOnce({ url, expiresAt: Date.now() + 600000 });
+                await api.getDownloadUrl(documentId);
+            };
+            const fresh = async (documentId, url) => {
+                mockBridge.request.mockClear();
+                mockBridge.request.mockResolvedValueOnce({ url, expiresAt: Date.now() + 600000 });
+                await expect(api.getDownloadUrl(documentId)).resolves.toMatchObject({ url });
+            };
+            // A brand-new hook whose FIRST answer is "no access" (the old one unmounted).
+            await cacheUrl('file_f', 'https://example.com/old');
+            mockBridge.request.mockRejectedValueOnce(new FiasBridgeError('gone', 'NOT_A_MEMBER'));
+            useFiasAccess('ws_9');
+            await settle();
+            await fresh('file_f', 'https://example.com/new');
+            // One hook sees an answer; a later, new hook sees a different one.
+            const answer = (tier) => ({
+                output: { access: { mode: 'tier', workspaceId: 'ws_8', tier, expiresAt: null } },
+            });
+            mockBridge.request.mockResolvedValueOnce(answer('admin'));
+            useFiasAccess('ws_8');
+            await settle();
+            await cacheUrl('file_g', 'https://example.com/old-g');
+            // The first hook unmounts (instances of one workspace share an answer
+            // while any is mounted), then a new one mounts.
+            capturedEffectCleanup?.();
+            mockBridge.request.mockResolvedValueOnce(answer('viewer'));
+            useFiasAccess('ws_8');
+            await settle();
+            await fresh('file_g', 'https://example.com/new-g');
+        });
+        it('a fetch already in flight when the caches are forgotten does not refill them', async () => {
+            const hooks = freshHooks();
+            const api = hooks.useVaultDocuments();
+            let answer;
+            mockBridge.request.mockImplementationOnce(() => new Promise((r) => (answer = r)));
+            const pending = api.getDownloadUrl('file_e');
+            hooks.clearSdkReadCaches();
+            answer({
+                url: 'https://example.com/minted-before',
+                expiresAt: new Date(Date.now() + 600000).toISOString(),
+            });
+            await pending;
+            mockBridge.request.mockResolvedValueOnce({
+                url: 'https://example.com/after',
+                expiresAt: new Date(Date.now() + 600000).toISOString(),
+            });
+            await expect(api.getDownloadUrl('file_e')).resolves.toMatchObject({
+                url: 'https://example.com/after',
+            });
+        });
         it('getDownloadUrl dedups concurrent in-flight calls', async () => {
             const { useVaultDocuments } = freshHooks();
             const api = useVaultDocuments();
@@ -1535,6 +2094,47 @@ describe('SDK hooks', () => {
                 data: { score: 100 },
             }));
         });
+        it('put with a null key creates: no key is sent, the audience is, and the server’s key comes back (ADR-034 phase 2)', async () => {
+            const { useFiasDataStore } = require('./hooks');
+            const ds = useFiasDataStore();
+            mockBridge.request.mockResolvedValueOnce(output({ key: 'rec_0123456789abcdef0123456789abcdef', version: 1, audience: 'board' }));
+            const result = await ds.put('papers', null, { t: 1 }, { workspaceId: 'ws_1', audience: 'board' });
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'put', {
+                collection: 'papers',
+                data: { t: 1 },
+                workspaceId: 'ws_1',
+                audience: 'board',
+            }));
+            expect(result).toEqual({
+                key: 'rec_0123456789abcdef0123456789abcdef',
+                version: 1,
+                audience: 'board',
+            });
+        });
+        it('create is a keyless put; a host that predates server keys is refused, never guessed at', async () => {
+            const { useFiasDataStore } = require('./hooks');
+            const ds = useFiasDataStore();
+            mockBridge.request.mockResolvedValueOnce(output({ key: 'rec_1', version: 1, audience: 'staff' }));
+            await expect(ds.create('papers', { t: 1 }, { workspaceId: 'ws_1', audience: 'staff' })).resolves.toMatchObject({ key: 'rec_1', audience: 'staff' });
+            mockBridge.request.mockResolvedValueOnce(output({ version: 1 }));
+            await expect(ds.create('papers', { t: 1 }, { workspaceId: 'ws_1', audience: 'staff' })).rejects.toMatchObject({ code: 'AUDIENCES_UNAVAILABLE' });
+        });
+        it('get, query and search forward an audience only when one is named', async () => {
+            const { useFiasDataStore } = require('./hooks');
+            const ds = useFiasDataStore();
+            mockBridge.request.mockResolvedValue(output({ data: null, documents: [], matches: [] }));
+            await ds.get('papers', 'k', { workspaceId: 'ws_1', audience: 'staff' });
+            await ds.query('papers', {}, { workspaceId: 'ws_1', audience: 'staff' });
+            await ds.search('papers', 'q', {}, { workspaceId: 'ws_1', audience: 'staff' });
+            await ds.get('papers', 'k', { workspaceId: 'ws_1' });
+            const payloads = mockBridge.request.mock.calls.map((c) => c[1].payload);
+            expect(payloads.slice(0, 3).map((p) => p.audience)).toEqual([
+                'staff',
+                'staff',
+                'staff',
+            ]);
+            expect(payloads[3]).not.toHaveProperty('audience');
+        });
         it('get unwraps { data } from the bridge envelope', async () => {
             const { useFiasDataStore } = require('./hooks');
             const ds = useFiasDataStore();
@@ -2311,6 +2911,19 @@ describe('useDataSubscription (ADR-012 Phase M4)', () => {
         expect(onInvalidate).toHaveBeenCalledTimes(1);
         expect(mockSetState).toHaveBeenCalledWith({ status: 'active' });
     });
+    it('names the audience to watch, where a collection has audiences (ADR-034 phase 2)', async () => {
+        subscribed();
+        const { useDataSubscription } = require('./hooks');
+        useDataSubscription('papers', jest.fn().mockResolvedValue(undefined), {
+            workspaceId: 'ws_1',
+            audience: 'board',
+        });
+        await flush();
+        expect(mockBridge.request).toHaveBeenCalledWith('entity_invoke', {
+            entityId: 'ent_intg_plugin_datastore_000000',
+            payload: { op: 'subscribe', collection: 'papers', workspaceId: 'ws_1', audience: 'board' },
+        });
+    });
     it('runs onInvalidate single-flight with exactly one trailing call', async () => {
         subscribed();
         let resolveFirst = () => undefined;
@@ -2358,6 +2971,95 @@ describe('useDataSubscription (ADR-012 Phase M4)', () => {
         expect(onInvalidate).not.toHaveBeenCalled();
     });
 });
+describe('useEntitySubscription (ADR-012 Phase M4 — any subscribe-kind verb)', () => {
+    const flush = async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+        await Promise.resolve();
+    };
+    let mockBridge;
+    beforeEach(() => {
+        mockBridge = createMockBridge();
+        mockContextValue = mockBridge;
+        mockSingletonBridge = mockBridge;
+    });
+    it('forwards the entity id and the verb payload verbatim, then refetches once live', async () => {
+        mockBridge.request.mockResolvedValue({
+            output: { kind: 'subscription', subscriptionId: 'lsub_chat' },
+        });
+        const onInvalidate = jest.fn().mockResolvedValue(undefined);
+        const { useEntitySubscription } = require('./hooks');
+        useEntitySubscription('ent_intg_litcraft_player_0000000', { op: 'subscribe_guild_chat' }, onInvalidate);
+        await flush();
+        expect(mockBridge.request).toHaveBeenCalledWith('entity_invoke', {
+            entityId: 'ent_intg_litcraft_player_0000000',
+            payload: { op: 'subscribe_guild_chat' },
+        });
+        expect(mockBridge.onSubscriptionEvent).toHaveBeenCalledWith('lsub_chat', expect.any(Function));
+        expect(onInvalidate).toHaveBeenCalledTimes(1);
+        expect(mockSetState).toHaveBeenCalledWith({ status: 'active' });
+    });
+    it('enabled: false subscribes to nothing and reports unsubscribed', async () => {
+        const onInvalidate = jest.fn();
+        const { useEntitySubscription } = require('./hooks');
+        useEntitySubscription('ent_x', { op: 'subscribe_x' }, onInvalidate, { enabled: false });
+        await flush();
+        expect(mockBridge.request).not.toHaveBeenCalled();
+        expect(onInvalidate).not.toHaveBeenCalled();
+        expect(mockSetState).toHaveBeenCalledWith({ status: 'ended', endedReason: 'unsubscribed' });
+    });
+    it('sends the payload exactly as given (key order is identity-neutral, not rewritten)', async () => {
+        mockBridge.request.mockResolvedValue({
+            output: { kind: 'subscription', subscriptionId: 'lsub_1' },
+        });
+        const { useEntitySubscription } = require('./hooks');
+        useEntitySubscription('ent_x', { workspaceId: 'ws_1', op: 'subscribe_x' }, jest.fn());
+        await flush();
+        expect(mockBridge.request).toHaveBeenCalledWith('entity_invoke', {
+            entityId: 'ent_x',
+            payload: { op: 'subscribe_x', workspaceId: 'ws_1' },
+        });
+    });
+    it('minRefetchIntervalMs caps refetches to one per interval with one trailing run', async () => {
+        jest.useFakeTimers();
+        try {
+            mockBridge.request.mockResolvedValue({
+                output: { kind: 'subscription', subscriptionId: 'lsub_1' },
+            });
+            const onInvalidate = jest.fn().mockResolvedValue(undefined);
+            const { useEntitySubscription } = require('./hooks');
+            useEntitySubscription('ent_x', { op: 'subscribe_x' }, onInvalidate, {
+                minRefetchIntervalMs: 2000,
+            });
+            await flush();
+            expect(onInvalidate).toHaveBeenCalledTimes(1); // the subscribe-then-fetch run
+            const eventCb = mockBridge.onSubscriptionEvent.mock.calls[0][1];
+            eventCb();
+            eventCb();
+            eventCb();
+            await flush();
+            expect(onInvalidate).toHaveBeenCalledTimes(1); // inside the interval: deferred, not dropped
+            await jest.advanceTimersByTimeAsync(2000);
+            expect(onInvalidate).toHaveBeenCalledTimes(2); // exactly one trailing run at the interval's end
+            capturedEffectCleanup?.();
+        }
+        finally {
+            jest.useRealTimers();
+        }
+    });
+    it('a rejected handshake ends with transport_error and never refetches', async () => {
+        mockBridge.request.mockRejectedValue(new Error('NOT_A_MEMBER'));
+        const onInvalidate = jest.fn();
+        const { useEntitySubscription } = require('./hooks');
+        useEntitySubscription('ent_x', { op: 'subscribe_x' }, onInvalidate);
+        await flush();
+        expect(mockSetState).toHaveBeenCalledWith({
+            status: 'ended',
+            endedReason: 'transport_error',
+        });
+        expect(onInvalidate).not.toHaveBeenCalled();
+    });
+});
 describe('useFiasAIActions', () => {
     let mockBridge;
     beforeEach(() => {