@memberjunction/server 6.1.0-edge.3 → 6.1.0-edge.4

package/src/__tests__/CustomColumnPromoterOnePass.test.ts

@@ -0,0 +1,387 @@
+/**
+ * The promoter's one-pass batch, spread recovery, and idempotent spread.
+ *
+ * Before: PromoteForSync ran the FULL RSU pipeline (migrate + CodeGen + compile) once per entity —
+ * a sync touching N entities with candidates paid N passes where the batch API exists to pay one.
+ * And a run interrupted between ADD COLUMN and the value spread was a dead end: the column and
+ * field map existed, so the terminate check skipped the key as done, capture stopped (the key was
+ * no longer unmapped), and rows kept the value only in the overflow JSON forever.
+ *
+ * These tests drive PromoteForSync with plan/metadata/spread stubbed at the seam and
+ * RuntimeSchemaManager mocked, plus the two pure-ish decision points (resolveWorkItems,
+ * spreadOneRow) directly.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+const runPipelineBatchMock = vi.fn();
+vi.mock('@memberjunction/schema-engine', () => ({
+    RuntimeSchemaManager: {
+        get Instance() {
+            return { RunPipelineBatch: runPipelineBatchMock };
+        },
+    },
+}));
+
+vi.mock('@memberjunction/integration-schema-builder', () => ({
+    DDLGenerator: class {
+        GenerateAlterTableAddColumn(schema: string, table: string, col: { ColumnName: string }): string {
+            return `ALTER TABLE [${schema}].[${table}] ADD [${col.ColumnName}]`;
+        }
+    },
+}));
+
+// The engine package registers a singleton hook at import; neutralize it.
+vi.mock('@memberjunction/integration-engine', () => ({
+    IntegrationEngine: { Instance: { SetPostSyncSchemaPromotionCallback: vi.fn() } },
+    CUSTOM_OVERFLOW_COLUMN: '__mj_integration_CustomFields',
+    CONTENT_HASH_COLUMN: '__mj_integration_ContentHash',
+    computeContentHash: (mapped: Record<string, unknown>) => `hash:${Object.keys(mapped).sort().join(',')}`,
+    // Mirror of the real sanitizer, close enough for these fixtures (plain identifiers pass through).
+    sanitizeColumnName: (key: string) => key.replace(/[^A-Za-z0-9_]/g, '_'),
+}));
+
+import { IntegrationCustomColumnPromoter } from '../integration/CustomColumnPromoter.js';
+import type { UserInfo, IMetadataProvider, EntityInfo } from '@memberjunction/core';
+
+type AnyPromoter = IntegrationCustomColumnPromoter & Record<string, unknown>;
+
+const user = { ID: 'u1' } as unknown as UserInfo;
+
+function makeProvider() {
+    return {
+        Refresh: vi.fn().mockResolvedValue(undefined),
+        EntityByName: vi.fn().mockReturnValue(undefined),
+        PlatformKey: 'sqlserver',
+    } as unknown as IMetadataProvider;
+}
+
+function workItem(sourceKey: string, opts: Partial<{ needsColumn: boolean; needsFieldMap: boolean; recoverSpread: boolean }> = {}) {
+    return {
+        candidate: { Key: sourceKey, Inferred: { SchemaFieldType: 'nvarchar(100)' } },
+        sourceKey,
+        columnName: sourceKey,
+        needsColumn: opts.needsColumn ?? true,
+        needsFieldMap: opts.needsFieldMap ?? true,
+        recoverSpread: opts.recoverSpread ?? false,
+    };
+}
+
+function stubPromoter(
+    provider: IMetadataProvider,
+    planByEntity: Record<string, ReturnType<typeof workItem>[]>,
+    staleByEntity: Record<string, Array<{ sourceKey: string; columnName: string }>> = {},
+) {
+    const promoter = new IntegrationCustomColumnPromoter(user, provider) as AnyPromoter;
+    const p = promoter as unknown as {
+        resolveIntegrationID: unknown; planWorkForEntity: unknown;
+        createIntegrationObjectFields: unknown; createFieldMaps: unknown; spreadAndRebaseline: unknown;
+        buildSchemaInput: unknown; activeFieldMaps: unknown; purgeStaleOverflowKeys: unknown;
+    };
+    // CompletePromotion re-reads the active field maps (it must: post-restart it has no plan to
+    // trust). That is a RunView, so it is stubbed at the seam like the other DB touches.
+    p.activeFieldMaps = vi.fn().mockResolvedValue(new Map<string, string>());
+    p.resolveIntegrationID = vi.fn().mockResolvedValue('int-1');
+    p.planWorkForEntity = vi.fn().mockImplementation(async (_ci: string, entityName: string) => {
+        const work = planByEntity[entityName];
+        if (!work) return null;
+        return {
+            entityInfo: { Name: entityName, SchemaName: 'mjc', BaseTable: entityName } as unknown as EntityInfo,
+            entityMap: { ID: `em-${entityName}`, ExternalObjectName: entityName.toLowerCase() },
+            work,
+            stale: staleByEntity[entityName] ?? [],
+        };
+    });
+    const iof = vi.fn().mockResolvedValue(undefined);
+    const maps = vi.fn().mockResolvedValue(undefined);
+    const spread = vi.fn().mockResolvedValue(undefined);
+    const purge = vi.fn().mockResolvedValue(undefined);
+    p.createIntegrationObjectFields = iof;
+    p.createFieldMaps = maps;
+    p.spreadAndRebaseline = spread;
+    p.purgeStaleOverflowKeys = purge;
+    return { promoter: promoter as IntegrationCustomColumnPromoter, iof, maps, spread, purge };
+}
+
+beforeEach(() => {
+    runPipelineBatchMock.mockReset();
+});
+
+describe('PromoteForSync — one batched RSU pass', () => {
+    it('runs ONE RunPipelineBatch for all entities instead of one pipeline per entity', async () => {
+        const provider = makeProvider();
+        const { promoter } = stubPromoter(provider, {
+            A: [workItem('a1')],
+            B: [workItem('b1')],
+            C: [workItem('c1')],
+        });
+        runPipelineBatchMock.mockResolvedValue({
+            Results: [{ Success: true }, { Success: true }, { Success: true }],
+            SuccessCount: 3, FailureCount: 0, TotalCount: 3,
+        });
+
+        const result = await promoter.PromoteForSync('ci-1', ['A', 'B', 'C']);
+
+        expect(runPipelineBatchMock).toHaveBeenCalledTimes(1);
+        expect(runPipelineBatchMock.mock.calls[0][0]).toHaveLength(3);
+        expect(result.Promoted).toBe(true);
+        expect(result.ColumnsAdded).toEqual([
+            { EntityName: 'A', ColumnName: 'a1' },
+            { EntityName: 'B', ColumnName: 'b1' },
+            { EntityName: 'C', ColumnName: 'c1' },
+        ]);
+        // ONE metadata refresh for the whole batch — before any spread reads the field list.
+        expect((provider as unknown as { Refresh: ReturnType<typeof vi.fn> }).Refresh).toHaveBeenCalledTimes(1);
+    });
+
+    it('registers the follow-up as promote-columns PendingWork, and does NOT skip the restart', async () => {
+        // The restart is what loads the regenerated entity classes, so everything downstream of the
+        // DDL belongs after it. Skipping the restart to finish inline is what left promoted columns
+        // invisible to GraphQL; skipping the commit left the database carrying columns git had no
+        // record of. Both flags are optional and RSU treats absent as false, so omitting them IS
+        // commit + restart — no caller or platform change required.
+        const provider = makeProvider();
+        const { promoter } = stubPromoter(provider, { A: [workItem('a1')], B: [workItem('b1')] });
+        runPipelineBatchMock.mockResolvedValue({
+            Results: [{ Success: true }, { Success: true }], SuccessCount: 2, FailureCount: 0, TotalCount: 2,
+        });
+
+        await promoter.PromoteForSync('ci-1', ['A', 'B']);
+
+        const inputs = runPipelineBatchMock.mock.calls[0][0] as Array<Record<string, unknown>>;
+        for (const input of inputs) {
+            expect(input.SkipRestart).toBeUndefined();
+            expect(input.SkipGitCommit).toBeUndefined();
+        }
+        // Carried on the FIRST input: RSU restarts once for the whole batch, so one payload
+        // describes every entity in the pass.
+        const pending = (inputs[0].PendingWork as Array<Record<string, unknown>>)[0];
+        expect(pending.WorkType).toBe('promote-columns');
+        expect(pending.CompanyIntegrationID).toBe('ci-1');
+        expect(inputs[1].PendingWork).toBeUndefined();
+
+        // The destination names are CARRIED, not recomputed — uniqueColumnName may have suffixed
+        // one to dodge a collision, and re-deriving it post-restart could pick a different name.
+        const promoted = pending.PromotedColumns as Array<{ EntityName: string; Columns: Array<{ SourceKey: string; ColumnName: string }> }>;
+        expect(promoted.map(p => p.EntityName)).toEqual(['A', 'B']);
+        expect(promoted[0].Columns[0]).toMatchObject({ ColumnName: 'a1' });
+    });
+
+    it('a failed migration leaves ITS entity captured for retry and does not stop the others', async () => {
+        const provider = makeProvider();
+        const { promoter, spread } = stubPromoter(provider, {
+            A: [workItem('a1')],
+            B: [workItem('b1')],
+        });
+        runPipelineBatchMock.mockResolvedValue({
+            Results: [{ Success: false, ErrorMessage: 'boom' }, { Success: true }],
+            SuccessCount: 1, FailureCount: 1, TotalCount: 2,
+        });
+
+        const result = await promoter.PromoteForSync('ci-1', ['A', 'B']);
+
+        // A's DDL failed → nothing written, not counted, left captured for retry.
+        // B's DDL succeeded → COUNTED (SchemaUpdatePending is derived from this list, and the
+        // client keys its "workspace updating" state off it), but its metadata and spread are NOT
+        // done here: the batch restarts, so the post-restart consumer owns them. Doing them inline
+        // as well would duplicate the work — and for B it would not run at all, since `pm2 restart`
+        // ends this process.
+        expect(result.ColumnsAdded).toEqual([{ EntityName: 'B', ColumnName: 'b1' }]);
+        expect(spread).not.toHaveBeenCalled();
+    });
+
+    it('purges stale staged keys BEFORE the pipeline, even with nothing to promote', async () => {
+        // The residue case: every key is already promoted, so there is no work and no DDL — but the
+        // staged JSON still carries the keys and nothing else will ever clear them. The purge must
+        // run anyway, and must run before any migration (it is not evidence a column is missing).
+        const provider = makeProvider();
+        const { promoter, purge } = stubPromoter(
+            provider,
+            { A: [] },
+            { A: [{ sourceKey: 'roundId', columnName: 'roundId' }] },
+        );
+
+        const result = await promoter.PromoteForSync('ci-1', ['A']);
+
+        expect(purge).toHaveBeenCalledTimes(1);
+        expect(purge.mock.calls[0][3]).toEqual([{ sourceKey: 'roundId', columnName: 'roundId' }]);
+        expect(runPipelineBatchMock).not.toHaveBeenCalled();
+        expect(result.Promoted).toBe(false);
+    });
+
+    it('a spread-recovery-only pass runs NO pipeline and reports no columns added', async () => {
+        const provider = makeProvider();
+        const { promoter, spread } = stubPromoter(provider, {
+            A: [workItem('a1', { needsColumn: false, needsFieldMap: false, recoverSpread: true })],
+        });
+
+        const result = await promoter.PromoteForSync('ci-1', ['A']);
+
+        // No DDL to run — the batch API is never touched, and SchemaUpdatePending stays honest.
+        expect(runPipelineBatchMock).not.toHaveBeenCalled();
+        expect(result.Promoted).toBe(false);
+        expect(result.ColumnsAdded).toEqual([]);
+        // But the backfill DID run — that is the whole point of the recovery item.
+        expect(spread).toHaveBeenCalledTimes(1);
+    });
+});
+
+describe('resolveWorkItems — the terminate check becomes spread recovery', () => {
+    /** fieldMaps: source key -> the destination column the field map names (as the data records it). */
+    function resolve(
+        promoter: IntegrationCustomColumnPromoter,
+        candidates: string[],
+        entityFields: string[],
+        fieldMaps: Record<string, string>,
+    ) {
+        const entityInfo = { Fields: entityFields.map(n => ({ Name: n })) } as unknown as EntityInfo;
+        return (promoter as unknown as {
+            resolveWorkItems: (p: Array<{ Key: string }>, e: EntityInfo, f: ReadonlyMap<string, string>) => Array<Record<string, unknown>>;
+        }).resolveWorkItems(
+            candidates.map(Key => ({ Key })),
+            entityInfo,
+            new Map(Object.entries(fieldMaps).map(([k, v]) => [k.toLowerCase(), v])),
+        );
+    }
+
+    it('a key whose column AND field map exist becomes a recoverSpread item, not a silent skip', () => {
+        const promoter = new IntegrationCustomColumnPromoter(user, makeProvider());
+        const items = resolve(promoter, ['roundId'], ['ID', 'roundId'], { roundId: 'roundId' });
+        expect(items).toHaveLength(1);
+        expect(items[0]).toMatchObject({ recoverSpread: true, needsColumn: false, needsFieldMap: false, columnName: 'roundId' });
+    });
+
+    it('a brand-new key still plans column + field map, with no recovery flag', () => {
+        const promoter = new IntegrationCustomColumnPromoter(user, makeProvider());
+        const items = resolve(promoter, ['newKey'], ['ID'], {});
+        expect(items).toHaveLength(1);
+        expect(items[0]).toMatchObject({ needsColumn: true, needsFieldMap: true });
+        expect(items[0].recoverSpread).toBeFalsy();
+    });
+
+    it('a collision-suffixed column is found via the field map, not re-promoted', () => {
+        // The real column is `roundId_2` — re-sanitizing 'roundId' can never produce that name, so the
+        // old check read "no column yet" and minted a THIRD column beside the working one.
+        const promoter = new IntegrationCustomColumnPromoter(user, makeProvider());
+        const items = resolve(promoter, ['roundId'], ['ID', 'roundId_2'], { roundId: 'roundId_2' });
+        expect(items).toHaveLength(1);
+        expect(items[0]).toMatchObject({ recoverSpread: true, needsColumn: false, columnName: 'roundId_2' });
+    });
+
+    it('a field map whose column is missing from stale in-process metadata is still terminal', () => {
+        // entityInfo predates the ADD COLUMN in THIS process. The map names the column, so the key is
+        // already promoted — planning another column for it is the duplicate-column bug.
+        const promoter = new IntegrationCustomColumnPromoter(user, makeProvider());
+        const items = resolve(promoter, ['roundId'], ['ID'], { roundId: 'roundId' });
+        expect(items).toHaveLength(1);
+        expect(items[0]).toMatchObject({ needsColumn: false, needsFieldMap: false, columnName: 'roundId' });
+    });
+});
+
+describe('purgeOneRow — what the per-pass budget actually spends', () => {
+    function makeRow(values: Record<string, unknown>) {
+        const data = { ...values };
+        return {
+            Get: vi.fn((f: string) => data[f]),
+            Set: vi.fn((f: string, v: unknown) => { data[f] = v; }),
+            Save: vi.fn().mockResolvedValue(true),
+            _data: data,
+        };
+    }
+    function purge(row: ReturnType<typeof makeRow>, stale: Array<{ sourceKey: string; columnName: string }>) {
+        const promoter = new IntegrationCustomColumnPromoter(user, makeProvider());
+        return (promoter as unknown as {
+            purgeOneRow: (r: unknown, s: unknown, h: boolean, m: string[]) => Promise<{ wrote: boolean; leftSet: boolean }>;
+        }).purgeOneRow(row, stale, false, []);
+    }
+
+    it('a row an earlier pass already cleaned costs NO budget and no write', async () => {
+        // This is what lets a capped pass reach residue further down the table: already-purged rows
+        // fall through in memory instead of being re-written.
+        const row = makeRow({ __mj_integration_CustomFields: JSON.stringify({ somethingElse: 1 }) });
+        const res = await purge(row, [{ sourceKey: 'eventCode', columnName: 'eventCode' }]);
+        expect(res).toEqual({ wrote: false, leftSet: false });
+        expect(row.Save).not.toHaveBeenCalled();
+    });
+
+    it('a row that keeps other unmapped keys is WRITTEN but stays in the filtered set', async () => {
+        // wrote and leftSet are different questions: the first spends budget, the second shifts the
+        // paged offsets. Conflating them made the walk skip rows.
+        const row = makeRow({
+            __mj_integration_CustomFields: JSON.stringify({ eventCode: 'ABC', notYetPromoted: 'x' }),
+            eventCode: null,
+        });
+        const res = await purge(row, [{ sourceKey: 'eventCode', columnName: 'eventCode' }]);
+        expect(res).toEqual({ wrote: true, leftSet: false });
+        expect(row._data['eventCode']).toBe('ABC');
+        expect(JSON.parse(row._data['__mj_integration_CustomFields'] as string)).toEqual({ notYetPromoted: 'x' });
+    });
+
+    it('the last key leaving takes the row out of the set', async () => {
+        const row = makeRow({ __mj_integration_CustomFields: JSON.stringify({ eventCode: 'ABC' }), eventCode: null });
+        const res = await purge(row, [{ sourceKey: 'eventCode', columnName: 'eventCode' }]);
+        expect(res).toEqual({ wrote: true, leftSet: true });
+        expect(row._data['__mj_integration_CustomFields']).toBeNull();
+    });
+
+    it('never overwrites a column that already has a value, but still strips the key', async () => {
+        const row = makeRow({ __mj_integration_CustomFields: JSON.stringify({ eventCode: 'ABC' }), eventCode: 'SETTLED' });
+        const res = await purge(row, [{ sourceKey: 'eventCode', columnName: 'eventCode' }]);
+        expect(row._data['eventCode']).toBe('SETTLED');
+        expect(res.leftSet).toBe(true);
+    });
+});
+
+describe('spreadOneRow — idempotent backfill', () => {
+    function makeRow(values: Record<string, unknown>) {
+        const data = { ...values };
+        return {
+            Get: vi.fn((f: string) => data[f]),
+            Set: vi.fn((f: string, v: unknown) => { data[f] = v; }),
+            Save: vi.fn().mockResolvedValue(true),
+            _data: data,
+        };
+    }
+
+    async function spread(row: ReturnType<typeof makeRow>, named: Array<ReturnType<typeof workItem>>) {
+        const promoter = new IntegrationCustomColumnPromoter(user, makeProvider());
+        await (promoter as unknown as {
+            spreadOneRow: (r: unknown, n: unknown, h: boolean, m: string[]) => Promise<boolean>;
+        }).spreadOneRow(row, named, false, []);
+    }
+
+    it('fills a still-null destination from the overflow JSON, strips the key, and saves', async () => {
+        const row = makeRow({ __mj_integration_CustomFields: JSON.stringify({ roundId: 42 }), roundId: null });
+        await spread(row, [workItem('roundId')]);
+        expect(row._data['roundId']).toBe(42);
+        // The key was the only one staged, so the column goes null — the same shape the engine's
+        // own eviction writes, and what drops this row out of the `IS NOT NULL` scan.
+        expect(row._data['__mj_integration_CustomFields']).toBeNull();
+        expect(row.Save).toHaveBeenCalledTimes(1);
+    });
+
+    it('leaves an already-backfilled VALUE alone but still strips the key', async () => {
+        // The destination is settled, so the value is not rewritten. The key is removed regardless:
+        // it has a column and an active field map, so it is no longer unmapped, and leaving it staged
+        // is exactly what re-offers it as a phantom new column forever.
+        const row = makeRow({ __mj_integration_CustomFields: JSON.stringify({ roundId: 42 }), roundId: 99 });
+        await spread(row, [workItem('roundId', { recoverSpread: true })]);
+        expect(row._data['roundId']).toBe(99);
+        expect(row._data['__mj_integration_CustomFields']).toBeNull();
+        expect(row.Save).toHaveBeenCalledTimes(1);
+    });
+
+    it('keeps the still-unmapped keys and reports the row as staying in the scan', async () => {
+        const row = makeRow({
+            __mj_integration_CustomFields: JSON.stringify({ roundId: 42, notYetPromoted: 'x' }),
+            roundId: null,
+        });
+        const promoter = new IntegrationCustomColumnPromoter(user, makeProvider());
+        const left = await (promoter as unknown as {
+            spreadOneRow: (r: unknown, n: unknown, h: boolean, m: string[]) => Promise<boolean>;
+        }).spreadOneRow(row, [workItem('roundId')], false, []);
+        expect(JSON.parse(row._data['__mj_integration_CustomFields'] as string)).toEqual({ notYetPromoted: 'x' });
+        // Still carries overflow, so it is still in the filtered set — the paged walk must NOT count
+        // it as removed or it will skip a later row.
+        expect(left).toBe(false);
+    });
+});

