meadow-integration 1.1.2 → 1.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "meadow-integration",
-    "version": "1.1.2",
+    "version": "1.1.3",
     "description": "Meadow Data Integration",
     "retoldBeacon": {
         "displayName": "Meadow Integration",
@@ -58,7 +58,7 @@
     "author": "steven velozo <steven@velozo.com>",
     "license": "MIT",
     "devDependencies": {
-        "meadow-connection-sqlite": "^1.0.20",
+        "meadow-connection-sqlite": "^1.0.21",
         "pict-docuserve": "^1.4.19",
         "quackage": "^1.3.0",
         "retold-harness": "^1.1.13"
@@ -82,19 +82,19 @@
         ]
     },
     "dependencies": {
-        "fable": "^3.1.75",
+        "fable": "^3.1.79",
         "fable-serviceproviderbase": "^3.0.19",
         "fast-xml-parser": "^4.4.1",
-        "meadow": "^2.0.43",
-        "meadow-connection-mssql": "^1.0.23",
-        "meadow-connection-mysql": "^1.0.19",
+        "meadow": "^2.0.47",
+        "meadow-connection-mssql": "^1.0.24",
+        "meadow-connection-mysql": "^1.0.20",
         "orator": "^6.1.2",
         "orator-serviceserver-restify": "^2.0.11",
         "pict-provider-theme": "^1.1.2",
         "pict-section-flow": "^1.0.1",
-        "pict-section-modal": "^1.1.4",
+        "pict-section-modal": "^1.3.2",
         "pict-section-theme": "^1.1.1",
-        "pict-service-commandlineutility": "^1.0.19",
+        "pict-service-commandlineutility": "^1.0.20",
         "pict-sessionmanager": "^1.0.2",
         "pict-view": "^1.0.68",
         "xlsx": "^0.18.5"

package/source/cli/commands/Meadow-Integration-Command-DataClone.js

@@ -7,6 +7,8 @@ const libMeadowConnectionManager = require('../../services/clone/Meadow-Service-
 const libMeadowCloneRestClient = require('../../services/clone/Meadow-Service-RestClient.js');
 const libMeadowSync = require('../../services/clone/Meadow-Service-Sync.js');
 const libSessionManagerSetup = require('../../Meadow-Integration-SessionManagerSetup.js');
+const libIndexPolicy = require('../../services/clone/Meadow-Service-IndexPolicy.js');
+const libIndexConvergence = require('../../services/clone/Meadow-Service-IndexConvergence.js');
 
 // Resolve an env var with the standard `_FILE` suffix fallback for
 // secrets — so docker / k8s secret mounts work without bespoke wiring.
@@ -65,6 +67,8 @@ class DataClone extends libCLICommandLineCommand
 
 		this.options.CommandOptions.push({ Name: '-w, --post_run_delay [post_run_delay]', Description: 'Minutes to wait after sync before exiting. Default is 0.', DefaultValue: '0' });
 
+		this.options.CommandOptions.push({ Name: '--index_config [index_config]', Description: 'Converge clone indexes before syncing. "all" applies the standard operational indexes to every table; or pass a path to a JSON index-policy file ({ StandardOperationalIndexes, PruneScope, TableIndexes }). Omit to leave indexes untouched.' });
+
 		this.addCommand();
 	}
 
@@ -373,6 +377,11 @@ class DataClone extends libCLICommandLineCommand
 						});
 				},
 				(fStageComplete) =>
+				{
+					// Converge indexes to the policy before syncing (opt-in via --index_config).
+					this._convergeIndexes(tmpSchemaModel, fStageComplete);
+				},
+				(fStageComplete) =>
 				{
 					// Execute the sync
 					this.fable.MeadowSync.syncAll(
@@ -405,6 +414,85 @@ class DataClone extends libCLICommandLineCommand
 				}, tmpPostRunDelay * 60 * 1000);
 			});
 	}
