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

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

@@ -0,0 +1,358 @@
+/**
+ * @fileoverview `RunAIAgentFromConversationDetail` after A19: only the server writes agent replies.
+ *
+ * The mutation names the user's message. The server loads the history, creates the agent's reply row as the person
+ * asking (marked as server-authored by `AgentRunner.CreateAgentReplyDetail`), and runs the agent into it. The
+ * fire-and-forget acknowledgement names the row (`conversationDetailId`, `createdAt`) and is returned before the run
+ * publishes anything; the run's status messages carry the same ID (`AgentRunStatusPublisher`, its own tests).
+ */
+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';
+
+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(() => ({
+    createReply: vi.fn(),
+    runAgentInConversation: vi.fn(),
+    widgetContext: vi.fn(),
+    agents: new Map<string, { ID: string; Name: string; Status: string }>(),
+}));
+
+vi.mock('@memberjunction/aiengine', () => ({
+    AIEngine: {
+        Instance: {
+            Config: async () => undefined,
+            GetAgentByID: (id: string) => hoisted.agents.get(id),
+        },
+    },
+    GetAttachmentService: () => ({}),
+}));
+
+vi.mock('@memberjunction/ai-agents', () => ({
+    AgentRunner: class {
+        CreateAgentReplyDetail(args: unknown) {
+            return hoisted.createReply(args);
+        }
+        RunAgentInConversation(...args: unknown[]) {
+            return hoisted.runAgentInConversation(...args);
+        }
+    },
+    ArtifactToolManager: class {},
+}));
+
+vi.mock('../realtimeWidget/widgetGuestElevation.js', () => ({
+    ResolveWidgetGuestRunContext: (...args: unknown[]) => hoisted.widgetContext(...args),
+    ElevateUserPayload: (payload: Record<string, unknown>, user: unknown) => ({ ...payload, userRecord: user }),
+}));
+
+import { RunAIAgentResolver } from '../resolvers/RunAIAgentResolver.js';
+import type { AppContext, UserPayload } from '../types.js';
+
+const USER = { ID: 'user-1', Email: 'user@example.com' };
+const SYSTEM = { ID: 'system-1', Email: 'system@example.com' };
+const CREATED_AT = new Date('2026-10-12T10:00:00.000Z');
+const REPLY = { ID: 'reply-1', ConversationID: 'conv-1', __mj_CreatedAt: CREATED_AT };
+
+type Fn = ReturnType<typeof vi.fn>;
+
+interface ResolverSeams {
+    CheckAPIKeyScopeAuthorization: Fn;
+    GetUserFromPayload: Fn;
+    loadConversationHistoryWithAttachments: Fn;
+    executeAIAgent: Fn;
+    executeAgentInBackground: Fn;
+    validateAgent: Fn;
+    persistInFlightAgentFailure: Fn;
+}
+
+/** The order the turn's steps happened in. */
+let steps: string[] = [];
+
+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: { userRecord: unknown }) => payload.userRecord);
+    seams.loadConversationHistoryWithAttachments = vi.fn(async () => {
+        steps.push('history');
+        return [];
+    });
+    seams.executeAIAgent = vi.fn(async () => {
+        steps.push('run');
+        return { success: true, result: '{}' };
+    });
+    seams.executeAgentInBackground = vi.fn(() => {
+        steps.push('run');
+    });
+    return { resolver, seams };
+}
+
+/**
+ * A provider whose conversation details are the user's message ('user-msg-1', in conv-1) plus `others`: message ID →
+ * its conversation. A load of any other ID finds nothing, as when the caller can't read it.
+ */
+function makeContext(userMessageFound = true, others: Record<string, string> = {}): { ctx: AppContext; loads: Fn } {
+    const conversations: Record<string, string> = { ...(userMessageFound ? { 'user-msg-1': 'conv-1' } : {}), ...others };
+    const loads = vi.fn();
+    const provider = {
+        GetEntityObject: vi.fn(async () => {
+            const row = { ConversationID: '', Load: async (id: string) => false };
+            row.Load = async (id: string) => {
+                loads(id);
+                row.ConversationID = conversations[id] ?? '';
+                return id in conversations;
+            };
+            return row;
+        }),
+    };
+    const ctx = {
+        userPayload: { sessionId: 'session-1', userRecord: USER } as unknown as UserPayload,
+        providers: [{ type: 'Read-Write', provider }],
+        dataSource: {},
+    } as unknown as AppContext;
+    return { ctx, loads };
+}
+
+const pubSub = { publish: vi.fn() } as unknown as PubSubEngine;
+
+function runMutation(
+    resolver: RunAIAgentResolver,
+    ctx: AppContext,
+    fireAndForget: boolean,
+    threading: { replyParentId?: string; announcedByAgentId?: string } = {}
+) {
+    return resolver.RunAIAgentFromConversationDetail(
+        'user-msg-1', 'agent-1', ctx, 'session-1', pubSub,
+        undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined,
+        undefined, undefined, fireAndForget, undefined, undefined, undefined,
+        threading.replyParentId, threading.announcedByAgentId
+    );
+}
+
+beforeEach(() => {
+    steps = [];
+    hoisted.agents.clear();
+    hoisted.agents.set('agent-1', { ID: 'agent-1', Name: 'Research', Status: 'Active' });
+    hoisted.agents.set('manager-1', { ID: 'manager-1', Name: 'Sage', Status: 'Active' });
+    hoisted.agents.set('retired-1', { ID: 'retired-1', Name: 'Old', Status: 'Disabled' });
+    hoisted.widgetContext.mockReset().mockResolvedValue(null);
+    hoisted.createReply.mockReset().mockImplementation(async () => {
+        steps.push('reply');
+        return REPLY;
+    });
+    vi.spyOn(console, 'log').mockImplementation(() => undefined);
+});
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('RunAIAgentFromConversationDetail — the server creates the reply row', () => {
+    it("acks the reply row it created, with its ID and creation time, before the run publishes anything", async () => {
+        const { resolver, seams } = makeResolver();
+        const { ctx } = makeContext();
+
+        const result = await runMutation(resolver, ctx, true);
+
+        expect(result.success).toBe(true);
+        expect(JSON.parse(result.result)).toEqual({
+            accepted: true,
+            fireAndForget: true,
+            conversationDetailId: 'reply-1',
+            createdAt: CREATED_AT.toISOString(),
+        });
+        // History first (so it never holds the empty reply), then the reply row, then the run.
+        expect(steps).toEqual(['history', 'reply', 'run']);
+    });
+
+    it("creates the reply as the person asking, answering their message, for the agent that runs", async () => {
+        const { resolver } = makeResolver();
+        const { ctx } = makeContext();
+
+        await runMutation(resolver, ctx, true);
+
+        expect(hoisted.createReply).toHaveBeenCalledOnce();
+        expect(hoisted.createReply.mock.calls[0][0]).toMatchObject({
+            conversationId: 'conv-1',
+            agentId: 'agent-1',
+            contextUser: USER,
+            parentId: 'user-msg-1',
+        });
+    });
+
+    it('runs the agent into that row on both paths: its ID and the row itself reach the run', async () => {
+        const background = makeResolver();
+        await runMutation(background.resolver, makeContext().ctx, true);
+        const bgArgs = background.seams.executeAgentInBackground.mock.calls[0];
+        expect(bgArgs[12]).toBe('reply-1');
+        expect(bgArgs.at(-1)).toBe(REPLY);
+
+        const sync = makeResolver();
+        await runMutation(sync.resolver, makeContext().ctx, false);
+        const syncArgs = sync.seams.executeAIAgent.mock.calls[0];
+        expect(syncArgs[13]).toBe('reply-1');
+        expect(syncArgs.at(-1)).toBe(REPLY);
+    });
+
+    it('hands agentResponseDetail through the real executeAIAgent into RunAgentInConversation', async () => {
+        const resolver = new RunAIAgentResolver();
+        const seams = resolver as unknown as ResolverSeams;
+        seams.validateAgent = vi.fn().mockResolvedValue({ ID: 'agent-1', Name: 'Research' });
+        seams.persistInFlightAgentFailure = vi.fn().mockResolvedValue(undefined);
+        hoisted.runAgentInConversation.mockReset().mockRejectedValue(new Error('stop here'));
+        vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+        const execute = (resolver as unknown as { executeAIAgent(...args: unknown[]): Promise<unknown> }).executeAIAgent.bind(resolver);
+        const userPayload = { sessionId: 'session-1', userRecord: USER };
+        await execute(
+            {}, {}, 'agent-1', userPayload, '[{"role":"user","content":"hi"}]', 'session-1', pubSub,
+            undefined, undefined, undefined, undefined, undefined, undefined, 'reply-1', false, false,
+            undefined, undefined, 'conv-1', undefined, undefined, undefined, undefined, undefined,
+            false, null, REPLY
+        );
+
+        expect(hoisted.runAgentInConversation).toHaveBeenCalledOnce();
+        expect(hoisted.runAgentInConversation.mock.calls[0][1]).toMatchObject({
+            conversationDetailId: 'reply-1',
+            agentResponseDetail: REPLY,
+        });
+    });
+
+    it('hands agentResponseDetail through the real executeAgentInBackground into executeAIAgent', async () => {
+        const { resolver, seams } = makeResolver();
+        seams.executeAgentInBackground = (
+            RunAIAgentResolver.prototype as unknown as { executeAgentInBackground: ResolverSeams['executeAgentInBackground'] }
+        ).executeAgentInBackground.bind(resolver);
+
+        await runMutation(resolver, makeContext().ctx, true);
+
+        expect(seams.executeAIAgent).toHaveBeenCalledOnce();
+        const bgToExecArgs = seams.executeAIAgent.mock.calls[0];
+        expect(bgToExecArgs[13]).toBe('reply-1');
+        expect(bgToExecArgs.at(-1)).toBe(REPLY);
+    });
+
+    it("loads the user's message as the caller, and creates nothing when they can't read it", async () => {
+        const { resolver, seams } = makeResolver();
+        const { ctx, loads } = makeContext(false);
+        vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+        const result = await runMutation(resolver, ctx, true);
+
+        expect(loads).toHaveBeenCalledWith('user-msg-1');
+        expect(result.success).toBe(false);
+        expect(result.errorMessage).toContain('user-msg-1');
+        expect(hoisted.createReply).not.toHaveBeenCalled();
+        expect(seams.executeAgentInBackground).not.toHaveBeenCalled();
+    });
+
+    it('fails the request with the reason when the reply row is refused, and starts no run', async () => {
+        const { resolver, seams } = makeResolver();
+        hoisted.createReply.mockRejectedValue(new Error('Failed to create agent response conversation detail: You have view-only access to this conversation.'));
+        vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+        const result = await runMutation(resolver, makeContext().ctx, true);
+
+        expect(result.success).toBe(false);
+        expect(result.errorMessage).toContain('view-only access');
+        expect(seams.executeAgentInBackground).not.toHaveBeenCalled();
+    });
+
+    it("writes a widget guest's reply as the guest, while the agent runs under the elevated principal", async () => {
+        hoisted.widgetContext.mockResolvedValue({ ElevatedUser: SYSTEM, PinnedAgentId: 'pinned-agent' });
+        const { resolver, seams } = makeResolver();
+
+        await runMutation(resolver, makeContext().ctx, true);
+
+        expect(hoisted.createReply.mock.calls[0][0]).toMatchObject({ contextUser: USER, agentId: 'pinned-agent' });
+        const runPayload = seams.executeAgentInBackground.mock.calls[0][3] as { userRecord: unknown };
+        expect(runPayload.userRecord).toBe(SYSTEM);
+    });
+});
+
+describe('RunAIAgentFromConversationDetail — where the reply sits', () => {
+    it("threads the reply under a message of the same conversation the caller names", async () => {
+        const { resolver } = makeResolver();
+
+        const result = await runMutation(resolver, makeContext(true, { 'manager-reply-1': 'conv-1' }).ctx, true, { replyParentId: 'manager-reply-1' });
+
+        expect(result.success).toBe(true);
+        expect(hoisted.createReply.mock.calls[0][0]).toMatchObject({ parentId: 'manager-reply-1' });
+    });
+
+    it('refuses a parent from another conversation, or one the caller cannot read, and creates nothing', async () => {
+        vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        for (const parent of ['elsewhere-1', 'hidden-1']) {
+            const { resolver, seams } = makeResolver();
+            hoisted.createReply.mockClear();
+
+            const result = await runMutation(resolver, makeContext(true, { 'elsewhere-1': 'conv-2' }).ctx, true, { replyParentId: parent });
+
+            expect(result.success).toBe(false);
+            expect(result.errorMessage).toContain(parent);
+            expect(hoisted.createReply).not.toHaveBeenCalled();
+            expect(seams.executeAgentInBackground).not.toHaveBeenCalled();
+        }
+    });
+
+    it("posts the announcing agent's fixed line first, threads the reply under it, and names it in the ack", async () => {
+        const { resolver, seams } = makeResolver();
+        hoisted.createReply.mockImplementation(async (args: { message?: string }) => (
+            args.message ? { ID: 'announcement-1', ConversationID: 'conv-1', __mj_CreatedAt: CREATED_AT } : REPLY
+        ));
+
+        const result = await runMutation(resolver, makeContext().ctx, true, { announcedByAgentId: 'manager-1' });
+
+        expect(seams.CheckAPIKeyScopeAuthorization).toHaveBeenCalledWith('agent:execute', 'manager-1', expect.anything());
+        expect(hoisted.createReply.mock.calls[0][0]).toMatchObject({
+            agentId: 'manager-1',
+            contextUser: USER,
+            parentId: 'user-msg-1',
+            message: 'Continuing with **Research** for refinement...',
+            status: 'Complete',
+        });
+        expect(hoisted.createReply.mock.calls[1][0]).toMatchObject({ agentId: 'agent-1', parentId: 'announcement-1' });
+        expect(JSON.parse(result.result)).toMatchObject({ conversationDetailId: 'reply-1', announcementDetailId: 'announcement-1' });
+    });
+
+    it('ignores announcedByAgentId when elevated under a widget guest token', async () => {
+        hoisted.widgetContext.mockResolvedValue({ ElevatedUser: SYSTEM, PinnedAgentId: 'pinned-agent' });
+        const { resolver } = makeResolver();
+
+        const result = await runMutation(resolver, makeContext().ctx, true, { announcedByAgentId: 'manager-1' });
+
+        expect(result.success).toBe(true);
+        expect(hoisted.createReply).toHaveBeenCalledOnce();
+        expect(hoisted.createReply.mock.calls[0][0]).toMatchObject({ agentId: 'pinned-agent', parentId: 'user-msg-1' });
+        expect(JSON.parse(result.result)).not.toHaveProperty('announcementDetailId');
+    });
+
+    it('refuses an announcement by an agent that is not active, and creates nothing', async () => {
+        const { resolver } = makeResolver();
+        vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+        const result = await runMutation(resolver, makeContext().ctx, true, { announcedByAgentId: 'retired-1' });
+
+        expect(result.success).toBe(false);
+        expect(hoisted.createReply).not.toHaveBeenCalled();
+    });
+
+    it('without threading, answers the user message directly and the ack names no announcement', async () => {
+        const { resolver } = makeResolver();
+
+        const result = await runMutation(resolver, makeContext().ctx, true);
+
+        expect(hoisted.createReply).toHaveBeenCalledOnce();
+        expect(hoisted.createReply.mock.calls[0][0]).toMatchObject({ parentId: 'user-msg-1' });
+        expect(JSON.parse(result.result)).not.toHaveProperty('announcementDetailId');
+    });
+});

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