package/src/__tests__/InactiveRowWarnings.test.ts

@@ -0,0 +1,87 @@
+/**
+ * An apply rebuilds its source schema from ACTIVE IntegrationObject/IntegrationObjectField rows
+ * only. Declared rows that a rediscovery deactivated are therefore dropped from the schema it
+ * materializes — the column never appears, or a requested object is never created — and the apply
+ * output said nothing about it. These tests pin what the operator is now told, and what they are
+ * deliberately NOT told, since an unfiltered apply on a large catalog can carry hundreds of
+ * legitimately deactivated objects.
+ */
+import { describe, it, expect } from 'vitest';
+import { ComputeInactiveRowWarnings, SummarizeNames } from '../integration/InactiveRowWarnings.js';
+
+const active = (Name: string) => ({ Name, Status: 'Active' });
+const disabled = (Name: string) => ({ Name, Status: 'Disabled' });
+
+describe('ComputeInactiveRowWarnings', () => {
+    it('says nothing when every declared row in scope is Active', () => {
+        expect(ComputeInactiveRowWarnings({
+            RequestedNames: ['Contacts'],
+            AllObjects: [active('Contacts')],
+            FieldsByObjectName: { Contacts: [active('ID'), active('Email')] },
+        })).toEqual([]);
+    });
+
+    it('names the deactivated fields of an object it DOES materialize', () => {
+        const [warning, ...rest] = ComputeInactiveRowWarnings({
+            RequestedNames: ['Contacts'],
+            AllObjects: [active('Contacts')],
+            FieldsByObjectName: { Contacts: [active('ID'), disabled('MiddleName')] },
+        });
+        expect(rest).toEqual([]);
+        expect(warning).toContain('Contacts:');
+        expect(warning).toContain('1 declared field(s)');
+        expect(warning).toContain('MiddleName (Disabled)');
+    });
+
+    it('reports a requested object that is not Active — the caller named it and got nothing', () => {
+        const warnings = ComputeInactiveRowWarnings({
+            RequestedNames: ['Contacts', 'Invoices'],
+            AllObjects: [active('Contacts'), disabled('Invoices')],
+            FieldsByObjectName: { Contacts: [active('ID')] },
+        });
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]).toContain('Invoices (Disabled)');
+        expect(warnings[0]).toContain('1 requested object(s)');
+    });
+
+    it('matches requested names case-insensitively, the way the apply path resolves them', () => {
+        const warnings = ComputeInactiveRowWarnings({
+            RequestedNames: ['invoices'],
+            AllObjects: [disabled('Invoices')],
+            FieldsByObjectName: {},
+        });
+        expect(warnings[0]).toContain('Invoices (Disabled)');
+    });
+
+    it('stays quiet about deactivated objects when nothing was requested by name', () => {
+        // The unfiltered apply: hundreds of deactivated audit objects are the normal state of a
+        // large catalog, and announcing them on every apply is noise that buries the field warning.
+        const warnings = ComputeInactiveRowWarnings({
+            RequestedNames: null,
+            AllObjects: [active('Contacts'), disabled('Invoices'), disabled('Invoices__History')],
+            FieldsByObjectName: { Contacts: [active('ID')] },
+        });
+        expect(warnings).toEqual([]);
+    });
+
+    it('treats any non-Active status as not materialized, and shows which one it is', () => {
+        const warnings = ComputeInactiveRowWarnings({
+            RequestedNames: null,
+            AllObjects: [active('Contacts')],
+            FieldsByObjectName: { Contacts: [{ Name: 'Legacy', Status: 'Deprecated' }, { Name: 'Blank', Status: null }] },
+        });
+        expect(warnings[0]).toContain('Legacy (Deprecated)');
+        expect(warnings[0]).toContain('Blank (no status)');
+    });
+});
+
+describe('SummarizeNames', () => {
+    it('lists everything when the list is short', () => {
+        expect(SummarizeNames(['a', 'b', 'c'])).toBe('a, b, c');
+    });
+
+    it('caps a long list and says how many were left out', () => {
+        const names = Array.from({ length: 15 }, (_, i) => `f${i}`);
+        expect(SummarizeNames(names)).toBe(`${names.slice(0, 12).join(', ')}, and 3 more`);
+    });
+});

