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

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

@@ -24,16 +24,22 @@ vi.mock('type-graphql', () => {
     return Object.fromEntries(exportNames.map((name) => [name, decoratorFactory]));
 });
 
+const hoisted = vi.hoisted(() => ({
+    runAgentInConversation: vi.fn().mockResolvedValue({ agentResult: { success: true } }),
+}));
+
 vi.mock('@memberjunction/ai-agents', () => ({
     AgentRunner: class {
-        RunAgentInConversation() {
-            return Promise.resolve({ agentResult: { success: true } });
+        RunAgentInConversation(...args: unknown[]) {
+            return hoisted.runAgentInConversation(...args);
         }
         CreateAgentReplyDetail() {
             return Promise.resolve({ ID: 'reply-1', __mj_CreatedAt: new Date() }); // the server creates the reply row (A19)
         }
     },
     ArtifactToolManager: class {},
+    CanAgentOwnSubAgentConsults: vi.fn(() => false),
+    LoadOpenSubAgentConsults: vi.fn(async () => []),
 }));
 
 vi.mock('../realtimeWidget/widgetGuestElevation.js', () => ({
@@ -46,6 +52,7 @@ import type { AppContext, UserPayload } from '../types.js';
 
 const USER = { ID: 'user-1', Email: 'user@example.com' };
 const STOPPED_RUN = '16787b44-29f6-44a5-8bd4-fc1538e79275';
+const CONSULT_RUN = 'c0ffee00-29f6-44a5-8bd4-fc1538e79275';
 
 type Fn = ReturnType<typeof vi.fn>;
 
@@ -55,7 +62,9 @@ interface ResolverSeams {
     loadConversationHistoryWithAttachments: Fn;
     executeAIAgent: Fn;
     executeAgentInBackground: Fn;
-    findUserStoppedPredecessorRunId: Fn;
+    findChainablePredecessor: Fn;
+    validateAgent: Fn;
+    syncFeedbackRequestFromConversation: Fn;
 }
 
 /** Argument positions of lastRunId / autoPopulateLastRunPayload on the two dispatch seams. */
@@ -69,7 +78,7 @@ function makeResolver(): { resolver: RunAIAgentResolver; seams: ResolverSeams }
     seams.loadConversationHistoryWithAttachments = vi.fn().mockResolvedValue([]);
     seams.executeAIAgent = vi.fn().mockResolvedValue({ success: true, result: '{}' });
     seams.executeAgentInBackground = vi.fn();
-    seams.findUserStoppedPredecessorRunId = vi.fn().mockResolvedValue(null);
+    seams.findChainablePredecessor = vi.fn().mockResolvedValue(null);
     return { resolver, seams };
 }
 
@@ -102,7 +111,7 @@ afterEach(() => {
     vi.restoreAllMocks();
 });
 
-describe('RunAIAgentFromConversationDetail — continuing from a user-stopped run', () => {
+describe('RunAIAgentFromConversationDetail — continuing from a chainable predecessor run', () => {
     let resolver: RunAIAgentResolver;
     let seams: ResolverSeams;
 
@@ -111,19 +120,19 @@ describe('RunAIAgentFromConversationDetail — continuing from a user-stopped ru
     });
 
     it('chains the new run to the stopped predecessor and rolls its payload in when none was supplied', async () => {
-        seams.findUserStoppedPredecessorRunId.mockResolvedValue(STOPPED_RUN);
+        seams.findChainablePredecessor.mockResolvedValue({ runId: STOPPED_RUN, reason: 'stopped' });
 
         const result = await runMutation(resolver, {});
 
         expect(result.success).toBe(true);
-        expect(seams.findUserStoppedPredecessorRunId).toHaveBeenCalledWith('conv-1', 'agent-1', null, USER, expect.anything());
+        expect(seams.findChainablePredecessor).toHaveBeenCalledWith('conv-1', 'agent-1', null, USER, expect.anything());
         const args = seams.executeAIAgent.mock.calls[0];
         expect(args[SYNC_LAST_RUN]).toBe(STOPPED_RUN);
         expect(args[SYNC_AUTO]).toBe(true);
     });
 
     it('keeps the caller\'s payload as the start when one was supplied (chains, but does not roll the old one in)', async () => {
-        seams.findUserStoppedPredecessorRunId.mockResolvedValue(STOPPED_RUN);
+        seams.findChainablePredecessor.mockResolvedValue({ runId: STOPPED_RUN, reason: 'stopped' });
 
         await runMutation(resolver, { payload: '{"fromArtifact":true}' });
 
@@ -133,7 +142,7 @@ describe('RunAIAgentFromConversationDetail — continuing from a user-stopped ru
     });
 
     it('hands the chain to a fire-and-forget run too', async () => {
-        seams.findUserStoppedPredecessorRunId.mockResolvedValue(STOPPED_RUN);
+        seams.findChainablePredecessor.mockResolvedValue({ runId: STOPPED_RUN, reason: 'stopped' });
 
         await runMutation(resolver, { fireAndForget: true });
 
@@ -143,17 +152,83 @@ describe('RunAIAgentFromConversationDetail — continuing from a user-stopped ru
         expect(args[BG_AUTO]).toBe(true);
     });
 
+    it('chains an open-consult predecessor on both synchronous and fire-and-forget paths, setting autoPopulate only when no payload was supplied', async () => {
+        seams.findChainablePredecessor.mockResolvedValue({ runId: CONSULT_RUN, reason: 'open-consult' });
+
+        // 1. Synchronous without payload -> effectiveAutoPopulate = true
+        await runMutation(resolver, {});
+        const syncNoPayloadArgs = seams.executeAIAgent.mock.calls[0];
+        expect(syncNoPayloadArgs[SYNC_LAST_RUN]).toBe(CONSULT_RUN);
+        expect(syncNoPayloadArgs[SYNC_AUTO]).toBe(true);
+
+        // 2. Synchronous with payload -> effectiveAutoPopulate = undefined
+        await runMutation(resolver, { payload: '{"custom":1}' });
+        const syncWithPayloadArgs = seams.executeAIAgent.mock.calls[1];
+        expect(syncWithPayloadArgs[SYNC_LAST_RUN]).toBe(CONSULT_RUN);
+        expect(syncWithPayloadArgs[SYNC_AUTO]).toBeUndefined();
+
+        // 3. Fire-and-forget without payload -> effectiveAutoPopulate = true
+        await runMutation(resolver, { fireAndForget: true });
+        const bgNoPayloadArgs = seams.executeAgentInBackground.mock.calls[0];
+        expect(bgNoPayloadArgs[BG_LAST_RUN]).toBe(CONSULT_RUN);
+        expect(bgNoPayloadArgs[BG_AUTO]).toBe(true);
+
+        // 4. Fire-and-forget with payload -> effectiveAutoPopulate = undefined
+        await runMutation(resolver, { fireAndForget: true, payload: '{"custom":1}' });
+        const bgWithPayloadArgs = seams.executeAgentInBackground.mock.calls[1];
+        expect(bgWithPayloadArgs[BG_LAST_RUN]).toBe(CONSULT_RUN);
+        expect(bgWithPayloadArgs[BG_AUTO]).toBeUndefined();
+    });
+
+    it('threads a lastRunId chained from findChainablePredecessor into syncFeedbackRequestFromConversation when executeAIAgent runs', async () => {
+        const realResolver = new RunAIAgentResolver();
+        const realSeams = realResolver as unknown as ResolverSeams;
+        realSeams.CheckAPIKeyScopeAuthorization = vi.fn().mockResolvedValue(undefined);
+        realSeams.GetUserFromPayload = vi.fn().mockReturnValue(USER);
+        realSeams.loadConversationHistoryWithAttachments = vi.fn().mockResolvedValue([
+            { role: 'user', content: 'Proceed with option A' },
+        ]);
+        realSeams.findChainablePredecessor = vi.fn().mockResolvedValue({
+            runId: CONSULT_RUN,
+            reason: 'open-consult',
+        });
+        realSeams.validateAgent = vi.fn().mockResolvedValue({
+            ID: 'agent-1',
+            Name: 'Director',
+            Status: 'Active',
+        });
+        realSeams.syncFeedbackRequestFromConversation = vi.fn().mockResolvedValue(undefined);
+        hoisted.runAgentInConversation.mockResolvedValueOnce({
+            agentResult: {
+                success: true,
+                agentRun: { ID: 'new-run-99', ConversationDetailID: 'detail-1' },
+            },
+            conversationId: 'conv-1',
+        });
+
+        const res = await runMutation(realResolver, {});
+
+        expect(res.success).toBe(true);
+        expect(realSeams.syncFeedbackRequestFromConversation).toHaveBeenCalledWith(
+            CONSULT_RUN,
+            'new-run-99',
+            'Proceed with option A',
+            USER,
+            expect.anything()
+        );
+    });
+
     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());
+        expect(seams.findChainablePredecessor).toHaveBeenCalledWith('conv-1', 'agent-1', 'B', expect.anything(), expect.anything());
         await runMutation(resolver, {});
-        expect(seams.findUserStoppedPredecessorRunId).toHaveBeenLastCalledWith('conv-1', 'agent-1', null, expect.anything(), expect.anything());
+        expect(seams.findChainablePredecessor).toHaveBeenLastCalledWith('conv-1', 'agent-1', null, expect.anything(), expect.anything());
     });
 
     it('a caller-supplied lastRunId wins and the lookup is skipped', async () => {
         await runMutation(resolver, { lastRunId: 'caller-run', autoPopulate: false });
 
-        expect(seams.findUserStoppedPredecessorRunId).not.toHaveBeenCalled();
+        expect(seams.findChainablePredecessor).not.toHaveBeenCalled();
         const args = seams.executeAIAgent.mock.calls[0];
         expect(args[SYNC_LAST_RUN]).toBe('caller-run');
         expect(args[SYNC_AUTO]).toBe(false);

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

@@ -32,12 +32,22 @@ import type { AgentExecutionStreamingCallback } from '@memberjunction/ai-core-pl
 import { AgentRunStatusPublisher } from '../resolvers/AgentRunStatusPublisher.js';
 import type { UserPayload } from '../types.js';
 
-const agentRun = {
+const runFields = {
     ID: 'run-1',
-    GetAll: () => ({ ID: 'run-1', ConversationDetailID: 'detail-1', Agent: 'Betty' }),
+    AgentID: 'agent-1',
+    Agent: 'Betty',
+    ParentRunID: null,
+    Status: 'Running',
+    ConversationID: 'conversation-1',
+    ConversationDetailID: 'detail-1',
+};
+
+const agentRun = {
+    ...runFields,
+    GetAll: () => ({ ...runFields }),
 };
 
-function buildHarness() {
+function buildHarness(run: object = agentRun) {
     const publish = vi.fn().mockResolvedValue(undefined);
     const pubSub = { publish } as unknown as PubSubEngine;
     const userPayload = { sessionId: 'session-1', userRecord: { ID: 'user-1' } } as UserPayload;
@@ -46,7 +56,7 @@ function buildHarness() {
     publisher.OnProgress({
         step: 'initialization',
         message: 'starting',
-        metadata: { agentRun },
+        metadata: { agentRun: run },
     });
     publish.mockClear();
     const callback: AgentExecutionStreamingCallback = publisher.OnStreaming;
@@ -81,6 +91,20 @@ describe('AgentRunStatusPublisher streaming wire shape', () => {
         });
     });
 
+    it('sends the run summary on each chunk, not the steps and payload the run holds', () => {
+        const getAll = vi.fn(() => ({
+            ...runFields,
+            FinalPayload: '{"rows":[1,2,3]}',
+            __runSteps: [{ ID: 'step-1', __promptRun: { Messages: 'the full prompt' } }],
+        }));
+        const { publish, callback } = buildHarness({ ...runFields, GetAll: getAll });
+
+        callback({ content: 'Hel', isComplete: false, stepType: 'prompt', kind: 'final-response' });
+
+        expect(publishedData(publish).agentRun).toEqual(runFields);
+        expect(getAll).not.toHaveBeenCalled();
+    });
+
     it('maps isComplete=true to isPartial=false on the final chunk', () => {
         const { publish, callback } = buildHarness();
 

package/src/__tests__/SchemaEvolutionCustomColumns.test.ts

@@ -0,0 +1,119 @@
+/**
+ * everything.txt C9: a custom column the source starts sending is CAPTURED automatically, but
+ * turning it into a real column "requires that the user accepts" it.
+ *
+ * A schema refresh is where an operator asks what changed on the source, so that is where the
+ * accumulated overflow columns should be offered. Offering is free; promoting is not. These pin
+ * the split, and the one thing that makes acceptance cheap enough to offer at all: the accepted
+ * columns ride the refresh's OWN migration instead of starting a second one, because two RSU
+ * restarts back-to-back for a single user action is its own incident class here.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SRC = readFileSync(join(__dirname, '..', 'resolvers', 'IntegrationDiscoveryResolver.ts'), 'utf-8');
+const PROMOTER = readFileSync(join(__dirname, '..', 'integration', 'CustomColumnPromoter.ts'), 'utf-8');
+
+function methodBody(name: string): string {
+  const i = SRC.indexOf(`async ${name}(`);
+  expect(i, `${name} not found`).toBeGreaterThan(-1);
+  const rest = SRC.slice(i);
+  const end = rest.search(/\n    @(Query|Mutation)\(/);
+  return end === -1 ? rest : rest.slice(0, end);
+}
+
+describe('the refresh offers the overflow columns', () => {
+  const body = () => methodBody('IntegrationSchemaEvolution');
+
+  it('reports candidates on the output', () => {
+    expect(SRC).toMatch(/CustomColumnCandidates\?: CustomColumnCandidate\[\]/);
+    expect(body()).toMatch(/ListCandidates\(/);
+  });
+
+  it('reports them ALWAYS, not only when something was accepted', () => {
+    // The listing must not sit inside the acceptance branch — an operator cannot accept a column
+    // they were never shown.
+    const b = body();
+    const list = b.indexOf('ListCandidates(');
+    const acceptGate = b.indexOf('if (accepted.size > 0)');
+    expect(list).toBeGreaterThan(-1);
+    expect(acceptGate).toBeGreaterThan(-1);
+    expect(list, 'ListCandidates must run before the acceptance gate').toBeLessThan(acceptGate);
+  });
+
+  it('promotes NOTHING by default', () => {
+    expect(SRC).toMatch(/@Arg\("acceptCustomColumns"[\s\S]{0,200}?defaultValue: \[\]/);
+  });
+});
+
+describe('acceptance', () => {
+  const body = () => methodBody('IntegrationSchemaEvolution');
+
+  it('plans only the entities that own an accepted column', () => {
+    // Planning a whole entity because ONE of its columns was accepted would promote its other
+    // candidates too — exactly the un-asked-for materialisation the gate exists to prevent.
+    const b = body();
+    // It is not enough that the narrowed list is COMPUTED — it has to be what gets planned.
+    expect(b).toMatch(/PlanPromotion\(companyIntegrationID, entitiesWithAccepted\)/);
+    expect(b).toMatch(/filter\(c => accepted\.has\(c\.ColumnName\.toLowerCase\(\)\)\)/);
+    expect(b).not.toMatch(/PlanPromotion\(companyIntegrationID, mapped\)/);
+  });
+
+  it('folds the accepted migrations into the SAME batch as the refresh DDL', () => {
+    // The retrying variant, as every install path uses: it replays only while nothing was applied.
+    expect(body()).toMatch(/RunPipelineBatchWithRetry\(\[rsuInput, \.\.\.promotionInputs\]\)/);
+  });
+
+  it('still runs a batch when the refresh itself has no DDL', () => {
+    // Source shape unchanged but columns accepted: they still need their migration.
+    expect(body()).toMatch(/else if \(promotionInputs\.length > 0\)/);
+  });
+
+  it('drops accepted columns from the outstanding offer, so they cannot be accepted twice', () => {
+    const b = body();
+    // The offer returned must be the FILTERED list, not the raw one.
+    expect(b).toMatch(/const acceptedNames = new Set\(promotedColumns\.map\(c => c\.ColumnName\.toLowerCase\(\)\)\)/);
+    expect(b).toMatch(/const outstandingCandidates = customColumnCandidates\.filter\(c => !acceptedNames\.has\(c\.ColumnName\.toLowerCase\(\)\)\)/);
+    expect(b).toMatch(/CustomColumnCandidates: outstandingCandidates\.length > 0 \? outstandingCandidates : undefined/);
+  });
+
+  it('a candidates failure costs the offer, never the refresh', () => {
+    const b = body();
+    const i = b.indexOf('catch (candErr)');
+    expect(i).toBeGreaterThan(-1);
+    const handler = b.slice(i, i + 400);
+    expect(handler).not.toMatch(/return \{[\s\S]{0,120}Success: false/);
+    expect(handler).toMatch(/customColumnCandidates = \[\]/);
+  });
+});
+
+describe('PlanPromotion — the split that makes one batch possible', () => {
+  it('is public and runs no pipeline itself', () => {
+    expect(PROMOTER).toMatch(/public async PlanPromotion\(/);
+    const i = PROMOTER.indexOf('public async PlanPromotion(');
+    const end = PROMOTER.indexOf('/** Entry point: promote custom columns');
+    const body = PROMOTER.slice(i, end);
+    expect(body).not.toMatch(/RunPipelineBatch\(/);
+  });
+
+  it('still purges stale staged keys during planning, before any column is created', () => {
+    // This side effect belongs to planning: it is the only thing that ever cleans residue on rows
+    // a sync never rewrites, so moving it out of the plan would resurrect phantom candidates.
+    const i = PROMOTER.indexOf('public async PlanPromotion(');
+    const end = PROMOTER.indexOf('/** Entry point: promote custom columns');
+    expect(PROMOTER.slice(i, end)).toMatch(/purgeStaleOverflowKeys/);
+  });
+
+  it('carries the post-restart PendingWork on its first input, so it survives being appended', () => {
+    const i = PROMOTER.indexOf('public async PlanPromotion(');
+    const end = PROMOTER.indexOf('/** Entry point: promote custom columns');
+    const body = PROMOTER.slice(i, end);
+    expect(body).toMatch(/batchInputs\[0\]\.PendingWork/);
+    expect(body).toMatch(/WorkType: 'promote-columns'/);
+  });
+
+  it('PromoteForSync now goes through it, so the two paths cannot drift', () => {
+    expect(PROMOTER).toMatch(/const promotionPlan = await this\.PlanPromotion\(/);
+  });
+});

package/src/__tests__/SchemaRefreshLaunch.test.ts

@@ -14,6 +14,8 @@ function summary(over: Partial<SchemaRefreshSummaryLike> = {}): SchemaRefreshSum
         Succeeded: true,
         ObjectsCreated: 12,
         ObjectsUpdated: 3,
+        FieldsCreated: 69,
+        FieldsUpdated: 487,
         UnresolvedObjects: ['Widgets'],
         ...over,
     };
@@ -25,6 +27,8 @@ describe('BuildCreateConnectionMessage', () => {
             InProgress: true,
             ObjectsCreated: 0,
             ObjectsUpdated: 0,
+            FieldsCreated: 0,
+            FieldsUpdated: 0,
             UnresolvedObjects: [],
         }));
 
@@ -33,13 +37,14 @@ describe('BuildCreateConnectionMessage', () => {
         // The placeholder zeros must not surface as results.
         expect(msg).not.toMatch(/\d+ created/);
         expect(msg).not.toMatch(/\d+ updated/);
+        expect(msg).not.toMatch(/\d+ fields/);
         expect(msg).not.toMatch(/PK-unresolved/);
     });
 
     it('reports real counts once the refresh has completed inline', () => {
         const msg = BuildCreateConnectionMessage(true, summary());
 
-        expect(msg).toContain('12 created');
+        expect(msg).toContain('12 objects created');
         expect(msg).toContain('3 updated');
         expect(msg).toContain('1 PK-unresolved');
         expect(msg).not.toMatch(/running/i);
@@ -74,6 +79,8 @@ describe('failed-refresh reporting', () => {
         FailureMessage: 'ConnectionTest failed: No HubSpot credentials found',
         ObjectsCreated: 0,
         ObjectsUpdated: 0,
+        FieldsCreated: 0,
+        FieldsUpdated: 0,
         UnresolvedObjects: [],
     });
 
@@ -99,10 +106,25 @@ describe('failed-refresh reporting', () => {
 
     it('still reports counts for a refresh that genuinely succeeded (update)', () => {
         const msg = BuildUpdateConnectionMessage(summary());
-        expect(msg).toContain('12 created');
+        expect(msg).toContain('12 objects created');
         expect(msg).toContain('3 updated');
         expect(msg).not.toMatch(/FAILED/);
     });
+
+    it('names the FIELD counts, so a refresh that only changed fields does not read as a no-op', () => {
+        // A PRESUPPOSED connector creates no objects on any run. A live PheedLoop refresh that created
+        // 69 fields and updated 487 reported "0 created, 0 updated" — literally true of objects, and
+        // read by every operator as "the refresh did nothing".
+        const fieldsOnly = summary({ ObjectsCreated: 0, ObjectsUpdated: 0, UnresolvedObjects: [] });
+        for (const msg of [
+            BuildCreateConnectionMessage(true, fieldsOnly),
+            BuildUpdateConnectionMessage(fieldsOnly),
+        ]) {
+            expect(msg).toContain('69 fields created');
+            expect(msg).toContain('487 updated');
+            expect(msg).toContain('0 objects created');
+        }
+    });
 });
 
 describe('BuildDetachedRefreshMessage', () => {

package/src/__tests__/ScopedFieldsForBuild.test.ts

@@ -0,0 +1,192 @@
+/**
+ * A schema build materializes the CONNECTION's field rows, read for the build, not whatever the
+ * engine happens to hold in memory.
+ *
+ * A connection's per-object field rows are warmed on demand, and the only site that warms them is
+ * the sync loop — so an apply reading them from the engine found `[]` for every object and built a
+ * migration with no tables: "Reusing 364 persisted IOs", then `[tables: ]` in 4 ms, no error.
+ *
+ * These pin the loader the five build paths now share: when it reads, what it reads, that a failed
+ * read is loud, and that with no per-connection catalog in scope nothing changes. The wiring into
+ * the resolver is pinned at the bottom against the source, because the resolver needs a provider,
+ * a connector and an RSU pipeline to invoke.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { RunView, type UserInfo } from '@memberjunction/core';
+import { IntegrationEngineBase } from '@memberjunction/integration-engine-base';
+import { WithCatalogScope } from '@memberjunction/integration-engine';
+import { LoadScopedFieldsForBuild, FieldsForBuild, SCOPED_FIELDS_CHUNK } from '../integration/ScopedFieldsForBuild.js';
+
+const USER = { ID: 'user-1' } as UserInfo;
+type RunViewParams = Parameters<RunView['RunView']>[0];
+type RunViewResult = Awaited<ReturnType<RunView['RunView']>>;
+
+/** A per-connection field row as the per-connection field view returns it. */
+const storedField = (objectID: string, Name: string, Status = 'Active', related: string | null = null) => ({
+    ID: `${objectID}-${Name}`, Name, DisplayName: Name, Description: null, Type: 'nvarchar', Length: 100,
+    Precision: null, Scale: null, AllowsNull: true, DefaultValue: null, IsPrimaryKey: Name === 'id',
+    IsUniqueKey: false, IsReadOnly: false, IsRequired: false, Status,
+    CompanyIntegrationObjectID: objectID, RelatedCompanyIntegrationObjectID: related,
+});
+
+/** An engine whose per-connection FIELD cache is cold — the state an apply runs in. */
+function installEngine(objectIDs: string[], hasCatalog = true) {
+    const getFields = vi.fn(() => []);
+    vi.spyOn(IntegrationEngineBase, 'Instance', 'get').mockReturnValue({
+        HasCompanyIntegrationCatalog: () => hasCatalog,
+        GetActiveIntegrationObjects: () => objectIDs.map(ID => ({ ID, Name: `obj-${ID}` })),
+        GetIntegrationObjectFields: getFields,
+    } as unknown as IntegrationEngineBase);
+    return getFields;
+}
+
+describe('LoadScopedFieldsForBuild', () => {
+    let runView: ReturnType<typeof vi.spyOn>;
+    beforeEach(() => {
+        vi.spyOn(console, 'log').mockImplementation(() => undefined);
+        runView = vi.spyOn(RunView.prototype, 'RunView');
+    });
+    afterEach(() => { vi.restoreAllMocks(); });
+
+    it('reads nothing outside a catalog scope — the build reads the shared catalog as before', async () => {
+        installEngine(['CIO-1']);
+        expect(await LoadScopedFieldsForBuild('INT-1', USER)).toBeNull();
+        expect(runView).not.toHaveBeenCalled();
+    });
+
+    it('reads nothing for a connection in scope that has no catalog of its own', async () => {
+        installEngine(['CIO-1'], false);
+        const loaded = await WithCatalogScope('CI-1', () => LoadScopedFieldsForBuild('INT-1', USER));
+        expect(loaded).toBeNull();
+        expect(runView).not.toHaveBeenCalled();
+    });
+
+    it('reads the connection\'s field rows from the database, bypassing the cache and the row cap', async () => {
+        installEngine(['CIO-1', 'CIO-2']);
+        runView.mockResolvedValue({
+            Success: true,
+            Results: [storedField('CIO-1', 'id'), storedField('CIO-1', 'parent', 'Active', 'CIO-2'), storedField('CIO-2', 'id')],
+        } as unknown as RunViewResult);
+
+        const loaded = await WithCatalogScope('CI-1', () => LoadScopedFieldsForBuild('INT-1', USER));
+
+        const params = runView.mock.calls[0][0] as RunViewParams;
+        expect(params.EntityName).toBe('MJ: Company Integration Object Fields');
+        expect(params.ExtraFilter).toBe("CompanyIntegrationObjectID IN ('CIO-1','CIO-2')");
+        expect(params.ResultType).toBe('simple');
+        expect(params.BypassCache).toBe(true);
+        expect(params.IgnoreMaxRows).toBe(true);
+        // Keyed by lower-cased object id, and carrying the legacy names the build reads.
+        const rows = loaded?.get('cio-1') ?? [];
+        expect(rows.map(r => r.Name)).toEqual(['id', 'parent']);
+        expect(rows[1].IntegrationObjectID).toBe('CIO-1');
+        expect(rows[1].RelatedIntegrationObjectID).toBe('CIO-2');
+        expect(loaded?.get('cio-2')?.map(r => r.Name)).toEqual(['id']);
+    });
+
+    it(`reads ${SCOPED_FIELDS_CHUNK} objects per query`, async () => {
+        installEngine(Array.from({ length: 2 * SCOPED_FIELDS_CHUNK + 50 }, (_, i) => `CIO-${i}`));
+        runView.mockResolvedValue({ Success: true, Results: [] } as unknown as RunViewResult);
+
+        await WithCatalogScope('CI-1', () => LoadScopedFieldsForBuild('INT-1', USER));
+
+        expect(runView).toHaveBeenCalledTimes(3);
+    });
+
+    it('THROWS on a failed read rather than building a schema from an empty field list', async () => {
+        installEngine(['CIO-1']);
+        runView.mockResolvedValue({ Success: false, ErrorMessage: 'timeout', Results: [] } as unknown as RunViewResult);
+
+        await expect(WithCatalogScope('CI-1', () => LoadScopedFieldsForBuild('INT-1', USER)))
+            .rejects.toThrow(/PER_CONNECTION_FIELDS_UNREADABLE/);
+    });
+});
+
+describe('FieldsForBuild', () => {
+    afterEach(() => { vi.restoreAllMocks(); });
+
+    it('with loaded rows, answers from them and never asks the (cold) engine', async () => {
+        const getFields = installEngine(['CIO-1']);
+        vi.spyOn(console, 'log').mockImplementation(() => undefined);
+        vi.spyOn(RunView.prototype, 'RunView').mockResolvedValue(
+            { Success: true, Results: [storedField('CIO-1', 'id'), storedField('CIO-1', 'name')] } as unknown as RunViewResult,
+        );
+        const loaded = await WithCatalogScope('CI-1', () => LoadScopedFieldsForBuild('INT-1', USER));
+
+        expect(FieldsForBuild('CIO-1', loaded, IntegrationEngineBase.Instance).map(f => f.Name)).toEqual(['id', 'name']);
+        expect(getFields).not.toHaveBeenCalled();
+    });
+
+    it('without loaded rows, reads the engine exactly as before', () => {
+        const getFields = installEngine(['IO-1']);
+        FieldsForBuild('IO-1', null, IntegrationEngineBase.Instance);
+        expect(getFields).toHaveBeenCalledWith('IO-1');
+    });
+});
+
+describe('every schema build reads its fields through the loader', () => {
+    const SRC = readFileSync(join(__dirname, '..', 'resolvers', 'IntegrationDiscoveryResolver.ts'), 'utf-8');
+
+    it('all five build paths pass the loaded rows to the rebuild', () => {
+        const calls = SRC.match(/this\.buildSourceSchemaFromPersistedRows\([\s\S]*?\);/g) ?? [];
+        // ApplySchema, ApplyAll, buildSchemaForConnector, ApplyAllBatch, SchemaEvolution.
+        expect(calls.length).toBe(5);
+        const inline = /await LoadScopedFieldsForBuild\(companyIntegration\.IntegrationID, user\)/;
+        // SchemaEvolution and buildSchemaForConnector load once into `scopedFields`: evolution's
+        // field-map reconcile reads the same rows, and buildSchemaForConnector's prefetched (batch)
+        // branch needs them for its inactive-row warnings without running the rebuild at all.
+        const hoisted = /scopedFields,?\s*\)/;
+        for (const call of calls) {
+            expect(inline.test(call) || hoisted.test(call)).toBe(true);
+        }
+        const hoistedCalls = calls.filter(c => !inline.test(c));
+        expect(hoistedCalls).toHaveLength(2);
+        expect(SRC.match(/const scopedFields = await LoadScopedFieldsForBuild\(companyIntegration\.IntegrationID, user\);/g)).toHaveLength(2);
+    });
+
+    it('the rebuild reads fields only through FieldsForBuild, never the engine directly', () => {
+        const start = SRC.indexOf('private buildSourceSchemaFromPersistedRows(');
+        expect(start).toBeGreaterThan(-1);
+        const body = SRC.slice(start, SRC.indexOf('private async runSchemaRefreshPipeline(', start));
+        expect(body).toMatch(/FieldsForBuild\(io\.ID, scopedFields, engine\)/);
+        expect(body).not.toMatch(/engine\.GetIntegrationObjectFields\(/);
+    });
+});
+
+/**
+ * A refresh's field-map reconcile and the dependency map read the same cold per-connection fields.
+ * Reconcile is the destructive one: an empty field list there DISABLES every Active field map on the
+ * object, on a refresh that reports success. The dependency map only needs FK edges, which the scope
+ * carries without any field row being warm.
+ */
+describe('a refresh reads the connection\'s fields, never a cold engine cache', () => {
+    const SRC = readFileSync(join(__dirname, '..', 'resolvers', 'IntegrationDiscoveryResolver.ts'), 'utf-8');
+    const body = (start: string, end: string) => {
+        const i = SRC.indexOf(start);
+        expect(i).toBeGreaterThan(-1);
+        return SRC.slice(i, SRC.indexOf(end, i + start.length));
+    };
+
+    it('the field-map reconcile reads through FieldsForBuild with the loaded rows', () => {
+        const reconcile = body('private async reconcileFieldMapsForEntityMap(', '\n    }\n');
+        expect(reconcile).toMatch(/FieldsForBuild\(integrationObjectID, scopedFields, IntegrationEngineBase\.Instance\)/);
+        expect(reconcile).not.toMatch(/\.GetIntegrationObjectFields\(/);
+        expect(SRC).toMatch(/this\.reconcileFieldMapsForEntityMap\(em, io\.ID, user, md, autoEnableNewColumns, scopedFields\)/);
+    });
+
+    it('the re-key check reads the catalog key through FieldsForBuild with the loaded rows', () => {
+        expect(SRC).toMatch(/CatalogIdentityKey\(\s*FieldsForBuild\(io\.ID, scopedFields, IntegrationEngineBase\.Instance\)\s*\)/);
+    });
+
+    it('nothing in the resolver reads field rows from the engine directly', () => {
+        expect(SRC).not.toMatch(/\.GetIntegrationObjectFields\(/);
+    });
+
+    it('the dependency map reads FK parents from the edge set, not from field rows', () => {
+        const deps = body('private computeObjectDependencyNames(', '\n    }\n');
+        expect(deps).toMatch(/engine\.GetRelatedIntegrationObjectIDs\(io\.ID\)/);
+        expect(deps).not.toMatch(/GetIntegrationObjectFields\(/);
+    });
+});