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

package/src/__tests__/MediaAccessKeys.test.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect } from 'vitest';
+import { createHmac } from 'node:crypto';
 import jwt from 'jsonwebtoken';
+import { GetGlobalObjectStore } from '@memberjunction/global';
 import { MediaAccessKeyManager, MEDIA_ACCESS_TOKEN_TYPE } from '../rest/MediaAccessKeys.js';
 
 /**
@@ -53,16 +55,61 @@ describe('MediaAccessKeyManager', () => {
     expect(km.Verify(Token).Valid).toBe(false);
   });
 
-  it('rejects a token with the wrong typ even if validly signed', () => {
+  it('rejects a token with the wrong typ even when validly signed with the real secret', () => {
     const km = MediaAccessKeyManager.Instance;
-    // Mint a valid token, then read the real secret out of a known-good token by
-    // re-signing through the manager is not possible; instead assert that a token
-    // whose typ differs is rejected by signing a structurally-valid JWT with a
-    // foreign secret (signature failure also yields false, which is the safe outcome).
-    const foreign = jwt.sign({ fileId: 'FILE-5', userId: 'USER-5', typ: 'something-else' }, 'foreign-secret', {
-      algorithm: 'HS256',
-      expiresIn: 3600,
-    });
-    expect(km.Verify(foreign).Valid).toBe(false);
+    const uploadToken = km.SignUpload('USER-5').Token;
+    expect(km.Verify(uploadToken).Valid).toBe(false);
+
+    const mediaToken = km.Sign('FILE-5', 'USER-5').Token;
+    expect(km.VerifyUpload(mediaToken).Valid).toBe(false);
+  });
+
+  it('derives a domain-separated HS256 signing key from MJ_BASE_ENCRYPTION_KEY and rejects tokens signed with the raw master key', () => {
+    const store = GetGlobalObjectStore();
+    const savedStoreSecret = store?.['___MEDIA_ACCESS_SECRET___'];
+    const savedEnvKey = process.env.MJ_BASE_ENCRYPTION_KEY;
+    const rawMasterKey = 'test-master-encryption-key-do-not-use-directly';
+
+    try {
+      if (store) {
+        delete store['___MEDIA_ACCESS_SECRET___'];
+      }
+      process.env.MJ_BASE_ENCRYPTION_KEY = rawMasterKey;
+
+      const isolatedKm = new MediaAccessKeyManager();
+      const { Token } = isolatedKm.Sign('FILE-KEY-SEP', 'USER-KEY-SEP');
+
+      // Round-trips through the manager using the derived subkey
+      const verified = isolatedKm.Verify(Token);
+      expect(verified.Valid).toBe(true);
+
+      // Matches the documented HMAC-SHA256 key derivation label
+      const expectedDerivedSecret = createHmac('sha256', rawMasterKey)
+        .update('mj-media-access-token-signing-v1')
+        .digest('base64');
+      const decoded = jwt.verify(Token, expectedDerivedSecret, { algorithms: ['HS256'] });
+      expect(typeof decoded).toBe('object');
+
+      // A JWT signed directly with the raw MJ_BASE_ENCRYPTION_KEY MUST be rejected
+      const forgedWithRawMasterKey = jwt.sign(
+        { fileId: 'FILE-KEY-SEP', userId: 'USER-KEY-SEP', typ: MEDIA_ACCESS_TOKEN_TYPE },
+        rawMasterKey,
+        { algorithm: 'HS256', expiresIn: 3600 },
+      );
+      expect(isolatedKm.Verify(forgedWithRawMasterKey).Valid).toBe(false);
+    } finally {
+      if (savedEnvKey === undefined) {
+        delete process.env.MJ_BASE_ENCRYPTION_KEY;
+      } else {
+        process.env.MJ_BASE_ENCRYPTION_KEY = savedEnvKey;
+      }
+      if (store) {
+        if (savedStoreSecret === undefined) {
+          delete store['___MEDIA_ACCESS_SECRET___'];
+        } else {
+          store['___MEDIA_ACCESS_SECRET___'] = savedStoreSecret;
+        }
+      }
+    }
   });
 });

package/src/__tests__/NewArrivalsDefaultDisabled.test.ts

@@ -0,0 +1,50 @@
+/**
+ * everything.txt is explicit about what a schema refresh does with objects it has just found:
+ * "we create entity maps for all objects that are determined as things that should be now added
+ * but arent, we enable nothing (because the user needs to, after the refresh, then go turn them
+ * on)". These pin that contract at the only place it is expressed - the argument defaults.
+ *
+ * They defaulted TRUE for a period on the claim that a disabled new object never reached a
+ * migration. That claim was wrong: `CreateDisabled` governs only the entity/field MAP status,
+ * new IntegrationObject rows are written Active unconditionally, and phase 4 evolves over
+ * `continuingMaps + newObjects` regardless of the flag. The table is created either way; the
+ * flag decides only whether the object starts SYNCING unasked.
+ *
+ * Read from source rather than by invoking the resolver: the default lives in a type-graphql
+ * decorator, and a test that booted the schema to read it back would be testing type-graphql.
+ */
+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',
+);
+
+function argDefault(name: string): string | null {
+  const m = SRC.match(new RegExp(`@Arg\\("${name}",\\s*\\{\\s*defaultValue:\\s*(true|false)`));
+  return m ? m[1] : null;
+}
+
+describe('new arrivals default to disabled', () => {
+  it('autoEnableNewObjects defaults false', () => {
+    expect(argDefault('autoEnableNewObjects')).toBe('false');
+  });
+
+  it('autoEnableNewColumns defaults false', () => {
+    expect(argDefault('autoEnableNewColumns')).toBe('false');
+  });
+
+  it('the description does not promise auto-adoption', () => {
+    const line = SRC.split('\n').find(l => l.includes('@Arg("autoEnableNewObjects"'));
+    expect(line).toBeDefined();
+    expect(line!).toMatch(/DISABLED/);
+    expect(line!).not.toMatch(/created ENABLED/);
+  });
+
+  it('CreateDisabled is still what carries the decision to the post-restart consumer', () => {
+    // If this coupling is ever renamed, the defaults above stop meaning anything.
+    expect(SRC).toMatch(/CreateDisabled:\s*!autoEnableNewObjects/);
+  });
+});

