@memberjunction/server 6.2.0-edge.4 → 6.2.0-edge.5

package/src/__tests__/RunAIAgentResolver.runDataGuard.test.ts

@@ -0,0 +1,258 @@
+/**
+ * @fileoverview Every agent-run entry of `RunAIAgentResolver` tells the run whether it may read the reserved scope
+ * and agent-type keys from a client's `data` (`ExecuteAgentParams.TrustReservedRunData`, A12.15).
+ *
+ * The decision is pinned by `agent-run-data-guard.test.ts`, and what an untrusted run loses by the ai-core-plus and
+ * ai-agents suites (`BaseAgent.Execute` drops the keys). These tests pin the call sites: the synchronous and
+ * fire-and-forget paths of `RunAIAgent` and `RunAIAgentFromConversationDetail`, the widget-guest path (judged on
+ * the guest's own payload, not the system principal it is elevated to), the trusted callers, and an API key with and
+ * without the `agent:trusted` scope — each through the real `executeAIAgent`, up to the params handed to
+ * `AgentRunner`. The resolver forwards `data` as sent.
+ */
+import 'reflect-metadata'; // must precede any type-graphql decorator evaluation
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { PubSubEngine } from 'type-graphql';
+
+// type-graphql's real decorators need emitDecoratorMetadata, which vitest's esbuild transform
+// does not emit; the schema is irrelevant here, so every decorator is a no-op.
+vi.mock('type-graphql', () => {
+    const decoratorFactory = (..._args: unknown[]) => (..._decorated: unknown[]) => undefined;
+    const exportNames = [
+        'Resolver', 'Query', 'Mutation', 'Subscription', 'Arg', 'Args', 'ArgsType', 'Ctx', 'Root',
+        'Info', 'Field', 'FieldResolver', 'ObjectType', 'InputType', 'InterfaceType', 'Authorized',
+        'UseMiddleware', 'Extensions', 'Directive', 'ID', 'Int', 'Float', 'GraphQLISODateTime',
+        'GraphQLTimestamp', 'registerEnumType', 'createMethodDecorator', 'createParamDecorator',
+        'buildSchema', 'buildSchemaSync', 'PubSub',
+    ];
+    return Object.fromEntries(exportNames.map((name) => [name, decoratorFactory]));
+});
+
+const hoisted = vi.hoisted(() => ({
+    runAgentInConversation: vi.fn(),
+    resolveWidgetGuestRunContext: vi.fn(),
+    authorize: vi.fn(),
+}));
+
+// Only the key engine is stubbed: Authorize allows `agent:trusted` for the key whose hash is 'hash-trusted'.
+vi.mock('@memberjunction/api-keys', async (importOriginal) => ({
+    ...(await importOriginal<typeof import('@memberjunction/api-keys')>()),
+    GetAPIKeyEngine: () => ({ Authorize: hoisted.authorize }),
+}));
+
+vi.mock('@memberjunction/ai-agents', () => ({
+    AgentRunner: class {
+        RunAgentInConversation(...args: unknown[]) {
+            return hoisted.runAgentInConversation(...args);
+        }
+    },
+    ArtifactToolManager: class {},
+}));
+
+// Only the widget lookup is stubbed; ElevateUserPayload is the real one, so the widget-guest test runs
+// against the elevated system-user payload the resolver really builds.
+vi.mock('../realtimeWidget/widgetGuestElevation.js', async (importOriginal) => ({
+    ...(await importOriginal<typeof import('../realtimeWidget/widgetGuestElevation.js')>()),
+    ResolveWidgetGuestRunContext: hoisted.resolveWidgetGuestRunContext,
+}));
+
+import { UserCache } from '@memberjunction/generic-database-provider';
+import type { UserInfo } from '@memberjunction/core';
+import { RunAIAgentResolver } from '../resolvers/RunAIAgentResolver.js';
+import type { AppContext, UserPayload } from '../types.js';
+
+const SCOPE_RECORD_ID = 'B1A2C3D4-0000-4000-8000-00000000A115';
+const ORDINARY = { conversationId: 'conv-1', latestMessageId: 'detail-1', invocationReason: 'user-message' };
+const CLIENT_DATA = JSON.stringify({
+    ...ORDINARY,
+    PrimaryScopeRecordID: SCOPE_RECORD_ID,
+    PrimaryScopeEntityName: 'MJ: Companies',
+    SecondaryScopes: { TeamID: 'team-other' },
+    __agentTypePromptParams: { enableTaskGraphs: true },
+});
+
+const USER = { ID: 'user-1', Email: 'browser.user@example.com' };
+const SYSTEM_USER = { ID: 'system-user', Email: 'system@example.com' };
+const GUEST = { ID: 'guest-1', Email: 'anonymous@magic-link.local', IsMagicLinkAnonymous: true };
+
+type Fn = ReturnType<typeof vi.fn>;
+
+/** The private members this test reaches, through an explicit shape (no `any`). */
+interface ResolverSeams {
+    CheckAPIKeyScopeAuthorization: Fn;
+    GetUserFromPayload: Fn;
+    loadConversationHistoryWithAttachments: Fn;
+    validateAgent: Fn;
+    persistInFlightAgentFailure: Fn;
+}
+
+const pubSub = { publish: vi.fn().mockResolvedValue(undefined) } as unknown as PubSubEngine;
+
+function makeResolver(): { resolver: RunAIAgentResolver; seams: ResolverSeams } {
+    const resolver = new RunAIAgentResolver();
+    const seams = resolver as unknown as ResolverSeams;
+    seams.CheckAPIKeyScopeAuthorization = vi.fn().mockResolvedValue(undefined);
+    seams.GetUserFromPayload = vi.fn((payload: UserPayload) => payload.userRecord);
+    seams.loadConversationHistoryWithAttachments = vi.fn().mockResolvedValue([{ role: 'user', content: 'hi' }]);
+    seams.validateAgent = vi.fn().mockResolvedValue({ ID: 'agent-1', Name: 'Test Agent' });
+    seams.persistInFlightAgentFailure = vi.fn().mockResolvedValue(undefined);
+    return { resolver, seams };
+}
+
+function makeContext(userPayload: Partial<UserPayload>): AppContext {
+    const provider = {
+        GetEntityObject: vi.fn().mockResolvedValue({ ConversationID: 'conv-1', Load: vi.fn().mockResolvedValue(true) }),
+    };
+    return {
+        userPayload: { sessionId: 'session-1', email: USER.Email, userRecord: USER, ...userPayload } as UserPayload,
+        providers: [{ type: 'Read-Write', provider }],
+        dataSource: {},
+    } as unknown as AppContext;
+}
+
+/** The params the n-th run was handed by the real executeAIAgent (what AgentRunner.RunAgentInConversation received). */
+interface HandedParams {
+    data: Record<string, unknown>;
+    TrustReservedRunData?: boolean;
+    contextUser: { ID: string };
+}
+
+/** Waits for the n-th run to start (the fire-and-forget path starts it after the resolver has returned). */
+async function handedParams(n = 0): Promise<HandedParams> {
+    await vi.waitFor(() => expect(hoisted.runAgentInConversation.mock.calls.length).toBeGreaterThan(n));
+    return hoisted.runAgentInConversation.mock.calls[n][0] as HandedParams;
+}
+
+function runAIAgent(resolver: RunAIAgentResolver, ctx: AppContext, fireAndForget?: boolean) {
+    return resolver.RunAIAgent(
+        'agent-1', ctx, '[{"role":"user","content":"hi"}]', 'session-1', pubSub, CLIENT_DATA,
+        undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined,
+        fireAndForget
+    );
+}
+
+function runFromDetail(resolver: RunAIAgentResolver, ctx: AppContext, fireAndForget?: boolean) {
+    return resolver.RunAIAgentFromConversationDetail(
+        'detail-1', 'agent-1', ctx, 'session-1', pubSub, undefined, CLIENT_DATA,
+        undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, fireAndForget
+    );
+}
+
+beforeEach(() => {
+    hoisted.resolveWidgetGuestRunContext.mockReset().mockResolvedValue(null);
+    // Stop right after the run's params are captured — the rest of the run is out of scope.
+    hoisted.runAgentInConversation.mockReset().mockRejectedValue(new Error('stop here'));
+    hoisted.authorize.mockReset().mockImplementation(async (apiKeyHash: string, _app: string, scopePath: string) =>
+        apiKeyHash === 'hash-trusted' && scopePath === 'agent:trusted'
+            ? { Allowed: true, MatchedKeyRule: { ScopePath: scopePath }, EvaluatedRules: [] }
+            : { Allowed: false, Reason: 'No matching key scope rules', EvaluatedRules: [] });
+    vi.spyOn(UserCache.Instance, 'GetSystemUser').mockReturnValue(SYSTEM_USER as UserInfo);
+    vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+});
+
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+
+describe('RunAIAgent — reserved run-data keys', () => {
+    it('marks the run untrusted for an interactive user and forwards data as sent', async () => {
+        const { resolver } = makeResolver();
+
+        await runAIAgent(resolver, makeContext({}));
+
+        const params = await handedParams();
+        expect(params.TrustReservedRunData).toBe(false);
+        expect(params.data).toEqual(JSON.parse(CLIENT_DATA));
+    });
+
+    it('marks it untrusted on the fire-and-forget path too', async () => {
+        const { resolver } = makeResolver();
+
+        await runAIAgent(resolver, makeContext({}), true);
+
+        expect((await handedParams()).TrustReservedRunData).toBe(false);
+    });
+
+    it('marks it trusted for an API key holding agent:trusted, on both paths', async () => {
+        const { resolver } = makeResolver();
+        const ctx = makeContext({ apiKeyId: 'key-1', apiKeyHash: 'hash-trusted' });
+
+        await runAIAgent(resolver, ctx);
+        await runAIAgent(resolver, ctx, true);
+
+        expect((await handedParams(0)).TrustReservedRunData).toBe(true);
+        expect((await handedParams(1)).TrustReservedRunData).toBe(true);
+    });
+
+    it('marks it untrusted for an API key without agent:trusted, on both paths', async () => {
+        const { resolver } = makeResolver();
+        const ctx = makeContext({ apiKeyId: 'key-2', apiKeyHash: 'hash-plain' });
+
+        await runAIAgent(resolver, ctx);
+        await runAIAgent(resolver, ctx, true);
+
+        expect((await handedParams(0)).TrustReservedRunData).toBe(false);
+        expect((await handedParams(1)).TrustReservedRunData).toBe(false);
+    });
+});
+
+describe('RunAIAgentFromConversationDetail — reserved run-data keys', () => {
+    it('marks the run untrusted for an interactive user on both paths', async () => {
+        const { resolver } = makeResolver();
+
+        await runFromDetail(resolver, makeContext({}));
+        await runFromDetail(resolver, makeContext({}), true);
+
+        expect((await handedParams(0)).TrustReservedRunData).toBe(false);
+        expect((await handedParams(1)).TrustReservedRunData).toBe(false);
+    });
+
+    it('marks a widget-guest run untrusted although it executes as the system user', async () => {
+        const { resolver } = makeResolver();
+        hoisted.resolveWidgetGuestRunContext.mockResolvedValue({
+            ElevatedUser: SYSTEM_USER,
+            Widget: {},
+            PinnedAgentId: 'pinned-agent',
+        });
+
+        await runFromDetail(resolver, makeContext({ email: GUEST.Email, userRecord: GUEST }));
+
+        const params = await handedParams();
+        expect(params.contextUser.ID).toBe(SYSTEM_USER.ID); // the premise: the run is elevated
+        expect(params.TrustReservedRunData).toBe(false);
+    });
+
+    it('marks it trusted for the system user, on both paths', async () => {
+        const { resolver } = makeResolver();
+        const ctx = makeContext({ isSystemUser: true, email: SYSTEM_USER.Email, userRecord: SYSTEM_USER });
+
+        await runFromDetail(resolver, ctx);
+        await runFromDetail(resolver, ctx, true);
+
+        expect((await handedParams(0)).TrustReservedRunData).toBe(true);
+        expect((await handedParams(1)).TrustReservedRunData).toBe(true);
+    });
+
+    it('marks it trusted for an API key holding agent:trusted, and untrusted for one without', async () => {
+        const { resolver } = makeResolver();
+
+        await runFromDetail(resolver, makeContext({ apiKeyId: 'key-1', apiKeyHash: 'hash-trusted' }));
+        await runFromDetail(resolver, makeContext({ apiKeyId: 'key-2', apiKeyHash: 'hash-plain' }));
+
+        expect((await handedParams(0)).TrustReservedRunData).toBe(true);
+        expect((await handedParams(1)).TrustReservedRunData).toBe(false);
+    });
+});
+
+describe('RunAIAgentSystemUser — reserved run-data keys', () => {
+    it('marks the run trusted for the system user it admits, and forwards data as sent', async () => {
+        const { resolver } = makeResolver();
+        const ctx = makeContext({ isSystemUser: true, email: SYSTEM_USER.Email, userRecord: SYSTEM_USER });
+
+        await resolver.RunAIAgentSystemUser('agent-1', ctx, '[]', 'session-1', pubSub, CLIENT_DATA);
+
+        const params = await handedParams();
+        expect(params.TrustReservedRunData).toBe(true);
+        expect(params.data).toEqual(JSON.parse(CLIENT_DATA));
+    });
+});