@@ -29,6 +29,9 @@ vi.mock('@memberjunction/ai-agents', () => ({
         RunAgentInConversation() {
             return Promise.resolve({ agentResult: { success: true } });
         }
+        CreateAgentReplyDetail() {
+            return Promise.resolve({ ID: 'reply-1', __mj_CreatedAt: new Date() }); // the server creates the reply row (A19)
+        }
     },
     ArtifactToolManager: class {},
 }));
@@ -140,7 +143,7 @@ describe('RunAIAgentFromConversationDetail — continuing from a user-stopped ru
         expect(args[BG_AUTO]).toBe(true);
     });
 
-    it('looks up the predecessor on the branch the reply row was created on', async () => {
+    it('looks up the predecessor on the branch the person\'s message was posted on', async () => {
         await runMutation(resolver, { branchId: 'B' });
         expect(seams.findUserStoppedPredecessorRunId).toHaveBeenCalledWith('conv-1', 'agent-1', 'B', expect.anything(), expect.anything());
         await runMutation(resolver, {});

package/src/__tests__/RunTemplateResolver.test.ts

@@ -7,7 +7,7 @@ import 'reflect-metadata';
  * magic-link and widget sessions, so the resolver applies its own rule. These tests pin that it
  * refuses scope-limited sessions and callers who cannot read templates before it loads anything.
  */
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, afterEach } from 'vitest';
 
 // As in RunDecisionResolver.test.ts: vitest's esbuild transform does not apply
 // `emitDecoratorMetadata`, so the decorators are no-ops and the resolver runs as a plain class.
@@ -29,7 +29,8 @@ vi.mock('type-graphql', () => {
   };
 });
 
-import { EntityInfo, UserInfo, UserRoleInfo } from '@memberjunction/core';
+import { EntityInfo, RunView, UserInfo, UserRoleInfo } from '@memberjunction/core';
+import { TemplateEngineServer } from '@memberjunction/templates';
 import { RunTemplateResolver } from '../resolvers/RunTemplateResolver.js';
 import type { AppContext, UserPayload } from '../types.js';
 
@@ -130,3 +131,35 @@ describe('RunTemplate authorization', () => {
     expect(provider.EntityObjectRequests).toEqual(['MJ: Templates']);
   });
 });
