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

package/src/__tests__/CustomColumnPromoterCompletion.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Completing a promotion after the restart.
+ *
+ * The post-restart consumer calls CompletePromotion with no catalog scope. Unscoped, a connection
+ * with per-connection rows reads as having none, so building its catalog writer threw
+ * PER_CONNECTION_CATALOG_MISSING. CompletePromotion caught that per entity and returned normally,
+ * and the consumer marked the pending work Completed: the columns existed in the database and were
+ * never mapped, with nothing failed anywhere.
+ *
+ * So: the catalog writes run in the connection's own scope, entered per entry; and a failed entry
+ * no longer returns normally — the others still run, then the failure is thrown, so the consumer
+ * fails the pending row instead of completing it.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const h = vi.hoisted(() => ({
+    scopeAtBuild: [] as Array<string | undefined>,
+    savedFields: [] as string[],
+}));
+
+vi.mock('@memberjunction/schema-engine', () => ({
+    RuntimeSchemaManager: { get Instance() { return {}; } },
+}));
+vi.mock('@memberjunction/integration-schema-builder', () => ({ DDLGenerator: class {} }));
+
+// The real scope; only the writer is replaced. It behaves as the real one does for a connection
+// with per-connection rows: outside that connection's scope it cannot tell, and refuses.
+vi.mock('@memberjunction/integration-engine', async (orig) => {
+    const actual = await orig<typeof import('@memberjunction/integration-engine')>();
+    return {
+        ...actual,
+        BuildCatalogWriter: () => {
+            const ci = actual.CurrentCatalogCI();
+            h.scopeAtBuild.push(ci);
+            if (!ci) throw new Error('PER_CONNECTION_CATALOG_MISSING: built outside the connection scope');
+            return {
+                ObjectsInScope: async () => [{ Name: 'Members', ID: 'obj-members' }],
+                FieldsForObject: async () => [],
+                LoadField: async () => null,
+                NewFieldRow: async () => {
+                    const row: Record<string, unknown> = {};
+                    return Object.assign(row, { Save: async () => { h.savedFields.push(String(row.Name)); return true; } });
+                },
+                StampNewField: () => undefined,
+            };
+        },
+    };
+});
+
+import type { UserInfo, IMetadataProvider, EntityInfo } from '@memberjunction/core';
+import { IntegrationEngineBase } from '@memberjunction/integration-engine-base';
+import { WithCatalogScope } from '@memberjunction/integration-engine';
+import { IntegrationCustomColumnPromoter } from '../integration/CustomColumnPromoter.js';
+
+const USER = { ID: 'u-1' } as UserInfo;
+const CONN = 'CCCCCCCC-0000-0000-0000-000000000001';
+const OTHER_CONN = 'CCCCCCCC-0000-0000-0000-000000000002';
+
+type Seams = {
+    createIntegrationObjectFields: (integrationID: string, entityMapID: string, objectName: string, named: unknown[]) => Promise<void>;
+    activeFieldMaps: unknown; createFieldMaps: unknown; spreadAndRebaseline: unknown;
+};
+
+function provider(known: string[]): IMetadataProvider {
+    return {
+        EntityByName: (n: string) => (known.includes(n) ? ({ Name: n } as unknown as EntityInfo) : undefined),
+        PlatformKey: 'sqlserver',
+    } as unknown as IMetadataProvider;
+}
+
+const region = { sourceKey: 'region', columnName: 'region', candidate: { Coverage: 0.5, Inferred: { SchemaFieldType: 'nvarchar', MaxLength: 50 } } };
+
+function entry(entityName: string) {
+    return {
+        EntityName: entityName, EntityMapID: `em-${entityName}`, ExternalObjectName: 'Members', IntegrationID: 'int-1',
+        Columns: [{ SourceKey: 'region', ColumnName: 'region', SchemaFieldType: 'nvarchar', MaxLength: 50, Coverage: 0.5 }],
+    };
+}
+
+beforeEach(() => {
+    h.scopeAtBuild.length = 0;
+    h.savedFields.length = 0;
+    // No catalog entities registered: entering a scope loads nothing and reads nothing.
+    vi.spyOn(IntegrationEngineBase.Instance, 'ProviderToUse', 'get').mockImplementation(() => ({ EntityByName: () => undefined }) as never);
+    vi.spyOn(IntegrationEngineBase.Instance, 'EntityMaps', 'get')
+        .mockReturnValue([{ ID: 'em-Members', CompanyIntegrationID: CONN }] as never);
+    vi.spyOn(IntegrationEngineBase.Instance, 'GetCompanyIntegrationByID')
+        .mockImplementation((id: string) => ({ ID: id }) as never);
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+});
+afterEach(() => { vi.restoreAllMocks(); });
+
+describe('the catalog writes of a promotion run in the connection\'s own scope', () => {
+    it('called with no scope (the post-restart consumer), the writer is built in the connection\'s scope', async () => {
+        const promoter = new IntegrationCustomColumnPromoter(USER, provider([])) as unknown as Seams;
+        await promoter.createIntegrationObjectFields('int-1', 'em-Members', 'Members', [region]);
+        expect(h.scopeAtBuild).toEqual([CONN]);
+        expect(h.savedFields).toEqual(['region']);
+    });
+
+    it('called inside another connection\'s scope, the entry\'s own connection wins', async () => {
+        const promoter = new IntegrationCustomColumnPromoter(USER, provider([])) as unknown as Seams;
+        await WithCatalogScope(OTHER_CONN, () => promoter.createIntegrationObjectFields('int-1', 'em-Members', 'Members', [region]), USER);
+        expect(h.scopeAtBuild).toEqual([CONN]);
+    });
+});
+
+describe('CompletePromotion does not complete over a failed entity', () => {
+    function stub(known: string[], failing: string[] = []) {
+        const promoter = new IntegrationCustomColumnPromoter(USER, provider(known));
+        const p = promoter as unknown as Seams;
+        p.activeFieldMaps = vi.fn().mockResolvedValue(new Map<string, string>());
+        p.createIntegrationObjectFields = vi.fn(async (_i: string, emID: string) => {
+            if (failing.some(f => emID === `em-${f}`)) throw new Error('PER_CONNECTION_CATALOG_MISSING');
+        });
+        const maps = vi.fn().mockResolvedValue(undefined);
+        p.createFieldMaps = maps;
+        p.spreadAndRebaseline = vi.fn().mockResolvedValue(undefined);
+        return { promoter, maps };
+    }
+
+    it('every entry completes: returns the columns and throws nothing', async () => {
+        const { promoter } = stub(['A', 'B']);
+        await expect(promoter.CompletePromotion([entry('A'), entry('B')])).resolves.toEqual([
+            { EntityName: 'A', ColumnName: 'region' },
+            { EntityName: 'B', ColumnName: 'region' },
+        ]);
+    });
+
+    it('one entry fails: the others still complete, then it throws naming the failed one', async () => {
+        const { promoter, maps } = stub(['A', 'B'], ['A']);
+        await expect(promoter.CompletePromotion([entry('A'), entry('B')]))
+            .rejects.toThrow(/PROMOTION_INCOMPLETE: 1 of 2 .*A: PER_CONNECTION_CATALOG_MISSING/);
+        expect(maps).toHaveBeenCalledTimes(1);   // B's field maps were still created
+    });
+
+    it('an entity that is not found after the restart is a failure, not a skip', async () => {
+        const { promoter } = stub(['B']);
+        await expect(promoter.CompletePromotion([entry('A'), entry('B')]))
+            .rejects.toThrow(/PROMOTION_INCOMPLETE: 1 of 2 .*A: entity not found/);
+    });
+});