package/src/__tests__/RunViewResolver.cacheCheckScreen.test.ts

@@ -0,0 +1,165 @@
+// ResolverBase pulls in type-graphql decorators, which need the Reflect.metadata polyfill first.
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+/**
+ * `RunViewsWithCacheCheck` is the transport `RunViews` switches to when any view in the batch is
+ * `CacheLocal`, so it carries the same client-supplied clauses as `RunViews`. These tests pin that
+ * it applies the same GraphQL-boundary protections before the provider is called: the base-view
+ * AST screen on ExtraFilter / OrderBy / OverrideExcludeFilter, and the API-key scope check.
+ *
+ * Every payload here is harmless (stacked `SELECT`s); the point is only whether it reaches the
+ * provider. The provider's own keyword denylist accepts the bracket-identifier payload, because a
+ * quote inside `[a']` hides the rest of the text from its literal stripper.
+ */
+
+const { authorize } = vi.hoisted(() => ({ authorize: vi.fn() }));
+
+vi.mock('@memberjunction/api-keys', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/api-keys')>();
+    return { ...actual, GetAPIKeyEngine: () => ({ Authorize: authorize }) };
+});
+
+import type { DatabaseProviderBase, EntityInfo, RunViewWithCacheCheckParams, UserInfo } from '@memberjunction/core';
+import { UserCache } from '@memberjunction/generic-database-provider';
+import { RunDynamicViewInput, RunViewResolver, RunViewWithCacheCheckInput } from '../generic/RunViewResolver.js';
+import type { AppContext, UserPayload } from '../types.js';
+
+/** A stacked statement hidden from the keyword denylist by a quote inside a bracket identifier. */
+const BRACKET_STACKED =
+    "1 = (SELECT 1 AS [a'])) ; SELECT 1 AS [x] ; SELECT * FROM __mj.vwUserViews WHERE (1 = (SELECT 1 AS [b'])";
+
+const USER = { ID: 'user-1', Email: 'reader@example.com', Name: 'Reader' } as UserInfo;
+
+function entity(name: string, schema: string, baseView: string): EntityInfo {
+    return {
+        Name: name,
+        SchemaName: schema,
+        BaseView: baseView,
+        PrimaryKeys: [{ Name: 'ID' }],
+        GetUserPermisions: () => ({ CanRead: true }),
+        GetEffectiveRowFilterWhereClause: () => '',
+        GetDeniedReadFields: () => new Set<string>(),
+    } as unknown as EntityInfo;
+}
+
+/** Provider double: the metadata the screen reads, and a cache-check method that records calls. */
+function fakeProvider() {
+    const calls: RunViewWithCacheCheckParams[][] = [];
+    const entities = [
+        entity('MJ: User Views', '__mj', 'vwUserViews'),
+        entity('MJ: Users', '__mj', 'vwUsers'),
+    ];
+    const provider = {
+        Entities: entities,
+        EntityByName: (name: string) => entities.find((e) => e.Name === name),
+        RunViewsWithCacheCheck: async (params: RunViewWithCacheCheckParams[]) => {
+            calls.push(params);
+            return { success: true, results: [] };
+        },
+    };
+    return { provider: provider as unknown as DatabaseProviderBase, calls };
+}
+
+function context(provider: DatabaseProviderBase, payload: Partial<UserPayload> = {}): AppContext {
+    const userPayload = { email: USER.Email, userRecord: USER, ...payload } as UserPayload;
+    return { providers: [{ type: 'Read-Only', provider }], userPayload } as unknown as AppContext;
+}
+
+function cacheCheckInput(params: Partial<RunDynamicViewInput>): RunViewWithCacheCheckInput[] {
+    const dynamic = Object.assign(new RunDynamicViewInput(), { EntityName: 'MJ: User Views', ...params });
+    return [Object.assign(new RunViewWithCacheCheckInput(), { params: dynamic })];
+}
+
+describe('RunViewsWithCacheCheck — GraphQL-boundary clause screen', () => {
+    it('refuses a stacked statement hidden behind a bracket identifier, before the provider runs', async () => {
+        const { provider, calls } = fakeProvider();
+
+        const result = await new RunViewResolver().RunViewsWithCacheCheck(
+            cacheCheckInput({ ExtraFilter: BRACKET_STACKED }),
+            context(provider),
+        );
+
+        expect(calls).toHaveLength(0);
+        expect(result.success).toBe(false);
+        expect(result.errorMessage).toMatch(/Invalid ExtraFilter: multiple statements/);
+    });
+
+    it('refuses a subquery against a base table', async () => {
+        const { provider, calls } = fakeProvider();
+
+        const result = await new RunViewResolver().RunViewsWithCacheCheck(
+            cacheCheckInput({ ExtraFilter: `EXISTS (SELECT 1 FROM __mj.[User] WHERE [Type] = 'Owner')` }),
+            context(provider),
+        );
+
+        expect(calls).toHaveLength(0);
+        expect(result.success).toBe(false);
+        expect(result.errorMessage).toMatch(/entity base view/);
+    });
+
+    it('screens OrderBy and OverrideExcludeFilter too', async () => {
+        for (const params of [
+            { OrderBy: "[a'] ; SELECT 1 AS [x] ; SELECT 1 AS [b']" },
+            { OverrideExcludeFilter: BRACKET_STACKED },
+        ]) {
+            const { provider, calls } = fakeProvider();
+
+            const result = await new RunViewResolver().RunViewsWithCacheCheck(cacheCheckInput(params), context(provider));
+
+            expect(calls).toHaveLength(0);
+            expect(result.success).toBe(false);
+        }
+    });
+
+    it('passes a filter that only reads entity base views through to the provider', async () => {
+        const { provider, calls } = fakeProvider();
+        const filter = `UserID IN (SELECT ID FROM [__mj].[vwUsers] WHERE Email = 'o''brien@example.com')`;
+
+        const result = await new RunViewResolver().RunViewsWithCacheCheck(
+            cacheCheckInput({ ExtraFilter: filter, OrderBy: '[Name] DESC' }),
+            context(provider),
+        );
+
+        expect(result.success).toBe(true);
+        expect(calls).toHaveLength(1);
+        expect(calls[0][0].params.ExtraFilter).toBe(filter);
+    });
+});
+
+describe('RunViewsWithCacheCheck — API-key scope', () => {
+    beforeEach(() => {
+        authorize.mockReset();
+        vi.spyOn(UserCache.Instance, 'GetSystemUser').mockReturnValue({ ID: 'system', Email: 'system@example.com' } as UserInfo);
+    });
+
+    it('refuses an API key without the batch view scope, before the provider runs', async () => {
+        authorize.mockResolvedValue({ Allowed: false, Reason: 'scope not granted' });
+        const { provider, calls } = fakeProvider();
+
+        const result = await new RunViewResolver().RunViewsWithCacheCheck(
+            cacheCheckInput({ ExtraFilter: `Name = 'x'` }),
+            context(provider, { apiKeyHash: 'hash-of-a-narrow-key' }),
+        );
+
+        expect(calls).toHaveLength(0);
+        expect(result.success).toBe(false);
+        expect(result.errorMessage).toMatch(/'view:batch' scope/);
+    });
+
+    it('lets an API key holding the scope through', async () => {
+        authorize.mockImplementation(async (_hash: string, _app: string, scope: string) => ({
+            Allowed: scope === 'view:batch',
+            Reason: scope === 'view:batch' ? 'granted' : 'not full access',
+        }));
+        const { provider, calls } = fakeProvider();
+
+        const result = await new RunViewResolver().RunViewsWithCacheCheck(
+            cacheCheckInput({ ExtraFilter: `Name = 'x'` }),
+            context(provider, { apiKeyHash: 'hash-of-a-batch-key' }),
+        );
+
+        expect(result.success).toBe(true);
+        expect(calls).toHaveLength(1);
+    });
+});

