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

package/src/__tests__/AssertTargetConfigs.test.ts

@@ -0,0 +1,75 @@
+/**
+ * An apply whose selected objects all drop out of buildTargetConfigs must fail, not run RSU on
+ * nothing (PropFuel, 2026-10-29). A selection that produces even one table must still apply.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { TargetTableConfig } from '@memberjunction/integration-schema-builder';
+import { AssertTargetConfigs, NewTargetConfigDrops, SampleNames } from '../integration/TargetConfigGuard.js';
+
+const selected = [{ SourceObjectName: 'clicks' }, { SourceObjectName: 'sends' }, { SourceObjectName: 'opens' }];
+const oneTable = [{ SchemaName: 'propfuel', TableName: 'clicks' } as TargetTableConfig];
+
+describe('AssertTargetConfigs', () => {
+    it('refuses a selection none of whose objects produced a table, naming what was asked for', () => {
+        expect(() => AssertTargetConfigs(selected, [], 'PropFuel')).toThrow(
+            /NO_TARGET_TABLES: none of the 3 selected object\(s\) for PropFuel produced a target table \(clicks, sends, opens\)/
+        );
+    });
+
+    it('names why each object was dropped, so a caller does not need the server log', () => {
+        const drops = NewTargetConfigDrops();
+        drops.NotInSchema.push('clicks', 'sends');
+        drops.NoPrimaryKey.push('opens');
+        expect(() => AssertTargetConfigs(selected, [], 'PropFuel', drops)).toThrow(
+            'Dropped as not in the source schema: clicks, sends; no primary key: opens.'
+        );
+    });
+
+    it('says nothing was applied by default, and what was already committed when the caller says so', () => {
+        expect(() => AssertTargetConfigs(selected, [], 'PropFuel')).toThrow('Nothing was applied.');
+        expect(() => AssertTargetConfigs(selected, [], 'PropFuel', undefined, 'The catalog had already been saved.'))
+            .toThrow(/The catalog had already been saved\. Re-run discovery/);
+    });
+
+    it('caps the names it lists, so a large selection cannot make a multi-KB error', () => {
+        const many = Array.from({ length: 168 }, (_v, i) => ({ SourceObjectName: `obj${i}` }));
+        expect(() => AssertTargetConfigs(many, [], 'NetForum')).toThrow('(obj0, obj1, obj2, obj3, obj4 and 163 more)');
+        expect(SampleNames(['a', 'b'])).toBe('a, b');
+    });
+
+    it('lets a selection through when at least one object produced a table', () => {
+        expect(() => AssertTargetConfigs(selected, oneTable, 'PropFuel')).not.toThrow();
+    });
+
+    it('lets an empty selection through — there was nothing to refuse', () => {
+        expect(() => AssertTargetConfigs([], [], 'PropFuel')).not.toThrow();
+    });
+});
+
+/**
+ * Read from source: the call sites are resolver mutations that need a provider, a connector and an
+ * RSU pipeline to run.
+ */
+describe('the guard\'s callers', () => {
+    const SRC = readFileSync(join(__dirname, '..', 'resolvers', 'IntegrationDiscoveryResolver.ts'), 'utf-8');
+
+    it('IntegrationApplySchema filters on names whose casing resolveObjectInputs has corrected', () => {
+        // A filter built from the raw input is case-sensitive: `Clicks` for a stored `clicks` selected
+        // nothing, and the guard then told the caller to re-run discovery, which cannot fix casing.
+        const start = SRC.indexOf('async IntegrationApplySchema(');
+        const body = SRC.slice(start, SRC.indexOf('AssertTargetConfigs(', start));
+        const resolve = body.indexOf('await this.resolveObjectInputs(objects, sourceSchema, user);');
+        const names = body.indexOf('const resolvedNames = new Set(objects.map(o => o.SourceObjectName));');
+        expect(resolve).toBeGreaterThan(-1);
+        expect(names).toBeGreaterThan(resolve);
+        expect(body).toMatch(/sourceSchema\.Objects\.filter\(o => resolvedNames\.has\(o\.ExternalName\)\)/);
+    });
+
+    it('every call passes the drop reasons, and schema evolution says what it had already committed', () => {
+        const calls = [...SRC.matchAll(/AssertTargetConfigs\(objects, targetConfigs, companyIntegration\.Integration, drops([\s\S]*?)\);/g)];
+        expect(calls).toHaveLength(3);
+        expect(calls.filter(c => /already been saved/.test(c[1]))).toHaveLength(1);
+    });
+});

