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

package/src/__tests__/EntityRecordNameResolver.rowSecurity.test.ts

@@ -0,0 +1,152 @@
+// ResolverBase transitively pulls in type-graphql decorators, which need the
+// Reflect.metadata polyfill at import time.
+import 'reflect-metadata';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { CompositeKey, DatabaseProviderBase, EntityInfo, EntityPermissionType, Metadata, RowLevelSecurityFilterInfo, UserInfo } from '@memberjunction/core';
+import type { DeleteSQLResult, IMetadataProvider, QueryExecutionSpec, RunQueryResult, SaveSQLResult } from '@memberjunction/core';
+import { EntityRecordNameResolver } from '../resolvers/EntityRecordNameResolver.js';
+import type { AppContext, UserPayload } from '../types.js';
+
+/**
+ * The record-name queries against a real provider whose database only records what it is sent.
+ * The lookup the resolver causes carries the acting user's read row filter, binds the key value,
+ * refuses a key that is not the entity's primary key, and never runs without an acting user.
+ */
+
+const CLIENTS_ID = 'E0000000-0000-0000-0000-0000000000C1';
+const ACCOUNT_MANAGER_ROLE_ID = 'B0000000-0000-0000-0000-0000000000C1';
+const OWN_CLIENTS_FILTER_ID = 'F0000000-0000-0000-0000-0000000000C1';
+const MANAGER_ID = 'C0000000-0000-0000-0000-0000000000C1';
+const CLIENT_ID_VALUE = '33333333-3333-3333-3333-333333333333';
+
+const ROW_FILTERS: RowLevelSecurityFilterInfo[] = [
+    new RowLevelSecurityFilterInfo({ ID: OWN_CLIENTS_FILTER_ID, Name: 'Own clients', FilterText: "AccountManagerID = '{{UserID}}'" }),
+];
+
+/** `Clients`: account managers read only the clients they manage. */
+function clientsEntity(): EntityInfo {
+    return new EntityInfo({
+        ID: CLIENTS_ID, Name: 'Clients', SchemaName: 'dbo', BaseTable: 'Client', BaseView: 'vwClients',
+        Permissions: [
+            { ID: 'perm-manager', EntityID: CLIENTS_ID, RoleID: ACCOUNT_MANAGER_ROLE_ID, CanRead: true, ReadRLSFilterID: OWN_CLIENTS_FILTER_ID, Type: 'Allow' },
+        ],
+        Fields: [
+            { ID: 'cl-id', EntityID: CLIENTS_ID, Sequence: 1, Name: 'ID', Type: 'uniqueidentifier', IsPrimaryKey: true, NeedsQuotes: true },
+            { ID: 'cl-name', EntityID: CLIENTS_ID, Sequence: 2, Name: 'Name', Type: 'nvarchar', IsNameField: true, NeedsQuotes: true },
+            { ID: 'cl-tier', EntityID: CLIENTS_ID, Sequence: 3, Name: 'Tier', Type: 'int', NeedsQuotes: false },
+            { ID: 'cl-manager', EntityID: CLIENTS_ID, Sequence: 4, Name: 'AccountManagerID', Type: 'uniqueidentifier', NeedsQuotes: true },
+        ],
+    });
+}
+
+interface SentQuery {
+    SQL: string;
+    Parameters: unknown[] | undefined;
+}
+
+/** A SQL Server-shaped provider over `Clients`, whose database answers every query with one row. */
+class RecordingProvider extends DatabaseProviderBase {
+    public Sent: SentQuery[] = [];
+    private readonly entities = [clientsEntity()];
+
+    public override get Entities(): EntityInfo[] {
+        return this.entities;
+    }
+
+    public override get RowLevelSecurityFilters(): RowLevelSecurityFilterInfo[] {
+        return ROW_FILTERS;
+    }
+
+    async ExecuteSQL<T>(sql: string, parameters?: unknown[]): Promise<Array<T>> {
+        this.Sent.push({ SQL: sql, Parameters: parameters });
+        return [{ Name: 'Acme Manufacturing' }] as T[];
+    }
+
+    public override BuildParameterPlaceholder(index: number): string { return `@p${index}`; }
+    protected get UUIDFunctionPattern(): RegExp { return /^newid\(\)$/i; }
+    protected get DBDefaultFunctionPattern(): RegExp { return /^getdate\(\)$/i; }
+    public QuoteIdentifier(name: string): string { return `[${name}]`; }
+    public QuoteSchemaAndView(schema: string, obj: string): string { return `[${schema}].[${obj}]`; }
+    protected BuildChildDiscoverySQL(): string { return ''; }
+    protected BuildHardLinkDependencySQL(): string { return ''; }
+    protected BuildSoftLinkDependencySQL(): string { return ''; }
+    protected async GenerateSaveSQL(): Promise<SaveSQLResult> { return { fullSQL: '' }; }
+    protected GenerateDeleteSQL(): DeleteSQLResult { return { fullSQL: '' }; }
+    protected BuildRecordChangeSQL(): { sql: string; parameters?: unknown[] } | null { return null; }
+    protected BuildSiblingRecordChangeSQL(): string { return ''; }
+    async BeginTransaction(): Promise<void> {}
+    async CommitTransaction(): Promise<void> {}
+    async RollbackTransaction(): Promise<void> {}
+    protected async InternalExecuteQueryFromSpec(_spec: QueryExecutionSpec): Promise<RunQueryResult> {
+        throw new Error('Not supported.');
+    }
+}
+
+const MANAGER = new UserInfo(null, {
+    ID: MANAGER_ID, Name: 'Morgan', Email: 'morgan@example.com', IsActive: true,
+    UserRoles: [{ UserID: MANAGER_ID, RoleID: ACCOUNT_MANAGER_ROLE_ID, Role: 'Account Managers' }],
+});
+
+function key(fieldName: string, value: string): CompositeKey {
+    return new CompositeKey([{ FieldName: fieldName, Value: value }]);
+}
+
+describe('EntityRecordNameResolver lookups under row-level security', () => {
+    let provider: RecordingProvider;
+    let savedProvider: IMetadataProvider;
+    let context: AppContext;
+    const resolver = new EntityRecordNameResolver();
+
+    beforeEach(() => {
+        provider = new RecordingProvider();
+        // Row filters resolve through the global provider.
+        savedProvider = Metadata.Provider;
+        Metadata.Provider = provider;
+        const userPayload: UserPayload = { email: MANAGER.Email, userRecord: MANAGER, sessionId: 'session-1' };
+        context = { dataSource: undefined, dataSources: [], providers: [{ provider, type: 'Read-Only' }], userPayload };
+    });
+
+    afterEach(() => {
+        Metadata.Provider = savedProvider;
+    });
+
+    function managerRowFilter(): string {
+        return provider.EntityByName('Clients').GetEffectiveRowFilterWhereClause(MANAGER, EntityPermissionType.Read, '');
+    }
+
+    it("looks the name up under the acting user's read row filter, with the key value bound", async () => {
+        const rowFilter = managerRowFilter();
+        expect(rowFilter).toContain(MANAGER_ID);
+
+        const result = await resolver.GetEntityRecordName('Clients', key('ID', CLIENT_ID_VALUE), context);
+
+        expect(result.Success).toBe(true);
+        expect(provider.Sent).toEqual([
+            { SQL: `SELECT [Name] FROM [dbo].[vwClients] WHERE [ID]=@p0 AND (${rowFilter})`, Parameters: [CLIENT_ID_VALUE] },
+        ]);
+    });
+
+    it('applies the row filter to each item of a batch', async () => {
+        const rowFilter = managerRowFilter();
+
+        const results = await resolver.GetEntityRecordNames([{ EntityName: 'Clients', CompositeKey: key('ID', CLIENT_ID_VALUE) }], context);
+
+        expect(results.map(r => r.Success)).toEqual([true]);
+        expect(provider.Sent.map(q => q.SQL)).toEqual([`SELECT [Name] FROM [dbo].[vwClients] WHERE [ID]=@p0 AND (${rowFilter})`]);
+    });
+
+    it('refuses a key field that is not a primary key, without querying', async () => {
+        const result = await resolver.GetEntityRecordName('Clients', key('Tier', '1'), context);
+
+        expect(result.Success).toBe(false);
+        expect(result.RecordName).toBeUndefined();
+        expect(provider.Sent).toHaveLength(0);
+    });
+
+    it('looks no name up when there is no acting user', async () => {
+        const result = await resolver.InnerGetEntityRecordName(provider, 'Clients', key('ID', CLIENT_ID_VALUE));
+
+        expect(result.Success).toBe(false);
+        expect(provider.Sent).toHaveLength(0);
+    });
+});