package/src/__tests__/ObjectNamesByID.test.ts

@@ -0,0 +1,176 @@
+/**
+ * A table selection's ids resolve against the CONNECTION's catalog, and an apply that resolves
+ * nothing builds nothing.
+ *
+ * Inside a catalog scope, `IntegrationListSourceObjects` hands the picker per-connection
+ * (CompanyIntegrationObject) ids. Every name lookup the apply paths ran read only the shared
+ * `MJ: Integration Objects` catalog, so an id-only selection was dropped with a LogError, the
+ * migration ran with an empty table list, CodeGen and the restart still ran, and the apply reported
+ * Success with 0 tables — 118 picked, 0 built, twice, on a WordPress connection.
+ *
+ * These pin the lookup the four resolver paths now share, and — against the source, because the
+ * resolver needs a provider, a connector and an RSU pipeline to invoke — that the apply refuses an
+ * empty resolution before it builds anything.
+ */
+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 { LookupObjectNamesByID, OBJECT_ID_LOOKUP_CHUNK } from '../integration/ObjectNamesByID.js';
+
+const USER = { ID: 'user-1' } as UserInfo;
+type RunViewParams = Parameters<RunView['RunView']>[0];
+type RunViewResult = Awaited<ReturnType<RunView['RunView']>>;
+
+/** An engine holding a per-connection catalog: each row is a CIO id, its shared IO id, and a name. */
+function installEngine(rows: Array<{ ID: string; IntegrationObjectID: string | null; Name: string }>, hasCatalog = true) {
+    vi.spyOn(IntegrationEngineBase, 'Instance', 'get').mockReturnValue({
+        HasCompanyIntegrationCatalog: () => hasCatalog,
+        GetCompanyIntegrationObjects: () => rows,
+    } as unknown as IntegrationEngineBase);
+}
+
+describe('LookupObjectNamesByID', () => {
+    let runView: ReturnType<typeof vi.spyOn>;
+    beforeEach(() => {
+        runView = vi.spyOn(RunView.prototype, 'RunView');
+    });
+    afterEach(() => { vi.restoreAllMocks(); });
+
+    it('resolves per-connection ids from the scope\'s catalog with no query, whatever their case', async () => {
+        installEngine([
+            { ID: 'cio-aaa', IntegrationObjectID: 'io-111', Name: 'posts' },
+            { ID: 'cio-bbb', IntegrationObjectID: null, Name: 'pages' },
+        ]);
+
+        const map = await WithCatalogScope('CI-1', () => LookupObjectNamesByID(['CIO-AAA', 'cio-bbb'], USER));
+
+        expect(map.get('CIO-AAA')).toBe('posts');
+        expect(map.get('CIO-BBB')).toBe('pages');
+        expect(runView).not.toHaveBeenCalled();
+    });
+
+    it('also resolves a shared IntegrationObject id through the row that carries it', async () => {
+        installEngine([{ ID: 'cio-aaa', IntegrationObjectID: 'io-111', Name: 'posts' }]);
+
+        const map = await WithCatalogScope('CI-1', () => LookupObjectNamesByID(['IO-111'], USER));
+
+        expect(map.get('IO-111')).toBe('posts');
+        expect(runView).not.toHaveBeenCalled();
+    });
+
+    it('reads a cache miss straight from the connection\'s catalog: one uncached query, scoped to the connection', async () => {
+        installEngine([{ ID: 'cio-aaa', IntegrationObjectID: null, Name: 'posts' }]);
+        runView.mockResolvedValue({ Success: true, Results: [{ ID: 'cio-new', Name: 'comments' }] } as unknown as RunViewResult);
+
+        const map = await WithCatalogScope('CI-1', () => LookupObjectNamesByID(['cio-aaa', 'cio-new'], USER));
+
+        expect(runView).toHaveBeenCalledTimes(1);
+        const params = runView.mock.calls[0][0] as RunViewParams;
+        expect(params.EntityName).toBe('MJ: Company Integration Objects');
+        expect(params.ExtraFilter).toBe("CompanyIntegrationID='CI-1' AND ID IN ('CIO-NEW')");
+        expect(params.BypassCache).toBe(true);
+        expect(params.IgnoreMaxRows).toBe(true);
+        expect(map.get('CIO-NEW')).toBe('comments');
+        expect(map.get('CIO-AAA')).toBe('posts');
+    });
+
+    it(`reads cache misses ${OBJECT_ID_LOOKUP_CHUNK} ids per query`, async () => {
+        installEngine([]);
+        runView.mockResolvedValue({ Success: true, Results: [] } as unknown as RunViewResult);
+        const ids = Array.from({ length: OBJECT_ID_LOOKUP_CHUNK + 1 }, (_, i) => `cio-${i}`);
+
+        await WithCatalogScope('CI-1', () => LookupObjectNamesByID(ids, USER));
+
+        const perConnection = runView.mock.calls.filter(c => (c[0] as RunViewParams).EntityName === 'MJ: Company Integration Objects');
+        expect(perConnection).toHaveLength(2);
+    });
+
+    it('falls through to the shared catalog only for ids neither tier resolved', async () => {
+        installEngine([]);
+        runView
+            .mockResolvedValueOnce({ Success: true, Results: [] } as unknown as RunViewResult)
+            .mockResolvedValueOnce({ Success: true, Results: [{ ID: 'io-9', Name: 'users' }] } as unknown as RunViewResult);
+
+        const map = await WithCatalogScope('CI-1', () => LookupObjectNamesByID(['io-9'], USER));
+
+        expect(runView).toHaveBeenCalledTimes(2);
+        expect((runView.mock.calls[1][0] as RunViewParams).EntityName).toBe('MJ: Integration Objects');
+        expect(map.get('IO-9')).toBe('users');
+    });
+
+    it('outside a catalog scope, queries only the shared catalog — exactly as before', async () => {
+        installEngine([{ ID: 'cio-aaa', IntegrationObjectID: null, Name: 'posts' }]);
+        runView.mockResolvedValue({ Success: true, Results: [{ ID: 'io-1', Name: 'users' }] } as unknown as RunViewResult);
+
+        const map = await LookupObjectNamesByID(['io-1'], USER);
+
+        expect(runView).toHaveBeenCalledTimes(1);
+        const params = runView.mock.calls[0][0] as RunViewParams;
+        expect(params.EntityName).toBe('MJ: Integration Objects');
+        expect(params.ExtraFilter).toBe("ID='IO-1'");
+        expect(map.get('IO-1')).toBe('users');
+    });
+
+    it('quotes ids, so a stray quote cannot break out of the filter', async () => {
+        installEngine([]);
+        runView.mockResolvedValue({ Success: true, Results: [] } as unknown as RunViewResult);
+
+        await LookupObjectNamesByID(["x' OR 1=1 --"], USER);
+
+        expect((runView.mock.calls[0][0] as RunViewParams).ExtraFilter).toBe("ID='X'' OR 1=1 --'");
+    });
+
+    it('escapes ids the way every filter does: a NUL byte never reaches the query', async () => {
+        installEngine([]);
+        runView.mockResolvedValue({ Success: true, Results: [] } as unknown as RunViewResult);
+
+        await LookupObjectNamesByID(['io-1\0'], USER);
+
+        expect((runView.mock.calls[0][0] as RunViewParams).ExtraFilter).toBe("ID='IO-1'");
+    });
+
+    it('asks nothing for an empty selection', async () => {
+        installEngine([]);
+        expect((await LookupObjectNamesByID([], USER)).size).toBe(0);
+        expect(runView).not.toHaveBeenCalled();
+    });
+});
+
+describe('the resolver uses the lookup, and refuses to build an empty resolution', () => {
+    const source = readFileSync(join(__dirname, '../resolvers/IntegrationDiscoveryResolver.ts'), 'utf8');
+    const body = (signature: string): string => {
+        const start = source.indexOf(signature);
+        expect(start, `not found: ${signature}`).toBeGreaterThan(-1);
+        return source.slice(start, source.indexOf('\n    }\n', start));
+    };
+
+    it.each([
+        'private async resolveSelectionPlan(',
+        'private async resolveSourceObjectNames(',
+        'private async resolveSourceObjectsToNames(',
+        'private async resolveObjectInputs(',
+    ])('%s resolves ids through LookupObjectNamesByID, never the shared catalog alone', (signature) => {
+        const fn = body(signature);
+        expect(fn).toContain('LookupObjectNamesByID(');
+        expect(fn).not.toContain("EntityName: 'MJ: Integration Objects'");
+    });
+
+    it('IntegrationApplyAll refuses an empty resolution BEFORE the schema build', () => {
+        const resolve = source.indexOf('const resolved = await this.resolveSourceObjectsToNames(input.SourceObjects, sourceSchema, user);');
+        expect(resolve).toBeGreaterThan(-1);
+        const refusal = source.indexOf('input.SourceObjects.length > 0 && resolvedNames.length === 0', resolve);
+        const build = source.indexOf('this.buildSchemaForConnector(', resolve);
+        expect(refusal).toBeGreaterThan(resolve);
+        expect(refusal).toBeLessThan(build);
+        expect(source.slice(refusal, build)).toContain('Success: false');
+        expect(source.slice(refusal, build)).toContain('Apply refused');
+    });
+
+    it('the batch flow throws on an empty resolution, mirroring the filtered flow', () => {
+        expect(source).toContain('connInput.SourceObjects.length > 0 && resolvedNames.length === 0');
+        expect(source).toContain('No source objects resolved');
+    });
+});