package/src/__tests__/BatchApplyParity.test.ts

@@ -0,0 +1,109 @@
+/**
+ * The two apply paths must agree, because the shared connector surface collapses onto the batch
+ * one. Two defects made them differ, and both are invisible until a surface migrates:
+ *
+ *  - MJ-APPLY-12: the batch never made the first-apply full-sync determination, and its input
+ *    declared `defaultValue: false` for FullSync, which made the null-coalesce dead code. A
+ *    re-apply the caller left unspecified therefore ran INCREMENTAL against objects whose
+ *    watermark the schema change had just reset. everything.txt: "for the very first RSU of a
+ *    connector, the sync afterwards should be chosen to be full/incremental, but always full
+ *    generally as the default."
+ *  - MJ-APPLY-13: the batch's skipRestart branch never applied remove-as-disable, so
+ *    UnselectedAction was a silent no-op and a deselected table kept syncing.
+ *
+ * Read from source: both live in a resolver that needs a provider, a connector and an RSU
+ * pipeline to invoke, and the property under test is a one-line policy, not a behaviour worth
+ * standing all that up to observe.
+ */
+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',
+);
+
+/** The body of a named input class, up to its closing brace. */
+function classBody(name: string): string {
+  const start = SRC.indexOf(`class ${name} {`);
+  expect(start, `${name} not found`).toBeGreaterThan(-1);
+  const rest = SRC.slice(start);
+  const end = rest.indexOf('\n}');
+  return end === -1 ? rest : rest.slice(0, end);
+}
+
+/** The body of a named resolver method, up to the next method at the same indent. */
+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('MJ-APPLY-12 first-apply full sync', () => {
+  it('the batch resolves FullSync from prior maps, not from a bare false', () => {
+    const body = methodBody('IntegrationApplyAllBatch');
+    expect(body).toMatch(/const fullSync = input\.FullSync\s*\?\?\s*!hadPriorMaps;/);
+    expect(body).toMatch(/FullSync:\s*fullSync,/);
+    expect(body).not.toMatch(/input\.FullSync\s*\?\?\s*false/);
+  });
+
+  it('ApplyAllBatchInput.FullSync has NO defaultValue, or the coalesce is dead again', () => {
+    // Scope to the CLASS. There are several `FullSync?: boolean` fields in this file and a bare
+    // find() picks ApplyAllInput's, which would pass no matter what the batch input declared.
+    const body = classBody('ApplyAllBatchInput');
+    const line = body.split('\n').find(l => l.includes('FullSync?: boolean') && l.includes('@Field'));
+    expect(line, 'ApplyAllBatchInput.FullSync not found').toBeDefined();
+    expect(line!).not.toMatch(/defaultValue/);
+  });
+
+  it('the single-connector path still does the same thing', () => {
+    expect(methodBody('IntegrationApplyAll')).toMatch(/input\.FullSync\s*\?\?\s*!hadPriorMaps/);
+  });
+
+  it('the prior-maps read UUID-validates the connection id, like every other caller-supplied id', () => {
+    // The batch takes its CompanyIntegrationIDs from the caller. The rest of this resolver refuses a
+    // non-UUID id with sqlUuid before it reaches an ExtraFilter; quote-doubling is not that check.
+    const body = methodBody('IntegrationApplyAllBatch');
+    expect(body).toMatch(/CompanyIntegrationID='\$\{sqlUuid\(connInput\.CompanyIntegrationID, 'CompanyIntegrationID'\)\}'/);
+    expect(body).not.toMatch(/connInput\.CompanyIntegrationID\.replace\(/);
+  });
+
+  it('the skipRestart branch starts its sync with the RESOLVED FullSync, as the restart path queues it', () => {
+    // The restart path carries the coalesced value in its PendingWork; the skipRestart branch starts
+    // the sync itself. Passing the raw input there means an omitted FullSync is undefined, which
+    // startSyncAfterApply reads as incremental — against tables the apply just created.
+    const body = methodBody('IntegrationApplyAllBatch');
+    const call = body.match(/this\.startSyncAfterApply\(build\.connInput\.CompanyIntegrationID,[^)]*\)/);
+    expect(call, 'skipRestart sync start not found').not.toBeNull();
+    expect(call![0]).not.toMatch(/input\.FullSync/);
+    expect(call![0]).toMatch(/build\.fullSync\)$/);
+    expect(body).toMatch(/^\s*fullSync,$/m);
+  });
+
+  it('the prior-maps probe skips the row count, as the single path does', () => {
+    // MaxRows: 1 is an existence probe; without SkipTotalRowCount the provider follows every hit
+    // with a COUNT(*) over the connection's maps.
+    const body = methodBody('IntegrationApplyAllBatch');
+    const probe = body.slice(body.indexOf('const priorMapsResult'), body.indexOf('const hadPriorMaps'));
+    expect(probe).toMatch(/MaxRows:\s*1,/);
+    expect(probe).toMatch(/SkipTotalRowCount:\s*true/);
+  });
+});
+
+describe('MJ-APPLY-13 remove-as-disable', () => {
+  it('the batch skipRestart branch disables unselected maps', () => {
+    const body = methodBody('IntegrationApplyAllBatch');
+    expect(body).toMatch(/UnselectedAction\s*\?\?\s*'disable'\)\s*!==\s*'ignore'/);
+    expect(body).toMatch(/DisableUnselectedEntityMaps\(/);
+  });
+
+  it('and honours the ignore opt-out rather than always disabling', () => {
+    const body = methodBody('IntegrationApplyAllBatch');
+    const at = body.indexOf('DisableUnselectedEntityMaps(');
+    // the guard must precede the call, not follow it
+    expect(body.lastIndexOf("!== 'ignore'", at)).toBeGreaterThan(-1);
+  });
+});

