pict-section-dataimport 1.0.1 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pict-section-dataimport",
-	"version": "1.0.1",
+	"version": "1.1.1",
 	"description": "Embeddable, configurable data-import wizard for Pict apps — upload a CSV/TSV/Excel/fixed-width file, validate + detect its schema, map columns to a Meadow (or host-config) entity schema, generate comprehensions, and push them (records via the browser EntityProvider, or one POST to a Comprehension endpoint). Composes pict-section-upload + pict-section-accordion + pict-section-form, reusing meadow-integration's browser-safe transform/push engine.",
 	"main": "source/Pict-Section-DataImport.js",
 	"files": [
@@ -44,7 +44,7 @@
 		"pict-view": "^1.0.68"
 	},
 	"peerDependencies": {
-		"meadow-integration": ">=1.0.43",
+		"meadow-integration": ">=1.1.1",
 		"pict": ">=1.0.300",
 		"pict-section-accordion": ">=1.0.0",
 		"pict-section-form": ">=1.0.0",

package/source/Pict-Section-DataImport-CSS.js

@@ -70,4 +70,19 @@ module.exports = /*css*/`
 .psd-progress { height: 8px; border-radius: var(--theme-radius-pill, 999px); overflow: hidden; background: var(--theme-color-background-tertiary, #e9edf2); }
 .psd-progress-fill { height: 100%; background: var(--theme-color-brand-primary, #156dd1); transition: width var(--theme-duration-normal, 0.2s) ease; }
 .psd-row-actions { display: flex; gap: 0.5rem; flex-wrap: wrap; align-items: center; }
+
+.psd-guid { display: flex; flex-direction: column; gap: 0.4rem; margin: 0.3rem 0 0.6rem; padding: 0.5rem 0.65rem;
+	border: 1px solid var(--theme-color-border-light, #e6e9ee); border-radius: var(--theme-radius-md, 6px); background: var(--theme-color-background-secondary, #f7f9fb); }
+.psd-guid-line { display: flex; align-items: center; gap: 0.4rem; flex-wrap: wrap; }
+.psd-guid-label { font-size: var(--theme-typography-size-sm, 0.82rem); font-weight: 600; color: var(--theme-color-text-primary, #1f2733); }
+.psd-guid-sub { font-size: var(--theme-typography-size-sm, 0.8rem); color: var(--theme-color-text-secondary, #6b7686); }
+.psd-guid-parent { display: flex; align-items: center; gap: 0.4rem; flex-wrap: wrap; padding-left: 0.5rem; }
+.psd-guid-rm { padding: 0 0.45rem; line-height: 1.4; }
+.psd-guid-add { padding-left: 0.5rem; }
+.psd-guid-owncol { display: inline-flex; align-items: center; gap: 0.15rem; }
+.psd-guid-owadd { max-width: 8rem; opacity: 0.85; }
+.psd-guid-tpl { min-width: 16rem; font-family: var(--theme-typography-family-mono, monospace); }
+.psd-guid-own-fx { padding: 0 0.5rem; font-size: var(--theme-typography-size-sm, 0.78rem); }
+.psd-guid-preview { font-size: var(--theme-typography-size-sm, 0.82rem); color: var(--theme-color-text-secondary, #6b7686); }
+.psd-guid-warn { display: flex; align-items: center; gap: 0.4rem; font-size: var(--theme-typography-size-sm, 0.82rem); color: var(--theme-color-status-warning, #b8860b); }
 `;

package/source/providers/Pict-Provider-DataImport.js

@@ -70,6 +70,15 @@ class PictProviderDataImport extends libPictProvider
 			pConfig || {},
 			{ WizardHash: pWizardHash });
 
+		// When a context-aware GUID strategy is active the composer owns the ENTIRE GUID (the desired
+		// `UI_..._...` format is not the engine's prefix-marshal format), so the marshaling prefixes must
+		// be empty — otherwise the push would double-prefix the already-composed GUID.
+		if (tmpConfig.GUIDStrategy)
+		{
+			tmpConfig.GUIDPrefix = '';
+			tmpConfig.EntityGUIDPrefix = '';
+		}
+
 		// Resolve the seams onto the config — the wizard view reads these directly.
 		tmpConfig.ResolvedParsers = this._resolveParsers(tmpConfig);
 		tmpConfig.ResolvedSchemaProvider = this._resolveSchemaProvider(tmpConfig);

package/source/services/DataImport-GuidStrategyApply.js

