meadow-integration 1.0.42 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "meadow-integration",
-    "version": "1.0.42",
+    "version": "1.1.0",
     "description": "Meadow Data Integration",
     "retoldBeacon": {
         "displayName": "Meadow Integration",

package/source/Meadow-Integration-Engine.js

@@ -0,0 +1,47 @@
+// Meadow-Integration-Engine — the browser-safe, dependency-light entry point for the comprehension
+// transform / push ENGINE classes, decoupled from the full meadow-integration package.
+//
+// The package `main` (Meadow-Integration.js) and the `browser` entry pull in orator, the meadow ORM,
+// the DB connection drivers, xlsx, etc. — none of which the engine itself needs. These three services
+// depend ONLY on fable-serviceproviderbase (and each other), so an in-browser consumer — e.g.
+// pict-section-dataimport — can `require('meadow-integration/source/Meadow-Integration-Engine.js')`
+// to get the engine WITHOUT dragging any server-only code into its bundle.
+//
+// This file is the stable public contract for in-browser engine consumers: if the internal layout
+// under source/ ever changes, update the requires HERE and consumers keep importing this one path.
+//
+//   const { MeadowIntegrationTabularTransform, MeadowIntegrationAdapter, MeadowGUIDMap, getAdapter }
+//       = require('meadow-integration/source/Meadow-Integration-Engine.js');
+//
+// - MeadowIntegrationTabularTransform : maps tabular rows -> a Comprehension (transformRecord per row;
+//   runs Solvers + MultipleGUIDUniqueness fan-out).
+// - MeadowIntegrationAdapter          : GUID marshaling, FK resolution, bulk upsert (setRestClient,
+//   addSourceRecord, integrateRecords). Use getAdapter(fable, entity, prefix, options) for the
+//   per-entity singleton.
+// - MeadowGUIDMap                     : the in-session external-GUID <-> Meadow-ID map.
+
+const MeadowIntegrationTabularTransform = require('./services/tabular/Service-TabularTransform.js');
+const MeadowIntegrationAdapter = require('./Meadow-Service-Integration-Adapter.js');
+const MeadowGUIDMap = require('./Meadow-Service-Integration-GUIDMap.js');
+
+// Opt-in context-aware GUID layer (pure, dependency-light): compose deterministic, length-safe GUIDs that
+// embed parent context (e.g. `UI_C10_P01278_LI8675309`) + a compiler that turns a per-entity strategy
+// config into the structured spec the TabularTransform stamps. Reusable by the CLI, the server endpoints,
+// and the browser import wizard alike.
+const MeadowIntegrationGUIDComposer = require('./services/guid/Meadow-Integration-GUIDComposer.js');
+const MeadowIntegrationGUIDStrategy = require('./services/guid/Meadow-Integration-GUIDStrategy.js');
+
+module.exports =
+{
+	MeadowIntegrationTabularTransform,
+	MeadowIntegrationAdapter,
+	MeadowGUIDMap,
+	// The per-entity adapter factory (caches on fable.servicesMap.IntegrationAdapter[Entity]).
+	getAdapter: MeadowIntegrationAdapter.getAdapter,
+
+	// Context-aware GUID composition + strategy compilation.
+	MeadowIntegrationGUIDComposer,
+	MeadowIntegrationGUIDStrategy,
+	composeGUID: MeadowIntegrationGUIDComposer.composeGUID,
+	compileGUIDStrategy: MeadowIntegrationGUIDStrategy.compile,
+};

package/source/Meadow-Service-Integration-Adapter.js

@@ -1,5 +1,6 @@
 const libFableServiceProviderBase = require('fable-serviceproviderbase');
 const libGUIDMap = require('./Meadow-Service-Integration-GUIDMap.js');
+const libGUIDComposer = require('./services/guid/Meadow-Integration-GUIDComposer.js');
 
 const defaultMeadowIntegrationAdapterOptions = (
 	{
@@ -27,6 +28,11 @@ const defaultMeadowIntegrationAdapterOptions = (
 		// When true, the prefix is truncated to fit while preserving the full external GUID.
 		"AllowGUIDTruncation": false,
 
+		// How to shrink an over-length marshaled GUID when AllowGUIDTruncation is on:
+		//   "substring" (default) — truncate the prefix, keep the external GUID whole (current behavior).
+		//   "hash"                — keep the prefix, deterministically hash the external GUID to fit (stable).
+		"GUIDTruncationStrategy": "substring",
+
 		// When true, only marshal fields that are present in the schema (no passthrough of unknown fields).
 		"SimpleMarshal": false,
 
@@ -105,6 +111,7 @@ class MeadowIntegrationAdapter extends libFableServiceProviderBase
 			this.GUIDMaxLength = this.options.DefaultGUIDColumnSize;
 		}
 		this.AllowGUIDTruncation = this.options.AllowGUIDTruncation;
+		this.GUIDTruncationStrategy = this.options.GUIDTruncationStrategy || 'substring';
 
 		// Integration Adapter Controls
 		this._PerformUpserts = this.options.PerformUpserts;
@@ -214,19 +221,33 @@ class MeadowIntegrationAdapter extends libFableServiceProviderBase
 			}
 
 			// AllowGUIDTruncation is on — the external GUID is sacrosanct, so truncate the prefix instead.
-			let tmpAvailablePrefixLength = this.GUIDMaxLength - pExternalGUID.length;
-
-			if (tmpAvailablePrefixLength <= 0)
+			if (this.GUIDTruncationStrategy === 'hash')
 			{
-				// External GUID alone meets or exceeds the limit; drop the prefix entirely.
-				this.log.warn(`External GUID [${pExternalGUID}] for [${this.Entity}] is ${pExternalGUID.length} characters which meets or exceeds the GUID max length of ${this.GUIDMaxLength}.  Using external GUID with no prefix.`);
-				tmpFullGUID = pExternalGUID.substring(0, this.GUIDMaxLength);
+				// Hash strategy: keep the prefix; deterministically hash the external GUID into the remaining
+				// budget so the result stays stable across runs (idempotent) rather than losing prefix chars.
+				let tmpHashBudget = Math.max(8, this.GUIDMaxLength - this.GUIDPrefix.length);
+				let tmpHashedExternal = libGUIDComposer.hashSegment(pExternalGUID, tmpHashBudget);
+				tmpFullGUID = `${this.GUIDPrefix}${tmpHashedExternal}`;
+				if (tmpFullGUID.length > this.GUIDMaxLength) { tmpFullGUID = tmpFullGUID.substring(0, this.GUIDMaxLength); }
+				this.log.warn(`Generated GUID for [${this.Entity}] exceeded ${this.GUIDMaxLength} chars; external GUID hashed (GUIDTruncationStrategy=hash) to [${tmpHashedExternal}].`);
 			}
 			else
 			{
-				let tmpTruncatedPrefix = this.GUIDPrefix.substring(0, tmpAvailablePrefixLength);
-				tmpFullGUID = `${tmpTruncatedPrefix}${pExternalGUID}`;
-				this.log.warn(`Generated GUID for [${this.Entity}] would be ${this.GUIDPrefix.length + pExternalGUID.length} characters (limit ${this.GUIDMaxLength}); prefix truncated from [${this.GUIDPrefix}] to [${tmpTruncatedPrefix}].`);
+				// Substring strategy (default): the external GUID is sacrosanct, so truncate the prefix instead.
+				let tmpAvailablePrefixLength = this.GUIDMaxLength - pExternalGUID.length;
+
+				if (tmpAvailablePrefixLength <= 0)
+				{
+					// External GUID alone meets or exceeds the limit; drop the prefix entirely.
+					this.log.warn(`External GUID [${pExternalGUID}] for [${this.Entity}] is ${pExternalGUID.length} characters which meets or exceeds the GUID max length of ${this.GUIDMaxLength}.  Using external GUID with no prefix.`);
+					tmpFullGUID = pExternalGUID.substring(0, this.GUIDMaxLength);
+				}
+				else
+				{
+					let tmpTruncatedPrefix = this.GUIDPrefix.substring(0, tmpAvailablePrefixLength);
+					tmpFullGUID = `${tmpTruncatedPrefix}${pExternalGUID}`;
+					this.log.warn(`Generated GUID for [${this.Entity}] would be ${this.GUIDPrefix.length + pExternalGUID.length} characters (limit ${this.GUIDMaxLength}); prefix truncated from [${this.GUIDPrefix}] to [${tmpTruncatedPrefix}].`);
+				}
 			}
 		}
 

package/source/services/guid/Meadow-Integration-GUIDComposer.js

@@ -0,0 +1,131 @@
+// Meadow-Integration-GUIDComposer — deterministic, length-safe composition of context-aware GUIDs.
+//
+// A "context-aware" GUID embeds its parents' identifiers so it is globally unique without a true UUID,
+// e.g. a Line Item 8675309 on Contract 10 / Project 01278 composes to `UI_C10_P01278_LI8675309`. The
+// hard part is staying inside the destination GUID column's width: when the composed string is too long
+// this DETERMINISTICALLY hashes segments (interior context first, then the own segment, then the first)
+// until it fits — `UI_C10_HASH_LI8675309` → `UI_C10_HASH_HASH` — so the same source row always yields the
+// same GUID (idempotent upsert) even after shrinking.
+//
+// PURE + dependency-light on purpose: no node `crypto`, no fable, no DOM. It runs unchanged in the browser
+// engine bundle (the Meadow-Integration-Engine boundary) and is trivially unit-testable in isolation.
+
+const _DEFAULT_SEPARATOR = '_';
+const _DEFAULT_HASH_LENGTH = 10;
+
+/**
+ * Deterministic 53-bit string hash (cyrb53) rendered as a fixed-length base36 token. Same input → same
+ * output in any JS runtime, forever — which is what makes a shrunk GUID still match on re-import.
+ * @param {string} pValue
+ * @param {number} [pLength] - max token length (default 10)
+ * @returns {string}
+ */
+function hashSegment(pValue, pLength)
+{
+	const tmpLength = (typeof pLength === 'number' && pLength > 0) ? pLength : _DEFAULT_HASH_LENGTH;
+	const tmpString = String((pValue === null || pValue === undefined) ? '' : pValue);
+	let tmpH1 = 0xdeadbeef;
+	let tmpH2 = 0x41c6ce57;
+	for (let i = 0; i < tmpString.length; i++)
+	{
+		const tmpCharCode = tmpString.charCodeAt(i);
+		tmpH1 = Math.imul(tmpH1 ^ tmpCharCode, 2654435761);
+		tmpH2 = Math.imul(tmpH2 ^ tmpCharCode, 1597334677);
+	}
+	tmpH1 = Math.imul(tmpH1 ^ (tmpH1 >>> 16), 2246822507) ^ Math.imul(tmpH2 ^ (tmpH2 >>> 13), 3266489909);
+	tmpH2 = Math.imul(tmpH2 ^ (tmpH2 >>> 16), 2246822507) ^ Math.imul(tmpH1 ^ (tmpH1 >>> 13), 3266489909);
+	// 53-bit unsigned integer (safe-integer range) → base36 token.
+	const tmpHashNumber = 4294967296 * (2097151 & tmpH2) + (tmpH1 >>> 0);
+	const tmpToken = tmpHashNumber.toString(36);
+	return (tmpToken.length > tmpLength) ? tmpToken.slice(0, tmpLength) : tmpToken;
+}
+
+/** Render one segment as `<abbrev><value>` (e.g. `P01278`). */
+function segmentString(pSegment)
+{
+	const tmpSegment = pSegment || {};
+	const tmpAbbrev = (tmpSegment.abbrev === null || tmpSegment.abbrev === undefined) ? '' : String(tmpSegment.abbrev);
+	const tmpValue = (tmpSegment.value === null || tmpSegment.value === undefined) ? '' : String(tmpSegment.value);
+	return `${tmpAbbrev}${tmpValue}`;
+}
+
+/** Join the prefix (if any) + the segment strings with the separator. */
+function _assemble(pPrefix, pSegmentStrings, pSeparator)
+{
+	const tmpParts = pPrefix ? [ pPrefix ].concat(pSegmentStrings) : pSegmentStrings.slice();
+	return tmpParts.join(pSeparator);
+}
+
+/**
+ * The order to hash segments when shrinking: interior context segments first (left→right), then the own
+ * (last) segment, then the first context segment — so the prefix + first context + own stay readable
+ * longest. Deterministic, so the same overflow always shrinks the same way.
+ * @param {number} pCount
+ * @returns {Array<number>}
+ */
+function _shrinkOrder(pCount)
+{
+	const tmpOrder = [];
+	for (let i = 1; i < pCount - 1; i++) { tmpOrder.push(i); }
+	if (pCount - 1 >= 1) { tmpOrder.push(pCount - 1); }
+	if (pCount >= 1) { tmpOrder.push(0); }
+	const tmpSeen = {};
+	return tmpOrder.filter((pIndex) => (tmpSeen[pIndex] ? false : (tmpSeen[pIndex] = true)));
+}
+
+/**
+ * Compose a deterministic, length-safe context-aware GUID.
+ * @param {object} pSpec
+ * @param {string} [pSpec.prefix] - the leading token (e.g. `UI`); omitted if falsy
+ * @param {Array<{abbrev:string, value:*}>} pSpec.segments - ordered context segments + the own segment last
+ * @param {string} [pSpec.separator] - default `_`
+ * @param {number} [pSpec.maxLength] - the destination GUID column width; <=0 means unbounded
+ * @param {number} [pSpec.hashLength] - per-segment hash token length (default 10)
+ * @returns {string}
+ */
+function composeGUID(pSpec)
+{
+	const tmpSpec = pSpec || {};
+	const tmpPrefix = tmpSpec.prefix ? String(tmpSpec.prefix) : '';
+	const tmpSeparator = (typeof tmpSpec.separator === 'string') ? tmpSpec.separator : _DEFAULT_SEPARATOR;
+	const tmpMaxLength = (typeof tmpSpec.maxLength === 'number') ? tmpSpec.maxLength : 0;
+	const tmpHashLength = (typeof tmpSpec.hashLength === 'number' && tmpSpec.hashLength > 0) ? tmpSpec.hashLength : _DEFAULT_HASH_LENGTH;
+	const tmpSegments = Array.isArray(tmpSpec.segments) ? tmpSpec.segments : [];
+
+	const tmpSegmentStrings = tmpSegments.map(segmentString);
+	let tmpFull = _assemble(tmpPrefix, tmpSegmentStrings, tmpSeparator);
+	if (tmpMaxLength <= 0 || tmpFull.length <= tmpMaxLength)
+	{
+		return tmpFull;
+	}
+
+	// Too long — hash segment VALUES (keeping each segment's abbreviation for readability) in shrink order
+	// until it fits. The hash is deterministic, so this stays stable across runs.
+	const tmpShrinkOrder = _shrinkOrder(tmpSegments.length);
+	for (let k = 0; k < tmpShrinkOrder.length; k++)
+	{
+		const tmpIndex = tmpShrinkOrder[k];
+		const tmpSegment = tmpSegments[tmpIndex] || {};
+		const tmpAbbrev = (tmpSegment.abbrev === null || tmpSegment.abbrev === undefined) ? '' : String(tmpSegment.abbrev);
+		tmpSegmentStrings[tmpIndex] = `${tmpAbbrev}${hashSegment(segmentString(tmpSegment), tmpHashLength)}`;
+		tmpFull = _assemble(tmpPrefix, tmpSegmentStrings, tmpSeparator);
+		if (tmpFull.length <= tmpMaxLength)
+		{
+			return tmpFull;
+		}
+	}
+
+	// Last resort (even all-hashed is too long, or a tiny column): collapse the whole body after the prefix
+	// into a single hash sized to the remaining budget.
+	const tmpBody = _assemble(tmpPrefix, tmpSegments.map(segmentString), tmpSeparator);
+	const tmpPrefixCost = tmpPrefix ? (tmpPrefix.length + tmpSeparator.length) : 0;
+	const tmpBudget = Math.max(6, tmpMaxLength - tmpPrefixCost);
+	tmpFull = (tmpPrefix ? `${tmpPrefix}${tmpSeparator}` : '') + hashSegment(tmpBody, tmpBudget);
+	return (tmpFull.length > tmpMaxLength) ? tmpFull.slice(0, tmpMaxLength) : tmpFull;
+}
+
+module.exports = {
+	composeGUID,
+	hashSegment,
+	segmentString,
+};

package/source/services/guid/Meadow-Integration-GUIDStrategy.js

@@ -0,0 +1,238 @@
+// Meadow-Integration-GUIDStrategy — compiles a high-level, per-entity GUID strategy into the structured
+// spec the transform consumes (which `Service-TabularTransform.createRecordFromMapping` resolves per row
+// via the GUID composer). This is the configurable brain behind context-aware import GUIDs.
+//
+// It does NOT touch fable or the DOM and produces only plain data (segment value-TEMPLATES, field names,
+// length budgets) — so it is reusable by the CLI, the server endpoints, and the browser import wizard
+// alike, and is trivially unit-testable.
+//
+// Three modes per entity AND per join, mapped onto the adapter's existing FK conventions:
+//   - prefixed (default): compose `UI_<context…>_<own>`; own → `GUID<Entity>`. A join to a parent that
+//       was uploaded in THIS run → `GUID<Parent>` (sync session GUIDMap); a join to a PRE-EXISTING parent
+//       (crossSession) → `_GUID<Parent>` (async server `getEntityByGUID` lookup).
+//   - raw: the source already carries a true Meadow GUID → `_GUID<Parent>` (join) / `GUID<Entity>` (own).
+//   - rawid: the source already carries a real `ID<Parent>` → used directly.
+
+const _DEFAULT_PREFIX = 'UI';
+const _DEFAULT_SEPARATOR = '_';
+const _DEFAULT_HASH_LENGTH = 10;
+
+/** A `{~D:Record.<column>~}` value template (what the transform resolves per row). */
+function valueTemplate(pColumn)
+{
+	return `{~D:Record.${pColumn}~}`;
+}
+
+/** Derive a short uppercase abbreviation for an entity with no catalog entry (initials / first letters). */
+function _deriveAbbreviation(pEntityName)
+{
+	const tmpName = String(pEntityName || '');
+	const tmpCapitals = tmpName.replace(/[^A-Z]/g, '');
+	if (tmpCapitals.length >= 2)
+	{
+		return tmpCapitals.slice(0, 3);
+	}
+	return tmpName.slice(0, 3).toUpperCase();
+}
+
+/**
+ * @param {string} pEntityName @param {Record<string, any>} pContext
+ * @returns {string} the host-fixed abbreviation (catalog) or a derived fallback
+ */
+function abbreviationFor(pEntityName, pContext)
+{
+	const tmpCatalog = (pContext && pContext.Catalog) || {};
+	const tmpEntry = tmpCatalog[pEntityName];
+	if (tmpEntry && tmpEntry.Abbrev)
+	{
+		return String(tmpEntry.Abbrev);
+	}
+	return _deriveAbbreviation(pEntityName);
+}
+
+/** The GUID column width for an entity (from the live schema), or 0 (unbounded) if unknown. */
+function _maxLengthFor(pEntityName, pContext)
+{
+	const tmpSizes = (pContext && pContext.SchemaSizes) || {};
+	const tmpSize = Number(tmpSizes[pEntityName] || 0);
+	return (tmpSize > 0) ? tmpSize : 0;
+}
+
+/** Build a compose spec (prefix + ordered segments + length budget) for an entity's fullGUID. */
+function _composeSpec(pEntityName, pSegments, pContext)
+{
+	return {
+		prefix: (pContext && (pContext.Prefix !== undefined)) ? pContext.Prefix : _DEFAULT_PREFIX,
+		separator: (pContext && pContext.Separator) || _DEFAULT_SEPARATOR,
+		hashLength: (pContext && pContext.HashLength) || _DEFAULT_HASH_LENGTH,
+		maxLength: _maxLengthFor(pEntityName, pContext),
+		segments: pSegments,
+	};
+}
+
+/**
+ * The ordered context + own segments for an entity's OWN fullGUID.
+ * @returns {{segments:Array<any>, warnings:Array<string>}}
+ */
+function _ownSegments(pEntityName, pEntityConfig, pContext)
+{
+	const tmpWarnings = [];
+	const tmpSegments = [];
+	const tmpContextEntities = Array.isArray(pEntityConfig.ContextEntities) ? pEntityConfig.ContextEntities : [];
+	const tmpContextKeyColumns = pEntityConfig.ContextKeyColumns || {};
+
+	tmpContextEntities.forEach((pParentEntity) =>
+	{
+		const tmpKeyColumn = tmpContextKeyColumns[pParentEntity];
+		if (!tmpKeyColumn)
+		{
+			tmpWarnings.push(`Context entity "${pParentEntity}" for "${pEntityName}" has no key column mapped — its segment will be empty.`);
+		}
+		tmpSegments.push({ abbrev: abbreviationFor(pParentEntity, pContext), valueTemplate: tmpKeyColumn ? valueTemplate(tmpKeyColumn) : '' });
+	});
+
+	if (!pEntityConfig.OwnKeyColumn)
+	{
+		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).`);
+	}
+	tmpSegments.push({ abbrev: abbreviationFor(pEntityName, pContext), valueTemplate: pEntityConfig.OwnKeyColumn ? valueTemplate(pEntityConfig.OwnKeyColumn) : '' });
+
+	return { segments: tmpSegments, warnings: tmpWarnings };
+}
+
+/** Compile the OWN GUID descriptor (field name + compose spec / raw template) for one entity. */
+function _compileOwn(pEntityName, pEntityConfig, pContext)
+{
+	const tmpGUIDName = `GUID${pEntityName}`;
+	const tmpMode = pEntityConfig.Mode || 'prefixed';
+
+	if (tmpMode === 'raw')
+	{
+		// Source carries a true Meadow GUID; with empty marshal prefixes it passes through GUID<Entity>.
+		return { Own: { Mode: 'raw', FieldName: tmpGUIDName, ValueTemplate: valueTemplate(pEntityConfig.OwnGUIDColumn || pEntityConfig.OwnKeyColumn) }, warnings: [] };
+	}
+	if (tmpMode === 'rawid')
+	{
+		// rawid OWN is deferred: the comprehension is keyed by GUID<Entity>, so an ID-only own record has
+		// no comprehension key. Use a join in rawid mode instead, or import such sheets via the raw path.
+		return { Own: { Mode: 'prefixed', FieldName: tmpGUIDName, Compose: _composeSpec(pEntityName, _ownSegments(pEntityName, pEntityConfig, pContext).segments, pContext) },
+			warnings: [ `"${pEntityName}" requested raw-ID own mode, which is not yet supported for the entity's own GUID — fell back to prefixed.` ] };
+	}
+
+	// prefixed (default)
+	const tmpOwn = _ownSegments(pEntityName, pEntityConfig, pContext);
+	return { Own: { Mode: 'prefixed', FieldName: tmpGUIDName, Compose: _composeSpec(pEntityName, tmpOwn.segments, pContext) }, warnings: tmpOwn.warnings };
+}
+
+/** The FK field name for a join, per the adapter's conventions. */
+function joinFieldName(pParentEntity, pMode, pCrossSession)
+{
+	if (pMode === 'rawid')
+	{
+		return `ID${pParentEntity}`;
+	}
+	if (pMode === 'raw')
+	{
+		return `_GUID${pParentEntity}`;
+	}
+	// prefixed: sync (same-upload) vs async server lookup (pre-existing parent)
+	return pCrossSession ? `_GUID${pParentEntity}` : `GUID${pParentEntity}`;
+}
+
+/** Compile one join (FK) descriptor for an entity. */
+function _compileJoin(pParentEntity, pJoin, pContext)
+{
+	const tmpMode = pJoin.Mode || 'prefixed';
+	const tmpCrossSession = !!pJoin.CrossSession;
+	const tmpFieldName = joinFieldName(pParentEntity, tmpMode, tmpCrossSession);
+	const tmpWarnings = [];
+
+	if (tmpMode === 'raw' || tmpMode === 'rawid')
+	{
+		const tmpColumn = pJoin.GUIDColumn || pJoin.IDColumn || pJoin.KeyColumn;
+		if (!tmpColumn)
+		{
+			tmpWarnings.push(`Join "${pParentEntity}" (${tmpMode}) has no source column mapped.`);
+		}
+		return { Join: { ParentEntity: pParentEntity, Mode: tmpMode, FieldName: tmpFieldName, ValueTemplate: tmpColumn ? valueTemplate(tmpColumn) : '' }, warnings: tmpWarnings };
+	}
+
+	// prefixed: recompute the PARENT's fullGUID from this row's columns (so it matches the parent's own GUID).
+	if (!pJoin.KeyColumn)
+	{
+		tmpWarnings.push(`Join "${pParentEntity}" (prefixed) has no parent key column mapped — the foreign key will not resolve.`);
+	}
+	const tmpParentContextEntities = Array.isArray(pJoin.ContextEntities) ? pJoin.ContextEntities : [];
+	const tmpParentContextKeyColumns = pJoin.ContextKeyColumns || {};
+	const tmpSegments = tmpParentContextEntities.map((pGrandparent) => (
+		{ abbrev: abbreviationFor(pGrandparent, pContext), valueTemplate: tmpParentContextKeyColumns[pGrandparent] ? valueTemplate(tmpParentContextKeyColumns[pGrandparent]) : '' }));
+	tmpSegments.push({ abbrev: abbreviationFor(pParentEntity, pContext), valueTemplate: pJoin.KeyColumn ? valueTemplate(pJoin.KeyColumn) : '' });
+
+	return { Join: { ParentEntity: pParentEntity, Mode: 'prefixed', FieldName: tmpFieldName, Compose: _composeSpec(pParentEntity, tmpSegments, pContext) }, warnings: tmpWarnings };
+}
+
+/**
+ * Compile one entity's strategy (own GUID + joins).
+ * @param {string} pEntityName @param {Record<string, any>} pEntityConfig @param {Record<string, any>} pContext
+ * @returns {{Strategy:Record<string, any>, Warnings:Array<string>}}
+ */
+function compileEntity(pEntityName, pEntityConfig, pContext)
+{
+	const tmpConfig = pEntityConfig || {};
+	const tmpWarnings = [];
+
+	const tmpOwn = _compileOwn(pEntityName, tmpConfig, pContext);
+	tmpWarnings.push(...tmpOwn.warnings);
+
+	const tmpJoins = [];
+	(Array.isArray(tmpConfig.Joins) ? tmpConfig.Joins : []).forEach((pJoin) =>
+	{
+		if (!pJoin || !pJoin.ParentEntity) { return; }
+		const tmpCompiled = _compileJoin(pJoin.ParentEntity, pJoin, pContext);
+		tmpJoins.push(tmpCompiled.Join);
+		tmpWarnings.push(...tmpCompiled.warnings);
+	});
+
+	return {
+		Strategy: { Entity: pEntityName, GUIDName: `GUID${pEntityName}`, Own: tmpOwn.Own, Joins: tmpJoins },
+		Warnings: tmpWarnings,
+	};
+}
+
+/**
+ * Compile a whole import's GUID strategy.
+ * @param {Record<string, any>} pConfig - { Prefix?, Separator?, HashLength?, Entities:{ <name>: <entityConfig> } }
+ * @param {Record<string, any>} pContext - { Catalog:{ <entity>:{Abbrev,KeyField} }, SchemaSizes:{ <entity>:size } }
+ * @returns {{Strategies:Record<string, any>, Warnings:Array<string>}}
+ */
+function compile(pConfig, pContext)
+{
+	const tmpConfig = pConfig || {};
+	const tmpContext = Object.assign(
+		{
+			Prefix: (tmpConfig.Prefix !== undefined) ? tmpConfig.Prefix : _DEFAULT_PREFIX,
+			Separator: tmpConfig.Separator || _DEFAULT_SEPARATOR,
+			HashLength: tmpConfig.HashLength || _DEFAULT_HASH_LENGTH,
+		},
+		pContext || {});
+
+	const tmpEntities = tmpConfig.Entities || {};
+	const tmpStrategies = {};
+	const tmpWarnings = [];
+	Object.keys(tmpEntities).forEach((pEntityName) =>
+	{
+		const tmpCompiled = compileEntity(pEntityName, tmpEntities[pEntityName], tmpContext);
+		tmpStrategies[pEntityName] = tmpCompiled.Strategy;
+		tmpWarnings.push(...tmpCompiled.Warnings);
+	});
+
+	return { Strategies: tmpStrategies, Warnings: tmpWarnings };
+}
+
+module.exports = {
+	compile,
+	compileEntity,
+	joinFieldName,
+	abbreviationFor,
+	valueTemplate,
+};

