meadow-integration 1.1.0 → 1.1.2

package/.github/workflows/publish-image.yml

@@ -9,8 +9,8 @@
 #   - One step to wire: GITHUB_TOKEN already has `packages: write`
 #
 # Image lands at:
-#   ghcr.io/stevenvelozo/meadow-integration:<version>
-#   ghcr.io/stevenvelozo/meadow-integration:latest   (only on the
+#   ghcr.io/fable-retold/meadow-integration:<version>
+#   ghcr.io/fable-retold/meadow-integration:latest   (only on the
 #                                                     highest stable tag)
 #
 # Manual run: `Actions → Publish container image → Run workflow`,

package/BUILDING-AND-PUBLISHING.md

@@ -170,7 +170,7 @@ postpublish: BUILD_DOCKER=1 → tag + push       ← image trigger
   ↓ (tag arrives at GitHub)
 .github/workflows/publish-image.yml fires:
   - docker buildx build --platform linux/amd64,linux/arm64
-  - docker push ghcr.io/stevenvelozo/meadow-integration:<version>
+  - docker push ghcr.io/fable-retold/meadow-integration:<version>
   - tags: <version>, <major>.<minor>, <major>, latest
 ```
 
@@ -189,14 +189,14 @@ After `release:patch` completes:
 2. **GHCR workflow**: visit
    `https://github.com/fable-retold/meadow-integration/actions` and
    confirm the "Publish container image" run succeeded.
-3. **Image**: `docker pull ghcr.io/stevenvelozo/meadow-integration:<version>`
+3. **Image**: `docker pull ghcr.io/fable-retold/meadow-integration:<version>`
    should succeed. The image is also tagged as `latest`, `<major>`, and
    `<major>.<minor>`.
 4. **Smoke test** (one-shot — runs the bundled BookStore default schema
    against a non-existent API; expect it to fail at the data-fetch step,
    which proves the binary started correctly):
    ```bash
-   docker run --rm ghcr.io/stevenvelozo/meadow-integration:latest
+   docker run --rm ghcr.io/fable-retold/meadow-integration:latest
    ```
 
 ---
@@ -280,7 +280,7 @@ whatever stability level fits.
 ### Pull and run (one-shot)
 
 ```bash
-docker pull ghcr.io/stevenvelozo/meadow-integration:latest
+docker pull ghcr.io/fable-retold/meadow-integration:latest
 
 # Single sync run; container exits when done
 docker run --rm \
@@ -293,7 +293,7 @@ docker run --rm \
   -e MEADOW_INTEGRATION_DB_NAME=mydatabase \
   -e MEADOW_INTEGRATION_SCHEMA_PATH=/schemas/my-schema.json \
   -v $(pwd)/schemas:/schemas:ro \
-  ghcr.io/stevenvelozo/meadow-integration:latest
+  ghcr.io/fable-retold/meadow-integration:latest
 ```
 
 ### Configuration via env vars

package/CONTRIBUTING.md

@@ -47,4 +47,4 @@ When in doubt, match what the surrounding code does.
 
 ## Repository Structure
 