@@ -0,0 +1,168 @@
+// DataImport-GuidStrategyApply — wires the meadow-integration GUID strategy compiler into a wizard
+// mapping. Given the per-entity strategy config + the host context catalog + the resolved schema (for
+// the GUID column widths), it compiles the strategy and attaches it to each entity mapping, then strips
+// the GUID / FK fields the strategy now owns out of each entity's data Mappings.
+//
+// Thin glue over meadow-integration's engine (the composer + compiler live there, reused by the CLI +
+// server endpoints too); this only knows the dataimport mapping shape. Pure + unit-testable.
+
+const libEngine = require('meadow-integration/source/Meadow-Integration-Engine.js');
+
+/**
+ * Build { <entity>: <GUID column width> } from a resolved dataimport schema (Entities[].Fields[].Size,
+ * IsGUID), so the composer can keep each entity's GUID inside its column.
+ * @param {Record<string, any>} pSchema
+ * @returns {Record<string, number>}
+ */
+function schemaSizes(pSchema)
+{
+	const tmpSizes = {};
+	((pSchema && pSchema.Entities) || []).forEach((pEntity) =>
+	{
+		const tmpGUIDField = (pEntity.Fields || []).find((pField) => pField.IsGUID);
+		if (tmpGUIDField && (Number(tmpGUIDField.Size) > 0))
+		{
+			tmpSizes[pEntity.Entity] = Number(tmpGUIDField.Size);
+		}
+	});
+	return tmpSizes;
+}
+
+/**
+ * Compile + attach GUID strategies to a mapping.
+ * @param {Record<string, any>} pMapping - { Order, Entities:{ <name>: <entityMapping> } }
+ * @param {Record<string, any>} pStrategyConfig - { Prefix?, Entities:{ <name>: <entityConfig> } }
+ * @param {Record<string, any>} pCatalog - { <entity>:{ Abbrev, KeyField } }
+ * @param {Record<string, any>} pSchema - resolved dataimport schema (for GUID column sizes)
+ * @returns {{Mapping:Record<string, any>, Warnings:Array<string>}}
+ */
+function applyStrategy(pMapping, pStrategyConfig, pCatalog, pSchema)
+{
+	const tmpCompiled = libEngine.compileGUIDStrategy(pStrategyConfig || {}, { Catalog: pCatalog || {}, SchemaSizes: schemaSizes(pSchema) });
+	const tmpEntities = (pMapping && pMapping.Entities) || {};
+
+	Object.keys(tmpEntities).forEach((pEntityName) =>
+	{
+		const tmpStrategy = tmpCompiled.Strategies[pEntityName];
+		if (!tmpStrategy) { return; }
+		const tmpEntityMapping = tmpEntities[pEntityName];
+		tmpEntityMapping.GUIDStrategy = tmpStrategy;
+
+		// Strip the fields the strategy now stamps (own GUID + every FK field) out of the data Mappings,
+		// so they aren't double-written by the flat-template Mappings loop.
+		const tmpStrategyFields = {};
+		if (tmpStrategy.Own && tmpStrategy.Own.FieldName) { tmpStrategyFields[tmpStrategy.Own.FieldName] = true; }
+		(tmpStrategy.Joins || []).forEach((pJoin) => { if (pJoin.FieldName) { tmpStrategyFields[pJoin.FieldName] = true; } });
+		if (tmpEntityMapping.Mappings)
+		{
+			Object.keys(tmpEntityMapping.Mappings).forEach((pField) =>
+			{
+				if (tmpStrategyFields[pField]) { delete tmpEntityMapping.Mappings[pField]; }
+			});
+		}
+	});
+
+	return { Mapping: pMapping, Warnings: tmpCompiled.Warnings || [] };
+}
+
+/**
+ * Build a meadow-integration strategy config from the simplified per-entity UI model the wizard panel
+ * edits. Each "parent link" becomes BOTH a context segment in the entity's own GUID (when prefixed) AND
+ * a foreign-key join — which is the user's mental model (`UI_C10_P01278_LI8675309` embeds Contract +
+ * Project context and the Line Item carries GUIDContract / GUIDProject FKs).
+ * @param {Record<string, any>} pUIEntities - { <entity>: { Mode, OwnKeyColumn, Parents:[{Entity,KeyColumn,Mode,CrossSession}] } }
+ * @param {string} pPrefix - the GUID prefix (e.g. 'UI')
+ * @returns {{Prefix:string, Entities:Record<string, any>}}
+ */
+function buildStrategyConfig(pUIEntities, pPrefix)
+{
+	const tmpEntities = {};
+	Object.keys(pUIEntities || {}).forEach((pEntityName) =>
+	{
+		const tmpUI = pUIEntities[pEntityName] || {};
+		const tmpParents = Array.isArray(tmpUI.Parents) ? tmpUI.Parents : [];
+		// Only prefixed parents contribute a context segment to the own GUID (raw / rawid carry an external
+		// GUID / ID that has no composable key for the prefix).
+		const tmpContextEntities = [];
+		const tmpContextKeyColumns = {};
+		tmpParents.forEach((pParent) =>
+		{
+			if ((pParent.Mode || 'prefixed') === 'prefixed' && pParent.Entity)
+			{
+				tmpContextEntities.push(pParent.Entity);
+				tmpContextKeyColumns[pParent.Entity] = pParent.KeyColumn;
+			}
+		});
+		tmpEntities[pEntityName] = {
+			Mode: tmpUI.Mode || 'prefixed',
+			OwnKeyColumn: tmpUI.OwnKeyColumn,
+			// Combinatorial own key: several columns concatenated, or a user-typed pict template. The engine's
+			// ownValueTemplate() prefers OwnKeyTemplate, then OwnKeyColumns, then the single OwnKeyColumn.
+			OwnKeyColumns: Array.isArray(tmpUI.OwnKeyColumns) ? tmpUI.OwnKeyColumns : undefined,
+			OwnKeyTemplate: tmpUI.OwnKeyTemplate,
+			OwnGUIDColumn: tmpUI.OwnGUIDColumn,
+			ContextEntities: tmpContextEntities,
+			ContextKeyColumns: tmpContextKeyColumns,
+			Joins: tmpParents.filter((pParent) => !!pParent.Entity).map((pParent) =>
+			{
+				const tmpMode = pParent.Mode || 'prefixed';
+				return {
+					ParentEntity: pParent.Entity,
+					Mode: tmpMode,
+					KeyColumn: pParent.KeyColumn,
+					GUIDColumn: pParent.KeyColumn,
+					IDColumn: pParent.KeyColumn,
+					CrossSession: (pParent.CrossSession !== false),
+				};
+			}),
+		};
+	});
+	return { Prefix: (pPrefix !== undefined) ? pPrefix : 'UI', Entities: tmpEntities };
+}
+
+/**
+ * Preview the GUID a compose spec would produce for a sample row (simple `{~D:Record.X~}` resolution, no
+ * fable needed) — used by the wizard panel to show a live example as the user configures the strategy.
+ * @param {Record<string, any>} pComposeSpec @param {Record<string, any>} pSampleRow
+ * @returns {string}
+ */
+function previewGUID(pComposeSpec, pSampleRow)
+{
+	if (!pComposeSpec || !Array.isArray(pComposeSpec.segments)) { return ''; }
+	const tmpRow = pSampleRow || {};
+	const tmpSegments = pComposeSpec.segments.map((pSegment) =>
+	{
+		// Resolve EVERY `{~D:Record.<col>~}` tag in the segment (a segment can now be multiple columns or a
+		// typed template, not just one column) — a lightweight parseTemplate stand-in for the live preview.
+		// Any non-tag literal text in the template is kept verbatim.
+		const tmpValue = String(pSegment.valueTemplate || '').replace(/\{~D:Record\.([^~}]+)~\}/g, (pFull, pColumn) =>
+		{
+			const tmpCell = tmpRow[pColumn];
+			return (tmpCell !== undefined && tmpCell !== null) ? String(tmpCell) : '';
+		});
+		return { abbrev: pSegment.abbrev, value: tmpValue };
+	});
+	return libEngine.composeGUID({ prefix: pComposeSpec.prefix, separator: pComposeSpec.separator, maxLength: pComposeSpec.maxLength, hashLength: pComposeSpec.hashLength, segments: tmpSegments });
+}
+
+/**
+ * One-call preview for the wizard panel: build the config from the UI model, compile it, and preview the
+ * given entity's OWN GUID on a sample row.
+ * @returns {string}
+ */
+function previewEntityGUID(pUIEntities, pPrefix, pCatalog, pSchema, pEntityName, pSampleRow)
+{
+	const tmpConfig = buildStrategyConfig(pUIEntities, pPrefix);
+	const tmpCompiled = libEngine.compileGUIDStrategy(tmpConfig, { Catalog: pCatalog || {}, SchemaSizes: schemaSizes(pSchema) });
+	const tmpStrategy = tmpCompiled.Strategies[pEntityName];
+	if (!tmpStrategy || !tmpStrategy.Own || !tmpStrategy.Own.Compose) { return ''; }
+	return previewGUID(tmpStrategy.Own.Compose, pSampleRow);
+}
+
+module.exports = {
+	applyStrategy,
+	schemaSizes,
+	buildStrategyConfig,
+	previewGUID,
+	previewEntityGUID,
+};