package/src/__tests__/BridgeHostInstance.test.ts

@@ -230,3 +230,45 @@ describe('StartBridgeOrphanReconciliation', () => {
         expect(runView.mock.calls[0][1]).toBe(user);
     });
 });
+
+describe('StartBridgeOrphanReconciliation with agentSessions.bridgeReconciler settings', () => {
+    const HOUR = 60 * 60_000;
+    afterEach(() => {
+        vi.restoreAllMocks();
+        vi.useRealTimers();
+    });
+
+    it('enabled: reconciles now, then on the configured interval', async () => {
+        vi.useFakeTimers();
+        const reconcile = vi.spyOn(AIBridgeEngine.Instance, 'ReconcileOrphans').mockResolvedValue(0);
+        const { provider } = bridgeTable([]);
+
+        StartBridgeOrphanReconciliation(provider, user, { enabled: true, sweepIntervalMs: 120_000 });
+        await vi.advanceTimersByTimeAsync(6 * 60_000);
+
+        expect(reconcile).toHaveBeenCalledTimes(4); // now + every 2 minutes
+    });
+
+    it('disabled: reconciles once now and never again', async () => {
+        vi.useFakeTimers();
+        const reconcile = vi.spyOn(AIBridgeEngine.Instance, 'ReconcileOrphans').mockResolvedValue(0);
+        const { provider } = bridgeTable([]);
+
+        StartBridgeOrphanReconciliation(provider, user, { enabled: false, sweepIntervalMs: 600_000 });
+        await vi.advanceTimersByTimeAsync(HOUR);
+
+        expect(reconcile).toHaveBeenCalledTimes(1);
+        expect(reconcile.mock.calls[0][0]).toBe(user);
+    });
+
+    it('with no settings keeps the shipped 10-minute repeat', async () => {
+        vi.useFakeTimers();
+        const reconcile = vi.spyOn(AIBridgeEngine.Instance, 'ReconcileOrphans').mockResolvedValue(0);
+        const { provider } = bridgeTable([]);
+
+        StartBridgeOrphanReconciliation(provider, user);
+        await vi.advanceTimersByTimeAsync(HOUR);
+
+        expect(reconcile).toHaveBeenCalledTimes(7);
+    });
+});