package/src/__tests__/FetchEntityVectorsResolver.test.ts

@@ -0,0 +1,433 @@
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { UserInfo, type DatabaseProviderBase, type EntityInfo, type RunViewParams } from '@memberjunction/core';
+import { MJGlobal } from '@memberjunction/global';
+import type { VectorDBBase } from '@memberjunction/ai-vectordb';
+
+type ViewResult = { Success: boolean; Results: unknown[]; ErrorMessage?: string };
+type RunViewHandler = (params: RunViewParams, contextUser: UserInfo | undefined) => ViewResult;
+
+// Vitest's transform emits no decorator metadata, so type-graphql can't infer field types —
+// stub the decorators; these tests exercise the resolver method, not the schema.
+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 runViewCalls: Array<{ params: RunViewParams; contextUser: UserInfo | undefined }> = [];
+/** Each RunViews call, as the list of entity names it batched. */
+const runViewsBatches: string[][] = [];
+let runViewHandler: RunViewHandler = () => ({ Success: true, Results: [] });
+
+vi.mock('@memberjunction/core', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/core')>();
+    class MockRunView {
+        async RunView(params: RunViewParams, contextUser?: UserInfo): Promise<ViewResult> {
+            runViewCalls.push({ params, contextUser });
+            return runViewHandler(params, contextUser);
+        }
+        async RunViews(params: RunViewParams[], contextUser?: UserInfo): Promise<ViewResult[]> {
+            runViewsBatches.push(params.map((p) => p.EntityName ?? ''));
+            return Promise.all(params.map((p) => this.RunView(p, contextUser)));
+        }
+    }
+    return { ...actual, RunView: MockRunView, LogStatus: () => undefined, LogError: () => undefined };
+});
+
+// GetAIAPIKey resolves through the ClassFactory too; keep it off the CreateInstance spy below.
+vi.mock('@memberjunction/ai', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/ai')>();
+    return { ...actual, GetAIAPIKey: () => 'test-key' };
+});
+
+vi.mock('@memberjunction/aiengine', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/aiengine')>();
+    return { ...actual, AIEngine: { Instance: { GetProviderIndexName: () => 'provider-index-name' } } };
+});
+
+import { FetchEntityVectorsResolver } from '../resolvers/FetchEntityVectorsResolver.js';
+import type { AppContext } from '../types.js';
+
+/* ───── fixtures ───── */
+
+const DOC_ID = 'DOC-1';
+const contextUser = new UserInfo();
+
+const membersEntity = {
+    Name: 'Members',
+    PrimaryKeys: [{ Name: 'ID' }],
+    Fields: [
+        { Name: 'ID', IsNameField: false },
+        { Name: 'FirstName', IsNameField: true },
+        { Name: 'LastName', IsNameField: true },
+        { Name: 'Email', IsNameField: false },
+    ],
+    NameField: undefined,
+} as unknown as EntityInfo;
+
+const orderLinesEntity = {
+    Name: 'Order Lines',
+    PrimaryKeys: [{ Name: 'OrderID' }, { Name: 'LineNo' }],
+    Fields: [
+        { Name: 'OrderID', IsNameField: false },
+        { Name: 'LineNo', IsNameField: false },
+        { Name: 'Description', IsNameField: false },
+    ],
+    NameField: { Name: 'Description' },
+} as unknown as EntityInfo;
+
+function fakeVectorDB(queryKeyIsEntityDocumentID: boolean) {
+    const queryIndex = vi.fn().mockResolvedValue({
+        success: true,
+        data: { matches: [{ id: 'pc-1', values: [0.5, 0.5], metadata: { Entity: 'Members', RecordID: 'a' } }] },
+    });
+    const db = { QueryKeyIsEntityDocumentID: queryKeyIsEntityDocumentID, QueryIndex: queryIndex } as unknown as VectorDBBase;
+    return { db, queryIndex };
+}
+
+function appContext(entityInfo: EntityInfo): AppContext {
+    const provider = { EntityByName: (name: string) => (name === entityInfo.Name ? entityInfo : undefined) } as unknown as DatabaseProviderBase;
+    return {
+        userPayload: { email: 'test@example.com', sessionId: 's', userRecord: contextUser },
+        providers: [{ type: 'Read-Only', provider }],
+    } as unknown as AppContext;
+}
+
+/** Route RunView by entity: the doc → index → database lookups, then the case-specific views. */
+function routeViews(entityName: string, views: Record<string, (params: RunViewParams) => ViewResult>): void {
+    runViewHandler = (params) => {
+        switch (params.EntityName) {
+            case 'MJ: Entity Documents':
+                return { Success: true, Results: [{ ID: DOC_ID, Name: 'Doc', Entity: entityName, VectorIndexID: 'VI-1' }] };
+            case 'MJ: Vector Indexes':
+                return { Success: true, Results: [{ ID: 'VI-1', Name: 'Index', VectorDatabaseID: 'VDB-1', Dimensions: 2 }] };
+            case 'MJ: Vector Databases':
+                return { Success: true, Results: [{ ID: 'VDB-1', ClassKey: 'TestVectorDB' }] };
+            default: {
+                const view = views[params.EntityName ?? ''];
+                return view ? view(params) : { Success: false, Results: [], ErrorMessage: `unexpected view ${params.EntityName}` };
+            }
+        }
+    };
+}
+
+const storedRows = [
+    { ID: 'ERD-1', RecordID: 'AAA', VectorJSON: '[0.1,0.2]' },
+    { ID: 'ERD-2', RecordID: 'bbb', VectorJSON: '[0.3,0.4]' },
+    { ID: 'ERD-3', RecordID: 'ccc', VectorJSON: '[0.5,0.6]' },
+];
+const memberRows = [
+    { ID: 'aaa', FirstName: 'Ada', LastName: 'Lovelace' },
+    { ID: 'bbb', FirstName: 'Grace', LastName: 'Hopper' },
+    { ID: 'ccc', FirstName: 'Alan', LastName: null },
+];
+
+/**
+ * A fake `MJ: Entity Record Documents` view over `rows`: returns only the requested `Fields`, and
+ * only the rows named by an `ID IN ('a','b')` filter when one is given.
+ */
+function erdView(rows: Array<Record<string, string>>) {
+    return (params: RunViewParams): ViewResult => {
+        const idList = /^ID IN \((.*)\)$/.exec(params.ExtraFilter ?? '');
+        const ids = idList ? new Set(idList[1].split(',').map((v) => v.trim().replace(/^'|'$/g, ''))) : undefined;
+        const picked = ids ? rows.filter((r) => ids.has(r.ID)) : rows;
+        const fields = params.Fields ?? Object.keys(rows[0] ?? {});
+        return { Success: true, Results: picked.map((r) => Object.fromEntries(fields.map((f) => [f, r[f]]))) };
+    };
+}
+
+/** The VectorJSON fetches: Entity Record Documents views filtered by ID. */
+function vectorFetches() {
+    return callsFor('MJ: Entity Record Documents').filter((c) => c.params.ExtraFilter?.startsWith('ID IN ('));
+}
+
+function callsFor(entityName: string) {
+    return runViewCalls.filter((c) => c.params.EntityName === entityName);
+}
+
+/* ───── tests ───── */
+
+describe('FetchEntityVectorsResolver', () => {
+    let createInstanceSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+        runViewCalls.length = 0;
+        runViewsBatches.length = 0;
+    });
+
+    afterEach(() => {
+        createInstanceSpy?.mockRestore();
+    });
+
+    function useVectorDB(queryKeyIsEntityDocumentID: boolean) {
+        const fake = fakeVectorDB(queryKeyIsEntityDocumentID);
+        createInstanceSpy = vi.spyOn(MJGlobal.Instance.ClassFactory, 'CreateInstance').mockReturnValue(fake.db);
+        return fake;
+    }
+
+    describe('local vector store (QueryKeyIsEntityDocumentID)', () => {
+        it('reads VectorJSON for the document with the context user instead of calling QueryIndex', async () => {
+            const { queryIndex } = useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': erdView(storedRows),
+                Members: () => ({ Success: true, Results: memberRows }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(membersEntity));
+
+            expect(result.ErrorMessage).toBeUndefined();
+            expect(result.Success).toBe(true);
+            expect(queryIndex).not.toHaveBeenCalled();
+            expect(result.TotalCount).toBe(3);
+            expect(result.Results.map((r) => r.ID)).toEqual(['ERD-1', 'ERD-2', 'ERD-3']);
+            expect(result.Results.map((r) => r.Values)).toEqual([[0.1, 0.2], [0.3, 0.4], [0.5, 0.6]]);
+
+            const [listCall, vectorCall] = callsFor('MJ: Entity Record Documents');
+            expect(listCall.contextUser).toBe(contextUser);
+            expect(listCall.params.ExtraFilter).toBe(`EntityDocumentID='${DOC_ID}' AND VectorJSON IS NOT NULL`);
+            expect(listCall.params.Fields).toEqual(['ID', 'RecordID']);
+            expect(listCall.params.ResultType).toBe('simple');
+            expect(listCall.params.IgnoreMaxRows).toBe(true);
+            expect(vectorCall.contextUser).toBe(contextUser);
+            expect(vectorCall.params.ExtraFilter).toBe("ID IN ('ERD-1','ERD-2','ERD-3')");
+            expect(vectorCall.params.Fields).toEqual(['ID', 'VectorJSON']);
+            expect(vectorCall.params.ResultType).toBe('simple');
+            expect(vectorCall.params.IgnoreMaxRows).toBe(true);
+        });
+
+        it('bypasses the server RunView cache for both Entity Record Documents views, so Fields is honoured', async () => {
+            useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': erdView(storedRows),
+                Members: () => ({ Success: true, Results: memberRows }),
+            });
+
+            await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(membersEntity));
+
+            const erdCalls = callsFor('MJ: Entity Record Documents');
+            expect(erdCalls).toHaveLength(2);
+            expect(erdCalls.map((c) => c.params.BypassCache)).toEqual([true, true]);
+            expect(callsFor('Members')[0].params.BypassCache).toBeUndefined();
+        });
+
+        it('labels each item with Entity, RecordID and the record name fields (RecordID matched case-insensitively)', async () => {
+            useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': erdView(storedRows),
+                Members: () => ({ Success: true, Results: memberRows }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(membersEntity));
+
+            expect(result.Results.map((r) => JSON.parse(r.Metadata))).toEqual([
+                { Entity: 'Members', RecordID: 'AAA', FirstName: 'Ada', LastName: 'Lovelace' },
+                { Entity: 'Members', RecordID: 'bbb', FirstName: 'Grace', LastName: 'Hopper' },
+                { Entity: 'Members', RecordID: 'ccc', FirstName: 'Alan' },
+            ]);
+            const [membersCall] = callsFor('Members');
+            expect(membersCall.contextUser).toBe(contextUser);
+            expect(membersCall.params.Fields).toEqual(['ID', 'FirstName', 'LastName']);
+            expect(membersCall.params.ResultType).toBe('simple');
+            expect(membersCall.params.ExtraFilter).toBeUndefined();
+        });
+
+        it('honours the filter: passes it to the entity view and drops vectors whose record did not pass', async () => {
+            useVectorDB(true);
+            const filter = "LastName = 'Hopper'";
+            routeViews('Members', {
+                'MJ: Entity Record Documents': erdView(storedRows),
+                Members: (params) => ({
+                    Success: true,
+                    Results: params.ExtraFilter === filter ? memberRows.filter((r) => r.LastName === 'Hopper') : memberRows,
+                }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, filter, appContext(membersEntity));
+
+            expect(result.Success).toBe(true);
+            expect(callsFor('Members')[0].params.ExtraFilter).toBe(filter);
+            expect(result.TotalCount).toBe(1);
+            expect(result.Results[0].ID).toBe('ERD-2');
+            expect(JSON.parse(result.Results[0].Metadata)).toEqual({ Entity: 'Members', RecordID: 'bbb', FirstName: 'Grace', LastName: 'Hopper' });
+        });
+
+        it('stops at maxRecords', async () => {
+            useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': erdView(storedRows),
+                Members: () => ({ Success: true, Results: memberRows }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, 2, undefined, appContext(membersEntity));
+
+            expect(result.Results.map((r) => r.ID)).toEqual(['ERD-1', 'ERD-2']);
+            expect(result.TotalCount).toBe(2);
+            expect(vectorFetches().map((c) => c.params.ExtraFilter)).toEqual(["ID IN ('ERD-1','ERD-2')"]);
+        });
+
+        it('fetches VectorJSON only for vectors whose record passed the filter', async () => {
+            useVectorDB(true);
+            const filter = "LastName = 'Hopper'";
+            routeViews('Members', {
+                'MJ: Entity Record Documents': erdView(storedRows),
+                Members: () => ({ Success: true, Results: memberRows.filter((r) => r.LastName === 'Hopper') }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, filter, appContext(membersEntity));
+
+            expect(result.Results.map((r) => r.Values)).toEqual([[0.3, 0.4]]);
+            expect(vectorFetches().map((c) => c.params.ExtraFilter)).toEqual(["ID IN ('ERD-2')"]);
+        });
+
+        it('runs no VectorJSON fetch when no stored vector belongs to a readable record', async () => {
+            useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': erdView(storedRows),
+                Members: () => ({ Success: true, Results: [] }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(membersEntity));
+
+            expect(result.Success).toBe(true);
+            expect(result.Results).toEqual([]);
+            expect(vectorFetches()).toHaveLength(0);
+        });
+
+        it('splits a large VectorJSON fetch into ID lists of at most 1000, sent in one RunViews batch', async () => {
+            useVectorDB(true);
+            const ids = Array.from({ length: 1500 }, (_, i) => `id-${i}`);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': erdView(ids.map((id, i) => ({ ID: `ERD-${i}`, RecordID: id, VectorJSON: `[${i}]` }))),
+                Members: () => ({ Success: true, Results: ids.map((id) => ({ ID: id, FirstName: id, LastName: null })) }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, 1500, undefined, appContext(membersEntity));
+
+            expect(result.TotalCount).toBe(1500);
+            expect(result.Results[1499]).toMatchObject({ ID: 'ERD-1499', Values: [1499] });
+            const fetchSizes = vectorFetches().map((c) => (c.params.ExtraFilter ?? '').split(',').length);
+            expect(fetchSizes).toEqual([1000, 500]);
+            expect(runViewsBatches[1]).toEqual(['MJ: Entity Record Documents', 'MJ: Entity Record Documents']);
+        });
+
+        it('returns an error result when the VectorJSON fetch fails', async () => {
+            useVectorDB(true);
+            const listing = erdView(storedRows);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': (params) =>
+                    params.ExtraFilter?.startsWith('ID IN (') ? { Success: false, Results: [], ErrorMessage: 'deadlock' } : listing(params),
+                Members: () => ({ Success: true, Results: memberRows }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(membersEntity));
+
+            expect(result.Success).toBe(false);
+            expect(result.Results).toEqual([]);
+            expect(result.ErrorMessage).toBe('Failed to load vector values: deadlock');
+        });
+
+        it('matches composite-key records by the compact RecordID segment and falls back to NameField for labels', async () => {
+            useVectorDB(true);
+            routeViews('Order Lines', {
+                'MJ: Entity Record Documents': erdView([{ ID: 'ERD-9', RecordID: 'OrderID|o-1||LineNo|2', VectorJSON: '[1,0]' }]),
+                'Order Lines': () => ({ Success: true, Results: [{ OrderID: 'o-1', LineNo: 2, Description: 'Brie wheel' }] }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(orderLinesEntity));
+
+            expect(result.Success).toBe(true);
+            expect(result.Results).toHaveLength(1);
+            expect(JSON.parse(result.Results[0].Metadata)).toEqual({
+                Entity: 'Order Lines',
+                RecordID: 'OrderID|o-1||LineNo|2',
+                Description: 'Brie wheel',
+            });
+            expect(callsFor('Order Lines')[0].params.Fields).toEqual(['OrderID', 'LineNo', 'Description']);
+        });
+
+        it('returns an error result when the entity records cannot be loaded (e.g. an invalid filter)', async () => {
+            useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': erdView(storedRows),
+                Members: () => ({ Success: false, Results: [], ErrorMessage: 'bad filter' }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, 'nonsense', appContext(membersEntity));
+
+            expect(result.Success).toBe(false);
+            expect(result.Results).toEqual([]);
+            expect(result.ErrorMessage).toBe('Failed to load "Members" records: bad filter');
+        });
+
+        it('returns an error result when the stored vectors cannot be loaded', async () => {
+            useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': () => ({ Success: false, Results: [], ErrorMessage: 'timeout' }),
+                Members: () => ({ Success: true, Results: memberRows }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(membersEntity));
+
+            expect(result.Success).toBe(false);
+            expect(result.Results).toEqual([]);
+            expect(result.TotalCount).toBe(0);
+            expect(result.ErrorMessage).toBe('Failed to load stored vectors: timeout');
+        });
+
+        it('returns an error result, and runs neither view, when the document names an entity missing from metadata', async () => {
+            const { queryIndex } = useVectorDB(true);
+            routeViews('Retired Entity', {
+                'MJ: Entity Record Documents': erdView(storedRows),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(membersEntity));
+
+            expect(result.Success).toBe(false);
+            expect(result.Results).toEqual([]);
+            expect(result.ErrorMessage).toBe('Entity "Retired Entity" not found in metadata');
+            expect(queryIndex).not.toHaveBeenCalled();
+            expect(callsFor('MJ: Entity Record Documents')).toHaveLength(0);
+            expect(runViewsBatches).toHaveLength(0);
+        });
+
+        it('lists the entity records and the stored vectors in one RunViews batch, then fetches the vector values', async () => {
+            useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': erdView(storedRows),
+                Members: () => ({ Success: true, Results: memberRows }),
+            });
+
+            await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(membersEntity));
+
+            expect(runViewsBatches).toEqual([['Members', 'MJ: Entity Record Documents'], ['MJ: Entity Record Documents']]);
+        });
+    });
+
+    describe('index-keyed providers (Pinecone path, unchanged)', () => {
+        it('queries the provider index by name and never reads Entity Record Documents', async () => {
+            const { queryIndex } = useVectorDB(false);
+            routeViews('Members', {});
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, 50, undefined, appContext(membersEntity));
+
+            expect(result.Success).toBe(true);
+            expect(queryIndex).toHaveBeenCalledTimes(1);
+            const query = queryIndex.mock.calls[0][0];
+            expect(query.id).toBe('provider-index-name');
+            expect(query.topK).toBe(50);
+            expect(query.includeValues).toBe(true);
+            expect(query.filter).toEqual({ Entity: { $eq: 'Members' } });
+            expect(query.vector).toHaveLength(2);
+            expect(result.Results).toEqual([{ ID: 'pc-1', Values: [0.5, 0.5], Metadata: JSON.stringify({ Entity: 'Members', RecordID: 'a' }) }]);
+            expect(callsFor('MJ: Entity Record Documents')).toHaveLength(0);
+            expect(callsFor('Members')).toHaveLength(0);
+        });
+    });
+});