package/source/views/PictView-DataImport-Wizard.js

@@ -1,5 +1,6 @@
 const libPictView = require('pict-view');
 const libSession = require('../services/DataImport-Session.js');
+const libStrategyApply = require('../services/DataImport-GuidStrategyApply.js');
 
 // Required sibling controls (peers). The wizard registers their providers if the host hasn't.
 const libPictSectionAccordion = require('pict-section-accordion');
@@ -93,10 +94,35 @@ const _DEFAULT_CONFIGURATION =
 			Hash: 'DI-Map-Entity',
 			Template: /*html*/`
 <div class="psd-entity">
-	<div class="psd-entity-head"><span class="psd-entity-name">{~D:Record.Entity~}</span><span class="psd-entity-count">GUID: <span class="psd-mono">{~D:Record.GUIDTemplate~}</span></span></div>
+	<div class="psd-entity-head"><span class="psd-entity-name">{~D:Record.Entity~}</span>{~TS:DI-Map-GUID-Legacy:Record.LegacyGUIDSlot~}</div>
+	{~TS:DI-GUID-Panel:Record.StrategySlot~}
 	{~TS:DI-Map-Row:Record.Fields~}
 </div>`
 		},
+		{ Hash: 'DI-Map-GUID-Legacy', Template: /*html*/`<span class="psd-entity-count">GUID: <span class="psd-mono">{~D:Record.GUIDTemplate~}</span></span>` },
+		{
+			Hash: 'DI-GUID-Panel',
+			Template: /*html*/`
+<div class="psd-guid">
+	<div class="psd-guid-line"><span class="psd-guid-label">Identifier</span><select class="psd-select" onchange="_Pict.views['{~D:Record.WizardHash~}'].setStrategyMode('{~D:Record.Entity~}',this.value)">{~TS:DI-Opt:Record.ModeOptions~}</select>{~TS:DI-GUID-Own:Record.OwnKeySlot~}</div>
+	{~TS:DI-GUID-Parent:Record.Parents~}
+	{~TS:DI-GUID-AddParent:Record.AddParentSlot~}
+	{~TS:DI-GUID-Preview:Record.PreviewSlot~}
+	{~TS:DI-GUID-Warn:Record.Warnings~}
+</div>`
+		},
+		{ Hash: 'DI-GUID-Own', Template: /*html*/`<span class="psd-guid-sub">keyed by</span>{~TS:DI-GUID-OwnCol:Record.ColumnItems~}{~TS:DI-GUID-OwnAdd:Record.AddColumnSlot~}{~TS:DI-GUID-OwnTpl:Record.TemplateSlot~}<button type="button" class="psd-btn psd-btn-ghost psd-guid-own-fx" onclick="_Pict.views['{~D:Record.WizardHash~}'].toggleStrategyOwnMode('{~D:Record.Entity~}')" title="Switch between columns and a typed template">{~D:Record.ToggleLabel~}</button>` },
+		{ Hash: 'DI-GUID-OwnCol', Template: /*html*/`<span class="psd-guid-owncol"><select class="psd-select" onchange="_Pict.views['{~D:Record.WizardHash~}'].setStrategyOwnKeyAt('{~D:Record.Entity~}',{~D:Record.Index~},this.value)">{~TS:DI-Opt:Record.Options~}</select>{~TS:DI-GUID-OwnColRm:Record.RemoveSlot~}</span>` },
+		{ Hash: 'DI-GUID-OwnColRm', Template: /*html*/`<button type="button" class="psd-btn psd-btn-ghost psd-guid-rm" onclick="_Pict.views['{~D:Record.WizardHash~}'].removeStrategyOwnKey('{~D:Record.Entity~}',{~D:Record.Index~})" title="Remove column">&times;</button>` },
+		{ Hash: 'DI-GUID-OwnAdd', Template: /*html*/`<select class="psd-select psd-guid-owadd" onchange="if(this.value){_Pict.views['{~D:Record.WizardHash~}'].addStrategyOwnKey('{~D:Record.Entity~}',this.value);this.value='';}">{~TS:DI-Opt:Record.Options~}</select>` },
+		{ Hash: 'DI-GUID-OwnTpl', Template: /*html*/`<input type="text" class="psd-input psd-guid-tpl" placeholder="{~D:Record.Placeholder~}" value="{~D:Record.Template~}" onchange="_Pict.views['{~D:Record.WizardHash~}'].setStrategyOwnKeyTemplate('{~D:Record.Entity~}',this.value)" />` },
+		{
+			Hash: 'DI-GUID-Parent',
+			Template: /*html*/`<div class="psd-guid-parent"><span class="psd-guid-sub">related to</span><select class="psd-select" onchange="_Pict.views['{~D:Record.WizardHash~}'].setParentEntity('{~D:Record.Entity~}',{~D:Record.Index~},this.value)">{~TS:DI-Opt:Record.EntityOptions~}</select><span class="psd-guid-sub">via</span><select class="psd-select" onchange="_Pict.views['{~D:Record.WizardHash~}'].setParentKey('{~D:Record.Entity~}',{~D:Record.Index~},this.value)">{~TS:DI-Opt:Record.KeyOptions~}</select><select class="psd-select" onchange="_Pict.views['{~D:Record.WizardHash~}'].setParentMode('{~D:Record.Entity~}',{~D:Record.Index~},this.value)">{~TS:DI-Opt:Record.ModeOptions~}</select><button type="button" class="psd-btn psd-btn-ghost psd-guid-rm" onclick="_Pict.views['{~D:Record.WizardHash~}'].removeStrategyParent('{~D:Record.Entity~}',{~D:Record.Index~})" title="Remove">&times;</button></div>`
+		},
+		{ Hash: 'DI-GUID-AddParent', Template: /*html*/`<div class="psd-guid-add"><select class="psd-select" onchange="if(this.value){_Pict.views['{~D:Record.WizardHash~}'].addStrategyParent('{~D:Record.Entity~}',this.value);this.value='';}">{~TS:DI-Opt:Record.Options~}</select></div>` },
+		{ Hash: 'DI-GUID-Preview', Template: /*html*/`<div class="psd-guid-preview">Example: <span class="psd-mono">{~D:Record.Preview~}</span></div>` },
+		{ Hash: 'DI-GUID-Warn', Template: /*html*/`<div class="psd-guid-warn">{~I:Warning~} <span>{~D:Record.Message~}</span></div>` },
 		{
 			Hash: 'DI-Map-Row',
 			Template: /*html*/`<div class="psd-map-row"><span class="psd-map-field">{~D:Record.Name~}{~NE:Record.Required^ <span class="psd-map-required">*</span>~}</span><select class="psd-select" onchange="_Pict.views['{~D:Record.WizardHash~}'].setMappingBinding('{~D:Record.Entity~}','{~D:Record.Name~}',this.value)">{~TS:DI-Opt:Record.Options~}</select></div>`
@@ -415,12 +441,188 @@ class PictViewDataImportWizard extends libPictView
 			if (typeof this.options.OnSchemaLoaded === 'function') { try { this.options.OnSchemaLoaded(this._schema); } catch (pError) { /* host */ } }
 			// Seed the mapping from the schema if the host gave no default mapping yet.
 			if (!tmpSession.Mapping.Order || tmpSession.Mapping.Order.length === 0) { tmpSession.Mapping = this._autoBuildMapping(this._schema); }
+			this._seedStrategyUI();
+			this._applyGUIDStrategy();
 			this._persist();
 			this._renderStepBody('mapping');
 			this._refreshAccordionChrome();
 		}).catch((pError) => { this._reportError(pError); });
 	}
 