package/src/__tests__/SearchKnowledgeStreamResolver.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+/**
+ * Tests for SearchKnowledgeStreamResolver's wire mapping: a `provider` event is progress only.
+ *
+ * A provider's hits arrive before the engine's permission pass — rows the caller's row filters would drop,
+ * external-index hits not yet verified against the entity they name, content whose origin the caller may not
+ * read. The engine no longer puts them on its `provider` events, and the resolver does not forward them either,
+ * whatever the event holds: the client gets ProviderName, DurationMs and ResultCount, and results only in
+ * `fused`/`final`.
+ */
+
+const { streamEvents, streamCalls, resolveEffectivePermission, logForbiddenSearch } = vi.hoisted(() => ({
+    streamEvents: { current: [] as unknown[] },
+    streamCalls: { count: 0 },
+    resolveEffectivePermission: vi.fn(),
+    logForbiddenSearch: vi.fn(),
+}));
+
+vi.mock('@memberjunction/search-engine', () => ({
+    SearchEngine: {
+        Instance: {
+            streamSearch: async function* () {
+                streamCalls.count++;
+                for (const ev of streamEvents.current) yield ev;
+            },
+            LogForbiddenSearch: logForbiddenSearch,
+        },
+    },
+    GetSearchScopePermissionResolver: () => ({ ResolveEffectivePermission: resolveEffectivePermission }),
+}));
+
+vi.mock('@memberjunction/core', async (importOriginal) => {
+    const actual = await importOriginal<Record<string, unknown>>();
+    return { ...actual, LogError: vi.fn(), LogStatus: vi.fn() };
+});
+
+// Mock type-graphql to avoid the reflect-metadata dependency (the SearchKnowledgeResolver tests do the same).
+vi.mock('type-graphql', () => {
+    const noop = () => () => undefined;
+    const passthrough = () => (target: unknown) => target;
+    return {
+        Resolver: passthrough, Mutation: noop, Query: noop, Subscription: noop, Arg: noop, Args: noop, Ctx: noop,
+        ObjectType: passthrough, InputType: passthrough, ArgsType: passthrough, Field: noop,
+        Float: Number, Int: Number, ID: String, Authorized: noop, PubSub: noop, Root: noop,
+    };
+});
+
+import type { PubSubEngine } from 'type-graphql';
+import type { UserInfo } from '@memberjunction/core';
+import { SearchKnowledgeStreamResolver, SearchStreamNotification } from '../resolvers/SearchKnowledgeStreamResolver.js';
+import type { UserPayload } from '../types.js';
+
+class TestStreamResolver extends SearchKnowledgeStreamResolver {
+    protected override GetUserFromPayload(_userPayload: UserPayload): UserInfo | undefined {
+        return { ID: 'test-user-id', Email: 'test@test.com', Name: 'Test User' } as UserInfo;
+    }
+}
+
+const hit = (recordID: string) => ({
+    ID: `r-${recordID}`, EntityName: 'Customers', RecordID: recordID, SourceType: 'fulltext', ResultType: 'entity-record',
+    Title: `title of ${recordID}`, Snippet: `snippet of ${recordID}`, Score: 0.5, ScoreBreakdown: {}, Tags: [],
+    MatchedAt: new Date(), RawMetadata: `{"secret":"${recordID}"}`, ProviderId: 'prov-azure',
+});
+
+/** Run a stream to completion and return what the resolver published, in order. */
+async function publishedFor(events: unknown[]): Promise<SearchStreamNotification[]> {
+    streamEvents.current = events;
+    const published: SearchStreamNotification[] = [];
+    const pubSub = { publish: vi.fn(async (_topic: string, payload: SearchStreamNotification) => { published.push(payload); }) };
+    const start = await new TestStreamResolver().StreamScopedSearch(
+        'budget', 20, undefined, undefined, undefined, undefined,
+        pubSub as unknown as PubSubEngine, { userPayload: {} } as never,
+    );
+    expect(start.Success).toBe(true);
+    await vi.waitFor(() => expect(published.some(p => p.Phase === 'final' || p.Phase === 'error')).toBe(true),
+        { timeout: 500, interval: 5 });
+    return published;
+}
+
+describe('SearchKnowledgeStreamResolver — provider events are progress only', () => {
+    beforeEach(() => { vi.clearAllMocks(); });
+
+    it('publishes the count and no result, even when a provider event carries hits', async () => {
+        // An engine that (wrongly) put hits on a provider event: the resolver still must not forward them.
+        const published = await publishedFor([
+            { phase: 'provider', providerName: 'FullText', results: [hit('row-filtered')], resultCount: 1, durationMs: 7 },
+            { phase: 'fused', results: [] },
+            { phase: 'final', results: [], sourceCounts: { Vector: 0, FullText: 1, Entity: 0, Storage: 0 }, elapsedMs: 9 },
+        ]);
+
+        const progress = published.find(p => p.Phase === 'provider');
+        expect(progress).toMatchObject({ Phase: 'provider', ProviderName: 'FullText', DurationMs: 7, ResultCount: 1, Results: [] });
+        expect(JSON.stringify(progress)).not.toContain('row-filtered');
+    });
+
+    it('carries results on final, mapped as the synchronous resolver maps them', async () => {
+        const published = await publishedFor([
+            { phase: 'provider', providerName: 'FullText', results: [], resultCount: 1, durationMs: 7 },
+            { phase: 'fused', results: [hit('readable')] },
+            { phase: 'final', results: [hit('readable')], sourceCounts: { Vector: 0, FullText: 1, Entity: 0, Storage: 0 }, elapsedMs: 9 },
+        ]);
+
+        const final = published.find(p => p.Phase === 'final');
+        expect(final?.Results?.map(r => r.RecordID)).toEqual(['readable']);
+        expect(final?.ResultCount).toBeUndefined();
+    });
+});
+
+describe('SearchKnowledgeStreamResolver — the scope permission gate runs before the stream starts', () => {
+    const verdict = (Allowed: boolean, Level: string) => ({ Allowed, Level, Source: 'NoGrant', Reason: 'judged in test' });
+
+    beforeEach(() => {
+        streamEvents.current = [{ phase: 'final', results: [], sourceCounts: { Vector: 0, FullText: 0, Entity: 0, Storage: 0 }, elapsedMs: 1 }];
+        streamCalls.count = 0;
+        resolveEffectivePermission.mockReset();
+        logForbiddenSearch.mockReset();
+    });
+
+    async function start(scopeIDs: string[]) {
+        const pubSub = { publish: vi.fn(async () => undefined) };
+        const result = await new TestStreamResolver().StreamScopedSearch(
+            'budget', 20, undefined, scopeIDs, undefined, undefined,
+            pubSub as unknown as PubSubEngine, { userPayload: {} } as never,
+        );
+        return { result, pubSub };
+    }
+
+    it('refuses a denied scope, logs it, and never starts the stream or publishes', async () => {
+        resolveEffectivePermission.mockResolvedValue(verdict(false, 'None'));
+
+        const { result, pubSub } = await start(['scope-a']);
+
+        expect(result.Success).toBe(false);
+        expect(result.ErrorMessage).toMatch(/^Forbidden: refused for this user on scope 'scope-a'/);
+        expect(logForbiddenSearch).toHaveBeenCalledTimes(1);
+        await new Promise((r) => setTimeout(r, 20));
+        expect(streamCalls.count).toBe(0);
+        expect(pubSub.publish).not.toHaveBeenCalled();
+    });
+
+    it('refuses a Read-level grant: Read is metadata only, not search', async () => {
+        resolveEffectivePermission.mockResolvedValue(verdict(true, 'Read'));
+
+        const { result } = await start(['scope-a']);
+
+        expect(result.Success).toBe(false);
+        await new Promise((r) => setTimeout(r, 20));
+        expect(streamCalls.count).toBe(0);
+    });
+
+    it('judges every requested scope and starts the stream when all may be searched', async () => {
+        resolveEffectivePermission.mockResolvedValue(verdict(true, 'Search'));
+
+        const { result } = await start(['scope-a', 'scope-b']);
+
+        expect(result.Success).toBe(true);
+        expect(resolveEffectivePermission).toHaveBeenCalledTimes(2);
+        await vi.waitFor(() => expect(streamCalls.count).toBe(1), { timeout: 500, interval: 5 });
+    });
+});