package/src/__tests__/PipelineProgressResolver.filter.test.ts

@@ -0,0 +1,58 @@
+import 'reflect-metadata';
+import { describe, it, expect, vi } from 'vitest';
+
+vi.mock('type-graphql', () => {
+    const noopDecorator = () => () => undefined;
+    return {
+        Resolver: noopDecorator,
+        Mutation: noopDecorator,
+        Query: noopDecorator,
+        Subscription: noopDecorator,
+        ObjectType: noopDecorator,
+        InputType: noopDecorator,
+        Field: noopDecorator,
+        Arg: noopDecorator,
+        Args: noopDecorator,
+        Ctx: noopDecorator,
+        PubSub: noopDecorator,
+        Root: noopDecorator,
+        Float: class {},
+        Int: class {},
+        ID: class {},
+    };
+});
+
+import { PipelineProgressFilter, type PipelineProgressNotification } from '../resolvers/PipelineProgressResolver';
+
+const RUN_ID = 'AA11BB22-0000-4000-8000-000000000001';
+const OTHER_RUN_ID = 'CC33DD44-0000-4000-8000-000000000002';
+
+function makePayload(pipelineRunID: string): PipelineProgressNotification {
+    return {
+        PipelineRunID: pipelineRunID,
+        Stage: 'extract',
+        TotalItems: 100,
+        ProcessedItems: 25,
+        ElapsedMs: 500,
+        PercentComplete: 25,
+    };
+}
+
+describe('PipelineProgressFilter', () => {
+    it('delivers when PipelineRunID matches exactly', () => {
+        expect(PipelineProgressFilter({ payload: makePayload(RUN_ID), args: { pipelineRunID: RUN_ID } })).toBe(true);
+    });
+
+    it('delivers when PipelineRunID differs only in UUID casing (SQL Server uppercase vs client lowercase)', () => {
+        expect(
+            PipelineProgressFilter({
+                payload: makePayload(RUN_ID.toUpperCase()),
+                args: { pipelineRunID: RUN_ID.toLowerCase() },
+            })
+        ).toBe(true);
+    });
+
+    it('rejects notifications for a different pipeline run', () => {
+        expect(PipelineProgressFilter({ payload: makePayload(OTHER_RUN_ID), args: { pipelineRunID: RUN_ID } })).toBe(false);
+    });
+});