+	/** Is the context-aware GUID strategy panel + composition enabled for this wizard? */
+	_strategyActive()
+	{
+		return !!this.options.GUIDStrategy;
+	}
+
+	/** Seed the editable per-entity GUID strategy UI model (host default, else prefixed + first column). */
+	_seedStrategyUI()
+	{
+		if (!this._strategyActive()) { return; }
+		const tmpSession = this._session();
+		tmpSession.GUIDStrategyUI = tmpSession.GUIDStrategyUI || {};
+		const tmpDefaults = this.options.GUIDStrategyDefault || {};
+		const tmpFirstColumn = ((tmpSession.DetectedColumns || [])[0] || {}).SourceName || '';
+		(tmpSession.Mapping.Order || []).forEach((pEntityName) =>
+		{
+			if (!tmpSession.GUIDStrategyUI[pEntityName])
+			{
+				tmpSession.GUIDStrategyUI[pEntityName] = tmpDefaults[pEntityName]
+					? JSON.parse(JSON.stringify(tmpDefaults[pEntityName]))
+					: { Mode: 'prefixed', OwnKeyColumn: tmpFirstColumn, OwnKeyColumns: tmpFirstColumn ? [ tmpFirstColumn ] : [], OwnKeyMode: 'columns', OwnKeyTemplate: '', Parents: [] };
+			}
+		});
+	}
+
+	/**
+	 * Compile the editable GUID strategy UI model (meadow-integration) against the schema's GUID column
+	 * sizes + attach it to each entity mapping. The transform then composes stable, length-safe GUIDs +
+	 * foreign-key fields instead of the flat GUIDTemplate.
+	 */
+	_applyGUIDStrategy()
+	{
+		if (!this._strategyActive()) { return; }
+		const tmpSession = this._session();
+		const tmpConfig = libStrategyApply.buildStrategyConfig(tmpSession.GUIDStrategyUI || {}, this.options.GUIDStrategyPrefix || 'UI');
+		const tmpResult = libStrategyApply.applyStrategy(tmpSession.Mapping, tmpConfig, this.options.ContextEntityCatalog, this._schema);
+		this._strategyWarnings = tmpResult.Warnings || [];
+	}
+
+	/** Mutable per-entity UI model accessor (creates a default if absent). */
+	_strategyUIEntity(pEntity)
+	{
+		const tmpSession = this._session();
+		tmpSession.GUIDStrategyUI = tmpSession.GUIDStrategyUI || {};
+		if (!tmpSession.GUIDStrategyUI[pEntity]) { tmpSession.GUIDStrategyUI[pEntity] = { Mode: 'prefixed', OwnKeyColumn: '', OwnKeyColumns: [], OwnKeyMode: 'columns', OwnKeyTemplate: '', Parents: [] }; }
+		return tmpSession.GUIDStrategyUI[pEntity];
+	}
+
+	/** Recompile + re-render after any strategy panel edit. */
+	_afterStrategyEdit()
+	{
+		this._applyGUIDStrategy();
+		this._persist();
+		this._renderStepBody('mapping');
+	}
+
+	setStrategyMode(pEntity, pMode) { this._strategyUIEntity(pEntity).Mode = pMode; this._afterStrategyEdit(); }
+
+	// Combinatorial own key (#1): the entity's GUID can be keyed by ONE column, SEVERAL columns concatenated,
+	// or a user-typed pict template. OwnKeyColumns is the column list; OwnKeyTemplate (template mode) wins in
+	// the engine's ownValueTemplate(). OwnKeyColumn is kept in sync for backward compatibility.
+	/** The own-key column list (migrating a legacy single OwnKeyColumn on first access). */
+	_ownColumns(pEntity)
+	{
+		const tmpEntity = this._strategyUIEntity(pEntity);
+		if (!Array.isArray(tmpEntity.OwnKeyColumns))
+		{
+			tmpEntity.OwnKeyColumns = tmpEntity.OwnKeyColumn ? [ tmpEntity.OwnKeyColumn ] : [];
+		}
+		return tmpEntity.OwnKeyColumns;
+	}
+	_syncOwnSingle(pEntity) { const tmpEntity = this._strategyUIEntity(pEntity); tmpEntity.OwnKeyColumn = this._ownColumns(pEntity)[0] || ''; }
+	setStrategyOwnKey(pEntity, pColumn) { const tmpEntity = this._strategyUIEntity(pEntity); tmpEntity.OwnKeyColumns = pColumn ? [ pColumn ] : []; tmpEntity.OwnKeyColumn = pColumn; this._afterStrategyEdit(); }
+	setStrategyOwnKeyAt(pEntity, pIndex, pColumn)
+	{
+		const tmpColumns = this._ownColumns(pEntity);
+		if (pColumn) { tmpColumns[Number(pIndex)] = pColumn; } else { tmpColumns.splice(Number(pIndex), 1); }
+		this._syncOwnSingle(pEntity); this._afterStrategyEdit();
+	}
+	addStrategyOwnKey(pEntity, pColumn) { this._ownColumns(pEntity).push(pColumn); this._syncOwnSingle(pEntity); this._afterStrategyEdit(); }
+	removeStrategyOwnKey(pEntity, pIndex) { this._ownColumns(pEntity).splice(Number(pIndex), 1); this._syncOwnSingle(pEntity); this._afterStrategyEdit(); }
+	setStrategyOwnKeyTemplate(pEntity, pTemplate) { this._strategyUIEntity(pEntity).OwnKeyTemplate = pTemplate; this._afterStrategyEdit(); }
+	toggleStrategyOwnMode(pEntity)
+	{
+		const tmpEntity = this._strategyUIEntity(pEntity);
+		if (tmpEntity.OwnKeyMode === 'template')
+		{
+			tmpEntity.OwnKeyMode = 'columns';
+			tmpEntity.OwnKeyTemplate = '';   // columns win once template is cleared
+		}
+		else
+		{
+			tmpEntity.OwnKeyMode = 'template';
+			if (!tmpEntity.OwnKeyTemplate)
+			{
+				tmpEntity.OwnKeyTemplate = this._ownColumns(pEntity).map((pColumn) => `{~D:Record.${pColumn}~}`).join('');
+			}
+		}
+		this._afterStrategyEdit();
+	}
+	addStrategyParent(pEntity, pParentEntity)
+	{
+		const tmpEntity = this._strategyUIEntity(pEntity);
+		tmpEntity.Parents = tmpEntity.Parents || [];
+		tmpEntity.Parents.push({ Entity: pParentEntity, KeyColumn: '', Mode: 'prefixed', CrossSession: true });
+		this._afterStrategyEdit();
+	}
+	removeStrategyParent(pEntity, pIndex) { const tmpEntity = this._strategyUIEntity(pEntity); if (tmpEntity.Parents) { tmpEntity.Parents.splice(Number(pIndex), 1); } this._afterStrategyEdit(); }
+	setParentEntity(pEntity, pIndex, pParentEntity) { const tmpParent = (this._strategyUIEntity(pEntity).Parents || [])[Number(pIndex)]; if (tmpParent) { tmpParent.Entity = pParentEntity; } this._afterStrategyEdit(); }
+	setParentKey(pEntity, pIndex, pColumn) { const tmpParent = (this._strategyUIEntity(pEntity).Parents || [])[Number(pIndex)]; if (tmpParent) { tmpParent.KeyColumn = pColumn; } this._afterStrategyEdit(); }
+	setParentMode(pEntity, pIndex, pMode) { const tmpParent = (this._strategyUIEntity(pEntity).Parents || [])[Number(pIndex)]; if (tmpParent) { tmpParent.Mode = pMode; } this._afterStrategyEdit(); }
+
+	/** Build the strategy-panel render data for one entity (mode + own-key + parents + live preview). */
+	_strategyEntityState(pEntityName, pSourceNames)
+	{
+		const tmpSession = this._session();
+		const tmpUI = (tmpSession.GUIDStrategyUI || {})[pEntityName] || { Mode: 'prefixed', OwnKeyColumn: '', Parents: [] };
+		const tmpCatalog = this.options.ContextEntityCatalog || {};
+		const tmpCatalogEntities = Object.keys(tmpCatalog);
+		const tmpModeOptions = (pSelected) => [ { Value: 'prefixed', Label: 'Prefixed (auto)', Selected: pSelected === 'prefixed' }, { Value: 'raw', Label: 'Raw GUID', Selected: pSelected === 'raw' }, { Value: 'rawid', Label: 'Raw ID', Selected: pSelected === 'rawid' } ];
+		const tmpColumnOptions = (pSelected) => [ { Value: '', Label: '(column)', Selected: !pSelected } ].concat(pSourceNames.map((pName) => ({ Value: pName, Label: pName, Selected: pName === pSelected })));
+
+		// Own-key slot: only prefixed mode composes its own GUID. It can be one column, several columns
+		// (concatenated), or a typed template — see #1 combinatorial GUID.
+		let tmpOwnKeySlot = [];
+		if ((tmpUI.Mode || 'prefixed') === 'prefixed')
+		{
+			const tmpIsTemplate = (tmpUI.OwnKeyMode === 'template');
+			const tmpOwnCols = Array.isArray(tmpUI.OwnKeyColumns) ? tmpUI.OwnKeyColumns : (tmpUI.OwnKeyColumn ? [ tmpUI.OwnKeyColumn ] : []);
+			const tmpColumnItems = tmpIsTemplate ? [] : tmpOwnCols.map((pColumn, pIndex) => (
+				{
+					WizardHash: this.options.WizardHash, Entity: pEntityName, Index: pIndex,
+					Options: tmpColumnOptions(pColumn),
+					RemoveSlot: (tmpOwnCols.length > 1) ? [ { WizardHash: this.options.WizardHash, Entity: pEntityName, Index: pIndex } ] : [],
+				}));
+			const tmpUsedOwn = {};
+			tmpOwnCols.forEach((pColumn) => { if (pColumn) { tmpUsedOwn[pColumn] = true; } });
+			const tmpAddOwnOptions = [ { Value: '', Label: '+ column', Selected: true } ].concat(pSourceNames.filter((pName) => !tmpUsedOwn[pName]).map((pName) => ({ Value: pName, Label: pName, Selected: false })));
+			const tmpAddColumnSlot = (!tmpIsTemplate && (tmpAddOwnOptions.length > 1)) ? [ { WizardHash: this.options.WizardHash, Entity: pEntityName, Options: tmpAddOwnOptions } ] : [];
+			const tmpTemplateSlot = tmpIsTemplate ? [ { WizardHash: this.options.WizardHash, Entity: pEntityName, Template: tmpUI.OwnKeyTemplate || '', Placeholder: 'e.g. {~D:Record.District~}-{~D:Record.Code~}' } ] : [];
+			tmpOwnKeySlot = [ { WizardHash: this.options.WizardHash, Entity: pEntityName, ColumnItems: tmpColumnItems, AddColumnSlot: tmpAddColumnSlot, TemplateSlot: tmpTemplateSlot, ToggleLabel: tmpIsTemplate ? 'use columns' : 'ƒ template' } ];
+		}
+
+		const tmpParents = (tmpUI.Parents || []).map((pParent, pIndex) => (
+			{
+				WizardHash: this.options.WizardHash, Entity: pEntityName, Index: pIndex,
+				EntityOptions: [ { Value: '', Label: '(entity)', Selected: !pParent.Entity } ].concat(tmpCatalogEntities.map((pName) => ({ Value: pName, Label: pName, Selected: pName === pParent.Entity }))),
+				KeyOptions: tmpColumnOptions(pParent.KeyColumn),
+				ModeOptions: tmpModeOptions(pParent.Mode || 'prefixed'),
+			}));
+
+		const tmpUsed = {};
+		(tmpUI.Parents || []).forEach((pParent) => { if (pParent.Entity) { tmpUsed[pParent.Entity] = true; } });
+		const tmpAddOptions = [ { Value: '', Label: '+ Related entity', Selected: true } ].concat(tmpCatalogEntities.filter((pName) => !tmpUsed[pName] && (pName !== pEntityName)).map((pName) => ({ Value: pName, Label: pName, Selected: false })));
+		const tmpAddParentSlot = (tmpAddOptions.length > 1) ? [ { WizardHash: this.options.WizardHash, Entity: pEntityName, Options: tmpAddOptions } ] : [];
+
+		let tmpPreviewSlot = [];
+		try
+		{
+			const tmpPreview = libStrategyApply.previewEntityGUID(tmpSession.GUIDStrategyUI || {}, this.options.GUIDStrategyPrefix || 'UI', tmpCatalog, this._schema, pEntityName, (tmpSession.SampleRows || [])[0] || {});
+			if (tmpPreview) { tmpPreviewSlot = [ { Preview: tmpPreview } ]; }
+		}
+		catch (pError) { /* preview is best-effort */ }
+
+		const tmpWarnings = (this._strategyWarnings || []).filter((pWarning) => pWarning.indexOf(`"${pEntityName}"`) >= 0).map((pWarning) => ({ Message: pWarning }));
+
+		return {
+			WizardHash: this.options.WizardHash, Entity: pEntityName,
+			ModeOptions: tmpModeOptions(tmpUI.Mode || 'prefixed'),
+			OwnKeySlot: tmpOwnKeySlot, Parents: tmpParents, AddParentSlot: tmpAddParentSlot,
+			PreviewSlot: tmpPreviewSlot, Warnings: tmpWarnings,
+		};
+	}
+
 	/** Auto-build a starting mapping from the schema: same-named source columns + a GUID template guess. */
 	_autoBuildMapping(pSchema)
 	{
@@ -492,7 +694,11 @@ class PictViewDataImportWizard extends libPictView
 				const tmpRequired = tmpSchemaEntity ? !!(tmpSchemaEntity.Fields.find((pField) => pField.Name === pFieldName) || {}).Required : false;
 				return { WizardHash: this.options.WizardHash, Entity: pEntityName, Name: pFieldName, Required: tmpRequired, Options: tmpOptions };
 			});