+
+/** Metadata plus a template that loads, so the resolver reaches the render. */
+class RenderingProvider {
+  public readonly Template = { Load: async () => true, IsSaved: true, Name: 'T' };
+  constructor(private readonly entities: EntityInfo[]) {}
+  public EntityByName(name: string): EntityInfo | undefined {
+    return this.entities.find((e) => e.Name.trim().toLowerCase() === name.trim().toLowerCase());
+  }
+  public async GetEntityObject(): Promise<object> {
+    return this.Template;
+  }
+}
+
+describe('RunTemplate render user', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('REGRESSION: renders as the calling user, not whoever last configured the engine', async () => {
+    const provider = new RenderingProvider(readableEverywhere());
+    const content = { ID: 'content-1', TemplateText: 'x' };
+    vi.spyOn(RunView, 'FromMetadataProvider').mockReturnValue({
+      RunView: async () => ({ Success: true, Results: [content] }),
+    } as unknown as RunView);
+    vi.spyOn(TemplateEngineServer.Instance, 'Config').mockResolvedValue(undefined);
+    const render = vi.spyOn(TemplateEngineServer.Instance, 'RenderTemplate').mockResolvedValue({ Success: true, Output: 'ok', Message: undefined });
+    const caller = makeUser([UI_ROLE_ID]);
+
+    const result = await new RunTemplateResolver().RunTemplate(TEMPLATE_ID, contextFor(caller, provider as unknown as FakeProvider));
+
+    expect(result).toMatchObject({ success: true, output: 'ok' });
+    expect(render.mock.calls[0][5]).toEqual({ ContextUser: caller });
+  });
+});

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

@@ -60,4 +60,15 @@ describe('RunViewsWithCacheCheck resolver — param forwarding', () => {
         expect(forwarded.DataSource).toBe('Materialized');
         expect(forwarded.Aggregates).toEqual([{ expression: 'COUNT(*)', alias: 'total' }]);
     });
+
+    it('forwards AlternateBaseView (including empty-string override) and leaves it undefined when unset', async () => {
+        const withNamed = await forwardedParams({ EntityName: 'Customers', AlternateBaseView: 'Active Customers' });
+        expect(withNamed.AlternateBaseView).toBe('Active Customers');
+
+        const withEmptyOverride = await forwardedParams({ EntityName: 'Customers', AlternateBaseView: '' });
+        expect(withEmptyOverride.AlternateBaseView).toBe('');
+
+        const unset = await forwardedParams({ EntityName: 'Customers' });
+        expect(unset.AlternateBaseView).toBeUndefined();
+    });
 });

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);
+    });
+});