package/src/__tests__/CollectInactiveRowWarnings.test.ts

@@ -0,0 +1,115 @@
+/**
+ * The apply's declared-but-inactive-row warnings have to survive the path that PREFETCHES its schema.
+ *
+ * The collection used to live inside the resolver's schema REBUILD, so the batch apply lost it twice:
+ * its own rebuild passed no collector, and handing the result down to the shared builder took the
+ * `prefetchedSourceSchema` branch, which skips the rebuild entirely. An operator whose selected table
+ * came back without a column therefore had nothing to read on the batch path while the single path
+ * explained it.
+ *
+ * The warnings never depended on the rebuild — they are the catalog's own `Status` rows — so the
+ * gathering is a function of (catalog, integration, requested names). These tests pin it against a
+ * literal catalog, which is also the only way to test it at all: the resolver imports schema-builder
+ * and schema-engine and cannot be loaded in a unit test.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CollectInactiveRowWarnings } from '../integration/InactiveRowWarnings.js';
+import type { CatalogStatusReader } from '../integration/InactiveRowWarnings.js';
+
+type Row = { ID: string; Name: string; Status: string | null };
+
+/** A catalog of objects, each with its fields. `Status` is the whole question. */
+function catalog(objects: Array<Row & { Fields: Array<{ Name: string; Status: string | null }> }>): CatalogStatusReader {
+    return {
+        GetActiveIntegrationObjects: () => objects.filter(o => o.Status === 'Active'),
+        GetIntegrationObjectsByIntegrationID: () => objects,
+        GetIntegrationObjectFields: (objectID: string) => objects.find(o => o.ID === objectID)?.Fields ?? [],
+    };
+}
+
+const contacts = {
+    ID: 'io-1', Name: 'Contacts', Status: 'Active',
+    Fields: [
+        { Name: 'ID', Status: 'Active' },
+        { Name: 'MiddleName', Status: 'Disabled' },
+    ],
+};
+const invoices = { ID: 'io-2', Name: 'Invoices', Status: 'Disabled', Fields: [{ Name: 'ID', Status: 'Active' }] };
+
+describe('CollectInactiveRowWarnings', () => {
+    it('names a deactivated FIELD of an object the apply does materialize', () => {
+        const warnings = CollectInactiveRowWarnings(catalog([contacts]), 'int-1', ['Contacts']);
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]).toContain('Contacts:');
+        expect(warnings[0]).toContain('MiddleName (Disabled)');
+    });
+
+    it('reports a REQUESTED object that is not Active — the caller named it and got nothing', () => {
+        const warnings = CollectInactiveRowWarnings(catalog([contacts, invoices]), 'int-1', ['Contacts', 'Invoices']);
+        expect(warnings.some(w => w.includes('Invoices (Disabled)'))).toBe(true);
+    });
+
+    it('matches requested names case-insensitively, the way the apply resolves them', () => {
+        const warnings = CollectInactiveRowWarnings(catalog([contacts]), 'int-1', ['contacts']);
+        expect(warnings[0]).toContain('MiddleName (Disabled)');
+    });
+
+    it('reads fields ONLY for the objects in scope', () => {
+        // An out-of-scope object's own dropped fields are not this apply's business, and on a large
+        // catalog reporting them would bury the one line that matters.
+        const other = {
+            ID: 'io-3', Name: 'Events', Status: 'Active',
+            Fields: [{ Name: 'Venue', Status: 'Disabled' }],
+        };
+        const warnings = CollectInactiveRowWarnings(catalog([contacts, other]), 'int-1', ['Contacts']);
+        expect(warnings.join(' ')).not.toContain('Venue');
+    });
+
+    it('stays quiet about deactivated OBJECTS when nothing was requested by name', () => {
+        // The unfiltered apply. Hundreds of deactivated objects are the normal state of a large
+        // catalog; the field warnings for what IS materialized still come through.
+        const warnings = CollectInactiveRowWarnings(catalog([contacts, invoices]), 'int-1', []);
+        expect(warnings.join(' ')).not.toContain('Invoices');
+        expect(warnings.join(' ')).toContain('MiddleName (Disabled)');
+    });
+
+    it('says nothing when everything in scope is Active', () => {
+        const clean = {
+            ID: 'io-9', Name: 'Clean', Status: 'Active',
+            Fields: [{ Name: 'ID', Status: 'Active' }],
+        };
+        expect(CollectInactiveRowWarnings(catalog([clean]), 'int-1', ['Clean'])).toEqual([]);
+    });
+});
+
+/**
+ * Under a per-connection catalog the engine answers [] for a connection's fields during an apply, so
+ * every caller has to hand the helper the fields it loaded itself, or field-level warnings vanish.
+ * Read from source: the callers are resolver mutations that need a provider and a pipeline to run.
+ */
+describe('every inactive-row warning caller passes the connection\'s own fields', () => {
+    const SRC = readFileSync(join(__dirname, '..', 'resolvers', 'IntegrationDiscoveryResolver.ts'), 'utf-8');
+    const calls = [...SRC.matchAll(/this\.collectInactiveRowWarnings\(([\s\S]*?)\)\)?;/g)].map(m => m[1]);
+
+    it('finds the callers', () => {
+        expect(calls.length).toBeGreaterThanOrEqual(3);
+    });
+
+    it('passes scopedFields at every call', () => {
+        for (const args of calls) expect(args).toMatch(/scopedFields\s*,?\s*$/);
+    });
+
+    it('loads the fields BEFORE the batch branch, so the prefetched path has them too', () => {
+        const at = SRC.indexOf('if (prefetchedSourceSchema) {');
+        const load = SRC.lastIndexOf('const scopedFields = await LoadScopedFieldsForBuild(', at);
+        expect(at).toBeGreaterThan(-1);
+        expect(load).toBeGreaterThan(-1);
+        expect(at - load).toBeLessThan(400);
+    });
+
+    it('refreshes the catalog caches through the provider the mutation already holds', () => {
+        expect(SRC).not.toMatch(/refreshIntegrationCatalogCaches\(user\);/);
+    });
+});