-			return { Entity: pEntityName, GUIDTemplate: tmpEntityMapping.GUIDTemplate || '', Fields: tmpFields };
+			return {
+				Entity: pEntityName, GUIDTemplate: tmpEntityMapping.GUIDTemplate || '', Fields: tmpFields,
+				LegacyGUIDSlot: this._strategyActive() ? [] : [ { GUIDTemplate: tmpEntityMapping.GUIDTemplate || '' } ],
+				StrategySlot: this._strategyActive() ? [ this._strategyEntityState(pEntityName, tmpSourceNames) ] : [],
+			};
 		});
 
 		return { WizardHash: this.options.WizardHash, Entities: tmpEntities, RawJSON: JSON.stringify(tmpMapping, null, 2) };
@@ -591,6 +797,11 @@ class PictViewDataImportWizard extends libPictView
 			URLPrefix: this.options.URLPrefix,
 			ComprehensionPushURL: this.options.ComprehensionPushURL,
 			AllowGUIDTruncation: this.options.AllowGUIDTruncation,
+			// When the GUID strategy owns length, the composer has already sized every GUID to its real
+			// column width. Hand the push target those widths so a marshaling adapter doesn't re-truncate a
+			// composed (already-fitting) GUID down to a smaller default — which would clip the entity's own
+			// distinguishing segment and collide. Only sent for the strategy path (no behavior change otherwise).
+			GUIDColumnSizes: (this.options.GUIDStrategy && this._schema) ? libStrategyApply.schemaSizes(this._schema) : undefined,
 			onProgress: (pPushed, pTotal) => { tmpSession.Push.Progress = { Pushed: pPushed, Total: pTotal }; this._renderStepBody('push'); },
 		};
 		Promise.resolve(tmpTarget.push(tmpSession.Comprehension, tmpContext)).then((pResult) =>