meadow-integration 1.1.1 → 1.1.3

package/source/services/clone/Meadow-Service-Sync-Entity-Initial.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 MeadowSyncEntityInitial extends libFableServiceProviderBase
 {
@@ -48,6 +49,12 @@ class MeadowSyncEntityInitial extends libFableServiceProviderBase
 		// override the automatic Deleted=0 filter (e.g. "includeDeleted=true").
 		this.SyncDeletedRecordsQueryString = this.options.SyncDeletedRecordsQueryString || '';
 
+		// How many records to upsert concurrently within a table.  Defaults to the
+		// DB connection pool size (capped) so fan-out never oversubscribes the pool
+		// 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);
@@ -55,6 +62,27 @@ class MeadowSyncEntityInitial 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'))
@@ -80,66 +108,18 @@ class MeadowSyncEntityInitial extends libFableServiceProviderBase
 
 			return tmpProvider.createTable(this.EntitySchema, (pCreateError) =>
 			{
-
 				if (pCreateError)
 				{
 					this.log.warn(`${this.EntitySchema.TableName}: createTable returned error: ${pCreateError}`);
 				}
 
-				// Sync-entity init intentionally does not create indexes here.
-				// In the DataCloner flow there is no MeadowConnectionManager
-				// service registered, so the legacy createIndex path was dead
-				// code that just logged noise ("No connection manager
-				// available; skipping index creation for X") for every table.
-				// Indexes are created via the provider's own createIndices /
-				// generateCreateIndexStatements methods, invoked by the
-				// DataCloner's dedicated /indices/create endpoint after the
-				// initial sync is complete — that's the point where it makes
-				// sense to build indexes, since they're expensive on populated
-				// tables.
-				//
-				// Preserve the legacy MeadowConnectionManager path for the CLI
-				// Meadow-Integration-Command-DataClone.js flow (which does
-				// register that service), but do it silently when neither
-				// indexable column nor connection manager is available.
-				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) =>
-				{
-					if (pIndexError)
-					{
-						this.log.warn(`${this.EntitySchema.TableName}: Index creation error: ${pIndexError}`);
-					}
-					return fCallback(pIndexError || pCreateError);
-				});
+				// 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 fCallback(pCreateError);
 			});
 		}
 
@@ -249,7 +229,7 @@ class MeadowSyncEntityInitial extends libFableServiceProviderBase
 									return fPageComplete();
 								}
 
