meadow-integration 1.1.2 → 1.1.3

package/source/services/clone/Meadow-Service-Sync-Entity-Ongoing.js

@@ -1,5 +1,6 @@
 const libFableServiceProviderBase = require('fable-serviceproviderbase');
 const libMeadowOperation = require('./Meadow-Service-Operation.js');
+const libSyncPoolLimit = require('./Meadow-Service-Sync-PoolLimit.js');
 
 class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 {
@@ -60,6 +61,13 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 			? this.options.DateTimePrecisionMS
 			: 1000;
 
+		// How many records to reconcile/upsert concurrently within a table.
+		// Defaults to the DB connection pool size (capped) so fan-out never
+		// oversubscribes the pool (a 2-connection clone must not fan out 5-wide)
+		// nor runs unbounded on a very large pool.  Overridable globally or
+		// per-table via SyncEntityOptions.SyncRecordConcurrency.
+		this.SyncRecordConcurrency = this._resolveSyncRecordConcurrency(this.options.SyncRecordConcurrency);
+
 		this.Meadow = false;
 
 		this.operation = new libMeadowOperation(this.fable);
@@ -67,6 +75,27 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 		this.skipSync = false;
 	}
 
+	/**
+	 * Resolve the per-record fan-out concurrency for this entity.
+	 *
+	 * Precedence: an explicit configured value (global or per-table) wins and is
+	 * used as-is; otherwise fall back to the automatic default (pool size, capped)
+	 * — see resolveDefaultConcurrency in Meadow-Service-Sync-PoolLimit.js.
+	 *
+	 * @param {number|string} pConfigured - configured concurrency, if any
+	 * @returns {number} a positive integer concurrency
+	 */
+	_resolveSyncRecordConcurrency(pConfigured)
+	{
+		let tmpConfigured = parseInt(pConfigured, 10);
+		if (!isNaN(tmpConfigured) && tmpConfigured > 0)
+		{
+			return tmpConfigured;
+		}
+
+		return libSyncPoolLimit.resolveDefaultConcurrency(this.fable);
+	}
+
 	initialize(fCallback)
 	{
 		if (this.fable.hasOwnProperty('Meadow'))
@@ -78,46 +107,14 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 
 		if (this.Meadow && this.Meadow.provider)
 		{
+			// Init only ensures the table exists.  Index provisioning is handled
+			// separately and authoritatively by the index-convergence step
+			// (Meadow-Service-IndexConvergence), so indexes have a single writer —
+			// the legacy per-column MeadowConnectionManager.createIndex path was
+			// retired to avoid two mechanisms fighting over the same indexes.
 			return this.Meadow.provider.getProvider().createTable(this.EntitySchema, (pCreateError) =>
 			{
-				// Sync-entity init intentionally does not create indexes here
-				// in the DataCloner flow.  See the comment in
-				// Meadow-Service-Sync-Entity-Initial.js for the rationale —
-				// indexes go through the provider's createIndices path
-				// (triggered by DataCloner's /indices/create endpoint) rather
-				// than via MeadowConnectionManager, which isn't registered in
-				// the DataCloner service container.
-				const tmpGUIDColumn = this.EntitySchema.Columns.find((c) => c.DataType == 'GUID');
-				const tmpDeletedColumn = this.EntitySchema.Columns.find((c) => c.Column == 'Deleted');
-
-				let tmpCanCreateIndexes = (tmpGUIDColumn || tmpDeletedColumn)
-					&& this.fable.MeadowConnectionManager
-					&& this.fable.MeadowConnectionManager.ConnectionPool
-					&& typeof(this.fable.MeadowConnectionManager.createIndex) === 'function';
-
-				if (!tmpCanCreateIndexes)
-				{
-					return fCallback(pCreateError);
-				}
-
-				let tmpAnticipate = this.fable.newAnticipate();
-				if (tmpGUIDColumn)
-				{
-					tmpAnticipate.anticipate(
-						(fNext) =>
-						{
-							return this.fable.MeadowConnectionManager.createIndex(this.EntitySchema, tmpGUIDColumn, true, fNext);
-						});
-				}
-				if (tmpDeletedColumn)
-				{
-					tmpAnticipate.anticipate(
-						(fNext) =>
-						{
-							return this.fable.MeadowConnectionManager.createIndex(this.EntitySchema, tmpDeletedColumn, false, fNext);
-						});
-				}
-				tmpAnticipate.wait((pIndexError) => { return fCallback(pCreateError); });
+				return fCallback(pCreateError);
 			});
 		}
 		return fCallback();
@@ -467,7 +464,7 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 						return fCallback(null, tmpSyncedCount);
 					}
 