package/src/__tests__/ReactivateRefreshMessage.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from 'vitest';
+import { BuildReactivateMessage } from '../integration/SchemaRefreshLaunch.js';
+import type { SchemaRefreshSummaryLike } from '../integration/SchemaRefreshLaunch.js';
+
+/**
+ * Reactivation is committed BEFORE the refresh runs, so no refresh outcome — running, failed, or
+ * clean — may ever read as "resume didn't work". These pin that, plus the two reporting bugs the
+ * create/update paths already fixed and reactivate had kept its own copy of:
+ *
+ *   1. A detached run's placeholder zeros must not be reported as findings ("0 created, 0 updated"
+ *      tells an operator the source had nothing new, when in fact nothing has been looked at yet).
+ *   2. A pipeline that fails RETURNS with every count at zero rather than throwing, so counts alone
+ *      read identically to a clean no-op run.
+ */
+function summary(over: Partial<SchemaRefreshSummaryLike> = {}): SchemaRefreshSummaryLike {
+    return {
+        RunID: 'connector-1783000000000-abc123',
+        InProgress: false,
+        Succeeded: true,
+        ObjectsCreated: 12,
+        ObjectsUpdated: 3,
+        UnresolvedObjects: ['Widgets'],
+        ...over,
+    };
+}
+
+describe('BuildReactivateMessage', () => {
+    it('leads with the reactivation on every path', () => {
+        const paths = [
+            BuildReactivateMessage(undefined),
+            BuildReactivateMessage(summary({ InProgress: true, ObjectsCreated: 0, ObjectsUpdated: 0, UnresolvedObjects: [] })),
+            BuildReactivateMessage(summary()),
+            BuildReactivateMessage(summary({ Succeeded: false, FailureMessage: 'boom' })),
+        ];
+        for (const msg of paths) expect(msg).toMatch(/^Reactivated/);
+    });
+
+    it('names the run to tail — and reports NO counts — for a detached refresh', () => {
+        const msg = BuildReactivateMessage(summary({
+            InProgress: true,
+            ObjectsCreated: 0,
+            ObjectsUpdated: 0,
+            UnresolvedObjects: [],
+        }));
+
+        expect(msg).toContain('connector-1783000000000-abc123');
+        expect(msg).toMatch(/running/i);
+        expect(msg).not.toMatch(/\d+ created/);
+        expect(msg).not.toMatch(/\d+ updated/);
+        expect(msg).not.toMatch(/PK-unresolved/);
+    });
+
+    it('reports real counts when the caller asked to block', () => {
+        const msg = BuildReactivateMessage(summary());
+        expect(msg).toContain('12 created');
+        expect(msg).toContain('3 updated');
+        expect(msg).toContain('1 PK-unresolved');
+        expect(msg).not.toMatch(/running/i);
+    });
+
+    it('never reports a FAILED refresh as a zero-count success', () => {
+        // The old inline message formatted counts unconditionally, so a pipeline that failed at
+        // ConnectionTest produced "Reactivated, schema refresh: 0 created, 0 updated,
+        // 0 PK-unresolved" — indistinguishable from a source with nothing new.
+        const msg = BuildReactivateMessage(summary({
+            Succeeded: false,
+            FailureMessage: 'ConnectionTest failed: No Totara credentials found',
+            ObjectsCreated: 0,
+            ObjectsUpdated: 0,
+            UnresolvedObjects: [],
+        }));
+
+        expect(msg).toMatch(/FAILED/);
+        expect(msg).toContain('No Totara credentials found');
+        expect(msg).not.toMatch(/0 created/);
+        // ...and still says the connection is active, because it is.
+        expect(msg).toMatch(/^Reactivated/);
+    });
+
+    it('says nothing about a refresh that was never requested', () => {
+        const msg = BuildReactivateMessage(undefined);
+        expect(msg).toBe('Reactivated');
+        expect(msg).not.toMatch(/refresh/i);
+    });
+});