package/src/__tests__/DeleteConnectionRemovesPerConnectionCatalog.test.ts

@@ -0,0 +1,51 @@
+/**
+ * The per-connection catalog rows carry a plain FK to the connection and nothing cascades, so a
+ * connection that ever ran a discovery on it could not be deleted at all: the CompanyIntegration
+ * delete violated the constraint and the whole cascade rolled back (MJ-CAT-18). The fix deletes
+ * the field rows, then the object rows, inside the same transaction group, before the connection.
+ *
+ * Pinned from source, like PostRestartMapsInCatalogScope: the delete is a transaction over a live
+ * provider, and the fact being pinned is ORDER inside one method body.
+ */
+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 start = SRC.indexOf('async IntegrationDeleteConnection(');
+const end = SRC.indexOf('// ── SCHEMA EVOLUTION', start);
+const BODY = SRC.slice(start, end);
+
+describe('IntegrationDeleteConnection removes the per-connection catalog before the connection', () => {
+  it('is scoped to the method body', () => {
+    expect(start).toBeGreaterThan(0);
+    expect(end).toBeGreaterThan(start);
+  });
+
+  it('deletes per-connection fields, then objects, then the CompanyIntegration — in that order', () => {
+    const fields = BODY.indexOf("EntityName: 'MJ: Company Integration Object Fields'");
+    const objects = BODY.indexOf("EntityName: 'MJ: Company Integration Objects'");
+    const fieldDelete = BODY.indexOf('field.TransactionGroup = tg;');
+    const objectDelete = BODY.indexOf('object.TransactionGroup = tg;');
+    const ciDelete = BODY.indexOf('ci.TransactionGroup = tg;');
+    expect(objects).toBeGreaterThan(0);
+    expect(fields).toBeGreaterThan(objects);
+    expect(fieldDelete).toBeGreaterThan(fields);
+    expect(objectDelete).toBeGreaterThan(fieldDelete);
+    expect(ciDelete).toBeGreaterThan(objectDelete);
+  });
+
+  it('queues every catalog delete on the same transaction group as the cascade', () => {
+    expect(BODY).toMatch(/field\.TransactionGroup = tg;\s*await field\.Delete\(\);/);
+    expect(BODY).toMatch(/object\.TransactionGroup = tg;\s*await object\.Delete\(\);/);
+  });
+
+  it('is guarded on the catalog entities being registered, so an unmigrated workspace is untouched', () => {
+    expect(BODY).toMatch(/md\.Entities\.some\(e => e\.Name === 'MJ: Company Integration Objects'\)/);
+  });
+
+  it('selects the fields by the objects of THIS connection only', () => {
+    expect(BODY).toMatch(/ExtraFilter: `CompanyIntegrationID='\$\{companyIntegrationID\}'`,\s*ResultType: 'entity_object',\s*\}, sysUser\);\s*const perConnectionObjects/);
+    expect(BODY).toMatch(/ExtraFilter: `CompanyIntegrationObjectID IN \(\$\{objectIDs\}\)`/);
+  });
+});