-								this.fable.Utility.eachLimit(pBody, 5,
+								this.fable.Utility.eachLimit(pBody, this.SyncRecordConcurrency,
 									(pEntityRecord, fRecordComplete) =>
 									{
 										const tmpRecordID = pEntityRecord[this.DefaultIdentifier];
@@ -545,9 +525,17 @@ class MeadowSyncEntityInitial extends libFableServiceProviderBase
 					// Shared record-processing function used by both pagination modes
 					const fProcessPageRecords = (pBody, fPageProcessComplete) =>
 					{
-						this.fable.Utility.eachLimit(pBody, 5,
-							(pEntityRecord, fEntitySyncComplete) =>
+						this.fable.Utility.eachLimit(pBody, this.SyncRecordConcurrency,
+							(pEntityRecord, fRawEntitySyncComplete) =>
 							{
+								// node:sqlite resolves its callbacks synchronously, so the
+								// per-record Meadow behavior chain (doCreate -> CollisionRename
+								// -> doRead, threaded through async.waterfall/eachOfLimit) never
+								// yields and the call stack grows with the record count until it
+								// overflows on large syncs. Defer each record's completion so the
+								// stack unwinds between records — the same guard the advanced-ID
+								// pagination path applies with setImmediate(fFetchPage) below.
+								const fEntitySyncComplete = (pError) => setImmediate(() => fRawEntitySyncComplete(pError));
 								const tmpRecord = pEntityRecord;
 								const tmpQuery = this.Meadow.query;
 

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/source/services/guid/Meadow-Integration-GUIDStrategy.js

@@ -23,6 +23,33 @@ function valueTemplate(pColumn)
 	return `{~D:Record.${pColumn}~}`;
 }
 
+/**
+ * The value template for an entity's OWN key segment — the combinatorial-GUID input. Three shapes, in
+ * precedence order: a user-typed pict template `OwnKeyTemplate` (any expression, e.g.
+ * `{~D:Record.A~}-{~D:Record.B~}`); multiple columns `OwnKeyColumns` concatenated into one segment; or a
+ * single `OwnKeyColumn` (the original behavior). The transform resolves the whole string per row via
+ * fable's parseTemplate, so multiple `{~D:Record.X~}` tags in one segment just work.
+ * @param {Record<string, any>} pEntityConfig
+ * @returns {string}
+ */
+function ownValueTemplate(pEntityConfig)
+{
+	const tmpConfig = pEntityConfig || {};
+	if (tmpConfig.OwnKeyTemplate)
+	{
+		return String(tmpConfig.OwnKeyTemplate);
+	}
+	if (Array.isArray(tmpConfig.OwnKeyColumns) && (tmpConfig.OwnKeyColumns.length > 0))
+	{
+		return tmpConfig.OwnKeyColumns.map((pColumn) => valueTemplate(pColumn)).join('');
+	}
+	if (tmpConfig.OwnKeyColumn)
+	{
+		return valueTemplate(tmpConfig.OwnKeyColumn);
+	}
+	return '';
+}
+
 /** Derive a short uppercase abbreviation for an entity with no catalog entry (initials / first letters). */
 function _deriveAbbreviation(pEntityName)
 {
@@ -108,11 +135,12 @@ function _ownSegments(pEntityName, pEntityConfig, pContext)
 		tmpSegments.push({ abbrev: abbreviationFor(pParentEntity, pContext), valueTemplate: tmpKeyColumn ? valueTemplate(tmpKeyColumn) : '' });
 	});
 
-	if (!pEntityConfig.OwnKeyColumn)
+	const tmpOwnValue = ownValueTemplate(pEntityConfig);
+	if (!tmpOwnValue)
 	{
-		tmpWarnings.push(`"${pEntityName}" has no own-key column mapped — its GUID cannot be stable, so re-imports will create duplicates. Map a natural-key column (e.g. a code).`);
+		tmpWarnings.push(`"${pEntityName}" has no own-key column mapped — its GUID cannot be stable, so re-imports will create duplicates. Map a natural-key column (e.g. a code), several columns, or a template.`);
 	}
-	tmpSegments.push({ abbrev: abbreviationFor(pEntityName, pContext), valueTemplate: pEntityConfig.OwnKeyColumn ? valueTemplate(pEntityConfig.OwnKeyColumn) : '' });
+	tmpSegments.push({ abbrev: abbreviationFor(pEntityName, pContext), valueTemplate: tmpOwnValue });
 
 	return { segments: tmpSegments, warnings: tmpWarnings };
 }
@@ -252,4 +280,5 @@ module.exports = {
 	joinFieldName,
 	abbreviationFor,
 	valueTemplate,
+	ownValueTemplate,
 };

package/test/Meadow-Integration-ComprehensionPush_test.js

@@ -10,6 +10,7 @@
 const Chai = require('chai');
 const Expect = Chai.expect;
 
+const libPath = require('path');
 const libFable = require('fable');
 const libMeadowConnectionSQLite = require('meadow-connection-sqlite');
 const libRetoldDataService = require('retold-data-service');
@@ -291,7 +292,7 @@ suite
 						_Fable.serviceManager.addServiceType('RetoldDataService', libRetoldDataService);
 						_RetoldDataService = _Fable.serviceManager.instantiateServiceProvider('RetoldDataService',
 							{
-								FullMeadowSchemaPath: `${__dirname}/../node_modules/retold-harness/source/schemas/bookstore/`,
+								FullMeadowSchemaPath: `${libPath.dirname(require.resolve('retold-harness/source/schemas/bookstore/Schema.json'))}/`,
 								FullMeadowSchemaFilename: `Schema.json`,
 
 								StorageProvider: 'SQLite',

package/test/Meadow-Integration-GUIDStrategy_test.js

@@ -62,6 +62,29 @@ suite
 			}
 		);
 		test
+		(
+			'combinatorial own key: multiple columns concatenate into one own segment',
+			() =>
+			{
+				const tmpConfig = { Prefix: 'UI', Entities: { Project: { Mode: 'prefixed', OwnKeyColumns: [ 'District', 'ProjectCode' ] } } };
+				const tmpProject = libStrategy.compile(tmpConfig, { Catalog: CATALOG, SchemaSizes: SIZES }).Strategies.Project;
+				Expect(tmpProject.Own.Compose.segments).to.have.length(1);
+				Expect(tmpProject.Own.Compose.segments[0].valueTemplate).to.equal('{~D:Record.District~}{~D:Record.ProjectCode~}');
+			}
+		);
+		test
+		(
+			'combinatorial own key: a user-typed pict template becomes the own segment verbatim (and wins over a single column)',
+			() =>
+			{
+				const tmpConfig = { Prefix: 'UI', Entities: { Project: { Mode: 'prefixed', OwnKeyTemplate: '{~D:Record.District~}-{~D:Record.ProjectCode~}' } } };
+				const tmpProject = libStrategy.compile(tmpConfig, { Catalog: CATALOG, SchemaSizes: SIZES }).Strategies.Project;
+				Expect(tmpProject.Own.Compose.segments[0].valueTemplate).to.equal('{~D:Record.District~}-{~D:Record.ProjectCode~}');
+				const tmpBoth = libStrategy.compile({ Prefix: 'UI', Entities: { Project: { OwnKeyColumn: 'X', OwnKeyTemplate: 'T{~D:Record.Y~}' } } }, { Catalog: CATALOG }).Strategies.Project;
+				Expect(tmpBoth.Own.Compose.segments[0].valueTemplate).to.equal('T{~D:Record.Y~}');
+			}
+		);
+		test
 		(
 			'composes the headline LineItem own GUID from context + own segments',
 			() =>

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) {}
+		});
+	});