@memberjunction/server 6.2.0-edge.2 → 6.2.0-edge.3

package/src/__tests__/ResolverBase.adhocReadScope.test.ts

@@ -0,0 +1,96 @@
+// ResolverBase transitively pulls in type-graphql decorators, which need the
+// Reflect.metadata polyfill at import time.
+import 'reflect-metadata';
+import { describe, it, expect } from 'vitest';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { ResolverBase } from '../generic/ResolverBase.js';
+
+/**
+ * The ad-hoc SQL screen (`assertFullQueryUsesReadableEntityViews`) admits a table reference
+ * only when it resolves to an entity base view the caller can read UNSCOPED. These tests pin
+ * the three ways that resolution was looser than it looked (PR #4782 review):
+ *
+ * - a schema-qualified reference fell back to a bare-name match in another schema;
+ * - an unqualified name present in two schemas resolved to whichever loaded last;
+ * - entity CanRead was treated as unscoped read authority, though raw SQL applies neither the
+ *   row-level filter nor the denied-field projection RunView does.
+ */
+
+type EntityShape = {
+    Name: string;
+    SchemaName: string;
+    BaseView: string;
+    canRead?: boolean;
+    rowFilter?: string;
+    deniedFields?: string[];
+};
+
+function fakeProvider(entities: EntityShape[]): IMetadataProvider {
+    return {
+        Entities: entities.map((e) => ({
+            Name: e.Name,
+            SchemaName: e.SchemaName,
+            BaseView: e.BaseView,
+            GetUserPermisions: () => ({ CanRead: e.canRead ?? true }),
+            GetEffectiveRowFilterWhereClause: () => e.rowFilter ?? '',
+            GetDeniedReadFields: () => new Set(e.deniedFields ?? []),
+        })),
+    } as unknown as IMetadataProvider;
+}
+
+const USER = { ID: 'U1', Email: 'u@example.com' } as unknown as UserInfo;
+
+class Probe extends ResolverBase {
+    public Screen(sql: string, provider: IMetadataProvider, user: UserInfo | undefined = USER) {
+        return this.assertFullQueryUsesReadableEntityViews(sql, provider, user, 'ad-hoc SQL');
+    }
+}
+
+const PUBLIC_FOO: EntityShape = { Name: 'Public Foo', SchemaName: 'public', BaseView: 'vwFoo' };
+
+describe('assertFullQueryUsesReadableEntityViews', () => {
+    it('admits an unscoped readable base view', () => {
+        expect(() => new Probe().Screen('SELECT ID FROM [public].[vwFoo]', fakeProvider([PUBLIC_FOO]))).not.toThrow();
+    });
+
+    it('does not resolve a schema-qualified reference through another schema', () => {
+        expect(() => new Probe().Screen('SELECT ID FROM secret.vwFoo', fakeProvider([PUBLIC_FOO]))).toThrow(
+            /entity base view, not 'secret.vwFoo'/,
+        );
+    });
+
+    it('refuses an unqualified view name that exists in more than one schema', () => {
+        const provider = fakeProvider([PUBLIC_FOO, { Name: 'Other Foo', SchemaName: 'other', BaseView: 'vwFoo' }]);
+        expect(() => new Probe().Screen('SELECT ID FROM vwFoo', provider)).toThrow(/more than one schema/);
+        expect(() => new Probe().Screen('SELECT ID FROM other.vwFoo', provider)).not.toThrow();
+    });
+
+    it('refuses an entity the caller cannot read', () => {
+        expect(() => new Probe().Screen('SELECT ID FROM public.vwFoo', fakeProvider([{ ...PUBLIC_FOO, canRead: false }]))).toThrow(
+            /read permission/,
+        );
+    });
+
+    it('refuses an entity that is row-level-security filtered for the caller', () => {
+        const provider = fakeProvider([{ ...PUBLIC_FOO, rowFilter: "(UserID = 'U1')" }]);
+        expect(() => new Probe().Screen('SELECT ID, UserID FROM public.vwFoo', provider)).toThrow(/row-level-security/);
+    });
+
+    it('refuses an entity with a field the caller is denied', () => {
+        const provider = fakeProvider([{ ...PUBLIC_FOO, deniedFields: ['secret'] }]);
+        expect(() => new Probe().Screen('SELECT ID FROM public.vwFoo', provider)).toThrow(/not permitted to read/);
+    });
+
+    it('applies the scope check to every reference, including joins and subqueries', () => {
+        const provider = fakeProvider([PUBLIC_FOO, { Name: 'Bar', SchemaName: 'public', BaseView: 'vwBar', rowFilter: '(1=0)' }]);
+        expect(() =>
+            new Probe().Screen('SELECT f.ID FROM public.vwFoo f WHERE f.ID IN (SELECT FooID FROM public.vwBar)', provider),
+        ).toThrow(/'Bar' is row-level-security filtered/);
+    });
+
+    it('exempts CTE names the statement defines', () => {
+        expect(() =>
+            new Probe().Screen('WITH x AS (SELECT ID FROM public.vwFoo) SELECT ID FROM x', fakeProvider([PUBLIC_FOO])),
+        ).not.toThrow();
+    });
+});