+
+	/**
+	 * Converge the clone's indexes to the configured policy before syncing.
+	 * Opt-in via --index_config: "all" applies the standard operational indexes
+	 * to every table; a path loads a JSON index-policy file.  Uses the same
+	 * IndexPolicy + IndexConvergence the headless DataCloner pipeline uses.
+	 *
+	 * @param {object} pSchemaModel - loaded Meadow schema ({ Tables: {...} })
+	 * @param {Function} fCallback
+	 */
+	_convergeIndexes(pSchemaModel, fCallback)
+	{
+		let tmpIndexConfigArg = this.CommandOptions.index_config;
+		if (!tmpIndexConfigArg)
+		{
+			return fCallback();
+		}
+
+		let tmpIndexConfig;
+		if (String(tmpIndexConfigArg).toLowerCase() === 'all')
+		{
+			tmpIndexConfig = { StandardOperationalIndexes: true, PruneScope: 'managed' };
+		}
+		else
+		{
+			try
+			{
+				tmpIndexConfig = require(libPath.resolve(tmpIndexConfigArg));
+			}
+			catch (pReadError)
+			{
+				this.log.error(`Could not load --index_config ${tmpIndexConfigArg}: ${pReadError.message}`);
+				return fCallback();
+			}
+		}
+
+		let tmpProviderName = this.fable.MeadowConnectionManager && this.fable.MeadowConnectionManager.Provider;
+		let tmpProvider = tmpProviderName ? this.fable[`Meadow${tmpProviderName}Provider`] : null;
+		if (!tmpProvider || typeof(tmpProvider.introspectTableIndices) !== 'function')
+		{
+			this.log.warn(`Index convergence requested but provider '${tmpProviderName || '(unknown)'}' does not expose the index API; skipping.`);
+			return fCallback();
+		}
+
+		let tmpTables = (pSchemaModel && pSchemaModel.Tables) ? pSchemaModel.Tables : {};
+		// Converge only the tables actually deployed — respect SyncEntityList (a
+		// subset clone) so we never introspect/converge a table that was never
+		// created.  Mirrors loadMeadowSchema's filter and the headless endpoint's
+		// "deployed tables only" scope.  Empty list = all tables in the schema.
+		let tmpSyncList = (this.fable.MeadowSync && Array.isArray(this.fable.MeadowSync.SyncEntityList)) ? this.fable.MeadowSync.SyncEntityList : [];
+		let tmpTableNames = (tmpSyncList.length > 0)
+			? tmpSyncList.filter((pName) => { return tmpTables[pName]; })
+			: Object.keys(tmpTables);
+		let tmpPruneScope = tmpIndexConfig.PruneScope || libIndexConvergence.PRUNE_MANAGED;
+
+		this.log.info(`Converging indexes for ${tmpTableNames.length} deployed table(s) (prune scope: ${tmpPruneScope})...`);
+
+		this.fable.Utility.eachLimit(tmpTableNames, 1,
+			(pTableName, fNextTable) =>
+			{
+				let tmpTableSchema = tmpTables[pTableName];
+				let tmpDesired = libIndexPolicy.resolveDesiredIndexes(tmpTableSchema, tmpIndexConfig);
+				libIndexConvergence.convergeTableIndexes(tmpProvider, tmpTableSchema, tmpDesired,
+					{ PruneScope: tmpPruneScope, log: this.log },
+					(pConvergeError, pResult) =>
+					{
+						if (pConvergeError)
+						{
+							this.log.warn(`Index convergence for ${pTableName} failed: ${pConvergeError}`);
+						}
+						else if (pResult && (pResult.created.length > 0 || pResult.dropped.length > 0))
+						{
+							this.log.info(`${pTableName} — created [${pResult.created.join(', ')}], dropped [${pResult.dropped.join(', ')}]`);
+						}
+						return fNextTable();
+					});
+			},
+			() => { return fCallback(); });
+	}
 }
 
 module.exports = DataClone;

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

@@ -73,6 +73,15 @@ class MeadowConnectionManager extends libFableServiceProviderBase
 			// Apply MySQL settings to fable settings for meadow provider
 			this.fable.settings.MySQL = tmpConfig;
 
+			// Point the meadow ORM at this provider.  MeadowConnectionManager
+			// connects the connector (fable.MeadowMSSQLProvider/MySQLProvider),
+			// but the meadow instance built in Meadow-Service-Sync selects its
+			// provider from fable.settings.MeadowProvider (default 'None').
+			// Without this the ORM stays on the 'None' provider and createTable
+			// (via provider.getProvider()) has nothing to call.  Set before the
+			// sync service is instantiated so meadow picks it up.
+			this.fable.settings.MeadowProvider = this.Provider;
+
 			this.fable.serviceManager.addServiceType('MeadowMySQLProvider', libMeadowConnectionMySQL);
 			this.fable.serviceManager.instantiateServiceProvider('MeadowMySQLProvider', tmpConfig);
 