package/source/services/tabular/Service-TabularTransform.js

@@ -1,5 +1,7 @@
 const libFableService = require('fable-serviceproviderbase');
 
+const libGUIDComposer = require('../guid/Meadow-Integration-GUIDComposer.js');
+
 /*
 		// Comprehension Parameters
 		// This can be *either* a mapping file, in the following format, or a set of parameters listed below.  The mapping file lets you map columns way easier!
@@ -134,7 +136,17 @@ class MeadowIntegrationTabularTransform extends libFableService
 	{
 		let tmpRecord = ((typeof(pRecordPrototype) == 'object') && (pRecordPrototype != null)) ? JSON.parse(JSON.stringify(pRecordPrototype)) : {};
 
-		tmpRecord[pMapping.GUIDName] = this.fable.parseTemplate(pMapping.GUIDTemplate, pRecord);
+		// Opt-in context-aware GUID strategy: compose the entity's own GUID + its foreign-key GUID/ID
+		// fields from a structured spec (length-safe + deterministic). Falls back to the flat GUIDTemplate
+		// when no strategy is attached, so every existing mapping behaves exactly as before.
+		if (pMapping.GUIDStrategy)
+		{
+			this._applyGUIDStrategy(tmpRecord, pMapping.GUIDStrategy, pRecord);
+		}
+		else
+		{
+			tmpRecord[pMapping.GUIDName] = this.fable.parseTemplate(pMapping.GUIDTemplate, pRecord);
+		}
 
 		let tmpKeys = Object.keys(pMapping.Mappings);
 		for (let i = 0; i < tmpKeys.length; i++)
@@ -153,6 +165,56 @@ class MeadowIntegrationTabularTransform extends libFableService
 		return tmpRecord;
 	}
 
+	/**
+	 * Resolve a GUID compose spec's segment value-templates against the row, then run the deterministic
+	 * length-safe composer. The compiler (Meadow-Integration-GUIDStrategy) produced the spec.
+	 * @param {Record<string, any>} pComposeSpec @param {Record<string, any>} pRecord
+	 * @returns {string}
+	 */
+	composeGUIDFromSpec(pComposeSpec, pRecord)
+	{
+		let tmpSegments = (Array.isArray(pComposeSpec.segments) ? pComposeSpec.segments : []).map((pSegment) =>
+		{
+			return {
+				abbrev: pSegment.abbrev,
+				value: pSegment.valueTemplate ? this.fable.parseTemplate(pSegment.valueTemplate, pRecord) : '',
+			};
+		});
+		return libGUIDComposer.composeGUID(
+			{
+				prefix: pComposeSpec.prefix,
+				separator: pComposeSpec.separator,
+				maxLength: pComposeSpec.maxLength,
+				hashLength: pComposeSpec.hashLength,
+				segments: tmpSegments,
+			});
+	}
+
+	/**
+	 * Stamp an entity's own GUID + its foreign-key fields onto the record from a compiled GUID strategy.
+	 * Own / each join is one of: prefixed (Compose spec) or raw/rawid (a resolved source-column template).
+	 * @param {Record<string, any>} pTargetRecord @param {Record<string, any>} pStrategy @param {Record<string, any>} pRecord
+	 */
+	_applyGUIDStrategy(pTargetRecord, pStrategy, pRecord)
+	{
+		let tmpOwn = pStrategy.Own || {};
+		if (tmpOwn.FieldName)
+		{
+			pTargetRecord[tmpOwn.FieldName] = tmpOwn.Compose
+				? this.composeGUIDFromSpec(tmpOwn.Compose, pRecord)
+				: (tmpOwn.ValueTemplate ? this.fable.parseTemplate(tmpOwn.ValueTemplate, pRecord) : '');
+		}
+		let tmpJoins = Array.isArray(pStrategy.Joins) ? pStrategy.Joins : [];
+		for (let i = 0; i < tmpJoins.length; i++)
+		{
+			let tmpJoin = tmpJoins[i];
+			if (!tmpJoin || !tmpJoin.FieldName) { continue; }
+			pTargetRecord[tmpJoin.FieldName] = tmpJoin.Compose
+				? this.composeGUIDFromSpec(tmpJoin.Compose, pRecord)
+				: (tmpJoin.ValueTemplate ? this.fable.parseTemplate(tmpJoin.ValueTemplate, pRecord) : '');
+		}
+	}
+
 	addRecordToComprehension(pIncomingRecord, pMappingOutcome, pNewRecordPrototype, pGUIDUniquenessString)
 	{
 		let tmpNewRecordPrototype = (typeof(pNewRecordPrototype) == 'object') ? pNewRecordPrototype : {};

package/test/Meadow-Integration-GUIDComposer_test.js

@@ -0,0 +1,162 @@
+/*
+	Unit tests for the context-aware GUID composer (Meadow-Integration-GUIDComposer).
+
+	Pure module — no fable, no network. Verifies deterministic composition, the length-safe shrink-by-hash
+	behavior across the real GUID column widths (36 / 64 / 128), and idempotency (same input → same GUID).
+*/
+
+const Chai = require('chai');
+const Expect = Chai.expect;
+
+const libComposer = require('../source/services/guid/Meadow-Integration-GUIDComposer.js');
+
+const projectSpec = (pCode, pMaxLength) => (
+{
+	prefix: 'UI',
+	maxLength: pMaxLength,
+	segments: [ { abbrev: 'P', value: pCode } ],
+});
+
+const lineItemSpec = (pContract, pProject, pLineId, pMaxLength) => (
+{
+	prefix: 'UI',
+	maxLength: pMaxLength,
+	segments: [ { abbrev: 'C', value: pContract }, { abbrev: 'P', value: pProject }, { abbrev: 'LI', value: pLineId } ],
+});
+
+suite
+(
+	'Meadow Integration — GUID Composer',
+	() =>
+	{
+		suite
+		(
+			'composition',
+			() =>
+			{
+				test
+				(
+					'composes prefix + segments with underscores (the headline example)',
+					() =>
+					{
+						const tmpGUID = libComposer.composeGUID(lineItemSpec('10', '01278', '8675309', 64));
+						Expect(tmpGUID).to.equal('UI_C10_P01278_LI8675309');
+					}
+				);
+				test
+				(
+					'a top-level entity composes prefix + own segment',
+					() =>
+					{
+						Expect(libComposer.composeGUID(projectSpec('01278', 64))).to.equal('UI_P01278');
+					}
+				);
+				test
+				(
+					'omits the prefix (and its separator) when falsy',
+					() =>
+					{
+						const tmpGUID = libComposer.composeGUID({ prefix: '', maxLength: 64, segments: [ { abbrev: 'P', value: '01278' } ] });
+						Expect(tmpGUID).to.equal('P01278');
+					}
+				);
+				test
+				(
+					'a child FK recomputed from the parent spec matches the parent\'s own GUID',
+					() =>
+					{
+						// Parent (Project) own GUID, and the same Project spec evaluated on the child's row values.
+						const tmpParentOwn = libComposer.composeGUID(projectSpec('01278', 64));
+						const tmpChildFK = libComposer.composeGUID(projectSpec('01278', 64));
+						Expect(tmpChildFK).to.equal(tmpParentOwn);
+					}
+				);
+			}
+		);
+		suite
+		(
+			'determinism',
+			() =>
+			{
+				test
+				(
+					'same input → same GUID, every time',
+					() =>
+					{
+						const tmpA = libComposer.composeGUID(lineItemSpec('10', 'VERYLONGPROJECTCODE-001278-REGION-NORTH', '8675309', 36));
+						const tmpB = libComposer.composeGUID(lineItemSpec('10', 'VERYLONGPROJECTCODE-001278-REGION-NORTH', '8675309', 36));
+						Expect(tmpA).to.equal(tmpB);
+					}
+				);
+				test
+				(
+					'hashSegment is deterministic + length-bounded',
+					() =>
+					{
+						Expect(libComposer.hashSegment('P01278', 10)).to.equal(libComposer.hashSegment('P01278', 10));
+						Expect(libComposer.hashSegment('P01278', 10).length).to.be.at.most(10);
+						Expect(libComposer.hashSegment('A')).to.not.equal(libComposer.hashSegment('B'));
+					}
+				);
+			}
+		);
+		suite
+		(
+			'length-safety (real column widths)',
+			() =>
+			{
+				test
+				(
+					'fits inside a 36-char column by hashing, staying prefixed + stable',
+					() =>
+					{
+						const tmpSpec = lineItemSpec('CONTRACT-2026-NORTH', 'PROJECT-01278-HIGHWAY-10-REPAVE', 'LINEITEM-8675309-CONCRETE', 36);
+						const tmpGUID = libComposer.composeGUID(tmpSpec);
+						Expect(tmpGUID.length, tmpGUID).to.be.at.most(36);
+						Expect(tmpGUID.indexOf('UI_'), 'keeps the UI prefix').to.equal(0);
+						// idempotent
+						Expect(libComposer.composeGUID(tmpSpec)).to.equal(tmpGUID);
+					}
+				);
+				test
+				(
+					'a 64-char column keeps the readable form when it already fits',
+					() =>
+					{
+						Expect(libComposer.composeGUID(lineItemSpec('10', '01278', '8675309', 64))).to.equal('UI_C10_P01278_LI8675309');
+					}
+				);
+				test
+				(
+					'a 128-char column has ample room (PhysicalAsset-like)',
+					() =>
+					{
+						const tmpGUID = libComposer.composeGUID(lineItemSpec('10', '01278', '8675309', 128));
+						Expect(tmpGUID).to.equal('UI_C10_P01278_LI8675309');
+						Expect(tmpGUID.length).to.be.at.most(128);
+					}
+				);
+				test
+				(
+					'an unbounded (maxLength <= 0) compose never hashes',
+					() =>
+					{
+						const tmpGUID = libComposer.composeGUID(lineItemSpec('CONTRACT-2026', 'PROJECT-01278-HIGHWAY', 'LINEITEM-8675309', 0));
+						Expect(tmpGUID).to.equal('UI_CCONTRACT-2026_PPROJECT-01278-HIGHWAY_LILINEITEM-8675309');
+					}
+				);
+				test
+				(
+					'a pathologically tiny column still produces a stable, in-budget GUID',
+					() =>
+					{
+						const tmpSpec = lineItemSpec('CONTRACT-LONG', 'PROJECT-LONG', 'LINEITEM-LONG', 16);
+						const tmpGUID = libComposer.composeGUID(tmpSpec);
+						Expect(tmpGUID.length, tmpGUID).to.be.at.most(16);
+						Expect(libComposer.composeGUID(tmpSpec)).to.equal(tmpGUID);
+					}
+				);
+			}
+		);
+	}
+);

package/test/Meadow-Integration-GUIDStrategyTransform_test.js

@@ -0,0 +1,144 @@
+/*
+	Integration test: the GUID strategy flows end-to-end through the real TabularTransform.
+
+	Compiler (config → spec) → transform (resolves segment templates per row) → composer (length-safe) →
+	comprehension record with the entity's own GUID + its foreign-key GUID/ID fields. Uses a pict instance
+	as the host fable (pict provides `parseTemplate`) — the same shape the browser import wizard passes.
+*/
+
+const Chai = require('chai');
+const Expect = Chai.expect;
+
+const libPict = require('pict');
+
+const libEngine = require('../source/Meadow-Integration-Engine.js');
+
+const newTransform = () =>
+{
+	const tmpPict = new libPict({ Product: 'GUIDStrategyTransformTest', LogStreams: [ { streamtype: 'console', level: 'error' } ] });
+	return new libEngine.MeadowIntegrationTabularTransform(tmpPict);
+};
+
+const CATALOG =
+{
+	Project: { Abbrev: 'P' },
+	Contract: { Abbrev: 'C' },
+	LineItem: { Abbrev: 'LI' },
+};
+const SIZES = { Project: 64, Contract: 64, LineItem: 64 };
+
+// Build the comprehension for one entity mapping over one row (mirrors DataImport-ComprehensionBuilder).
+const runOneEntity = (pTransform, pMapping, pRow) =>
+{
+	const tmpOutcome = pTransform.newMappingOutcomeObject();
+	tmpOutcome.ImplicitConfiguration = {};
+	tmpOutcome.ExplicitConfiguration = pMapping;
+	pTransform.initializeMappingOutcomeObject(tmpOutcome);
+	pTransform.transformRecord(pRow, tmpOutcome);
+	return tmpOutcome.Comprehension[pMapping.Entity] || {};
+};
+
+suite
+(
+	'Meadow Integration — GUID strategy through the transform',
+	() =>
+	{
+		test
+		(
+			'composes a top-level entity own GUID from the strategy',
+			() =>
+			{
+				const tmpTransform = newTransform();
+				const tmpStrategy = libEngine.compileGUIDStrategy(
+					{ Prefix: 'UI', Entities: { Project: { Mode: 'prefixed', OwnKeyColumn: 'ProjectCode' } } },
+					{ Catalog: CATALOG, SchemaSizes: SIZES }).Strategies.Project;
+				const tmpMapping = { Entity: 'Project', GUIDName: 'GUIDProject', GUIDStrategy: tmpStrategy, Mappings: { Name: '{~D:Record.ProjectName~}' } };
+
+				const tmpComprehension = runOneEntity(tmpTransform, tmpMapping, { ProjectCode: '01278', ProjectName: 'Highway 10 Repave' });
+				const tmpKeys = Object.keys(tmpComprehension);
+				Expect(tmpKeys).to.deep.equal([ 'UI_P01278' ]);
+				Expect(tmpComprehension['UI_P01278'].GUIDProject).to.equal('UI_P01278');
+				Expect(tmpComprehension['UI_P01278'].Name).to.equal('Highway 10 Repave');
+			}
+		);
+		test
+		(
+			'composes a child own GUID (context chain) + cross-session FK fields',
+			() =>
+			{
+				const tmpTransform = newTransform();
+				const tmpStrategy = libEngine.compileGUIDStrategy(
+					{
+						Prefix: 'UI',
+						Entities:
+						{
+							LineItem:
+							{
+								Mode: 'prefixed',
+								OwnKeyColumn: 'LineId',
+								ContextEntities: [ 'Contract', 'Project' ],
+								ContextKeyColumns: { Contract: 'ContractNum', Project: 'ProjectCode' },
+								Joins:
+								[
+									{ ParentEntity: 'Project', Mode: 'prefixed', KeyColumn: 'ProjectCode', CrossSession: true },
+									{ ParentEntity: 'Contract', Mode: 'prefixed', KeyColumn: 'ContractNum', CrossSession: true },
+								],
+							},
+						},
+					},
+					{ Catalog: CATALOG, SchemaSizes: SIZES }).Strategies.LineItem;
+				const tmpMapping = { Entity: 'LineItem', GUIDName: 'GUIDLineItem', GUIDStrategy: tmpStrategy, Mappings: { Quantity: '{~D:Record.qty~}' } };
+
+				const tmpRow = { ContractNum: '10', ProjectCode: '01278', LineId: '8675309', qty: '5' };
+				const tmpComprehension = runOneEntity(tmpTransform, tmpMapping, tmpRow);
+				const tmpRecord = tmpComprehension['UI_C10_P01278_LI8675309'];
+				Expect(tmpRecord, 'record keyed by composed own GUID').to.be.an('object');
+				Expect(tmpRecord.GUIDLineItem).to.equal('UI_C10_P01278_LI8675309');
+				// Cross-session FK fields use the `_GUID<Parent>` async-lookup convention + the parent's own GUID.
+				Expect(tmpRecord._GUIDProject).to.equal('UI_P01278');
+				Expect(tmpRecord._GUIDContract).to.equal('UI_C10');
+				Expect(tmpRecord.Quantity).to.equal('5');
+			}
+		);
+		test
+		(
+			'the child FK equals the parent\'s own GUID (so the join resolves) — and is idempotent',
+			() =>
+			{
+				const tmpTransform = newTransform();
+				const tmpCompiled = libEngine.compileGUIDStrategy(
+					{
+						Prefix: 'UI',
+						Entities:
+						{
+							Project: { Mode: 'prefixed', OwnKeyColumn: 'ProjectCode' },
+							LineItem: { Mode: 'prefixed', OwnKeyColumn: 'LineId', Joins: [ { ParentEntity: 'Project', Mode: 'prefixed', KeyColumn: 'ProjectCode', CrossSession: false } ] },
+						},
+					},
+					{ Catalog: CATALOG, SchemaSizes: SIZES }).Strategies;
+
+				const tmpProjectComp = runOneEntity(tmpTransform, { Entity: 'Project', GUIDName: 'GUIDProject', GUIDStrategy: tmpCompiled.Project, Mappings: {} }, { ProjectCode: '01278' });
+				const tmpLineComp = runOneEntity(tmpTransform, { Entity: 'LineItem', GUIDName: 'GUIDLineItem', GUIDStrategy: tmpCompiled.LineItem, Mappings: {} }, { ProjectCode: '01278', LineId: '42' });
+
+				const tmpProjectGUID = Object.keys(tmpProjectComp)[0];
+				// same-upload join → sync `GUID<Parent>` field, value == the Project's own GUID
+				Expect(tmpLineComp['UI_LI42'].GUIDProject).to.equal(tmpProjectGUID);
+				// re-running yields the identical record (idempotent)
+				const tmpLineComp2 = runOneEntity(newTransform(), { Entity: 'LineItem', GUIDName: 'GUIDLineItem', GUIDStrategy: tmpCompiled.LineItem, Mappings: {} }, { ProjectCode: '01278', LineId: '42' });
+				Expect(Object.keys(tmpLineComp2)).to.deep.equal([ 'UI_LI42' ]);
+			}
+		);
+		test
+		(
+			'a non-strategy mapping still uses the flat GUIDTemplate (no behavior change)',
+			() =>
+			{
+				const tmpTransform = newTransform();
+				const tmpMapping = { Entity: 'Airport', GUIDName: 'GUIDAirport', GUIDTemplate: 'Airport_{~D:Record.iata~}', Mappings: { Name: '{~D:Record.name~}' } };
+				const tmpComprehension = runOneEntity(tmpTransform, tmpMapping, { iata: 'BTR', name: 'Baton Rouge' });
+				Expect(Object.keys(tmpComprehension)).to.deep.equal([ 'Airport_BTR' ]);
+				Expect(tmpComprehension['Airport_BTR'].Name).to.equal('Baton Rouge');
+			}
+		);
+	}
+);

package/test/Meadow-Integration-GUIDStrategy_test.js

@@ -0,0 +1,150 @@
+/*
+	Unit tests for the GUID strategy compiler (Meadow-Integration-GUIDStrategy).
+
+	Pure module — turns a per-entity strategy config + a host context catalog + schema GUID sizes into the
+	structured spec the transform consumes. Verifies own/context composition, the per-join FK field-name
+	selection (mapping to the adapter's GUID / _GUID / ID conventions), and the no-key warning.
+*/
+
+const Chai = require('chai');
+const Expect = Chai.expect;
+
+const libStrategy = require('../source/services/guid/Meadow-Integration-GUIDStrategy.js');
+const libComposer = require('../source/services/guid/Meadow-Integration-GUIDComposer.js');
+
+const CATALOG =
+{
+	Project: { Abbrev: 'P', KeyField: 'Code' },
+	Contract: { Abbrev: 'C', KeyField: 'Number' },
+	LineItem: { Abbrev: 'LI', KeyField: 'Code' },
+};
+const SIZES = { Project: 64, Contract: 64, LineItem: 64 };
+
+const CONFIG =
+{
+	Prefix: 'UI',
+	Entities:
+	{
+		Project: { Mode: 'prefixed', OwnKeyColumn: 'ProjectCode' },
+		LineItem:
+		{
+			Mode: 'prefixed',
+			OwnKeyColumn: 'LineId',
+			ContextEntities: [ 'Contract', 'Project' ],
+			ContextKeyColumns: { Contract: 'ContractNum', Project: 'ProjectCode' },
+			Joins:
+			[
+				{ ParentEntity: 'Project', Mode: 'prefixed', KeyColumn: 'ProjectCode', CrossSession: true },
+				{ ParentEntity: 'Contract', Mode: 'prefixed', KeyColumn: 'ContractNum', CrossSession: true },
+			],
+		},
+	},
+};
+
+suite
+(
+	'Meadow Integration — GUID Strategy compiler',
+	() =>
+	{
+		test
+		(
+			'compiles a top-level entity to a single-segment own GUID spec',
+			() =>
+			{
+				const tmpResult = libStrategy.compile(CONFIG, { Catalog: CATALOG, SchemaSizes: SIZES });
+				const tmpProject = tmpResult.Strategies.Project;
+				Expect(tmpProject.GUIDName).to.equal('GUIDProject');
+				Expect(tmpProject.Own.FieldName).to.equal('GUIDProject');
+				Expect(tmpProject.Own.Compose.prefix).to.equal('UI');
+				Expect(tmpProject.Own.Compose.maxLength).to.equal(64);
+				Expect(tmpProject.Own.Compose.segments).to.have.length(1);
+				Expect(tmpProject.Own.Compose.segments[0]).to.deep.equal({ abbrev: 'P', valueTemplate: '{~D:Record.ProjectCode~}' });
+			}
+		);
+		test
+		(
+			'composes the headline LineItem own GUID from context + own segments',
+			() =>
+			{
+				const tmpLineItem = libStrategy.compile(CONFIG, { Catalog: CATALOG, SchemaSizes: SIZES }).Strategies.LineItem;
+				const tmpSegments = tmpLineItem.Own.Compose.segments;
+				Expect(tmpSegments).to.have.length(3);
+				Expect(tmpSegments.map((s) => s.abbrev)).to.deep.equal([ 'C', 'P', 'LI' ]);
+				// Resolve the templates against a sample row + run the composer → the headline string.
+				const tmpRow = { ContractNum: '10', ProjectCode: '01278', LineId: '8675309' };
+				const tmpResolved = tmpSegments.map((s) => ({ abbrev: s.abbrev, value: tmpRow[s.valueTemplate.replace('{~D:Record.', '').replace('~}', '')] }));
+				Expect(libComposer.composeGUID({ prefix: 'UI', maxLength: 64, segments: tmpResolved })).to.equal('UI_C10_P01278_LI8675309');
+			}
+		);
+		test
+		(
+			'a cross-session prefixed join emits `_GUID<Parent>` (async server lookup) + the parent compose spec',
+			() =>
+			{
+				const tmpLineItem = libStrategy.compile(CONFIG, { Catalog: CATALOG, SchemaSizes: SIZES }).Strategies.LineItem;
+				const tmpProjectJoin = tmpLineItem.Joins.find((j) => j.ParentEntity === 'Project');
+				Expect(tmpProjectJoin.FieldName).to.equal('_GUIDProject');
+				Expect(tmpProjectJoin.Compose.segments).to.deep.equal([ { abbrev: 'P', valueTemplate: '{~D:Record.ProjectCode~}' } ]);
+				Expect(tmpProjectJoin.Compose.maxLength).to.equal(64);
+			}
+		);
+		test
+		(
+			'join field-name selection covers all modes',
+			() =>
+			{
+				Expect(libStrategy.joinFieldName('Project', 'prefixed', false)).to.equal('GUIDProject');   // same-upload, sync
+				Expect(libStrategy.joinFieldName('Project', 'prefixed', true)).to.equal('_GUIDProject');    // cross-session, async
+				Expect(libStrategy.joinFieldName('Project', 'raw', false)).to.equal('_GUIDProject');        // raw meadow GUID
+				Expect(libStrategy.joinFieldName('Project', 'rawid', false)).to.equal('IDProject');         // raw id
+			}
+		);
+		test
+		(
+			'a same-upload prefixed join emits sync `GUID<Parent>`',
+			() =>
+			{
+				const tmpConfig = { Prefix: 'UI', Entities: { LineItem: { OwnKeyColumn: 'LineId', Joins: [ { ParentEntity: 'Project', Mode: 'prefixed', KeyColumn: 'ProjectCode', CrossSession: false } ] } } };
+				const tmpJoin = libStrategy.compile(tmpConfig, { Catalog: CATALOG, SchemaSizes: SIZES }).Strategies.LineItem.Joins[0];
+				Expect(tmpJoin.FieldName).to.equal('GUIDProject');
+			}
+		);
+		test
+		(
+			'raw + rawid joins resolve a source column directly',
+			() =>
+			{
+				const tmpConfig =
+				{
+					Entities:
+					{
+						LineItem:
+						{
+							OwnKeyColumn: 'LineId',
+							Joins:
+							[
+								{ ParentEntity: 'Project', Mode: 'raw', GUIDColumn: 'ProjectGUID' },
+								{ ParentEntity: 'Contract', Mode: 'rawid', IDColumn: 'ContractID' },
+							],
+						},
+					},
+				};
+				const tmpJoins = libStrategy.compile(tmpConfig, { Catalog: CATALOG, SchemaSizes: SIZES }).Strategies.LineItem.Joins;
+				Expect(tmpJoins[0]).to.deep.include({ FieldName: '_GUIDProject', Mode: 'raw', ValueTemplate: '{~D:Record.ProjectGUID~}' });
+				Expect(tmpJoins[1]).to.deep.include({ FieldName: 'IDContract', Mode: 'rawid', ValueTemplate: '{~D:Record.ContractID~}' });
+			}
+		);
+		test
+		(
+			'warns (does not throw) when an entity has no own-key column — the dup-on-reimport fallback',
+			() =>
+			{
+				const tmpResult = libStrategy.compile({ Entities: { Widget: { Mode: 'prefixed' } } }, { Catalog: {}, SchemaSizes: {} });
+				Expect(tmpResult.Warnings.join(' ')).to.match(/no own-key column/i);
+				// still produces a usable strategy (derived abbreviation, unbounded length)
+				Expect(tmpResult.Strategies.Widget.Own.FieldName).to.equal('GUIDWidget');
+				Expect(tmpResult.Strategies.Widget.Own.Compose.segments[0].abbrev).to.equal('WID');
+			}
+		);
+	}
+);

package/test/Meadow-Integration-GUIDTruncation_test.js

@@ -0,0 +1,71 @@
+/*
+	Unit tests for the adapter's opt-in GUIDTruncationStrategy (the marshaling-path length safety).
+
+	"substring" (default) preserves the external GUID and truncates the prefix — existing behavior.
+	"hash" keeps the prefix and deterministically hashes the external GUID to fit — stable across runs.
+*/
+
+const Chai = require('chai');
+const Expect = Chai.expect;
+
+const libFable = require('fable');
+
+const libEngine = require('../source/Meadow-Integration-Engine.js');
+
+const newAdapter = (pOptions) =>
+{
+	const tmpFable = new libFable({ Product: 'GUIDTruncTest', LogStreams: [ { streamtype: 'console', level: 'error' } ] });
+	return new libEngine.MeadowIntegrationAdapter(tmpFable, Object.assign(
+		{
+			Entity: 'Specification',
+			AllowGUIDTruncation: true,
+			GUIDMaxLength: 36,
+			AdapterSetGUIDMarshalPrefix: 'HLICLI',
+			EntityGUIDMarshalPrefix: 'E-Specification',
+		}, pOptions || {}), 'GUIDTruncTest');
+};
+
+const EXTERNAL = 'SpecSet-2026-001278';   // 19 chars; prefix + this exceeds 36, exercising truncation
+
+suite
+(
+	'Meadow Integration — adapter GUID truncation strategy',
+	() =>
+	{
+		test
+		(
+			'substring (default) keeps the external GUID whole + truncates the prefix',
+			() =>
+			{
+				const tmpAdapter = newAdapter({ GUIDTruncationStrategy: 'substring' });
+				const tmpGUID = tmpAdapter.generateMeadowGUIDFromExternalGUID(EXTERNAL);
+				Expect(tmpGUID.length, tmpGUID).to.be.at.most(36);
+				Expect(tmpGUID.endsWith(EXTERNAL), 'external GUID preserved at the tail').to.equal(true);
+			}
+		);
+		test
+		(
+			'hash keeps the prefix whole + hashes the external GUID to fit, deterministically',
+			() =>
+			{
+				const tmpAdapter = newAdapter({ GUIDTruncationStrategy: 'hash' });
+				const tmpGUID = tmpAdapter.generateMeadowGUIDFromExternalGUID(EXTERNAL);
+				Expect(tmpGUID.length, tmpGUID).to.be.at.most(36);
+				Expect(tmpGUID.indexOf(tmpAdapter.GUIDPrefix), 'prefix preserved at the head').to.equal(0);
+				Expect(tmpGUID).to.not.equal(EXTERNAL);
+				// deterministic across adapter instances
+				Expect(newAdapter({ GUIDTruncationStrategy: 'hash' }).generateMeadowGUIDFromExternalGUID(EXTERNAL)).to.equal(tmpGUID);
+			}
+		);
+		test
+		(
+			'a short GUID is unchanged regardless of strategy',
+			() =>
+			{
+				const tmpShort = 'ABC';
+				Expect(newAdapter({ GUIDTruncationStrategy: 'hash' }).generateMeadowGUIDFromExternalGUID(tmpShort))
+					.to.equal(newAdapter({ GUIDTruncationStrategy: 'substring' }).generateMeadowGUIDFromExternalGUID(tmpShort));
+			}
+		);
+	}
+);