package/src/__tests__/PostRestartMapsInCatalogScope.test.ts

@@ -0,0 +1,146 @@
+/**
+ * The per-connection catalog answers correctly only when a read happens INSIDE a scope naming the
+ * connection; an unscoped read falls back to the shared catalog by design. Every request-time entry
+ * point enters the scope in the resolver. The one entry point that is NOT request-time is the
+ * post-restart consumer in index.ts: after the RSU restarts the process it introspects the connector
+ * to build the entity and field maps, and nothing upstream of it has entered a scope.
+ *
+ * Unscoped, that introspection sees only the declared fields, so every column this connection's own
+ * discovery sampled gets a table column (the RSU built the schema in scope) but no field map, and its
+ * values land in the overflow JSON instead of the column. On the sandbox that was 69 of 556 columns.
+ *
+ * Entering the scope is not enough on its own. In a freshly restarted process nothing has loaded the
+ * connection's catalog, so a synchronous entry reads the shared one; and an async entry loads objects
+ * but not fields, so a connector reading fields gets the connection's objects with none. These run
+ * the real catalog scope from a cold cache, with only the database reads stubbed.
+ */
+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 {
+    CATALOG_FIELD_COLUMNS,
+    CATALOG_OBJECT_COLUMNS,
+    ENTITY_COMPANY_INTEGRATION_OBJECTS,
+    ENTITY_COMPANY_INTEGRATION_OBJECT_FIELDS,
+    IntegrationEngineBase,
+} from '@memberjunction/integration-engine-base';
+import { CatalogFieldCacheStats, EvictCatalogScope, RunInCatalogScope, WithCatalogScope } from '@memberjunction/integration-engine';
+import { IntrospectInCatalogScope } from '../integration/PostRestartIntrospect.js';
+
+const SRC = readFileSync(join(__dirname, '..', 'index.ts'), 'utf-8');
+
+const INTEGRATION = 'AAAAAAAA-1111-2222-3333-444444444444';
+const CONN = 'CCCCCCCC-0000-0000-0000-000000000001';
+const MEMBERS = 'BBBBBBBB-0000-0000-0000-000000000001';
+const USER = { ID: 'u-1' } as UserInfo;
+type RunViewParams = Parameters<RunView['RunView']>[0];
+type RunViewResult = Awaited<ReturnType<RunView['RunView']>>;
+
+function row(columns: readonly string[], values: Record<string, unknown>) {
+    const all: Record<string, unknown> = {};
+    for (const c of columns) all[c] = null;
+    Object.assign(all, values);
+    return { Fields: Object.keys(all).map(Name => ({ Name })), Get: (c: string) => all[c] };
+}
+const membersRow = row(CATALOG_OBJECT_COLUMNS, {
+    ID: MEMBERS, CompanyIntegrationID: CONN, IntegrationID: INTEGRATION, Name: 'Members', Status: 'Active', Sequence: 1,
+});
+// `region` is the column this connection's discovery sampled; the connector never declared it.
+const memberFields = [
+    row(CATALOG_FIELD_COLUMNS, { ID: 'f0', CompanyIntegrationObjectID: MEMBERS, Name: 'id', Status: 'Active', Sequence: 1 }),
+    row(CATALOG_FIELD_COLUMNS, { ID: 'f1', CompanyIntegrationObjectID: MEMBERS, Name: 'region', Status: 'Active', Sequence: 2 }),
+];
+
+let objectsInDb: ReturnType<typeof row>[] = [];
+let fieldReadFails = false;
+let fieldReads = 0;
+
+function answer(p: RunViewParams): RunViewResult {
+    const ok = (Results: unknown[]) => ({ Success: true, Results } as unknown as RunViewResult);
+    if (p.EntityName === ENTITY_COMPANY_INTEGRATION_OBJECTS) return ok(objectsInDb);
+    if (p.EntityName === ENTITY_COMPANY_INTEGRATION_OBJECT_FIELDS && p.ResultType === 'simple') return ok([]); // the edge set
+    if (p.EntityName === ENTITY_COMPANY_INTEGRATION_OBJECT_FIELDS) {
+        fieldReads++;
+        if (fieldReadFails) return { Success: false, ErrorMessage: 'connection reset', Results: [] } as unknown as RunViewResult;
+        const oid = /CompanyIntegrationObjectID = '([^']+)'/.exec(String(p.ExtraFilter ?? ''))?.[1] ?? '';
+        return ok(oid.toUpperCase() === MEMBERS ? memberFields : []);
+    }
+    return ok([]);
+}
+
+/** What a REST connector's IntrospectSchema reads: the object by integration + name, then its fields. */
+async function introspectMembers(): Promise<string[]> {
+    const base = IntegrationEngineBase.Instance;
+    const obj = base.GetIntegrationObject(INTEGRATION, 'Members');
+    return obj ? base.GetIntegrationObjectFields(obj.ID).map(f => f.Name) : [];
+}
+
+beforeEach(() => {
+    EvictCatalogScope();                     // a freshly restarted process: nothing loaded, nothing warm
+    objectsInDb = [membersRow];
+    fieldReadFails = false;
+    fieldReads = 0;
+    vi.spyOn(RunView.prototype, 'RunView').mockImplementation(async (p: RunViewParams) => answer(p));
+    vi.spyOn(IntegrationEngineBase.Instance, 'ProviderToUse', 'get')
+        .mockImplementation(() => ({ EntityByName: (n: string) => ({ Name: n }) }) as never);
+    IntegrationEngineBase.Instance.SeedForTesting({
+        IntegrationObjects: [], IntegrationObjectFields: [], CompanyIntegrationObjects: [], CompanyIntegrationObjectFields: [],
+    });
+});
+afterEach(() => { vi.restoreAllMocks(); });
+
+describe('post-restart introspection sees the connection\'s own fields from a cold catalog', () => {
+    it('introspects the per-connection fields, sampled column included', async () => {
+        const fields = await IntrospectInCatalogScope(CONN, ['Members'], introspectMembers, USER);
+        expect(fields).toEqual(['id', 'region']);
+    });
+
+    it('releases its pins after the introspection', async () => {
+        await IntrospectInCatalogScope(CONN, ['Members'], introspectMembers, USER);
+        expect(CatalogFieldCacheStats().Pinned).toBe(0);
+    });
+
+    it('releases its pins when the introspection throws, and the error propagates', async () => {
+        await expect(IntrospectInCatalogScope(CONN, ['Members'], async () => { throw new Error('vendor 503'); }, USER))
+            .rejects.toThrow('vendor 503');
+        expect(CatalogFieldCacheStats().Pinned).toBe(0);
+    });
+
+    it('a failed field read throws instead of introspecting an object with no fields', async () => {
+        fieldReadFails = true;
+        const introspect = vi.fn(introspectMembers);
+        await expect(IntrospectInCatalogScope(CONN, ['Members'], introspect, USER)).rejects.toThrow();
+        expect(introspect).not.toHaveBeenCalled();
+    });
+
+    it('a connection with no catalog of its own warms nothing and introspects as before', async () => {
+        objectsInDb = [];
+        const introspect = vi.fn(async () => 'shared');
+        expect(await IntrospectInCatalogScope(CONN, ['Members'], introspect, USER)).toBe('shared');
+        expect(introspect).toHaveBeenCalledOnce();
+        expect(fieldReads).toBe(0);
+    });
+
+    it('why: a synchronous scope on a cold process reads the shared catalog — no object at all', async () => {
+        expect(await RunInCatalogScope(CONN, introspectMembers)).toEqual([]);
+    });
+
+    it('why: an async scope without the warm finds the object but none of its fields', async () => {
+        expect(await WithCatalogScope(CONN, introspectMembers, USER)).toEqual([]);
+    });
+});
+
+describe('index.ts wires the post-restart introspection through it', () => {
+    it('introspects through IntrospectInCatalogScope for the item\'s connection and objects', () => {
+        // Whitespace-tolerant: formatters may wrap the call.
+        expect(SRC).toMatch(
+            /const schema = await IntrospectInCatalogScope\(\s*item\.CompanyIntegrationID\s*,\s*item\.SourceObjectNames\s*,\s*\(\)\s*=>\s*introspect\(\s*companyIntegration\s*,\s*systemUser\s*\)\s*,\s*systemUser\s*,?\s*\)/,
+        );
+    });
+
+    it('has no bare or synchronously scoped post-restart introspect call left', () => {
+        expect(SRC).not.toMatch(/const schema = await introspect\(companyIntegration, systemUser\)/);
+        expect(SRC).not.toMatch(/RunInCatalogScope\(\s*item\.CompanyIntegrationID/);
+    });
+});

package/src/__tests__/QuerySystemUserResolver.childRows.test.ts

@@ -0,0 +1,80 @@
+/**
+ * The child rows `CreateQueryExtended` / `UpdateQueryExtended` return are mapped column by column
+ * from the saved query's rows. A column left out of that mapping reaches the client as `null`
+ * whatever is stored, so every column the GraphQL types carry must be mapped: a field's
+ * nullability, entity-field source and `schema.object` source, a parameter's server-set flag and
+ * a Query Entities row's alternate base view.
+ */
+import 'reflect-metadata';
+import { describe, it, expect, vi } from 'vitest';
+
+vi.mock('type-graphql', () => {
+    const decoratorFactory = (..._args: unknown[]) => (..._decorated: unknown[]) => undefined;
+    const exportNames = ['Arg', 'Ctx', 'Field', 'InputType', 'Mutation', 'ObjectType', 'Resolver', 'PubSub', 'Int', 'Float'];
+    return { ...Object.fromEntries(exportNames.map((name) => [name, decoratorFactory])), registerEnumType: () => undefined };
+});
+vi.mock('@memberjunction/core-entities-server', () => ({ MJQueryEntityServer: class {} }));
+vi.mock('../generic/DeleteOptionsInput.js', () => ({ DeleteOptionsInput: class {} }));
+vi.mock('../generated/generated.js', () => ({
+    MJQuery_: class {}, MJQueryField_: class {}, MJQueryParameter_: class {}, MJQueryEntity_: class {}, MJQueryPermission_: class {},
+    MJQueryResolver: class {
+        protected async MapFieldNamesToCodeNames(_entityName: string, values: Record<string, unknown>) {
+            return values;
+        }
+    },
+}));
+
+import { MJQueryResolverExtended } from '../resolvers/QuerySystemUserResolver.js';
+
+type MappedRows = { Fields: Record<string, unknown>[]; Parameters: Record<string, unknown>[]; Entities: Record<string, unknown>[] };
+
+const STAMP = new Date('2026-10-28T00:00:00Z');
+
+const FIELD = {
+    ID: 'field-1', QueryID: 'query-1', Query: 'Q', Name: 'UserName', Description: 'The name.', Sequence: 1, SQLBaseType: 'nvarchar', SQLFullType: 'nvarchar(100)',
+    SourceEntityID: 'entity-users', SourceEntity: 'MJ: Users', SourceFieldName: 'Name', SourceEntityFieldID: 'field-users-name', SourceEntityField: 'Name',
+    SourceObjectName: null, IsNullable: false, IsComputed: false, ComputationDescription: null, IsSummary: false, SummaryDescription: null,
+    DetectionMethod: 'Database', AutoDetectConfidenceScore: null, __mj_CreatedAt: STAMP, __mj_UpdatedAt: STAMP,
+};
+
+const OBJECT_FIELD = { ...FIELD, ID: 'field-2', Name: 'Code', SourceEntityID: null, SourceEntity: null, SourceEntityFieldID: null, SourceEntityField: null, SourceFieldName: 'Code', SourceObjectName: 'fixture.Customer', IsNullable: true };
+
+const PARAMETER = {
+    ID: 'parameter-1', QueryID: 'query-1', Query: 'Q', Name: 'OwnerID', Description: null, Type: 'string', IsRequired: true, DefaultValue: null, SampleValue: null,
+    ValidationFilters: null, IsServerSet: true, DetectionMethod: 'Manual', AutoDetectConfidenceScore: null, __mj_CreatedAt: STAMP, __mj_UpdatedAt: STAMP,
+};
+
+const ENTITY = {
+    ID: 'link-1', QueryID: 'query-1', Query: 'Q', EntityID: 'entity-users', Entity: 'MJ: Users', AlternateBaseViewID: 'abv-active', AlternateBaseView: 'Active Users',
+    DetectionMethod: 'Parser', AutoDetectConfidenceScore: 1, __mj_CreatedAt: STAMP, __mj_UpdatedAt: STAMP,
+};
+
+async function mapped(): Promise<MappedRows> {
+    const build = (MJQueryResolverExtended.prototype as unknown as {
+        buildSuccessResult(entity: unknown, user: unknown, provider: unknown): Promise<MappedRows>;
+    }).buildSuccessResult;
+    const entity = { GetAll: () => ({ ID: 'query-1' }), QueryFields: [FIELD, OBJECT_FIELD], QueryParameters: [PARAMETER], QueryEntities: [ENTITY], QueryPermissions: [] };
+    return build.call(new MJQueryResolverExtended(), entity, {}, {});
+}
+
+describe('QuerySystemUserResolver: the saved query\'s child rows are returned with every column', () => {
+    it('returns a field\'s nullability and its entity-field source', async () => {
+        const { Fields } = await mapped();
+        expect(Fields[0]).toMatchObject({ IsNullable: false, SourceEntityFieldID: 'field-users-name', SourceEntityField: 'Name', SourceObjectName: null });
+    });
+
+    it('returns the schema.object source of a field no entity backs', async () => {
+        const { Fields } = await mapped();
+        expect(Fields[1]).toMatchObject({ IsNullable: true, SourceObjectName: 'fixture.Customer', SourceEntityFieldID: null });
+    });
+
+    it('returns a parameter\'s server-set flag', async () => {
+        const { Parameters } = await mapped();
+        expect(Parameters[0]).toMatchObject({ IsServerSet: true });
+    });
+
+    it('returns a Query Entities row\'s alternate base view', async () => {
+        const { Entities } = await mapped();
+        expect(Entities[0]).toMatchObject({ AlternateBaseViewID: 'abv-active', AlternateBaseView: 'Active Users' });
+    });
+});