package/src/__tests__/DetachedDiscoveryStart.test.ts

@@ -0,0 +1,65 @@
+/**
+ * plan.md: "going to a page should NEVER, NEVER trigger such things automatically, it must in a
+ * very clean way tell the user to click a button to start discovery of tables".
+ *
+ * A button needs a call that returns at once. The only discovery entry point that existed was
+ * synchronous - it runs the whole pipeline inline and times out at the gateway on a large catalog -
+ * so both wizards auto-triggered on page entry and adopted whatever run they happened to find.
+ * IntegrationStartSchemaRefresh is the explicit start: it returns a tailable RunID immediately.
+ *
+ * Source-level, for the same reason the sibling default tests are: these are decorator and
+ * argument shapes, and invoking the resolver needs a provider, a connector driver and the RSU
+ * pipeline stood up.
+ */
+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 methodBody(name: string): string {
+  const start = SRC.indexOf(`async ${name}(`);
+  expect(start, `${name} not found`).toBeGreaterThan(-1);
+  const rest = SRC.slice(start);
+  const end = rest.search(/\n    @(Query|Mutation)\(/);
+  return end === -1 ? rest : rest.slice(0, end);
+}
+
+describe('IntegrationStartSchemaRefresh', () => {
+  it('exists as a mutation', () => {
+    expect(SRC).toMatch(/@Mutation\(\(\) => StartSchemaRefreshOutput\)/);
+    expect(SRC).toMatch(/async IntegrationStartSchemaRefresh\(/);
+  });
+
+  it('launches DETACHED rather than awaiting the pipeline', () => {
+    const body = methodBody('IntegrationStartSchemaRefresh');
+    expect(body).toMatch(/startSchemaRefreshPipelineDetached\(/);
+    // an await on the pipeline would reintroduce the gateway timeout this exists to avoid
+    expect(body).not.toMatch(/await this\.runSchemaRefreshPipeline\(/);
+  });
+
+  it('refuses a second start with the reason, instead of handing back a doomed RunID', () => {
+    const body = methodBody('IntegrationStartSchemaRefresh');
+    expect(body).toMatch(/GetMaintenanceLock\(/);
+    expect(body).toMatch(/RunID: 'not-started'/);
+    expect(body).toMatch(/BlockedBy/);
+  });
+
+  it('probes the lock BEFORE launching, or the refusal is useless', () => {
+    const body = methodBody('IntegrationStartSchemaRefresh');
+    expect(body.indexOf('GetMaintenanceLock('))
+      .toBeLessThan(body.indexOf('startSchemaRefreshPipelineDetached('));
+  });
+
+  it('uses the read-write provider, since the pipeline writes the catalog', () => {
+    expect(methodBody('IntegrationStartSchemaRefresh')).toMatch(/GetReadWriteProvider\(/);
+  });
+
+  it('is a separate mutation, so the synchronous one keeps its real-counts contract', () => {
+    // the synchronous reply promises counts because it waited; a detached launch has only zeros
+    expect(SRC).toMatch(/async IntegrationRefreshConnectorSchema\(/);
+    const detached = methodBody('IntegrationStartSchemaRefresh');
+    expect(detached).not.toMatch(/ObjectsCreated/);
+  });
+});

package/src/__tests__/DurableEntityActionTaskSubmitter.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+
+const { submitMock } = vi.hoisted(() => ({
+    submitMock: vi.fn(),
+}));
+
+vi.mock('@memberjunction/task-graph', () => ({
+    TaskGraphService: class {
+        public Submit = submitMock;
+    },
+}));
+
+import { DurableEntityActionTaskSubmitter } from '../services/DurableEntityActionTaskSubmitter.js';
+
+describe('DurableEntityActionTaskSubmitter', () => {
+    const contextUser = { ID: 'user-1', Email: 'test@example.com' } as UserInfo;
+
+    beforeEach(() => {
+        submitMock.mockReset();
+        submitMock.mockResolvedValue({ Success: true, ParentTaskID: 'parent-task-1' });
+    });
+
+    it('enlists in request.Provider when supplied instead of minting an isolated provider connection', async () => {
+        const savingProvider = { Name: 'saving-tx-provider', GetEntityObject: vi.fn() } as object as IMetadataProvider;
+        const createProvider = vi.fn();
+        const submitter = new DurableEntityActionTaskSubmitter({ CreateProvider: createProvider }, 'env-1');
+
+        const result = await submitter.Submit({
+            EntityActionID: 'ea-1',
+            ActionID: 'act-1',
+            ActionName: 'Send Order Webhook',
+            EntityID: 'ent-1',
+            EntityName: 'Orders',
+            RecordID: 'ID|ord-1',
+            InvocationType: 'AfterCreate',
+            RedactedParams: { OrderID: 'ord-1' },
+            ContextUser: contextUser,
+            Provider: savingProvider,
+        });
+
+        expect(result).toEqual({ Success: true, ParentTaskID: 'parent-task-1' });
+        expect(createProvider).not.toHaveBeenCalled();
+        expect(submitMock).toHaveBeenCalledTimes(1);
+        expect(submitMock.mock.calls[0][1]).toMatchObject({
+            EnvironmentID: 'env-1',
+            ContextUser: contextUser,
+            Provider: savingProvider,
+        });
+    });
+
+    it('falls back to providerFactory.CreateProvider() when request.Provider is omitted', async () => {
+        const factoryProvider = { Name: 'factory-provider' } as IMetadataProvider;
+        const createProvider = vi.fn().mockResolvedValue(factoryProvider);
+        const submitter = new DurableEntityActionTaskSubmitter({ CreateProvider: createProvider }, 'env-1');
+
+        const result = await submitter.Submit({
+            EntityActionID: 'ea-1',
+            ActionID: 'act-1',
+            ActionName: 'Send Order Webhook',
+            EntityID: 'ent-1',
+            EntityName: 'Orders',
+            RecordID: 'ID|ord-1',
+            InvocationType: 'AfterCreate',
+            RedactedParams: {},
+            ContextUser: contextUser,
+        });
+
+        expect(result).toEqual({ Success: true, ParentTaskID: 'parent-task-1' });
+        expect(createProvider).toHaveBeenCalledTimes(1);
+        expect(submitMock.mock.calls[0][1]).toMatchObject({ Provider: factoryProvider });
+    });
+});

package/src/__tests__/EntityMapLifecycle.rekey.test.ts

@@ -0,0 +1,252 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { RunView, type DatabaseProviderBase, type UserInfo } from '@memberjunction/core';
+import { CatalogIdentityKey, ClearRekeyedObjectData, DecideRekeyed, IdentityKeyFields } from '../integration/EntityMapLifecycle.js';
+
+/**
+ * A connector upgrade can change what identifies a row. PheedLoop 1.4.6 makes Attendees
+ * `code + eventCode`, because the object is fetched once per event and an attendee at two events
+ * comes back twice carrying the same `code`.
+ *
+ * `ToExternalRecord` joins every IsPrimaryKey field with '|' in Sequence order, so both the
+ * MEMBERS and the ORDER are part of identity. These pin the two pure decisions that drive the
+ * evolution's clear-and-rebuild.
+ */
+const f = (Name: string, IsPrimaryKey: boolean | null, Sequence: number | null) =>
+    ({ Name, IsPrimaryKey, Sequence });
+
+describe('IdentityKeyFields', () => {
+    it('takes only key fields, in Sequence order — not declaration order', () => {
+        expect(IdentityKeyFields([
+            f('eventCode', true, 2),
+            f('is_checked_in', false, 3),
+            f('code', true, 1),
+        ])).toEqual(['code', 'eventCode']);
+    });
+
+    it('is empty when nothing is flagged', () => {
+        expect(IdentityKeyFields([f('a', false, 1), f('b', null, 2)])).toEqual([]);
+    });
+
+    it('treats a missing Sequence as 0 rather than dropping the field', () => {
+        expect(IdentityKeyFields([f('b', true, null), f('a', true, 1)])).toEqual(['b', 'a']);
+    });
+
+    it('does not mutate the caller array', () => {
+        const input = [f('z', true, 9), f('a', true, 1)];
+        IdentityKeyFields(input);
+        expect(input[0].Name).toBe('z');
+    });
+});
+
+describe('DecideRekeyed', () => {
+    it('a column joining the key is a re-key — the PheedLoop case', () => {
+        expect(DecideRekeyed(['code'], ['code', 'eventCode'])).toBe(true);
+    });
+
+    it('a column leaving the key is a re-key', () => {
+        expect(DecideRekeyed(['code', 'eventCode'], ['code'])).toBe(true);
+    });
+
+    it('the same columns in a different ORDER is a re-key — the identity string differs', () => {
+        expect(DecideRekeyed(['code', 'eventCode'], ['eventCode', 'code'])).toBe(true);
+    });
+
+    it('an unchanged key is not', () => {
+        expect(DecideRekeyed(['code', 'eventCode'], ['code', 'eventCode'])).toBe(false);
+    });
+
+    it('matches case-insensitively, as every catalog-to-map reconciliation does', () => {
+        expect(DecideRekeyed(['Code'], ['code'])).toBe(false);
+    });
+
+    // The guard that stops this from clearing the fleet. An empty BUILT key means the entity's
+    // fields could not be read, not that the table never had a key — and treating unknown as
+    // empty would re-key (and therefore WIPE) every table on a workspace whose metadata failed
+    // to load.
+    it('an unreadable built key is never a re-key, however different the catalog looks', () => {
+        expect(DecideRekeyed([], ['code', 'eventCode'])).toBe(false);
+        expect(DecideRekeyed([], [])).toBe(false);
+    });
+
+    it('a catalog that reports no key against a real built key IS a re-key', () => {
+        expect(DecideRekeyed(['code'], [])).toBe(true);
+    });
+
+    // The same guard on the catalog side. A refresh reading a per-connection object whose fields
+    // were never warmed got `[]`, and "no key" against a real built key cleared the object's
+    // record maps and rows on every refresh.
+    it('an unread catalog key is never a re-key', () => {
+        expect(DecideRekeyed(['code'], null)).toBe(false);
+        expect(DecideRekeyed(['code', 'eventCode'], CatalogIdentityKey([]))).toBe(false);
+    });
+});
+
+describe('CatalogIdentityKey', () => {
+    const row = (Name: string, IsPrimaryKey: boolean, Sequence: number, Status = 'Active') =>
+        ({ Name, IsPrimaryKey, Sequence, Status });
+
+    it('is null when no field row was read — a cold per-connection object answers []', () => {
+        expect(CatalogIdentityKey([])).toBeNull();
+    });
+
+    it('is null when no row is Active — nothing describes the object', () => {
+        expect(CatalogIdentityKey([row('code', true, 1, 'Inactive')])).toBeNull();
+    });
+
+    it('is the Active key fields in Sequence order', () => {
+        expect(CatalogIdentityKey([
+            row('eventCode', true, 2),
+            row('old_key', true, 0, 'Inactive'),
+            row('code', true, 1),
+            row('name', false, 3),
+        ])).toEqual(['code', 'eventCode']);
+    });
+
+    it('is [] when Active rows declare no key — read, and keyless, so still a re-key', () => {
+        const key = CatalogIdentityKey([row('name', false, 1)]);
+        expect(key).toEqual([]);
+        expect(DecideRekeyed(['code'], key)).toBe(true);
+    });
+});
+
+/**
+ * Two connections to the same vendor share one schema, so they share every entity table. The clear
+ * may only touch the rows THIS connection's record maps point at; the other connection's rows in
+ * the same table are not its to delete.
+ */
+describe('ClearRekeyedObjectData', () => {
+    const USER = { ID: 'user-1' } as UserInfo;
+    const RECORD_MAPS = { Name: 'MJ: Company Integration Record Maps', SchemaName: '__mj', BaseTable: 'CompanyIntegrationRecordMap' };
+    const TARGET = { ExternalObjectName: 'attendees', EntityMapID: 'M1', EntityID: 'E1', SchemaName: 'pheedloop', BaseTable: 'attendees' };
+    type MapRow = { ID: string; EntityRecordID: string };
+    type RunViewParams = Parameters<RunView['RunView']>[0];
+    type RunViewResult = Awaited<ReturnType<RunView['RunView']>>;
+
+    /** A provider that records every statement and transaction step, in order. */
+    function fakeProvider(key: string[], failOn?: string) {
+        const log: string[] = [];
+        const provider = {
+            Dialect: {
+                QuoteIdentifier: (s: string) => `[${s}]`,
+                QuoteStringLiteral: (s: string) => `'${s.replace(/'/g, "''")}'`,
+            },
+            Entities: [RECORD_MAPS],
+            EntityByName: (name: string) => (name === RECORD_MAPS.Name ? RECORD_MAPS : undefined),
+            EntityByID: (id: string) => (id === 'E1' ? { PrimaryKeys: key.map(Name => ({ Name })) } : undefined),
+            ExecuteSQL: async (sql: string) => {
+                log.push(sql);
+                if (failOn && sql.includes(failOn)) throw new Error('deadlock victim');
+                return [];
+            },
+            BeginTransaction: async () => { log.push('BEGIN'); },
+            CommitTransaction: async () => { log.push('COMMIT'); },
+            RollbackTransaction: async () => { log.push('ROLLBACK'); },
+        };
+        return { provider: provider as unknown as DatabaseProviderBase, log };
+    }
+
+    let runView: ReturnType<typeof vi.spyOn>;
+    /** Answers the record-map reads one page at a time, then empty. */
+    function recordMapPages(...pages: MapRow[][]) {
+        for (const page of pages) {
+            runView.mockResolvedValueOnce({ Success: true, Results: page } as unknown as RunViewResult);
+        }
+        runView.mockResolvedValue({ Success: true, Results: [] } as unknown as RunViewResult);
+    }
+    const reads = () => runView.mock.calls.map(c => c[0] as RunViewParams);
+
+    beforeEach(() => { runView = vi.spyOn(RunView.prototype, 'RunView'); });
+    afterEach(() => { vi.restoreAllMocks(); });
+
+    it('deletes only the rows this connection\'s record maps point at — never the whole table', async () => {
+        const { provider, log } = fakeProvider(['ID']);
+        recordMapPages([{ ID: 'm1', EntityRecordID: 'r1' }, { ID: 'm2', EntityRecordID: 'r2' }]);
+
+        const cleared = await ClearRekeyedObjectData([TARGET], 'CI-A', USER, provider);
+
+        expect(cleared).toEqual(['attendees']);
+        expect(log).not.toContain('DELETE FROM [pheedloop].[attendees]');
+        expect(log).toContain("DELETE FROM [pheedloop].[attendees] WHERE [ID] IN ('r1','r2')");
+        expect(reads()[0].EntityName).toBe(RECORD_MAPS.Name);
+        expect(reads()[0].ExtraFilter).toBe("CompanyIntegrationID='CI-A' AND EntityID='E1'");
+    });
+
+    it('deletes the rows while their maps still say which rows they are, in one transaction with the maps', async () => {
+        const { provider, log } = fakeProvider(['ID']);
+        recordMapPages([{ ID: 'm1', EntityRecordID: 'r1' }]);
+
+        await ClearRekeyedObjectData([TARGET], 'CI-A', USER, provider);
+
+        expect(log).toEqual([
+            'BEGIN',
+            "DELETE FROM [pheedloop].[attendees] WHERE [ID] IN ('r1')",
+            "DELETE FROM [__mj].[CompanyIntegrationRecordMap] WHERE [CompanyIntegrationID]='CI-A' AND [EntityID]='E1' AND [ID] IN ('m1')",
+            'COMMIT',
+        ]);
+    });
+
+    it('matches every column of a composite key, split the way the engine joined it', async () => {
+        const { provider, log } = fakeProvider(['code', 'eventCode']);
+        recordMapPages([{ ID: 'm1', EntityRecordID: 'a|1' }, { ID: 'm2', EntityRecordID: "b'x|2" }]);
+
+        await ClearRekeyedObjectData([TARGET], 'CI-A', USER, provider);
+
+        expect(log).toContain(
+            "DELETE FROM [pheedloop].[attendees] WHERE ([code]='a' AND [eventCode]='1') OR ([code]='b''x' AND [eventCode]='2')"
+        );
+    });
+
+    it('leaves a map whose id cannot name exactly one row, and does not report the object cleared', async () => {
+        // 'a|1|z' against a two-column key is a value that itself contained '|': splitting it would
+        // name some OTHER row. An empty component is a null key value, which matches nothing safely.
+        const { provider, log } = fakeProvider(['code', 'eventCode']);
+        recordMapPages([
+            { ID: 'm1', EntityRecordID: 'a|1' },
+            { ID: 'm2', EntityRecordID: 'a|1|z' },
+            { ID: 'm3', EntityRecordID: '|2' },
+        ]);
+
+        const cleared = await ClearRekeyedObjectData([TARGET], 'CI-A', USER, provider);
+
+        expect(cleared).toEqual([]);
+        expect(log).toContain("DELETE FROM [pheedloop].[attendees] WHERE ([code]='a' AND [eventCode]='1')");
+        expect(log.some(s => s.includes('m2') || s.includes('m3'))).toBe(false);
+    });
+
+    it('pages through the maps by id, so a big table is never read or deleted whole', async () => {
+        const { provider, log } = fakeProvider(['ID']);
+        recordMapPages(
+            [{ ID: 'm1', EntityRecordID: 'r1' }, { ID: 'm2', EntityRecordID: 'r2' }],
+            [{ ID: 'm3', EntityRecordID: 'r3' }],
+        );
+
+        const cleared = await ClearRekeyedObjectData([TARGET], 'CI-A', USER, provider, 2);
+
+        expect(cleared).toEqual(['attendees']);
+        expect(reads()).toHaveLength(2);
+        expect(reads()[0]).toMatchObject({ OrderBy: 'ID', MaxRows: 2, SkipTotalRowCount: true, BypassCache: true });
+        expect(reads()[1].ExtraFilter).toBe("CompanyIntegrationID='CI-A' AND EntityID='E1' AND ID > 'm2'");
+        expect(log.filter(s => s === 'COMMIT')).toHaveLength(2);
+    });
+
+    it('rolls a failed chunk back and does not report the object cleared', async () => {
+        const { provider, log } = fakeProvider(['ID'], 'CompanyIntegrationRecordMap');
+        recordMapPages([{ ID: 'm1', EntityRecordID: 'r1' }]);
+
+        const cleared = await ClearRekeyedObjectData([TARGET], 'CI-A', USER, provider);
+
+        expect(cleared).toEqual([]);
+        expect(log).toContain('ROLLBACK');
+        expect(log).not.toContain('COMMIT');
+    });
+
+    it('deletes nothing when the record maps cannot be read', async () => {
+        const { provider, log } = fakeProvider(['ID']);
+        runView.mockResolvedValue({ Success: false, Results: [], ErrorMessage: 'timeout' } as unknown as RunViewResult);
+
+        const cleared = await ClearRekeyedObjectData([TARGET], 'CI-A', USER, provider);
+
+        expect(cleared).toEqual([]);
+        expect(log).toEqual([]);
+    });
+});