-Each module is its own git repository. The [retold](https://github.com/stevenvelozo/retold) repository tracks module organization but does not contain module source code. Direct your pull request to the specific module repository where your change belongs.
+Each module is its own git repository. The [retold](https://github.com/fable-retold/retold) repository tracks module organization but does not contain module source code. Direct your pull request to the specific module repository where your change belongs.

package/README.md

@@ -361,4 +361,4 @@ MIT
 
 ## Contributing
 
-Pull requests are welcome. For details on our code of conduct, contribution process, and testing requirements, see the [Retold Contributing Guide](https://github.com/stevenvelozo/retold/blob/main/docs/contributing.md).
+Pull requests are welcome. For details on our code of conduct, contribution process, and testing requirements, see the [Retold Contributing Guide](https://github.com/fable-retold/retold/blob/main/docs/contributing.md).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "meadow-integration",
-    "version": "1.1.0",
+    "version": "1.1.2",
     "description": "Meadow Data Integration",
     "retoldBeacon": {
         "displayName": "Meadow Integration",
@@ -60,7 +60,8 @@
     "devDependencies": {
         "meadow-connection-sqlite": "^1.0.20",
         "pict-docuserve": "^1.4.19",
-        "quackage": "^1.3.0"
+        "quackage": "^1.3.0",
+        "retold-harness": "^1.1.13"
     },
     "mocha": {
         "diff": true,

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

@@ -546,8 +546,16 @@ class MeadowSyncEntityInitial extends libFableServiceProviderBase
 					const fProcessPageRecords = (pBody, fPageProcessComplete) =>
 					{
 						this.fable.Utility.eachLimit(pBody, 5,
-							(pEntityRecord, fEntitySyncComplete) =>
+							(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/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)
 {
@@ -50,12 +77,29 @@ function abbreviationFor(pEntityName, pContext)
 	return _deriveAbbreviation(pEntityName);
 }
 
-/** The GUID column width for an entity (from the live schema), or 0 (unbounded) if unknown. */
+/**
+ * The GUID column width for an entity, or 0 (unbounded) if unknown.
+ *
+ * Prefers the live schema width (`SchemaSizes`, populated for the entity actually being imported), then
+ * falls back to the host catalog's declared `GUIDSize`. The fallback is LOAD-BEARING for JOIN compose:
+ * when a child references a parent (e.g. Product → Material), only the CHILD's schema is loaded, so
+ * `SchemaSizes` has no entry for the parent. Without the catalog width the parent's foreign-key GUID is
+ * composed unbounded (never hashed) while the parent's OWN GUID was hashed to fit its column — so a long
+ * key makes the two diverge and the cross-session match silently breaks. The catalog `GUIDSize` MUST
+ * therefore match the parent's real GUID column width for long keys to resolve.
+ */
 function _maxLengthFor(pEntityName, pContext)
 {
 	const tmpSizes = (pContext && pContext.SchemaSizes) || {};
-	const tmpSize = Number(tmpSizes[pEntityName] || 0);
-	return (tmpSize > 0) ? tmpSize : 0;
+	const tmpSchemaSize = Number(tmpSizes[pEntityName] || 0);
+	if (tmpSchemaSize > 0)
+	{
+		return tmpSchemaSize;
+	}
+	const tmpCatalog = (pContext && pContext.Catalog) || {};
+	const tmpEntry = tmpCatalog[pEntityName];
+	const tmpCatalogSize = tmpEntry ? Number(tmpEntry.GUIDSize || 0) : 0;
+	return (tmpCatalogSize > 0) ? tmpCatalogSize : 0;
 }
 
 /** Build a compose spec (prefix + ordered segments + length budget) for an entity's fullGUID. */
@@ -91,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 };
 }
@@ -235,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-GUIDStrategyTransform_test.js

@@ -129,6 +129,38 @@ suite
 			}
 		);
 		test
+		(
+			'a long parent key hashes IDENTICALLY for the own GUID and a cross-session FK (catalog GUIDSize fallback)',
+			() =>
+			{
+				// Mirrors the live failure: a parent key long enough to overflow the parent's GUID column.
+				// The parent's OWN GUID is hashed to fit (its schema width is loaded during the parent import);
+				// the child is imported SEPARATELY, so only the CHILD's schema width is loaded — the parent's
+				// width has to come from the host catalog, or the FK is composed unbounded and never matches.
+				const tmpCatalog = { Material: { Abbrev: 'M', GUIDSize: 36 }, Product: { Abbrev: 'PR', GUIDSize: 96 } };
+				const tmpLongKey = 'ZZHASHKEY_' + 'A'.repeat(32); // UI_M + 42 chars overflows 36 -> must hash
+
+				// Parent import — Material's 36-char column width is present in SchemaSizes.
+				const tmpMaterialStrategy = libEngine.compileGUIDStrategy(
+					{ Prefix: 'UI', Entities: { Material: { Mode: 'prefixed', OwnKeyColumn: 'MaterialKey' } } },
+					{ Catalog: tmpCatalog, SchemaSizes: { Material: 36 } }).Strategies.Material;
+				const tmpMaterialComp = runOneEntity(newTransform(), { Entity: 'Material', GUIDName: 'GUIDMaterial', GUIDStrategy: tmpMaterialStrategy, Mappings: {} }, { MaterialKey: tmpLongKey });
+				const tmpMaterialGUID = Object.keys(tmpMaterialComp)[0];
+				Expect(tmpMaterialGUID.length, 'parent own GUID fits its 36-char column').to.be.at.most(36);
+				Expect(tmpMaterialGUID.indexOf('AAAA'), 'parent own GUID was hashed, not raw').to.equal(-1);
+
+				// Child import (separate session) — ONLY Product's width is in SchemaSizes; Material's width must
+				// come from the catalog for the FK to hash the same way.
+				const tmpProductStrategy = libEngine.compileGUIDStrategy(
+					{ Prefix: 'UI', Entities: { Product: { Mode: 'prefixed', OwnKeyColumn: 'ProductKey', Joins: [ { ParentEntity: 'Material', Mode: 'prefixed', KeyColumn: 'MaterialKey', CrossSession: true } ] } } },
+					{ Catalog: tmpCatalog, SchemaSizes: { Product: 96 } }).Strategies.Product;
+				const tmpProductComp = runOneEntity(newTransform(), { Entity: 'Product', GUIDName: 'GUIDProduct', GUIDStrategy: tmpProductStrategy, Mappings: {} }, { ProductKey: 'PRLONG1', MaterialKey: tmpLongKey });
+				const tmpProductGUID = Object.keys(tmpProductComp)[0];
+
+				Expect(tmpProductComp[tmpProductGUID]._GUIDMaterial, 'long-key FK hashes identically to the parent own GUID').to.equal(tmpMaterialGUID);
+			}
+		);
+		test
 		(
 			'a non-strategy mapping still uses the flat GUIDTemplate (no behavior change)',
 			() =>

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',
 			() =>