package/src/__tests__/ConnectionPause.test.ts

@@ -0,0 +1,192 @@
+/**
+ * everything.txt C6: pausing a connection must actually pause it — and resuming must put back
+ * what pause took, not "everything".
+ *
+ * Each test below pins a way this went wrong or would go wrong. The two that matter most are
+ * `DecidePauseWrite` (a second pause must not erase the first pause's record) and the two guards
+ * in `DecideSchedulesToResume` (never resurrect a schedule the operator turned off themselves).
+ */
+import { describe, it, expect } from 'vitest';
+import {
+    DecideSchedulesToPause,
+    DecidePauseWrite,
+    DecideSchedulesToResume,
+    ReadPausedSchedules,
+    WritePausedSchedules,
+    DescribeCancelScope,
+    DescribeCancelOutcome,
+    DescribePauseOutcome,
+    PAUSED_SCHEDULES_KEY,
+    type ScheduleJobState,
+    type PausedScheduleRecord,
+} from '../integration/ConnectionPause.js';
+
+const job = (ID: string, Status: string | null, Kind: 'sync' | 'discovery' = 'sync'): ScheduleJobState =>
+    ({ ID, Status, Kind });
+
+describe('DecideSchedulesToPause', () => {
+    it('moves only the Active jobs', () => {
+        const out = DecideSchedulesToPause([job('a', 'Active'), job('b', 'Paused', 'discovery'), job('c', 'Active', 'discovery')]);
+        expect(out.map(r => r.ID)).toEqual(['a', 'c']);
+    });
+
+    it('leaves an already-Paused job out of the record, so resume cannot turn it on', () => {
+        // The whole point: 'b' was off before the pause. If it appeared here, resume would
+        // silently start a schedule the operator had deliberately stopped.
+        const out = DecideSchedulesToPause([job('b', 'Paused')]);
+        expect(out).toEqual([]);
+    });
+
+    it('ignores statuses that are neither Active nor Paused', () => {
+        expect(DecideSchedulesToPause([job('x', 'Disabled'), job('y', null)])).toEqual([]);
+    });
+
+    it('carries the kind through for the operator message', () => {
+        expect(DecideSchedulesToPause([job('a', 'Active', 'discovery')])).toEqual([{ ID: 'a', Kind: 'discovery' }]);
+    });
+});
+
+describe('DecidePauseWrite — the second pause must not erase the first', () => {
+    it('writes the record on a first pause', () => {
+        expect(DecidePauseWrite([], [{ ID: 'a', Kind: 'sync' }])).toEqual([{ ID: 'a', Kind: 'sync' }]);
+    });
+
+    it('REFUSES to overwrite a stored record with the empty set a re-pause produces', () => {
+        // Deactivate an already-deactivated connection: every job is Paused, so nothing is
+        // "moved" and newlyPaused is []. Writing that would lose the record and strand both
+        // schedules off forever, with no error anywhere.
+        const stored: PausedScheduleRecord[] = [{ ID: 'a', Kind: 'sync' }, { ID: 'b', Kind: 'discovery' }];
+        expect(DecidePauseWrite(stored, [])).toBeNull();
+    });
+
+    it('adds what a re-pause DID move to the stored record, keeping the stored entries as they were', () => {
+        // A schedule created or switched back on while paused, or a record a resume could not
+        // clear. Dropping the newly paused job would leave it paused with nothing to restore it.
+        const stored: PausedScheduleRecord[] = [{ ID: 'a', Kind: 'sync' }];
+        expect(DecidePauseWrite(stored, [{ ID: 'c', Kind: 'discovery' }])).toEqual([
+            { ID: 'a', Kind: 'sync' },
+            { ID: 'c', Kind: 'discovery' },
+        ]);
+    });
+
+    it('writes nothing when everything the re-pause moved is already recorded, whatever the id casing', () => {
+        const stored: PausedScheduleRecord[] = [{ ID: 'abc-1', Kind: 'sync' }];
+        expect(DecidePauseWrite(stored, [{ ID: 'ABC-1', Kind: 'sync' }])).toBeNull();
+    });
+
+    it('writes nothing when there is neither a stored record nor anything moved', () => {
+        expect(DecidePauseWrite([], [])).toBeNull();
+    });
+});
+
+describe('DecideSchedulesToResume', () => {
+    it('restores exactly the recorded jobs', () => {
+        const stored: PausedScheduleRecord[] = [{ ID: 'a', Kind: 'sync' }];
+        expect(DecideSchedulesToResume(stored, [job('a', 'Paused'), job('b', 'Paused')])).toEqual(['a']);
+    });
+
+    it('never touches a job that was NOT recorded, however it looks now', () => {
+        // 'b' is Paused and looks identical to 'a'. Only the record distinguishes them.
+        const out = DecideSchedulesToResume([{ ID: 'a', Kind: 'sync' }], [job('a', 'Paused'), job('b', 'Paused')]);
+        expect(out).not.toContain('b');
+    });
+
+    it('does not resurrect a recorded job that has since been deleted', () => {
+        expect(DecideSchedulesToResume([{ ID: 'gone', Kind: 'sync' }], [job('a', 'Paused')])).toEqual([]);
+    });
+
+    it('does not rewrite a recorded job someone already set back to Active', () => {
+        expect(DecideSchedulesToResume([{ ID: 'a', Kind: 'sync' }], [job('a', 'Active')])).toEqual([]);
+    });
+
+    it('returns nothing when the record is empty', () => {
+        expect(DecideSchedulesToResume([], [job('a', 'Paused')])).toEqual([]);
+    });
+});
+
+describe('Configuration round-trip', () => {
+    it('preserves unrelated keys when writing', () => {
+        const cfg = JSON.stringify({ discoveryMaxRecords: 50, catalogSource: 'perConnection' });
+        const out = JSON.parse(WritePausedSchedules(cfg, [{ ID: 'a', Kind: 'sync' }]));
+        expect(out.discoveryMaxRecords).toBe(50);
+        expect(out.catalogSource).toBe('perConnection');
+        expect(out[PAUSED_SCHEDULES_KEY]).toEqual([{ ID: 'a', Kind: 'sync' }]);
+    });
+
+    it('removes the key entirely when the record is cleared, rather than leaving []', () => {
+        const cfg = WritePausedSchedules(JSON.stringify({ a: 1 }), [{ ID: 'x', Kind: 'sync' }]);
+        const cleared = JSON.parse(WritePausedSchedules(cfg, []));
+        expect(PAUSED_SCHEDULES_KEY in cleared).toBe(false);
+        expect(cleared.a).toBe(1);
+    });
+
+    it('round-trips', () => {
+        const rec: PausedScheduleRecord[] = [{ ID: 'a', Kind: 'sync' }, { ID: 'b', Kind: 'discovery' }];
+        expect(ReadPausedSchedules(WritePausedSchedules(null, rec))).toEqual(rec);
+    });
+
+    it('reads nothing from null, junk, an array, or a non-array value', () => {
+        expect(ReadPausedSchedules(null)).toEqual([]);
+        expect(ReadPausedSchedules('not json {')).toEqual([]);
+        expect(ReadPausedSchedules('[1,2,3]')).toEqual([]);
+        expect(ReadPausedSchedules(JSON.stringify({ [PAUSED_SCHEDULES_KEY]: 'nope' }))).toEqual([]);
+    });
+
+    it('drops malformed entries instead of yielding an id-less record', () => {
+        // An entry with no ID would produce a restore target of undefined.
+        const cfg = JSON.stringify({ [PAUSED_SCHEDULES_KEY]: [{ Kind: 'sync' }, null, 7, { ID: '', Kind: 'sync' }, { ID: 'ok' }] });
+        expect(ReadPausedSchedules(cfg)).toEqual([{ ID: 'ok', Kind: 'sync' }]);
+    });
+
+    it('replaces, rather than refuses, when Configuration is unparseable', () => {
+        const out = JSON.parse(WritePausedSchedules('{broken', [{ ID: 'a', Kind: 'sync' }]));
+        expect(out[PAUSED_SCHEDULES_KEY]).toEqual([{ ID: 'a', Kind: 'sync' }]);
+    });
+});
+
+describe('DescribeCancelScope — reports what is TRUE, not what is reassuring', () => {
+    it('says none when nothing is live', () => {
+        expect(DescribeCancelScope({ liveRunPresent: false, durableRequestRecorded: false, runningInThisProcess: true }))
+            .toBe('none');
+    });
+
+    it('prefers durable when the request was recorded', () => {
+        expect(DescribeCancelScope({ liveRunPresent: true, durableRequestRecorded: true, runningInThisProcess: false }))
+            .toBe('durable');
+    });
+
+    it('falls back to this-process when only the in-process registry knows', () => {
+        expect(DescribeCancelScope({ liveRunPresent: true, durableRequestRecorded: false, runningInThisProcess: true }))
+            .toBe('this-process');
+    });
+
+    it('admits unknown when a run is live and neither signal reached it', () => {
+        // The tenant has no CancelRequestedAt column and the owner is another process.
+        expect(DescribeCancelScope({ liveRunPresent: true, durableRequestRecorded: false, runningInThisProcess: false }))
+            .toBe('unknown');
+    });
+
+    it('never promises a stop it cannot deliver', () => {
+        expect(DescribeCancelOutcome('unknown')).not.toMatch(/will stop/i);
+        expect(DescribeCancelOutcome('unknown')).toMatch(/no new sync will start/i);
+        expect(DescribeCancelOutcome('durable')).toMatch(/will stop after the current batch/i);
+        expect(DescribeCancelOutcome('none')).toBe('');
+    });
+});
+
+describe('DescribePauseOutcome', () => {
+    it('names both schedules when both moved', () => {
+        const msg = DescribePauseOutcome([{ ID: 'a', Kind: 'sync' }, { ID: 'b', Kind: 'discovery' }], false);
+        expect(msg).toMatch(/data sync and schema refresh/);
+        expect(msg).toMatch(/schedules\./);
+    });
+
+    it('is singular for one', () => {
+        expect(DescribePauseOutcome([{ ID: 'a', Kind: 'discovery' }], false)).toBe('Paused the schema refresh schedule.');
+    });
+
+    it('distinguishes "already paused" from "nothing to pause"', () => {
+        expect(DescribePauseOutcome([], true)).toMatch(/already paused/i);
+        expect(DescribePauseOutcome([], false)).toMatch(/No active schedules/i);
+    });
+});