@@ -108,6 +117,11 @@ class MeadowConnectionManager extends libFableServiceProviderBase
 			// Apply MSSQL settings to fable settings for meadow provider
 			this.fable.settings.MSSQL = tmpConfig;
 
+			// Point the meadow ORM at this provider (see the MySQL branch for
+			// the full rationale) — without it the ORM stays on 'None' and
+			// createTable has no underlying connector to call.
+			this.fable.settings.MeadowProvider = this.Provider;
+
 			this.fable.serviceManager.addServiceType('MeadowMSSQLProvider', libMeadowConnectionMSSQL);
 			this.fable.serviceManager.instantiateServiceProvider('MeadowMSSQLProvider', tmpConfig);
 

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

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * Index convergence for a clone table.
+ *
+ * Given a table's DESIRED index set (from Meadow-Service-IndexPolicy) and a
+ * connection provider, bring the table's actual indexes in line with the
+ * desired set:
+ *
+ *   introspect actual → diff by name → create missing → drop undeclared
+ *
+ * Two safety properties:
+ *   1. Create-before-drop: new indexes are built BEFORE any old one is removed,
+ *      so there is never a window with no covering index (matters because the
+ *      sync's range-count walk runs right after).
+ *   2. No-loss-on-failure: if any desired index fails to build this run, NO
+ *      drops happen — we never remove a still-needed index whose replacement is
+ *      not yet in place.  The drop is retried next run once the create succeeds.
+ *
+ * Prune scope controls what may be dropped:
+ *   - 'none'    : additive only (never drop).
+ *   - 'managed' : drop only indexes the policy owns or legacy artifacts
+ *                 (see IndexPolicy.isManagedIndexName) — a truly external,
+ *                 hand-authored index is left alone.  DEFAULT.
+ *   - 'all'     : drop any undeclared index.  (introspectTableIndices already
+ *                 excludes the primary key, so the PK is never a drop target.)
+ *
+ * @license MIT
+ */
+
+const libIndexPolicy = require('./Meadow-Service-IndexPolicy.js');
+
+const PRUNE_NONE = 'none';
+const PRUNE_MANAGED = 'managed';
+const PRUNE_ALL = 'all';
+
+const NOOP_LOG = { info: () => {}, warn: () => {}, error: () => {} };
+
+/**
+ * Converge a single table's indexes to the desired set.
+ *
+ * @param {object} pProvider - connection provider exposing introspectTableIndices,
+ *                             generateCreateIndexStatements, createIndex, dropIndex
+ * @param {object} pTableSchema - { TableName, Columns[] }
+ * @param {Array}  pDesiredIndexes - desired defs ({ Name, TableName, Columns[], Unique, Strategy })
+ * @param {object} [pOptions] - { PruneScope?: string, log?: object }
+ * @param {Function} fCallback - callback(pError, { table, created[], dropped[], skipped[] })
+ */
+function convergeTableIndexes(pProvider, pTableSchema, pDesiredIndexes, pOptions, fCallback)
+{
+	let tmpOptions = pOptions || {};
+	let tmpLog = tmpOptions.log || NOOP_LOG;
+	let tmpPruneScope = tmpOptions.PruneScope || PRUNE_MANAGED;
+	let tmpTableName = pTableSchema.TableName;
+	let tmpDesired = Array.isArray(pDesiredIndexes) ? pDesiredIndexes : [];
+
+	if (!pProvider
+		|| typeof(pProvider.introspectTableIndices) !== 'function'
+		|| typeof(pProvider.generateCreateIndexStatements) !== 'function'
+		|| typeof(pProvider.createIndex) !== 'function'
+		|| typeof(pProvider.dropIndex) !== 'function')
+	{
+		return fCallback(new Error('IndexConvergence requires a provider with introspectTableIndices / generateCreateIndexStatements / createIndex / dropIndex'));
+	}
+
+	pProvider.introspectTableIndices(tmpTableName,
+		(pIntrospectError, pActualIndices) =>
+		{
+			if (pIntrospectError)
+			{
+				return fCallback(pIntrospectError);
+			}
+
+			let tmpActual = Array.isArray(pActualIndices) ? pActualIndices : [];
+			let tmpActualNames = new Set(tmpActual.map((pIndex) => { return pIndex.Name; }));
+			let tmpDesiredNames = new Set(tmpDesired.map((pIndex) => { return pIndex.Name; }));
+
+			// Missing desired indexes to create.
+			let tmpToCreate = tmpDesired.filter((pIndex) => { return !tmpActualNames.has(pIndex.Name); });
+
+			// Undeclared actual indexes to drop, scoped by prune policy.
+			let tmpToDrop = [];
+			if (tmpPruneScope !== PRUNE_NONE)
+			{
+				tmpToDrop = tmpActual.filter((pIndex) =>
+					{
+						if (tmpDesiredNames.has(pIndex.Name))
+						{
+							return false;
+						}
+						if (tmpPruneScope === PRUNE_ALL)
+						{
+							return true;
+						}
+						return libIndexPolicy.isManagedIndexName(pIndex.Name, pTableSchema);
+					});
+			}
+
+			let tmpResult = { table: tmpTableName, created: [], dropped: [], skipped: [] };
+
+			// Render CREATE statements for exactly the to-create set.  Passing
+			// Columns:[] means the connector's per-column auto-derivation (GUID /
+			// FK / Indexed) contributes nothing — only the explicit Indices[] we
+			// hand it are rendered.
+			let tmpCreateStatements = pProvider.generateCreateIndexStatements(
+				{ TableName: tmpTableName, Columns: [], Indices: tmpToCreate });
+
+			// -- Phase B: drop (runs after all creates) --
+			let fDropPhase = (pCreateFailures) =>
+			{
+				if (tmpToDrop.length < 1)
+				{
+					return fCallback(null, tmpResult);
+				}
+				if (pCreateFailures > 0)
+				{
+					tmpLog.warn(`IndexConvergence: ${pCreateFailures} create(s) failed on ${tmpTableName}; skipping ${tmpToDrop.length} drop(s) this run to preserve coverage.`);
+					for (let i = 0; i < tmpToDrop.length; i++)
+					{
+						tmpResult.skipped.push(tmpToDrop[i].Name);
+					}
+					return fCallback(null, tmpResult);
+				}
+
+				let fDropNext = (pIndex) =>
+				{
+					if (pIndex >= tmpToDrop.length)
+					{
+						return fCallback(null, tmpResult);
+					}
+					let tmpDropName = tmpToDrop[pIndex].Name;
+					pProvider.dropIndex(tmpTableName, tmpDropName,
+						(pDropError) =>
+						{
+							if (pDropError)
+							{
+								tmpLog.warn(`IndexConvergence: drop ${tmpDropName} on ${tmpTableName} failed: ${pDropError}`);
+								tmpResult.skipped.push(tmpDropName);
+							}
+							else
+							{
+								tmpResult.dropped.push(tmpDropName);
+							}
+							return fDropNext(pIndex + 1);
+						});
+				};
+				fDropNext(0);
+			};
+
+			// -- Phase A: create --
+			let fCreateNext = (pIndex, pCreateFailures) =>
+			{
+				if (pIndex >= tmpCreateStatements.length)
+				{
+					return fDropPhase(pCreateFailures);
+				}
+				let tmpStatement = tmpCreateStatements[pIndex];
+				pProvider.createIndex(tmpStatement,
+					(pCreateError) =>
+					{
+						if (pCreateError)
+						{
+							tmpLog.warn(`IndexConvergence: create ${tmpStatement.Name} on ${tmpTableName} failed: ${pCreateError}`);
+							tmpResult.skipped.push(tmpStatement.Name);
+							return fCreateNext(pIndex + 1, pCreateFailures + 1);
+						}
+						tmpResult.created.push(tmpStatement.Name);
+						return fCreateNext(pIndex + 1, pCreateFailures);
+					});
+			};
+
+			fCreateNext(0, 0);
+		});
+}
+
+module.exports = {
+	PRUNE_NONE: PRUNE_NONE,
+	PRUNE_MANAGED: PRUNE_MANAGED,
+	PRUNE_ALL: PRUNE_ALL,
+	convergeTableIndexes: convergeTableIndexes
+};

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

@@ -0,0 +1,165 @@
+'use strict';
+
+/**
+ * Index policy for the clone/sync workload.
+ *
+ * This is the single source of truth for which indexes a synced table SHOULD
+ * have, independent of any one execution flow.  Both the headless DataCloner
+ * pipeline and the standalone CLI clone tool resolve their desired index set
+ * from here so they converge to the same shape.
+ *
+ * The desired set for a table is the union of:
+ *   1. Standard operational indexes (applied to every eligible table):
+ *        - (Deleted, ID<Table>) composite  — makes the OngoingEventualConsistency
+ *          range-count / delete-reconcile walk a seek instead of a scan.
+ *        - a GUID lookup index             — speeds meadow's app-side GUID
+ *          precheck on insert.  NON-UNIQUE by policy: the clone is a derived
+ *          replica of data with known duplicate GUIDs at the source, and a
+ *          unique index would fail to build on a table that holds a dup pair.
+ *   2. Caller-declared per-table indexes (the "observed required" extras):
+ *        config.TableIndexes[<TableName>] = [ { Columns, Unique?, Name?, Strategy? } ]
+ *
+ * Every policy-produced index carries the IX_M_SYNC_ prefix so the convergence
+ * pass can recognize the set it manages.  Definitions match the shape the
+ * connectors' generateCreateIndexStatements consumes:
+ *   { Name, TableName, Columns[], Unique, Strategy }
+ *
+ * @license MIT
+ */
+
+// All policy-managed indexes share this prefix so convergence can scope itself.
+const INDEX_POLICY_PREFIX = 'IX_M_SYNC_';
+
+/**
+ * Resolve the identity/PK column for a table.
+ * Prefers the schema's DefaultIdentifier, then an AutoIdentity/ID column, then
+ * the ID<Table> naming convention.
+ *
+ * @param {object} pTableSchema
+ * @param {Set<string>} pColumnNames
+ * @returns {string}
+ */
+function resolveIdentityColumn(pTableSchema, pColumnNames)
+{
+	let tmpIdentity = pTableSchema.DefaultIdentifier;
+	if (tmpIdentity && pColumnNames.has(tmpIdentity))
+	{
+		return tmpIdentity;
+	}
+	let tmpColumns = Array.isArray(pTableSchema.Columns) ? pTableSchema.Columns : [];
+	let tmpIdentityCol = tmpColumns.find((pColumn) => { return (pColumn.DataType === 'AutoIdentity' || pColumn.DataType === 'ID'); });
+	return tmpIdentityCol ? tmpIdentityCol.Column : `ID${pTableSchema.TableName}`;
+}
+
+/**
+ * Resolve the desired index definitions for a single table.
+ *
+ * @param {object} pTableSchema - Meadow table schema ({ TableName, Columns[], DefaultIdentifier })
+ * @param {object} [pIndexConfig] - { StandardOperationalIndexes?: boolean, TableIndexes?: { [table]: Array } }
+ * @returns {Array<{Name:string,TableName:string,Columns:string[],Unique:boolean,Strategy:string}>}
+ */
+function resolveDesiredIndexes(pTableSchema, pIndexConfig)
+{
+	let tmpConfig = pIndexConfig || {};
+	let tmpTableName = pTableSchema.TableName;
+	let tmpColumns = Array.isArray(pTableSchema.Columns) ? pTableSchema.Columns : [];
+	let tmpColumnNames = new Set(tmpColumns.map((pColumn) => { return pColumn.Column; }));
+	let tmpIndices = [];
+
+	// -- 1. Standard operational indexes (all eligible tables) --
+	// Enabled by default; set StandardOperationalIndexes:false to opt a run out.
+	if (tmpConfig.StandardOperationalIndexes !== false)
+	{
+		let tmpIdentity = resolveIdentityColumn(pTableSchema, tmpColumnNames);
+
+		// (Deleted, ID) composite — equality on Deleted then range on the identity.
+		if (tmpColumnNames.has('Deleted') && tmpColumnNames.has(tmpIdentity))
+		{
+			tmpIndices.push(
+				{
+					Name: `${INDEX_POLICY_PREFIX}${tmpTableName}_Deleted_${tmpIdentity}`,
+					TableName: tmpTableName,
+					Columns: [ 'Deleted', tmpIdentity ],
+					Unique: false,
+					Strategy: ''
+				});
+		}
+
+		// GUID lookup — NON-UNIQUE by policy (see file header).
+		let tmpGUIDColumn = tmpColumns.find((pColumn) => { return pColumn.DataType === 'GUID'; });
+		if (tmpGUIDColumn)
+		{
+			tmpIndices.push(
+				{
+					Name: `${INDEX_POLICY_PREFIX}${tmpTableName}_${tmpGUIDColumn.Column}`,
+					TableName: tmpTableName,
+					Columns: [ tmpGUIDColumn.Column ],
+					Unique: false,
+					Strategy: ''
+				});
+		}
+	}
+
+	// -- 2. Caller-declared per-table extras --
+	let tmpTableExtras = (tmpConfig.TableIndexes && Array.isArray(tmpConfig.TableIndexes[tmpTableName]))
+		? tmpConfig.TableIndexes[tmpTableName]
+		: [];
+	for (let i = 0; i < tmpTableExtras.length; i++)
+	{
+		let tmpExtra = tmpTableExtras[i];
+		let tmpCols = Array.isArray(tmpExtra.Columns) ? tmpExtra.Columns : [ tmpExtra.Columns ];
+		// Skip a declared index whose columns are not all present on the table.
+		if (!tmpCols.every((pCol) => { return tmpColumnNames.has(pCol); }))
+		{
+			continue;
+		}
+		tmpIndices.push(
+			{
+				Name: tmpExtra.Name || `${INDEX_POLICY_PREFIX}${tmpTableName}_${tmpCols.join('_')}`,
+				TableName: tmpTableName,
+				Columns: tmpCols,
+				Unique: !!tmpExtra.Unique,
+				Strategy: tmpExtra.Strategy || ''
+			});
+	}
+
+	return tmpIndices;
+}
+
+/**
+ * Whether an index name is one this policy manages — used by convergence's
+ * "managed" prune scope so it only ever drops indexes it owns.  Recognizes:
+ *   - policy-created indexes (IX_M_SYNC_ prefix),
+ *   - meadow schema-managed indexes (AK_M / IX_M prefixes),
+ *   - the legacy precursor / MeadowConnectionManager artifacts, which name a
+ *     single-column index after the column itself (e.g. [Deleted], [GUIDDocument]).
+ * A truly external, hand-authored index (unusual here, but possible) is NOT
+ * managed and is left untouched.
+ *
+ * @param {string} pIndexName
+ * @param {object} pTableSchema
+ * @returns {boolean}
+ */
+function isManagedIndexName(pIndexName, pTableSchema)
+{
+	if (!pIndexName)
+	{
+		return false;
+	}
+	if (pIndexName.indexOf(INDEX_POLICY_PREFIX) === 0
+		|| pIndexName.indexOf('AK_M') === 0
+		|| pIndexName.indexOf('IX_M') === 0)
+	{
+		return true;
+	}
+	// Legacy artifact: index named exactly after one of the table's columns.
+	let tmpColumns = Array.isArray(pTableSchema && pTableSchema.Columns) ? pTableSchema.Columns : [];
+	return tmpColumns.some((pColumn) => { return pColumn.Column === pIndexName; });
+}
+
+module.exports = {
+	INDEX_POLICY_PREFIX: INDEX_POLICY_PREFIX,
+	resolveIdentityColumn: resolveIdentityColumn,
+	resolveDesiredIndexes: resolveDesiredIndexes,
+	isManagedIndexName: isManagedIndexName
+};

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,7 +525,7 @@ class MeadowSyncEntityInitial extends libFableServiceProviderBase
 					// Shared record-processing function used by both pagination modes
 					const fProcessPageRecords = (pBody, fPageProcessComplete) =>
 					{
-						this.fable.Utility.eachLimit(pBody, 5,
+						this.fable.Utility.eachLimit(pBody, this.SyncRecordConcurrency,
 							(pEntityRecord, fRawEntitySyncComplete) =>
 							{
 								// node:sqlite resolves its callbacks synchronously, so the