-					this.fable.Utility.eachLimit(pRecords, 5,
+					this.fable.Utility.eachLimit(pRecords, this.SyncRecordConcurrency,
 						(pRecord, fRecordDone) =>
 						{
 							this._upsertRecord(pRecord,
@@ -723,7 +720,7 @@ class MeadowSyncEntityOngoing extends libFableServiceProviderBase
 								return fCallback();
 							}
 
-							this.fable.Utility.eachLimit(pBody, 5,
+							this.fable.Utility.eachLimit(pBody, this.SyncRecordConcurrency,
 								(pEntityRecord, fRecordComplete) =>
 								{
 									const tmpRecordID = pEntityRecord[this.DefaultIdentifier];

package/source/services/clone/Meadow-Service-Sync-Entity-OngoingEventualConsistency.js

@@ -260,7 +260,7 @@ class MeadowSyncEntityOngoingEventualConsistency extends libMeadowSyncEntityOngo
 								return fFinish('complete');
 							}
 
-							this.fable.Utility.eachLimit(pPageBody, 5,
+							this.fable.Utility.eachLimit(pPageBody, this.SyncRecordConcurrency,
 								(pEntityRecord, fRecordComplete) =>
 								{
 									tmpCounters.seen++;
@@ -504,7 +504,7 @@ class MeadowSyncEntityOngoingEventualConsistency extends libMeadowSyncEntityOngo
 						tmpMaxID = pPageBody[0][this.DefaultIdentifier]; // DESC → first row is the highest id
 					}
 
-					this.fable.Utility.eachLimit(pPageBody, 5,
+					this.fable.Utility.eachLimit(pPageBody, this.SyncRecordConcurrency,
 						(pEntityRecord, fRecordComplete) =>
 						{
 							tmpCounters.seen++;

package/source/services/clone/Meadow-Service-Sync-Entity-TrueUp.js

@@ -130,7 +130,7 @@ class MeadowSyncEntityTrueUp extends libMeadowSyncEntityOngoing
 									return fStageComplete();
 								}
 
-								this.fable.Utility.eachLimit(pRecords, 5,
+								this.fable.Utility.eachLimit(pRecords, this.SyncRecordConcurrency,
 									(pRecord, fRecordDone) =>
 									{
 										this._upsertRecord(pRecord,

package/source/services/clone/Meadow-Service-Sync-PoolLimit.js

@@ -0,0 +1,76 @@
+'use strict';
+
+// Connection providers that expose a connection pool size.  The clone/sync
+// engine defaults its fan-out (per-record reconcile, per-table init) to
+// whichever of these is the active clone target so it never oversubscribes the
+// pool.  Only one is instantiated per clone; SQLite is intentionally absent
+// (no pool — single writer).
+const POOLED_CONNECTION_PROVIDER_SERVICES = [ 'MeadowMSSQLProvider', 'MeadowMySQLProvider', 'MeadowPostgreSQLProvider' ];
+
+// Fan-out used when no pool size is reported (e.g. SQLite — single writer).
+const DEFAULT_CONCURRENCY = 5;
+
+// Ceiling on the AUTO-derived default fan-out.  Sizing to the pool avoids
+// oversubscribing a small pool, but a very large pool (say 100) should not make
+// the sync fan out 100-wide by default: the concurrency also gates source-API
+// reads, and that many in-flight reconciles would hammer the source and balloon
+// memory.  An explicit SyncRecordConcurrency / SyncTableInitConcurrency bypasses
+// this cap — it only tempers the automatic default.
+const MAX_DEFAULT_CONCURRENCY = 16;
+
+/**
+ * Resolve the active clone target's connection pool size.
+ *
+ * Returns the pool size of whichever pooled connection provider is registered on
+ * the fable, or 0 when the active provider does not report one (e.g. SQLite) so
+ * callers can apply their own default.
+ *
+ * @param {object} pFable - the fable instance the sync is running on
+ * @returns {number} the pool size, or 0 if none is available
+ */
+function resolveConnectionPoolLimit(pFable)
+{
+	if (!pFable)
+	{
+		return 0;
+	}
+	for (let i = 0; i < POOLED_CONNECTION_PROVIDER_SERVICES.length; i++)
+	{
+		let tmpProvider = pFable[POOLED_CONNECTION_PROVIDER_SERVICES[i]];
+		if (tmpProvider && (typeof(tmpProvider.connectionPoolLimit) === 'number') && tmpProvider.connectionPoolLimit > 0)
+		{
+			return tmpProvider.connectionPoolLimit;
+		}
+	}
+	return 0;
+}
+
+/**
+ * Resolve the automatic default fan-out concurrency for the active clone target.
+ *
+ * Sizes to the connection pool so the sync neither oversubscribes a small pool
+ * nor fans out unbounded on a very large one (capped at MAX_DEFAULT_CONCURRENCY),
+ * and falls back to DEFAULT_CONCURRENCY when the provider reports no pool (e.g.
+ * SQLite).  Callers apply this only when no explicit concurrency is configured;
+ * an explicit value is honored as-is and is not subject to the cap.
+ *
+ * @param {object} pFable - the fable instance the sync is running on
+ * @returns {number} a positive default concurrency
+ */
+function resolveDefaultConcurrency(pFable)
+{
+	let tmpPoolLimit = resolveConnectionPoolLimit(pFable);
+	if (tmpPoolLimit > 0)
+	{
+		return Math.min(tmpPoolLimit, MAX_DEFAULT_CONCURRENCY);
+	}
+	return DEFAULT_CONCURRENCY;
+}
+
+module.exports = {
+	POOLED_CONNECTION_PROVIDER_SERVICES: POOLED_CONNECTION_PROVIDER_SERVICES,
+	DEFAULT_CONCURRENCY: DEFAULT_CONCURRENCY,
+	MAX_DEFAULT_CONCURRENCY: MAX_DEFAULT_CONCURRENCY,
+	resolveConnectionPoolLimit: resolveConnectionPoolLimit,
+	resolveDefaultConcurrency: resolveDefaultConcurrency
+};

package/source/services/clone/Meadow-Service-Sync.js

@@ -4,6 +4,7 @@ const libMeadowSyncEntityOngoing = require('./Meadow-Service-Sync-Entity-Ongoing
 const libMeadowSyncEntityOngoingEventualConsistency = require('./Meadow-Service-Sync-Entity-OngoingEventualConsistency.js');
 const libMeadowSyncEntityTrueUp = require('./Meadow-Service-Sync-Entity-TrueUp.js');
 const libMeadowSyncEntityComparisonOnly = require('./Meadow-Service-Sync-Entity-ComparisonOnly.js');
+const libSyncPoolLimit = require('./Meadow-Service-Sync-PoolLimit.js');
 
 class MeadowSync extends libFableServiceProviderBase
 {
@@ -165,7 +166,16 @@ class MeadowSync extends libFableServiceProviderBase
 		let tmpErrorCount = 0;
 		let tmpSuccessCount = 0;
 
-		this.fable.Utility.eachLimit(this.MeadowSchemaTableList, 5,
+		// Bound table-initialization fan-out (createTable per table) to the DB
+		// connection pool size so deploy doesn't oversubscribe a small pool.
+		// Overridable via SyncTableInitConcurrency.
+		let tmpTableInitConcurrency = parseInt(this.options.SyncTableInitConcurrency, 10);
+		if (isNaN(tmpTableInitConcurrency) || tmpTableInitConcurrency < 1)
+		{
+			tmpTableInitConcurrency = libSyncPoolLimit.resolveDefaultConcurrency(this.fable);
+		}
+
+		this.fable.Utility.eachLimit(this.MeadowSchemaTableList, tmpTableInitConcurrency,
 			(pEntitySchemaName, fSyncInitializationComplete) =>
 			{
 				tmpEntityIndex++;
@@ -186,6 +196,7 @@ class MeadowSync extends libFableServiceProviderBase
 						TrueUpPageSize: this.TrueUpPageSize,
 						DeleteCursorStatePath: this.options.DeleteCursorStatePath,
 						DeleteResweepIntervalHours: this.options.DeleteResweepIntervalHours,
+						SyncRecordConcurrency: this.options.SyncRecordConcurrency,
 					};
 
 					// Apply per-entity option overrides if configured

package/test/Meadow-Integration-IndexConvergence-SQLite_test.js

@@ -0,0 +1,144 @@
+'use strict';
+
+/**
+ * Live-database smoke test for index convergence.
+ *
+ * Unlike the stub-provider unit test, this runs the convergence engine against a
+ * REAL connector + REAL database (Node's built-in node:sqlite via
+ * meadow-connection-sqlite) — exercising the actual introspectTableIndices,
+ * generateCreateIndexStatements, createIndex, and the NEW dropIndex end to end.
+ * No external server / credentials required.
+ */
+
+const Chai = require('chai');
+const Expect = Chai.expect;
+
+const libFs = require('fs');
+const libPath = require('path');
+const libOs = require('os');
+
+const libFable = require('fable');
+const libMeadowConnectionSQLite = require('meadow-connection-sqlite');
+const libIndexPolicy = require('../source/services/clone/Meadow-Service-IndexPolicy.js');
+const libConvergence = require('../source/services/clone/Meadow-Service-IndexConvergence.js');
+
+const _Schema =
+{
+	TableName: 'Document',
+	DefaultIdentifier: 'IDDocument',
+	Columns:
+	[
+		{ Column: 'IDDocument',   DataType: 'ID'   },
+		{ Column: 'GUIDDocument', DataType: 'GUID', Size: 36 },
+		{ Column: 'Deleted',      DataType: 'Boolean' },
+		{ Column: 'Name',         DataType: 'String', Size: 128 }
+	]
+};
+
+const COMPOSITE = 'IX_M_SYNC_Document_Deleted_IDDocument';
+const GUIDIDX = 'IX_M_SYNC_Document_GUIDDocument';
+
+suite('Meadow Integration - IndexConvergence (live SQLite)',
+	() =>
+	{
+		let _Fable = null;
+		let _Provider = null;
+		let _DbPath = '';
+
+		setup((fDone) =>
+		{
+			_DbPath = libPath.join(libOs.tmpdir(), `mi-index-converge-${process.pid}-${_Fable ? 1 : 0}.sqlite`);
+			if (libFs.existsSync(_DbPath)) { libFs.unlinkSync(_DbPath); }
+
+			_Fable = new libFable({ Product: 'IndexConvergenceSmoke', SQLite: { SQLiteFilePath: _DbPath } });
+			_Fable.serviceManager.addServiceType('MeadowSQLiteProvider', libMeadowConnectionSQLite);
+			_Fable.serviceManager.instantiateServiceProvider('MeadowSQLiteProvider');
+
+			_Fable.MeadowSQLiteProvider.connectAsync((pError) =>
+			{
+				if (pError) { return fDone(pError); }
+				_Provider = _Fable.MeadowSQLiteProvider;
+				// Create the table (real DDL) before each test.
+				_Provider.db.exec(_Provider.generateCreateTableStatement(_Schema));
+				return fDone();
+			});
+		});
+
+		let converge = (pOptions, fCallback) =>
+		{
+			let tmpDesired = libIndexPolicy.resolveDesiredIndexes(_Schema, { StandardOperationalIndexes: true });
+			libConvergence.convergeTableIndexes(_Provider, _Schema, tmpDesired,
+				Object.assign({ PruneScope: 'managed', log: _Fable.log }, pOptions || {}), fCallback);
+		};
+
+		test('fresh table: creates the operational indexes (composite + non-unique GUID), drops nothing',
+			(fDone) =>
+			{
+				converge({}, (pError, pResult) =>
+				{
+					if (pError) { return fDone(pError); }
+					_Provider.introspectTableIndices('Document', (pIntrospectError, pActual) =>
+					{
+						try {
+							if (pIntrospectError) { return fDone(pIntrospectError); }
+							let tmpNames = pActual.map((pIndex) => { return pIndex.Name; });
+							Expect(tmpNames, 'composite present').to.include(COMPOSITE);
+							Expect(tmpNames, 'GUID index present').to.include(GUIDIDX);
+							let tmpGUID = pActual.find((pIndex) => { return pIndex.Name === GUIDIDX; });
+							Expect(tmpGUID.Unique, 'GUID index is non-unique').to.not.equal(true);
+							Expect(pResult.dropped, 'nothing dropped on a fresh table').to.have.length(0);
+							fDone();
+						} catch (e) { fDone(e); }
+					});
+				});
+			});
+
+		test('managed prune: replaces a precursor [Deleted] index, leaves an unmanaged index alone',
+			(fDone) =>
+			{
+				// Seed a precursor-style single-column index + an external/unmanaged one.
+				_Provider.db.exec('CREATE INDEX IF NOT EXISTS "Deleted" ON "Document" ("Deleted")');
+				_Provider.db.exec('CREATE INDEX IF NOT EXISTS "IX_dba_custom" ON "Document" ("Name")');
+
+				converge({}, (pError, pResult) =>
+				{
+					if (pError) { return fDone(pError); }
+					_Provider.introspectTableIndices('Document', (pIntrospectError, pActual) =>
+					{
+						try {
+							if (pIntrospectError) { return fDone(pIntrospectError); }
+							let tmpNames = pActual.map((pIndex) => { return pIndex.Name; });
+							Expect(tmpNames, 'new composite created').to.include(COMPOSITE);
+							Expect(tmpNames, 'precursor [Deleted] dropped (managed)').to.not.include('Deleted');
+							Expect(tmpNames, 'unmanaged index untouched').to.include('IX_dba_custom');
+							Expect(pResult.dropped, 'precursor was dropped').to.include('Deleted');
+							fDone();
+						} catch (e) { fDone(e); }
+					});
+				});
+			});
+
+		test('idempotent: a second convergence run creates and drops nothing',
+			(fDone) =>
+			{
+				converge({}, (pFirstError) =>
+				{
+					if (pFirstError) { return fDone(pFirstError); }
+					converge({}, (pError, pResult) =>
+					{
+						try {
+							if (pError) { return fDone(pError); }
+							Expect(pResult.created, 'nothing created on 2nd run').to.have.length(0);
+							Expect(pResult.dropped, 'nothing dropped on 2nd run').to.have.length(0);
+							fDone();
+						} catch (e) { fDone(e); }
+					});
+				});
+			});
+
+		teardown(() =>
+		{
+			try { if (_Provider && _Provider.db) { _Provider.db.close(); } } catch (e) {}
+			try { if (_DbPath && libFs.existsSync(_DbPath)) { libFs.unlinkSync(_DbPath); } } catch (e) {}
+		});
+	});

package/test/Meadow-Integration-IndexConvergence_test.js

@@ -0,0 +1,163 @@
+'use strict';
+
+const Chai = require('chai');
+const Expect = Chai.expect;
+
+const libConvergence = require('../source/services/clone/Meadow-Service-IndexConvergence.js');
+const libIndexPolicy = require('../source/services/clone/Meadow-Service-IndexPolicy.js');
+
+const _DocSchema =
+{
+	TableName: 'Document',
+	DefaultIdentifier: 'IDDocument',
+	Columns:
+	[
+		{ Column: 'IDDocument',   DataType: 'ID'   },
+		{ Column: 'GUIDDocument', DataType: 'GUID' },
+		{ Column: 'Deleted',      DataType: 'Boolean' }
+	]
+};
+
+// Desired set from the policy: (Deleted, IDDocument) composite + GUID lookup.
+const _Desired = libIndexPolicy.resolveDesiredIndexes(_DocSchema, {});
+const COMPOSITE = 'IX_M_SYNC_Document_Deleted_IDDocument';
+const GUIDIDX = 'IX_M_SYNC_Document_GUIDDocument';
+
+// Stub connection provider recording the create/drop call order.
+function makeStubProvider(pActual, pFailCreateNames)
+{
+	let tmpFail = new Set(pFailCreateNames || []);
+	let tmpCalls = [];
+	return {
+		calls: tmpCalls,
+		introspectTableIndices: (pTable, fCallback) => { return fCallback(null, (pActual || []).slice()); },
+		generateCreateIndexStatements: (pSchema) =>
+		{
+			return (pSchema.Indices || []).map((pIndex) =>
+			{
+				return { Name: pIndex.Name, Statement: `CREATE INDEX ${pIndex.Name}`, CheckStatement: `CHECK ${pIndex.Name}` };
+			});
+		},
+		createIndex: (pStatement, fCallback) =>
+		{
+			tmpCalls.push('create:' + pStatement.Name);
+			if (tmpFail.has(pStatement.Name)) { return fCallback(new Error('simulated create failure')); }
+			return fCallback();
+		},
+		dropIndex: (pTableName, pIndexName, fCallback) =>
+		{
+			tmpCalls.push('drop:' + pIndexName);
+			return fCallback();
+		}
+	};
+}
+
+suite('Meadow Integration - IndexConvergence',
+	() =>
+	{
+		test('additive: creates the missing desired indexes, drops nothing',
+			(fDone) =>
+			{
+				let tmpProvider = makeStubProvider([]);
+				libConvergence.convergeTableIndexes(tmpProvider, _DocSchema, _Desired, { PruneScope: 'managed' },
+					(pError, pResult) =>
+					{
+						try {
+							Expect(pError).to.equal(null);
+							Expect(pResult.created).to.have.members([ COMPOSITE, GUIDIDX ]);
+							Expect(pResult.dropped).to.have.length(0);
+							fDone();
+						} catch (e) { fDone(e); }
+					});
+			});
+
+		test('managed convergence: replaces precursor artifacts, create BEFORE drop',
+			(fDone) =>
+			{
+				let tmpActual = [ { Name: 'Deleted', Columns: [ 'Deleted' ] }, { Name: 'GUIDDocument', Columns: [ 'GUIDDocument' ] } ];
+				let tmpProvider = makeStubProvider(tmpActual);
+				libConvergence.convergeTableIndexes(tmpProvider, _DocSchema, _Desired, { PruneScope: 'managed' },
+					(pError, pResult) =>
+					{
+						try {
+							Expect(pError).to.equal(null);
+							Expect(pResult.created).to.have.members([ COMPOSITE, GUIDIDX ]);
+							Expect(pResult.dropped).to.have.members([ 'Deleted', 'GUIDDocument' ]);
+							// Ordering: every create precedes every drop.
+							let tmpFirstDrop = tmpProvider.calls.findIndex((pCall) => pCall.indexOf('drop:') === 0);
+							let tmpLastCreate = tmpProvider.calls.map((pCall, i) => pCall.indexOf('create:') === 0 ? i : -1).reduce((a, b) => Math.max(a, b), -1);
+							Expect(tmpLastCreate).to.be.lessThan(tmpFirstDrop);
+							fDone();
+						} catch (e) { fDone(e); }
+					});
+			});
+
+		test('no-loss-on-failure: a failed create suppresses ALL drops this run',
+			(fDone) =>
+			{
+				let tmpActual = [ { Name: 'Deleted', Columns: [ 'Deleted' ] } ];
+				let tmpProvider = makeStubProvider(tmpActual, [ COMPOSITE ]); // composite build fails
+				libConvergence.convergeTableIndexes(tmpProvider, _DocSchema, _Desired, { PruneScope: 'managed' },
+					(pError, pResult) =>
+					{
+						try {
+							Expect(pError).to.equal(null);
+							Expect(pResult.created).to.deep.equal([ GUIDIDX ]);   // the GUID one still built
+							Expect(pResult.skipped).to.include(COMPOSITE);        // the failed create
+							Expect(pResult.dropped).to.have.length(0);            // no drops — coverage preserved
+							Expect(pResult.skipped).to.include('Deleted');        // the drop was deferred
+							Expect(tmpProvider.calls.some((pCall) => pCall.indexOf('drop:') === 0)).to.equal(false);
+							fDone();
+						} catch (e) { fDone(e); }
+					});
+			});
+
+		test("prune 'none' never drops, even a managed undeclared index",
+			(fDone) =>
+			{
+				let tmpActual = [ { Name: 'Deleted', Columns: [ 'Deleted' ] } ];
+				let tmpProvider = makeStubProvider(tmpActual);
+				libConvergence.convergeTableIndexes(tmpProvider, _DocSchema, _Desired, { PruneScope: 'none' },
+					(pError, pResult) =>
+					{
+						try {
+							Expect(pError).to.equal(null);
+							Expect(pResult.dropped).to.have.length(0);
+							fDone();
+						} catch (e) { fDone(e); }
+					});
+			});
+
+		test("prune 'managed' leaves a truly external index untouched",
+			(fDone) =>
+			{
+				let tmpActual = [ { Name: 'IX_dba_custom_reporting', Columns: [ 'Status' ] } ];
+				let tmpProvider = makeStubProvider(tmpActual);
+				libConvergence.convergeTableIndexes(tmpProvider, _DocSchema, _Desired, { PruneScope: 'managed' },
+					(pError, pResult) =>
+					{
+						try {
+							Expect(pError).to.equal(null);
+							Expect(pResult.dropped).to.have.length(0);   // unmanaged → not dropped
+							Expect(pResult.created).to.have.members([ COMPOSITE, GUIDIDX ]);
+							fDone();
+						} catch (e) { fDone(e); }
+					});
+			});
+
+		test("prune 'all' drops any undeclared index",
+			(fDone) =>
+			{
+				let tmpActual = [ { Name: 'IX_dba_custom_reporting', Columns: [ 'Status' ] } ];
+				let tmpProvider = makeStubProvider(tmpActual);
+				libConvergence.convergeTableIndexes(tmpProvider, _DocSchema, _Desired, { PruneScope: 'all' },
+					(pError, pResult) =>
+					{
+						try {
+							Expect(pError).to.equal(null);
+							Expect(pResult.dropped).to.deep.equal([ 'IX_dba_custom_reporting' ]);
+							fDone();
+						} catch (e) { fDone(e); }
+					});
+			});
+	});