package/src/__tests__/ResolverBase.filterEscaping.test.ts

@@ -33,7 +33,13 @@ type Captured = { params: RunViewParams | null };
  * its params. `Sequence` stands in for a numeric field (`NeedsQuotes` is false only for
  * Number and Boolean TS types).
  */
-function fakeProvider(captured: Captured, rows: Record<string, unknown>[] = []): DatabaseProviderBase {
+function fakeProvider(captured: Captured, rows: Record<string, unknown>[] = [], unreadableEntities: string[] = []): DatabaseProviderBase {
+    const withPerms = (e: Record<string, unknown>) => ({
+        ...e,
+        // Real EntityInfo aggregates per-user permissions; the boundary screen now consults
+        // CanRead for every subquery target, so the mock must answer it.
+        GetUserPermisions: () => ({ CanRead: !unreadableEntities.includes(e.Name as string) }),
+    });
     return {
         Entities: [
             {
@@ -67,7 +73,7 @@ function fakeProvider(captured: Captured, rows: Record<string, unknown>[] = []):
             { Name: 'Committees: Motions', SchemaName: '__mj_BizAppsCommittees', BaseView: 'vwMotions', BaseTable: 'Motion', Fields: [] },
             { Name: 'Committees: Memberships', SchemaName: '__mj_BizAppsCommittees', BaseView: 'vwMemberships', BaseTable: 'Membership', Fields: [] },
             { Name: 'Committees: Terms', SchemaName: '__mj_BizAppsCommittees', BaseView: 'vwTerms', BaseTable: 'Term', Fields: [] },
-        ],
+        ].map(withPerms),
         RunView: async (params: RunViewParams): Promise<RunViewResult> => {
             captured.params = params;
             return { Success: true, Results: rows, RowCount: rows.length, TotalRowCount: rows.length, ErrorMessage: '' } as RunViewResult;
@@ -246,6 +252,19 @@ describe('ResolverBase — GraphQL-boundary ExtraFilter AST screen', () => {
         expect(captured.params?.ExtraFilter).toBe(`ID IN (SELECT ID FROM [__mj].[vwUsers] WHERE Email = 'a@b.com')`);
     });
 
+    it('RunDynamicViewGeneric rejects a subquery into an entity the caller cannot read', async () => {
+        const captured: Captured = { params: null };
+        const input = {
+            EntityName: ENTITY_NAME,
+            ExtraFilter: `ID IN (SELECT TaskID FROM [__mj_BizAppsTasks].[vwTaskAssignments])`,
+        } as RunDynamicViewInput;
+
+        await expect(
+            new Probe().RunDynamic(input, fakeProvider(captured, [], ['MJ_BizApps_Tasks: Task Assignments']))
+        ).rejects.toThrow(/read permission/);
+        expect(captured.params).toBeNull();
+    });
+
     it('RunDynamicViewGeneric passes a benign ExtraFilter through to RunView', async () => {
         const captured: Captured = { params: null };
         const input = {

package/src/__tests__/ResolverBase.includeBinaryFields.test.ts

@@ -0,0 +1,291 @@
+// ResolverBase / RunViewResolver transitively pull in type-graphql decorators, which need the
+// Reflect.metadata polyfill at import time.
+import 'reflect-metadata';
+import { describe, it, expect } from 'vitest';
+import type {
+    DatabaseProviderBase,
+    EntityInfo,
+    IMetadataProvider,
+    RunViewParams,
+    RunViewResult,
+    RunViewWithCacheCheckParams,
+    RunViewsWithCacheCheckResponse,
+    UserInfo,
+} from '@memberjunction/core';
+import type { MJUserViewEntityExtended } from '@memberjunction/core-entities';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import {
+    RunViewResolver,
+    type RunDynamicViewInput,
+    type RunViewByIDInput,
+    type RunViewByNameInput,
+    type RunViewResultRow,
+    type RunViewWithCacheCheckInput,
+} from '../generic/RunViewResolver.js';
+import type { AppContext, UserPayload } from '../types.js';
+
+/**
+ * Binary DB fields (varbinary / bytea) are base64 strings in JS and on the wire, and RunView
+ * omits them unless `IncludeBinaryFields: true`. These tests pin the server half:
+ *
+ *   1. the GraphQL flag reaches the provider's RunView / RunViews / RunViewsWithCacheCheck params
+ *      on every resolver path (single by-ID / by-name / dynamic, batch, and the cache-check batch);
+ *   2. any byte array that still reaches a resolver is serialized as base64 — never as the
+ *      `{"type":"Buffer","data":[...]}` that `JSON.stringify` produces for a Node Buffer.
+ */
+
+const ENTITY_NAME = 'MJ: Vector Things';
+const ENTITY_ID = 'ent-1';
+
+/** Bytes whose base64 form is easy to recognise: [1,2,3,4] → "AQIDBA==". */
+const BYTES = [1, 2, 3, 4];
+const BYTES_BASE64 = 'AQIDBA==';
+
+const fakePayload = () =>
+    ({ email: 'tester@example.com', userRecord: { Email: 'tester@example.com' } as UserInfo } as UserPayload);
+
+function entityStub() {
+    return {
+        ID: ENTITY_ID,
+        Name: ENTITY_NAME,
+        BaseView: 'vwVectorThings',
+        PrimaryKeys: [{ Name: 'ID' }],
+        Fields: [
+            { Name: 'ID', CodeName: 'ID' },
+            { Name: 'Embedding', CodeName: 'Embedding' },
+        ],
+        EncryptedFields: [],
+    };
+}
+
+/** Provider that records every RunView / RunViews call and returns the given rows. */
+function recordingProvider(rows: Record<string, unknown>[] = []) {
+    const runViewCalls: RunViewParams[] = [];
+    const runViewsCalls: RunViewParams[][] = [];
+    const viewInfo = { ID: 'view-1', Name: 'Saved View', Entity: ENTITY_NAME, EntityID: ENTITY_ID };
+    const provider = {
+        Entities: [entityStub()],
+        EntityByName: (name: string) => (name === ENTITY_NAME ? entityStub() : undefined),
+        RunView: async (params: RunViewParams): Promise<RunViewResult> => {
+            // RunViewByNameGeneric looks the saved view up first — answer that lookup with the view row.
+            if (params.EntityName === 'MJ: User Views') {
+                return { Success: true, Results: [viewInfo], RowCount: 1, TotalRowCount: 1, ErrorMessage: '' } as RunViewResult;
+            }
+            runViewCalls.push(params);
+            return { Success: true, Results: rows, RowCount: rows.length, TotalRowCount: rows.length, ErrorMessage: '' } as RunViewResult;
+        },
+        RunViews: async (params: RunViewParams[]): Promise<RunViewResult[]> => {
+            runViewsCalls.push(params);
+            return params.map(() => ({ Success: true, Results: rows, RowCount: rows.length, TotalRowCount: rows.length, ErrorMessage: '' } as RunViewResult));
+        },
+        GetEntityObject: async () => ({ ...viewInfo, Load: async () => true }),
+    } as unknown as DatabaseProviderBase;
+    return { provider, runViewCalls, runViewsCalls };
+}
+
+/** Skips the encrypted-field filter (it needs live Metadata) — irrelevant to these assertions. */
+class Probe extends ResolverBase {
+    protected override async ArrayFilterEncryptedFieldsForAPI(
+        _entityName: string,
+        dataObjectArray: Record<string, unknown>[]
+    ): Promise<Record<string, unknown>[]> {
+        return dataObjectArray;
+    }
+
+    public MapOne(entityName: string, row: unknown, provider: IMetadataProvider) {
+        return this.MapFieldNamesToCodeNames(entityName, row, undefined, provider);
+    }
+}
+
+describe('IncludeBinaryFields forwarding — single-view resolver paths', () => {
+    it('RunDynamicViewGeneric forwards IncludeBinaryFields: true to provider.RunView', async () => {
+        const { provider, runViewCalls } = recordingProvider();
+        await new Probe().RunDynamicViewGeneric(
+            { EntityName: ENTITY_NAME, ExtraFilter: '', OrderBy: '', IncludeBinaryFields: true } as RunDynamicViewInput,
+            provider, fakePayload(), undefined as never,
+        );
+
+        expect(runViewCalls).toHaveLength(1);
+        expect(runViewCalls[0].IncludeBinaryFields).toBe(true);
+    });
+
+    it('RunDynamicViewGeneric leaves IncludeBinaryFields undefined when the caller did not set it', async () => {
+        const { provider, runViewCalls } = recordingProvider();
+        await new Probe().RunDynamicViewGeneric(
+            { EntityName: ENTITY_NAME, ExtraFilter: '', OrderBy: '' } as RunDynamicViewInput,
+            provider, fakePayload(), undefined as never,
+        );
+
+        expect(runViewCalls).toHaveLength(1);
+        expect(runViewCalls[0].IncludeBinaryFields).toBeUndefined();
+    });
+
+    it('RunViewByNameGeneric forwards IncludeBinaryFields to provider.RunView', async () => {
+        const { provider, runViewCalls } = recordingProvider();
+        await new Probe().RunViewByNameGeneric(
+            { ViewName: 'Saved View', ExtraFilter: '', OrderBy: '', IncludeBinaryFields: true } as RunViewByNameInput,
+            provider, fakePayload(), undefined as never,
+        );
+
+        expect(runViewCalls).toHaveLength(1);
+        expect(runViewCalls[0].EntityName).toBe(ENTITY_NAME);
+        expect(runViewCalls[0].IncludeBinaryFields).toBe(true);
+    });
+
+    it('RunViewByIDGeneric forwards IncludeBinaryFields to provider.RunView', async () => {
+        const { provider, runViewCalls } = recordingProvider();
+        await new Probe().RunViewByIDGeneric(
+            { ViewID: 'view-1', ExtraFilter: '', OrderBy: '', IncludeBinaryFields: false } as RunViewByIDInput,
+            provider, fakePayload(), undefined as never,
+        );
+
+        expect(runViewCalls).toHaveLength(1);
+        expect(runViewCalls[0].IncludeBinaryFields).toBe(false);
+    });
+
+    it('RunViewGenericInternal passes binary values through as the provider returned them (base64 strings)', async () => {
+        const { provider } = recordingProvider([{ ID: 'r1', Embedding: BYTES_BASE64 }]);
+        const result = await new Probe().RunDynamicViewGeneric(
+            { EntityName: ENTITY_NAME, ExtraFilter: '', OrderBy: '', IncludeBinaryFields: true } as RunDynamicViewInput,
+            provider, fakePayload(), undefined as never,
+        );
+
+        expect((result?.Results as Record<string, unknown>[])[0].Embedding).toBe(BYTES_BASE64);
+    });
+});
+
+describe('IncludeBinaryFields forwarding — batch resolver path', () => {
+    it('RunViewsGeneric → RunViewsGenericInternal forwards the per-view flag to provider.RunViews', async () => {
+        const { provider, runViewsCalls } = recordingProvider();
+        const inputs = [
+            { EntityName: ENTITY_NAME, ExtraFilter: '', OrderBy: '', IncludeBinaryFields: true },
+            { EntityName: ENTITY_NAME, ExtraFilter: '', OrderBy: '' },
+        ] as (RunViewByNameInput & RunViewByIDInput & RunDynamicViewInput)[];
+
+        await new Probe().RunViewsGeneric(inputs, provider, fakePayload());
+
+        expect(runViewsCalls).toHaveLength(1);
+        expect(runViewsCalls[0]).toHaveLength(2);
+        expect(runViewsCalls[0][0].IncludeBinaryFields).toBe(true);
+        expect(runViewsCalls[0][1].IncludeBinaryFields).toBeUndefined();
+    });
+});
+
+describe('MapFieldNamesToCodeNames — byte arrays become base64', () => {
+    const provider = {
+        EntityByName: (name: string) => (name === ENTITY_NAME ? (entityStub() as unknown as EntityInfo) : undefined),
+    } as unknown as IMetadataProvider;
+
+    it('converts a Buffer value to its base64 string', async () => {
+        const mapped = (await new Probe().MapOne(ENTITY_NAME, { ID: 'r1', Embedding: Buffer.from(BYTES) }, provider)) as Record<string, unknown>;
+
+        expect(mapped.Embedding).toBe(BYTES_BASE64);
+        expect(mapped.ID).toBe('r1');
+    });
+
+    it('converts a plain Uint8Array value too', async () => {
+        const mapped = (await new Probe().MapOne(ENTITY_NAME, { ID: 'r1', Embedding: new Uint8Array(BYTES) }, provider)) as Record<string, unknown>;
+
+        expect(mapped.Embedding).toBe(BYTES_BASE64);
+    });
+
+    it('leaves an already-base64 string untouched', async () => {
+        const mapped = (await new Probe().MapOne(ENTITY_NAME, { ID: 'r1', Embedding: BYTES_BASE64 }, provider)) as Record<string, unknown>;
+
+        expect(mapped.Embedding).toBe(BYTES_BASE64);
+    });
+
+    it('does not mutate the caller\'s row (it may be a frozen cache entry)', async () => {
+        const buffer = Buffer.from(BYTES);
+        const source = Object.freeze({ ID: 'r1', Embedding: buffer }) as Record<string, unknown>;
+
+        const mapped = (await new Probe().MapOne(ENTITY_NAME, source, provider)) as Record<string, unknown>;
+
+        expect(mapped.Embedding).toBe(BYTES_BASE64);
+        expect(source.Embedding).toBe(buffer);
+    });
+});
+
+/** Exposes the protected serializer. */
+class ResolverProbe extends RunViewResolver {
+    public Process(rows: Record<string, unknown>[]): RunViewResultRow[] {
+        return this.processRawData(rows, ENTITY_ID, entityStub() as unknown as EntityInfo);
+    }
+}
+
+describe('RunViewResolver.processRawData — Buffer → base64 in the Data JSON', () => {
+    it('serializes a Buffer value as base64, not {type:"Buffer",data:[...]}', () => {
+        const [row] = new ResolverProbe().Process([{ ID: 'r1', Embedding: Buffer.from(BYTES) }]);
+        const data = JSON.parse(row.Data) as Record<string, unknown>;
+
+        expect(data.Embedding).toBe(BYTES_BASE64);
+        expect(row.Data).not.toContain('"type":"Buffer"');
+        expect(row.PrimaryKey).toEqual([{ FieldName: 'ID', Value: 'r1' }]);
+        expect(row.EntityID).toBe(ENTITY_ID);
+    });
+
+    it('serializes a Uint8Array value as base64 (not an index-keyed object)', () => {
+        const [row] = new ResolverProbe().Process([{ ID: 'r1', Embedding: new Uint8Array(BYTES) }]);
+
+        expect((JSON.parse(row.Data) as Record<string, unknown>).Embedding).toBe(BYTES_BASE64);
+    });
+
+    it('leaves rows without byte arrays serialized exactly as before', () => {
+        const source = { ID: 'r1', Name: 'Plain', Embedding: BYTES_BASE64, Count: 3 };
+        const [row] = new ResolverProbe().Process([source]);
+
+        expect(row.Data).toBe(JSON.stringify(source));
+    });
+
+    it('does not mutate the source row', () => {
+        const buffer = Buffer.from(BYTES);
+        const source: Record<string, unknown> = { ID: 'r1', Embedding: buffer };
+
+        new ResolverProbe().Process([source]);
+
+        expect(source.Embedding).toBe(buffer);
+    });
+});
+
+describe('RunViewResolver.RunViewsWithCacheCheck — IncludeBinaryFields + Buffer serialization', () => {
+    function cacheCheckContext(rows: Record<string, unknown>[]) {
+        const received: RunViewWithCacheCheckParams[][] = [];
+        const provider = {
+            EntityByName: (name: string) => (name === ENTITY_NAME ? entityStub() : undefined),
+            RunViewsWithCacheCheck: async (params: RunViewWithCacheCheckParams[]): Promise<RunViewsWithCacheCheckResponse> => {
+                received.push(params);
+                return {
+                    success: true,
+                    results: params.map((_p, i) => ({ viewIndex: i, status: 'stale', results: rows, maxUpdatedAt: 'T', rowCount: rows.length })),
+                } as RunViewsWithCacheCheckResponse;
+            },
+        };
+        const ctx = { providers: [{ type: 'Read-Only', provider }], userPayload: fakePayload() } as unknown as AppContext;
+        return { ctx, received };
+    }
+
+    it('forwards IncludeBinaryFields into the core params (true, false and unset)', async () => {
+        const { ctx, received } = cacheCheckContext([]);
+        const input = [
+            { params: { EntityName: ENTITY_NAME, IncludeBinaryFields: true } },
+            { params: { EntityName: ENTITY_NAME, IncludeBinaryFields: false } },
+            { params: { EntityName: ENTITY_NAME } },
+        ] as RunViewWithCacheCheckInput[];
+
+        const out = await new RunViewResolver().RunViewsWithCacheCheck(input, ctx);
+
+        expect(out.success).toBe(true);
+        expect(received).toHaveLength(1);
+        expect(received[0].map(p => p.params.IncludeBinaryFields)).toEqual([true, false, undefined]);
+    });
+
+    it('serializes Buffers in stale results as base64', async () => {
+        const { ctx } = cacheCheckContext([{ ID: 'r1', Embedding: Buffer.from(BYTES) }]);
+        const input = [{ params: { EntityName: ENTITY_NAME, IncludeBinaryFields: true } }] as RunViewWithCacheCheckInput[];
+
+        const out = await new RunViewResolver().RunViewsWithCacheCheck(input, ctx);
+        const rows = out.results[0].Results as RunViewResultRow[];
+
+        expect((JSON.parse(rows[0].Data) as Record<string, unknown>).Embedding).toBe(BYTES_BASE64);
+    });
+});

package/src/__tests__/TaskGraphActionRunner.durablePayload.test.ts

@@ -129,3 +129,44 @@ describe('TaskGraphActionRunner — durable payload round-trips by param name (#
         expect(sentParams.map((p) => p.Name).sort()).toEqual(['EntityName', 'Record']);
     });
 });
+
+/**
+ * A durable step's Output is stored on the Task row as JSON. An action that hands back an output
+ * param holding a live object (an entity, an observable) used to surface much later, from the
+ * dispatcher, as a bare "Converting circular structure to JSON" with no hint of WHICH action or
+ * param — seen live with Execute Agent's AgentResult. The runner is the boundary that knows both
+ * names, so it refuses the output there and says which param it was.
+ */
+describe('TaskGraphActionRunner: outputs must be storable', () => {
+    beforeEach(() => vi.mocked(ActionEngineServer.Instance.RunAction).mockReset());
+
+    it('fails the step, naming the action and the param, when an output param cannot be serialized', async () => {
+        const cyclic: Record<string, unknown> = { kind: 'OperatorSubscriber' };
+        cyclic.self = cyclic;
+        vi.mocked(ActionEngineServer.Instance.RunAction).mockResolvedValue({
+            Success: true,
+            Message: 'started',
+            Params: [{ Name: 'AgentRunID', Type: 'Output', Value: 'RUN-1' }, { Name: 'AgentResult', Type: 'Output', Value: cyclic }],
+            LogEntry: { ID: 'LOG-1' },
+        } as never);
+
+        const result = await new TaskGraphActionRunner().RunActionForTask(baseRunParams({}));
+
+        expect(result.Success).toBe(false);
+        expect(result.ErrorMessage).toMatch(/Log Activity.*AgentResult.*cannot be stored/i);
+        expect(result.ActionLogID).toBe('LOG-1');
+    });
+
+    it('passes plain outputs through unchanged', async () => {
+        vi.mocked(ActionEngineServer.Instance.RunAction).mockResolvedValue({
+            Success: true,
+            Message: 'ok',
+            Params: [{ Name: 'AgentRunID', Type: 'Output', Value: 'RUN-1' }],
+            LogEntry: { ID: 'LOG-2' },
+        } as never);
+
+        const result = await new TaskGraphActionRunner().RunActionForTask(baseRunParams({}));
+
+        expect(result).toMatchObject({ Success: true, Output: { AgentRunID: 'RUN-1' }, ActionLogID: 'LOG-2' });
+    });
+});

package/src/__tests__/WorkQueueHostService.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect, vi } from 'vitest';
+
+// TaskGraphProviderFactory imports config.ts (which validates DB env at module load); UserCache needs a live
+// provider. Both are replaced; the tests pass explicit dependencies.
+vi.mock('../config.js', () => ({ configInfo: {}, mj_core_schema: '__mj' }));
+vi.mock('@memberjunction/generic-database-provider', async (importOriginal) => ({
+    ...(await importOriginal<typeof import('@memberjunction/generic-database-provider')>()),
+    UserCache: { get Users() { return []; } },
+}));
+
+import type { DatabaseProviderBase, IMetadataProvider, UserInfo } from '@memberjunction/core';
+import type { WorkQueueEngine, WorkQueueHostConfig, WorkQueueProviderSource } from '@memberjunction/work-queue-engine';
+import { WorkQueueSchema } from '../services/workQueueConfig.js';
+import type { WorkQueueConfig } from '../services/workQueueConfig.js';
+import {
+    BuildWorkQueueHostConfig, CreateWorkQueueInstanceID, IsWorkQueueHostDisabledByEnv, MJServerWorkQueueProviderSource,
+    StartWorkQueueHost, WORK_QUEUE_DISABLE_ENV,
+} from '../services/WorkQueueHostService.js';
+import type { WorkQueueHostStartDependencies } from '../services/WorkQueueHostService.js';
+
+const PROVIDER = { Name: 'server-provider' } as unknown as DatabaseProviderBase;
+const SYSTEM_USER = { ID: 'AAAAAAAA-1111-4111-8111-000000000001', Email: 'system@memberjunction.org' } as UserInfo;
+const ENGINE = { Name: 'engine' } as unknown as WorkQueueEngine;
+const PROVIDER_SOURCE: WorkQueueProviderSource = { CreateProvider: async (): Promise<IMetadataProvider> => PROVIDER };
+
+interface Recorder {
+    Dependencies: WorkQueueHostStartDependencies;
+    Started: WorkQueueHostConfig[];
+    EngineCalls: number;
+}
+
+function recorder(users: UserInfo[] = [SYSTEM_USER], env: Record<string, string | undefined> = {}): Recorder {
+    const result: Recorder = {
+        Started: [],
+        EngineCalls: 0,
+        Dependencies: {
+            Env: env,
+            FindUserByEmail: email => users.find(user => user.Email === email),
+            ConfigureEngine: async (user, provider) => {
+                expect(user).toBe(SYSTEM_USER);
+                expect(provider).toBe(PROVIDER);
+                result.EngineCalls++;
+                return ENGINE;
+            },
+            CreateHost: (config, engine, user, provider, source) => {
+                expect([engine, user, provider, source]).toEqual([ENGINE, SYSTEM_USER, PROVIDER, PROVIDER_SOURCE]);
+                return { Start: async () => { result.Started.push(config); } };
+            },
+        },
+    };
+    return result;
+}
+
+function enabled(overrides: Partial<WorkQueueConfig> = {}): WorkQueueConfig {
+    return { ...WorkQueueSchema.parse({ enabled: true }), ...overrides };
+}
+
+describe('workQueue configuration', () => {
+    it('defaults to disabled, running every MJWorker subscription once enabled', () => {
+        expect(WorkQueueSchema.parse({})).toEqual({
+            enabled: false, systemUserEmail: 'system@memberjunction.org', subscriptions: [{ name: '*', concurrency: 4 }],
+            idlePollMinMs: 250, idlePollMaxMs: 5000, shutdownDrainMs: 8000, sweeperEnabled: true, sweeperIntervalMs: 60000,
+            reconcileIntervalMs: 30000,
+        });
+    });
+
+    it('rejects an idle poll maximum below the minimum', () => {
+        expect(WorkQueueSchema.safeParse({ idlePollMinMs: 1000, idlePollMaxMs: 500 }).success).toBe(false);
+    });
+});
+
+describe('host configuration helpers', () => {
+    it('maps the section to a host config and disables the sweeper when asked', () => {
+        const config = enabled({ subscriptions: [{ name: 'email.unsubscribe', concurrency: 8 }], sweeperEnabled: false });
+        expect(BuildWorkQueueHostConfig(config, 'api-1')).toEqual({
+            InstanceID: 'api-1', Subscriptions: [{ Name: 'email.unsubscribe', Concurrency: 8 }], IdlePollMinMs: 250,
+            IdlePollMaxMs: 5000, ShutdownDrainMs: 8000, SweeperIntervalMs: 0, ReconcileIntervalMs: 30000,
+        });
+    });
+
+    it('builds a unique instance ID from host, pid and random entropy', () => {
+        const first = CreateWorkQueueInstanceID({ HOSTNAME: 'api-7' });
+        expect(first).toMatch(new RegExp(`^api-7-${process.pid}-[0-9a-f]{8}$`));
+        expect(CreateWorkQueueInstanceID({ HOSTNAME: 'api-7' })).not.toBe(first);
+    });
+
+    it(`treats only ${WORK_QUEUE_DISABLE_ENV}=1 as the kill switch`, () => {
+        expect(IsWorkQueueHostDisabledByEnv({ [WORK_QUEUE_DISABLE_ENV]: '1' })).toBe(true);
+        expect(IsWorkQueueHostDisabledByEnv({ [WORK_QUEUE_DISABLE_ENV]: 'true' })).toBe(false);
+        expect(IsWorkQueueHostDisabledByEnv({})).toBe(false);
+    });
+});
+
+describe('StartWorkQueueHost', () => {
+    it('starts nothing when the section is disabled', async () => {
+        const rec = recorder();
+        expect(await StartWorkQueueHost(WorkQueueSchema.parse({}), PROVIDER, PROVIDER_SOURCE, rec.Dependencies)).toBeNull();
+        expect(rec.EngineCalls).toBe(0);
+    });
+
+    it('starts nothing when the kill switch is set', async () => {
+        const rec = recorder([SYSTEM_USER], { [WORK_QUEUE_DISABLE_ENV]: '1' });
+        expect(await StartWorkQueueHost(enabled(), PROVIDER, PROVIDER_SOURCE, rec.Dependencies)).toBeNull();
+        expect(rec.EngineCalls).toBe(0);
+    });
+
+    it('refuses to start without the system user', async () => {
+        const rec = recorder([]);
+        await expect(StartWorkQueueHost(enabled(), PROVIDER, PROVIDER_SOURCE, rec.Dependencies)).rejects.toThrow('System user not found with email: system@memberjunction.org');
+    });
+
+    it('names the setting to fix when the placeholder email from DEFAULT_SERVER_CONFIG is still in effect', async () => {
+        const rec = recorder();
+        await expect(StartWorkQueueHost(enabled({ systemUserEmail: 'not.set@nowhere.com' }), PROVIDER, PROVIDER_SOURCE, rec.Dependencies))
+            .rejects.toThrow('set workQueue.systemUserEmail');
+    });
+
+    it('configures the engine, then creates and starts the host', async () => {
+        const rec = recorder();
+        const host = await StartWorkQueueHost(enabled(), PROVIDER, PROVIDER_SOURCE, rec.Dependencies);
+        expect(host).not.toBeNull();
+        expect(rec.EngineCalls).toBe(1);
+        expect(rec.Started).toHaveLength(1);
+        expect(rec.Started[0]).toMatchObject({ Subscriptions: [{ Name: '*', Concurrency: 4 }], SweeperIntervalMs: 60000 });
+    });
+});
+
+describe('MJServerWorkQueueProviderSource', () => {
+    it('falls back to the shared server provider when there is no SQL Server pool', async () => {
+        const source = new MJServerWorkQueueProviderSource(null, PROVIDER);
+        expect(await source.CreateProvider()).toBe(PROVIDER);
+    });
+});

package/src/__tests__/adhocTimeoutClamp.test.ts

@@ -0,0 +1,26 @@
+/**
+ * An ad-hoc query's timeout never exceeds the server's requestTimeout, so a caller cannot hold a
+ * read-only connection longer than any other request may.
+ */
+import { describe, it, expect } from 'vitest';
+import { ClampAdhocTimeoutSeconds } from '../resolvers/adhocTimeout';
+
+describe('ClampAdhocTimeoutSeconds', () => {
+    it('caps a longer request at requestTimeout', () => {
+        expect(ClampAdhocTimeoutSeconds(600, 30000)).toBe(30);
+    });
+
+    it('keeps a shorter request', () => {
+        expect(ClampAdhocTimeoutSeconds(5, 30000)).toBe(5);
+    });
+
+    it('uses 30 seconds when the caller names none, within the cap', () => {
+        expect(ClampAdhocTimeoutSeconds(undefined, 30000)).toBe(30);
+        expect(ClampAdhocTimeoutSeconds(undefined, 10000)).toBe(10);
+        expect(ClampAdhocTimeoutSeconds(0, 30000)).toBe(30);
+    });
+
+    it('leaves the request alone when the server sets no limit', () => {
+        expect(ClampAdhocTimeoutSeconds(600, 0)).toBe(600);
+    });
+});