@memberjunction/record-cloning-base 0.0.1-seed.1 → 6.2.0-edge.2

package/dist/CloneFieldMapper.js

@@ -0,0 +1,369 @@
+/**
+ * @file CloneFieldMapper.ts
+ * Pure 13-stage field mapping pipeline for record cloning.
+ * Maps: Excluded -> NotWritable -> DeniedRead/DeniedCreate -> Copy -> Reset -> Ownership
+ * -> ServerAllocated -> Rename -> Remap -> RemapJSON -> Override -> Prompt -> Rule.
+ * Rules run last, so a derived field (a user's Name from the prompted Email) sees the final
+ * values; request overrides and prompts are refused on fields a rule or reset governs.
+ * @see plans/record-cloning/README.md §7.1, §7.2, §13.1
+ */
+import { TryFindNextAvailableName } from './NameTemplate.js';
+import { ApplyJsonRemap } from './JsonRemapEngine.js';
+/** Whether the mapper renames this field on a clone: the name field, a field called Name, or a unique nvarchar. */
+export function IsRenameField(field) {
+    return !!field.IsNameField || field.Name.toLowerCase() === 'name' || (!!field.IsUnique && field.Type === 'nvarchar');
+}
+/**
+ * Runs the deterministic 12-stage field transformation pipeline on a record.
+ */
+export function MapFieldsForClone(ctx) {
+    const changes = [];
+    const values = {};
+    const excludedOrDenied = new Set();
+    const namingFailures = [];
+    let requiresIdentitySecondPass = false;
+    const keyMap = ctx.KeyMap || {};
+    const fieldRules = ctx.FieldRules || {};
+    const fls = ctx.FLS || {};
+    // A requested new parent for a hierarchy root is a request value like any other, so it passes
+    // the same UserEditable and governed-field checks (stage 11).
+    const reqOverrides = {
+        ...(ctx.RequestOverrides || {}),
+        ...(ctx.IsRoot && ctx.HierarchyParentField && ctx.NewParentKey !== undefined ? { [ctx.HierarchyParentField]: ctx.NewParentKey } : {}),
+    };
+    const promptedValues = ctx.PromptedValues || {};
+    // 1. Stage 1: Excluded (PKs, CreatedAt, UpdatedAt, SoftDelete, Configured Exclude)
+    for (const field of ctx.Fields) {
+        const srcVal = ctx.SourceRecord[field.Name];
+        if (field.IsPrimaryKey) {
+            excludedOrDenied.add(field.Name);
+            changes.push({
+                Field: field.Name,
+                Kind: 'Excluded',
+                OldValue: srcVal,
+                NewValue: undefined,
+                Reason: 'Primary key is not copied from source record.',
+            });
+            continue;
+        }
+        if (field.IsCreatedAtField || field.IsUpdatedAtField || field.IsSoftDeleteField) {
+            excludedOrDenied.add(field.Name);
+            changes.push({
+                Field: field.Name,
+                Kind: 'Excluded',
+                OldValue: srcVal,
+                NewValue: undefined,
+                Reason: 'Audit or soft-delete metadata field excluded.',
+            });
+            continue;
+        }
+        if (fieldRules.Exclude && fieldRules.Exclude.includes(field.Name)) {
+            excludedOrDenied.add(field.Name);
+            changes.push({
+                Field: field.Name,
+                Kind: 'Excluded',
+                OldValue: srcVal,
+                NewValue: undefined,
+                Reason: 'Configured field exclusion.',
+            });
+            continue;
+        }
+    }
+    // 2. Stage 2: NotWritable (Computed, virtual, persisted computed columns)
+    for (const field of ctx.Fields) {
+        if (excludedOrDenied.has(field.Name))
+            continue;
+        if (field.IsSPParameter && field.IsSPParameter(false) === false) {
+            excludedOrDenied.add(field.Name);
+            changes.push({
+                Field: field.Name,
+                Kind: 'NotWritable',
+                OldValue: ctx.SourceRecord[field.Name],
+                NewValue: undefined,
+                Reason: 'Field is not writable on insert (computed or virtual).',
+            });
+        }
+    }
+    // 3. Stage 3: DeniedRead / DeniedCreate (FLS evaluations)
+    for (const field of ctx.Fields) {
+        if (excludedOrDenied.has(field.Name))
+            continue;
+        if (fls.DeniedReadFields && fls.DeniedReadFields.includes(field.Name)) {
+            excludedOrDenied.add(field.Name);
+            changes.push({
+                Field: field.Name,
+                Kind: 'DeniedRead',
+                OldValue: undefined,
+                NewValue: undefined,
+                Reason: 'Field read permission denied by FLS.',
+            });
+            continue;
+        }
+        if (fls.DeniedCreateFields && fls.DeniedCreateFields.includes(field.Name)) {
+            excludedOrDenied.add(field.Name);
+            changes.push({
+                Field: field.Name,
+                Kind: 'DeniedCreate',
+                OldValue: ctx.SourceRecord[field.Name],
+                NewValue: undefined,
+                Reason: 'Field create permission denied by FLS.',
+            });
+            continue;
+        }
+    }
+    // 4. Stage 4: Copy (All eligible fields copied verbatim from source)
+    for (const field of ctx.Fields) {
+        if (excludedOrDenied.has(field.Name))
+            continue;
+        const srcVal = ctx.SourceRecord[field.Name];
+        values[field.Name] = srcVal;
+        changes.push({
+            Field: field.Name,
+            Kind: 'Copy',
+            OldValue: srcVal,
+            NewValue: srcVal,
+            Reason: 'Copied verbatim from source record.',
+        });
+    }
+    // 5. Stage 5: Reset (Configured literal resets)
+    if (fieldRules.Reset) {
+        for (const [fieldName, resetVal] of Object.entries(fieldRules.Reset)) {
+            if (excludedOrDenied.has(fieldName))
+                continue;
+            const oldVal = values[fieldName];
+            values[fieldName] = resetVal;
+            changes.push({
+                Field: fieldName,
+                Kind: 'Reset',
+                OldValue: oldVal,
+                NewValue: resetVal,
+                Reason: 'Configured field reset stamped.',
+            });
+        }
+    }
+    // 6. Stage 6: Ownership (Assign owner to current cloning user)
+    if (fieldRules.Ownership && ctx.CurrentUserId) {
+        for (const fieldName of fieldRules.Ownership) {
+            if (excludedOrDenied.has(fieldName))
+                continue;
+            const oldVal = values[fieldName];
+            values[fieldName] = ctx.CurrentUserId;
+            changes.push({
+                Field: fieldName,
+                Kind: 'Ownership',
+                OldValue: oldVal,
+                NewValue: ctx.CurrentUserId,
+                Reason: 'Ownership assigned to current user.',
+            });
+        }
+    }
+    // 7. Stage 7: ServerAllocated (Blanked so Save() hook mints)
+    if (fieldRules.ServerAllocated) {
+        for (const fieldName of fieldRules.ServerAllocated) {
+            if (excludedOrDenied.has(fieldName))
+                continue;
+            const oldVal = values[fieldName];
+            values[fieldName] = null;
+            changes.push({
+                Field: fieldName,
+                Kind: 'Reset',
+                OldValue: oldVal,
+                NewValue: null,
+                Reason: 'Server-allocated field blanked for Save() hook minting.',
+            });
+        }
+    }
+    // 8. Stage 8: Rename (Name fields or unique string fields)
+    for (const field of ctx.Fields) {
+        if (excludedOrDenied.has(field.Name))
+            continue;
+        if (IsRenameField(field) && values[field.Name] !== undefined && values[field.Name] !== null) {
+            const oldName = String(values[field.Name]);
+            const newName = TryFindNextAvailableName(oldName, ctx.NamingOptions?.ExistingNamesByField?.[field.Name] ?? ctx.NamingOptions?.ExistingNames ?? new Set(), {
+                Template: ctx.NamingOptions?.Template,
+                Strategy: ctx.NamingOptions?.Strategy,
+                MaxLength: field.MaxLength,
+                Context: {
+                    UserName: ctx.NamingOptions?.UserName,
+                },
+            });
+            if (newName === null) {
+                namingFailures.push(field.Name);
+                continue;
+            }
+            if (newName !== oldName) {
+                values[field.Name] = newName;
+                changes.push({
+                    Field: field.Name,
+                    Kind: 'Rename',
+                    OldValue: oldName,
+                    NewValue: newName,
+                    Reason: 'Name or unique string renamed to prevent collision.',
+                });
+            }
+        }
+    }
+    // 9. Stage 9: Remap (Foreign keys pointing to records in the clone set)
+    for (const field of ctx.Fields) {
+        if (excludedOrDenied.has(field.Name))
+            continue;
+        // Hierarchy parent field
+        if (ctx.HierarchyParentField && field.Name === ctx.HierarchyParentField) {
+            const oldParent = values[field.Name];
+            if (ctx.IsRoot) {
+                // The copy stays under the same parent; a requested move (NewParentKey, null = top
+                // level) is applied with the request overrides in stage 11.
+            }
+            else if (oldParent && String(oldParent) in keyMap) {
+                const newParent = keyMap[String(oldParent)];
+                values[field.Name] = newParent;
+                changes.push({
+                    Field: field.Name,
+                    Kind: 'Remap',
+                    OldValue: oldParent,
+                    NewValue: newParent,
+                    Reason: 'Hierarchy parent remapped to cloned ancestor.',
+                });
+            }
+            continue;
+        }
+        // Standard Foreign Key
+        if (field.RelatedEntityID || field.RelatedEntity) {
+            const oldFk = values[field.Name];
+            if (oldFk !== null && oldFk !== undefined) {
+                const targetEntity = field.RelatedEntity;
+                const qualifiedKey = targetEntity ? `${targetEntity}::${String(oldFk)}` : null;
+                const newFk = (qualifiedKey && qualifiedKey in keyMap)
+                    ? keyMap[qualifiedKey]
+                    : (String(oldFk) in keyMap ? keyMap[String(oldFk)] : undefined);
+                if (newFk !== undefined && newFk !== oldFk) {
+                    values[field.Name] = newFk;
+                    changes.push({
+                        Field: field.Name,
+                        Kind: 'Remap',
+                        OldValue: oldFk,
+                        NewValue: newFk,
+                        Reason: `Foreign key to '${targetEntity || 'entity'}' remapped to cloned target.`,
+                    });
+                }
+            }
+        }
+    }
+    // 10. Stage 10: RemapJSON (JSON columns with remap configurations)
+    if (fieldRules.JsonRemap) {
+        for (const remapSpec of fieldRules.JsonRemap) {
+            if (excludedOrDenied.has(remapSpec.Field))
+                continue;
+            const currentVal = values[remapSpec.Field];
+            if (typeof currentVal === 'string' || (currentVal && typeof currentVal === 'object')) {
+                const remapRes = ApplyJsonRemap(currentVal, {
+                    Rules: remapSpec.Rules,
+                    Preset: remapSpec.Preset,
+                    KeyMap: keyMap,
+                });
+                if (remapRes.Success) {
+                    values[remapSpec.Field] = remapRes.JsonString;
+                    changes.push({
+                        Field: remapSpec.Field,
+                        Kind: 'RemapJSON',
+                        OldValue: currentVal,
+                        NewValue: remapRes.JsonString,
+                        Reason: `JSON remapped: ${remapRes.PathsModified.length} paths touched (${remapRes.DropCount} dropped).`,
+                    });
+                }
+            }
+        }
+    }
+    // Fields the configuration decides; a request may not change them (that would undo a reset
+    // such as Type or IsActive on a user clone, or an ownership stamp).
+    const ignored = [];
+    const governed = new Set([
+        ...Object.keys(fieldRules.Reset ?? {}),
+        ...(fieldRules.Ownership ?? []),
+        ...(fieldRules.ServerAllocated ?? []),
+        ...(fieldRules.Rules?.Rules ?? []).map((r) => r.TargetField || r.Field || '').filter(Boolean),
+    ]);
+    const promptFor = new Set(fieldRules.PromptFor ?? []);
+    // 11. Stage 11: Override (Request-level field overrides)
+    for (const [fieldName, overrideVal] of Object.entries(reqOverrides)) {
+        if (excludedOrDenied.has(fieldName))
+            continue;
+        if (ctx.RequestFieldsEditable === false) {
+            ignored.push({ Field: fieldName, Kind: 'Override', Reason: "this entity's clone configuration doesn't allow field edits (UserEditable)" });
+            continue;
+        }
+        if (governed.has(fieldName)) {
+            ignored.push({ Field: fieldName, Kind: 'Override', Reason: 'the clone configuration sets this field' });
+            continue;
+        }
+        const oldVal = values[fieldName];
+        values[fieldName] = overrideVal;
+        changes.push({
+            Field: fieldName,
+            Kind: 'Override',
+            OldValue: oldVal,
+            NewValue: overrideVal,
+            Reason: 'Explicit request-level field override.',
+        });
+    }
+    // 12. Stage 12: Prompt (Prompted values, for the configured PromptFor fields only)
+    for (const [fieldName, promptVal] of Object.entries(promptedValues)) {
+        if (excludedOrDenied.has(fieldName))
+            continue;
+        if (!promptFor.has(fieldName)) {
+            ignored.push({ Field: fieldName, Kind: 'Prompt', Reason: 'the clone configuration does not prompt for this field' });
+            continue;
+        }
+        const oldVal = values[fieldName];
+        values[fieldName] = promptVal;
+        changes.push({
+            Field: fieldName,
+            Kind: 'Prompt',
+            OldValue: oldVal,
+            NewValue: promptVal,
+            Reason: 'User prompted value applied.',
+        });
+    }
+    // 13. Stage 13: Rules (Derived field rules, e.g. Name = Email)
+    if (fieldRules.Rules?.Rules) {
+        for (const rule of fieldRules.Rules.Rules) {
+            const targetField = rule.TargetField || rule.Field;
+            if (!targetField || excludedOrDenied.has(targetField))
+                continue;
+            let newVal;
+            if (rule.Source?.Kind === 'field' && rule.Source.Field) {
+                newVal = values[rule.Source.Field] ?? ctx.SourceRecord[rule.Source.Field];
+            }
+            else if (rule.Source?.Kind === 'static') {
+                newVal = rule.Source.Value;
+            }
+            if (newVal !== undefined) {
+                const oldVal = values[targetField];
+                values[targetField] = newVal;
+                changes.push({
+                    Field: targetField,
+                    Kind: 'Rule',
+                    OldValue: oldVal,
+                    NewValue: newVal,
+                    Reason: 'Derived via field rule.',
+                    // A value copied from an encrypted column is as secret as its source.
+                    ...(rule.Source?.Kind === 'field' && ctx.Fields.some((f) => f.Encrypted && f.Name === rule.Source?.Field) ? { Sensitive: true } : {}),
+                });
+            }
+        }
+    }
+    // Values of encrypted fields stay in the server-side plan, but are masked on the wire, in logs and in the hash.
+    const encrypted = new Set(ctx.Fields.filter((f) => f.Encrypted).map((f) => f.Name));
+    for (const change of changes) {
+        if (encrypted.has(change.Field))
+            change.Sensitive = true;
+    }
+    return {
+        FieldChanges: changes,
+        MappedValues: values,
+        RequiresIdentitySecondPass: requiresIdentitySecondPass,
+        IgnoredRequestValues: ignored,
+        NamingFailures: namingFailures,
+    };
+}
+//# sourceMappingURL=CloneFieldMapper.js.map

package/dist/CloneFieldMapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloneFieldMapper.js","sourceRoot":"","sources":["../src/CloneFieldMapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,wBAAwB,EAAuB,MAAM,gBAAgB,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAiB,MAAM,mBAAmB,CAAC;AAyBlE,mHAAmH;AACnH,MAAM,UAAU,aAAa,CAAC,KAA4B;IACtD,OAAO,CAAC,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;AACzH,CAAC;AA8DD;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAA6B;IAC3D,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAU,CAAC;IAC3C,MAAM,cAAc,GAAa,EAAE,CAAC;IACpC,IAAI,0BAA0B,GAAG,KAAK,CAAC;IAEvC,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC;IAChC,MAAM,UAAU,GAAG,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC;IACxC,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC;IAC1B,8FAA8F;IAC9F,8DAA8D;IAC9D,MAAM,YAAY,GAA4B;QAC1C,GAAG,CAAC,GAAG,CAAC,gBAAgB,IAAI,EAAE,CAAC;QAC/B,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,oBAAoB,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,oBAAoB,CAAC,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxI,CAAC;IACF,MAAM,cAAc,GAAG,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC;IAEhD,mFAAmF;IACnF,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAE5C,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;YACrB,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC;gBACT,KAAK,EAAE,KAAK,CAAC,IAAI;gBACjB,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE,MAAM;gBAChB,QAAQ,EAAE,SAAS;gBACnB,MAAM,EAAE,+CAA+C;aAC1D,CAAC,CAAC;YACH,SAAS;QACb,CAAC;QAED,IAAI,KAAK,CAAC,gBAAgB,IAAI,KAAK,CAAC,gBAAgB,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC9E,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC;gBACT,KAAK,EAAE,KAAK,CAAC,IAAI;gBACjB,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE,MAAM;gBAChB,QAAQ,EAAE,SAAS;gBACnB,MAAM,EAAE,+CAA+C;aAC1D,CAAC,CAAC;YACH,SAAS;QACb,CAAC;QAED,IAAI,UAAU,CAAC,OAAO,IAAI,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAChE,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC;gBACT,KAAK,EAAE,KAAK,CAAC,IAAI;gBACjB,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE,MAAM;gBAChB,QAAQ,EAAE,SAAS;gBACnB,MAAM,EAAE,6BAA6B;aACxC,CAAC,CAAC;YACH,SAAS;QACb,CAAC;IACL,CAAC;IAED,0EAA0E;IAC1E,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC7B,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,SAAS;QAE/C,IAAI,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,KAAK,EAAE,CAAC;YAC9D,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC;gBACT,KAAK,EAAE,KAAK,CAAC,IAAI;gBACjB,IAAI,EAAE,aAAa;gBACnB,QAAQ,EAAE,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC;gBACtC,QAAQ,EAAE,SAAS;gBACnB,MAAM,EAAE,wDAAwD;aACnE,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,0DAA0D;IAC1D,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC7B,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,SAAS;QAE/C,IAAI,GAAG,CAAC,gBAAgB,IAAI,GAAG,CAAC,gBAAgB,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACpE,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC;gBACT,KAAK,EAAE,KAAK,CAAC,IAAI;gBACjB,IAAI,EAAE,YAAY;gBAClB,QAAQ,EAAE,SAAS;gBACnB,QAAQ,EAAE,SAAS;gBACnB,MAAM,EAAE,sCAAsC;aACjD,CAAC,CAAC;YACH,SAAS;QACb,CAAC;QAED,IAAI,GAAG,CAAC,kBAAkB,IAAI,GAAG,CAAC,kBAAkB,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACxE,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC;gBACT,KAAK,EAAE,KAAK,CAAC,IAAI;gBACjB,IAAI,EAAE,cAAc;gBACpB,QAAQ,EAAE,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC;gBACtC,QAAQ,EAAE,SAAS;gBACnB,MAAM,EAAE,wCAAwC;aACnD,CAAC,CAAC;YACH,SAAS;QACb,CAAC;IACL,CAAC;IAED,qEAAqE;IACrE,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC7B,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,SAAS;QAE/C,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5C,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;QAC5B,OAAO,CAAC,IAAI,CAAC;YACT,KAAK,EAAE,KAAK,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM;YACZ,QAAQ,EAAE,MAAM;YAChB,QAAQ,EAAE,MAAM;YAChB,MAAM,EAAE,qCAAqC;SAChD,CAAC,CAAC;IACP,CAAC;IAED,gDAAgD;IAChD,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;QACnB,KAAK,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YACnE,IAAI,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC;gBAAE,SAAS;YAC9C,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;YACjC,MAAM,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC;YAC7B,OAAO,CAAC,IAAI,CAAC;gBACT,KAAK,EAAE,SAAS;gBAChB,IAAI,EAAE,OAAO;gBACb,QAAQ,EAAE,MAAM;gBAChB,QAAQ,EAAE,QAAQ;gBAClB,MAAM,EAAE,iCAAiC;aAC5C,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,+DAA+D;IAC/D,IAAI,UAAU,CAAC,SAAS,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;QAC5C,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;YAC3C,IAAI,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC;gBAAE,SAAS;YAC9C,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;YACjC,MAAM,CAAC,SAAS,CAAC,GAAG,GAAG,CAAC,aAAa,CAAC;YACtC,OAAO,CAAC,IAAI,CAAC;gBACT,KAAK,EAAE,SAAS;gBAChB,IAAI,EAAE,WAAW;gBACjB,QAAQ,EAAE,MAAM;gBAChB,QAAQ,EAAE,GAAG,CAAC,aAAa;gBAC3B,MAAM,EAAE,qCAAqC;aAChD,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,6DAA6D;IAC7D,IAAI,UAAU,CAAC,eAAe,EAAE,CAAC;QAC7B,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,eAAe,EAAE,CAAC;YACjD,IAAI,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC;gBAAE,SAAS;YAC9C,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;YACjC,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;YACzB,OAAO,CAAC,IAAI,CAAC;gBACT,KAAK,EAAE,SAAS;gBAChB,IAAI,EAAE,OAAO;gBACb,QAAQ,EAAE,MAAM;gBAChB,QAAQ,EAAE,IAAI;gBACd,MAAM,EAAE,yDAAyD;aACpE,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,2DAA2D;IAC3D,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC7B,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,SAAS;QAE/C,IAAI,aAAa,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAC1F,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YAC3C,MAAM,OAAO,GAAG,wBAAwB,CACpC,OAAO,EACP,GAAG,CAAC,aAAa,EAAE,oBAAoB,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,aAAa,EAAE,aAAa,IAAI,IAAI,GAAG,EAAE,EACtG;gBACI,QAAQ,EAAE,GAAG,CAAC,aAAa,EAAE,QAAQ;gBACrC,QAAQ,EAAE,GAAG,CAAC,aAAa,EAAE,QAAQ;gBACrC,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,OAAO,EAAE;oBACL,QAAQ,EAAE,GAAG,CAAC,aAAa,EAAE,QAAQ;iBACxC;aACJ,CACJ,CAAC;YAEF,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACnB,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAChC,SAAS;YACb,CAAC;YACD,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;gBACtB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;gBAC7B,OAAO,CAAC,IAAI,CAAC;oBACT,KAAK,EAAE,KAAK,CAAC,IAAI;oBACjB,IAAI,EAAE,QAAQ;oBACd,QAAQ,EAAE,OAAO;oBACjB,QAAQ,EAAE,OAAO;oBACjB,MAAM,EAAE,qDAAqD;iBAChE,CAAC,CAAC;YACP,CAAC;QACL,CAAC;IACL,CAAC;IAED,wEAAwE;IACxE,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC7B,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,SAAS;QAE/C,yBAAyB;QACzB,IAAI,GAAG,CAAC,oBAAoB,IAAI,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,oBAAoB,EAAE,CAAC;YACtE,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;gBACb,mFAAmF;gBACnF,4DAA4D;YAChE,CAAC;iBAAM,IAAI,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,IAAI,MAAM,EAAE,CAAC;gBAClD,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;gBAC5C,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;gBAC/B,OAAO,CAAC,IAAI,CAAC;oBACT,KAAK,EAAE,KAAK,CAAC,IAAI;oBACjB,IAAI,EAAE,OAAO;oBACb,QAAQ,EAAE,SAAS;oBACnB,QAAQ,EAAE,SAAS;oBACnB,MAAM,EAAE,+CAA+C;iBAC1D,CAAC,CAAC;YACP,CAAC;YACD,SAAS;QACb,CAAC;QAED,uBAAuB;QACvB,IAAI,KAAK,CAAC,eAAe,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;YAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxC,MAAM,YAAY,GAAG,KAAK,CAAC,aAAa,CAAC;gBACzC,MAAM,YAAY,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;gBAC/E,MAAM,KAAK,GAAG,CAAC,YAAY,IAAI,YAAY,IAAI,MAAM,CAAC;oBAClD,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;oBACtB,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;gBAEpE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;oBACzC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;oBAC3B,OAAO,CAAC,IAAI,CAAC;wBACT,KAAK,EAAE,KAAK,CAAC,IAAI;wBACjB,IAAI,EAAE,OAAO;wBACb,QAAQ,EAAE,KAAK;wBACf,QAAQ,EAAE,KAAK;wBACf,MAAM,EAAE,mBAAmB,YAAY,IAAI,QAAQ,8BAA8B;qBACpF,CAAC,CAAC;gBACP,CAAC;YACL,CAAC;QACL,CAAC;IACL,CAAC;IAED,mEAAmE;IACnE,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;QACvB,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;YAC3C,IAAI,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC;gBAAE,SAAS;YACpD,MAAM,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YAC3C,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,CAAC,UAAU,IAAI,OAAO,UAAU,KAAK,QAAQ,CAAC,EAAE,CAAC;gBACnF,MAAM,QAAQ,GAAG,cAAc,CAAC,UAA8C,EAAE;oBAC5E,KAAK,EAAE,SAAS,CAAC,KAAK;oBACtB,MAAM,EAAE,SAAS,CAAC,MAAM;oBACxB,MAAM,EAAE,MAAM;iBACjB,CAAC,CAAC;gBACH,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;oBACnB,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC;oBAC9C,OAAO,CAAC,IAAI,CAAC;wBACT,KAAK,EAAE,SAAS,CAAC,KAAK;wBACtB,IAAI,EAAE,WAAW;wBACjB,QAAQ,EAAE,UAAU;wBACpB,QAAQ,EAAE,QAAQ,CAAC,UAAU;wBAC7B,MAAM,EAAE,kBAAkB,QAAQ,CAAC,aAAa,CAAC,MAAM,mBAAmB,QAAQ,CAAC,SAAS,YAAY;qBAC3G,CAAC,CAAC;gBACP,CAAC;YACL,CAAC;QACL,CAAC;IACL,CAAC;IAED,2FAA2F;IAC3F,oEAAoE;IACpE,MAAM,OAAO,GAAoD,EAAE,CAAC;IACpE,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS;QAC7B,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,EAAE,CAAC;QACtC,GAAG,CAAC,UAAU,CAAC,SAAS,IAAI,EAAE,CAAC;QAC/B,GAAG,CAAC,UAAU,CAAC,eAAe,IAAI,EAAE,CAAC;QACrC,GAAG,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;KAChG,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IAEtD,yDAAyD;IACzD,KAAK,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QAClE,IAAI,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,SAAS;QAC9C,IAAI,GAAG,CAAC,qBAAqB,KAAK,KAAK,EAAE,CAAC;YACtC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,4EAA4E,EAAE,CAAC,CAAC;YAC3I,SAAS;QACb,CAAC;QACD,IAAI,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,yCAAyC,EAAE,CAAC,CAAC;YACxG,SAAS;QACb,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;QACjC,MAAM,CAAC,SAAS,CAAC,GAAG,WAAW,CAAC;QAChC,OAAO,CAAC,IAAI,CAAC;YACT,KAAK,EAAE,SAAS;YAChB,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE,MAAM;YAChB,QAAQ,EAAE,WAAW;YACrB,MAAM,EAAE,wCAAwC;SACnD,CAAC,CAAC;IACP,CAAC;IAED,mFAAmF;IACnF,KAAK,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QAClE,IAAI,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,SAAS;QAC9C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,wDAAwD,EAAE,CAAC,CAAC;YACrH,SAAS;QACb,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;QACjC,MAAM,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC;QAC9B,OAAO,CAAC,IAAI,CAAC;YACT,KAAK,EAAE,SAAS;YAChB,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,MAAM;YAChB,QAAQ,EAAE,SAAS;YACnB,MAAM,EAAE,8BAA8B;SACzC,CAAC,CAAC;IACP,CAAC;IAED,+DAA+D;IAC/D,IAAI,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC;QAC1B,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACxC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,KAAK,CAAC;YACnD,IAAI,CAAC,WAAW,IAAI,gBAAgB,CAAC,GAAG,CAAC,WAAW,CAAC;gBAAE,SAAS;YAChE,IAAI,MAAe,CAAC;YACpB,IAAI,IAAI,CAAC,MAAM,EAAE,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;gBACrD,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC9E,CAAC;iBAAM,IAAI,IAAI,CAAC,MAAM,EAAE,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACxC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;YAC/B,CAAC;YACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACvB,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;gBACnC,MAAM,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC;gBAC7B,OAAO,CAAC,IAAI,CAAC;oBACT,KAAK,EAAE,WAAW;oBAClB,IAAI,EAAE,MAAM;oBACZ,QAAQ,EAAE,MAAM;oBAChB,QAAQ,EAAE,MAAM;oBAChB,MAAM,EAAE,yBAAyB;oBACjC,sEAAsE;oBACtE,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,KAAK,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACxI,CAAC,CAAC;YACP,CAAC;QACL,CAAC;IACL,CAAC;IAED,gHAAgH;IAChH,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACpF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC;YAAE,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC;IAC7D,CAAC;IAED,OAAO;QACH,YAAY,EAAE,OAAO;QACrB,YAAY,EAAE,MAAM;QACpB,0BAA0B,EAAE,0BAA0B;QACtD,oBAAoB,EAAE,OAAO;QAC7B,cAAc,EAAE,cAAc;KACjC,CAAC;AACN,CAAC"}

package/dist/ClonePlanHash.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file ClonePlanHash.ts
+ * Canonical form of a ClonePlan's topology and transformations, for hashing.
+ * Stable across key ordering and ignores pre-minted TargetKey values. The engine hashes it with
+ * SHA-256 (`node:crypto`); this package stays dependency-free and client-safe.
+ * @see plans/record-cloning/README.md §3.5, §13.1
+ */
+import { ClonePlanEdge, ClonePlanNode } from './types.js';
+/**
+ * Input subset of ClonePlan required for computing the canonical hash.
+ */
+export interface ClonePlanHashInput {
+    Nodes: ClonePlanNode[];
+    Edges: ClonePlanEdge[];
+    Excluded?: unknown[];
+}
+/**
+ * The canonical string a plan hash is computed over.
+ *
+ * - Covers every node's (EntityName, SourceKey, Action)
+ * - Covers every edge's (FromKey, ToKey, Policy)
+ * - Covers every FieldChange (Field, Kind, OldValue, NewValue, Reason), with encrypted values masked
+ * - EXCLUDES TargetKey values (so re-planning does not drift on pre-minted UUIDs)
+ * - Immune to array ordering of nodes, edges, or field changes
+ */
+export declare function CanonicalPlanPayload(plan: ClonePlanHashInput): string;
+//# sourceMappingURL=ClonePlanHash.d.ts.map

package/dist/ClonePlanHash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClonePlanHash.d.ts","sourceRoot":"","sources":["../src/ClonePlanHash.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAEH,aAAa,EACb,aAAa,EAGhB,MAAM,SAAS,CAAC;AA+DjB;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAmDrE"}

package/dist/ClonePlanHash.js

@@ -0,0 +1,130 @@
+/**
+ * @file ClonePlanHash.ts
+ * Canonical form of a ClonePlan's topology and transformations, for hashing.
+ * Stable across key ordering and ignores pre-minted TargetKey values. The engine hashes it with
+ * SHA-256 (`node:crypto`); this package stays dependency-free and client-safe.
+ * @see plans/record-cloning/README.md §3.5, §13.1
+ */
+import { FormatCompositeKey, } from './types.js';
+import { MaskSensitiveFieldChange } from './SensitiveValues.js';
+/** The key values of a key given as pairs, a record-id segment ("F|V||F|V") or a bare value. */
+function keyValues(key) {
+    if (!key)
+        return [];
+    if (typeof key !== 'string')
+        return (key.KeyValuePairs ?? []).map((p) => String(p.Value ?? ''));
+    if (!key.includes('|'))
+        return [key];
+    return key.split('||').map((pair) => pair.slice(pair.indexOf('|') + 1));
+}
+/**
+ * Tokens for the key values a plan mints (a new UUID, a remapped key column): each maps to a stable
+ * name for the row it belongs to. Without this, remapped foreign keys would change the hash on every
+ * re-plan, and every Execute of an unchanged plan would come back PLAN_CHANGED.
+ */
+function mintedKeyTokens(nodes) {
+    const tokens = new Map();
+    // Visit rows in a fixed order and keep the first name a value gets: when sibling keys share a
+    // minted value (a composite key holding the parent's new ID), the token must not depend on the
+    // order the walker loaded the siblings in.
+    const named = nodes
+        .map((n) => ({ n, name: `${n.EntityName}::${FormatCompositeKey(n.SourceKey)}` }))
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const { n, name } of named) {
+        const source = new Set(keyValues(n.SourceKey).map((v) => v.toLowerCase()));
+        keyValues(n.TargetKey).forEach((value, i) => {
+            const k = value?.toLowerCase();
+            if (k && !source.has(k) && !tokens.has(k))
+                tokens.set(k, `@new(${name}#${i})`);
+        });
+    }
+    return tokens;
+}
+/**
+ * Deterministically stringifies an arbitrary value for canonical hashing, with minted key values
+ * (also inside strings, such as remapped JSON) replaced by their stable tokens.
+ */
+function canonicalizeValue(val, tokens, pattern) {
+    if (val === null || val === undefined) {
+        return '';
+    }
+    if (typeof val === 'object') {
+        if (val instanceof Date) {
+            return val.toISOString();
+        }
+        if (Array.isArray(val)) {
+            return `[${val.map((v) => canonicalizeValue(v, tokens, pattern)).join(',')}]`;
+        }
+        const obj = val;
+        const keys = Object.keys(obj).sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalizeValue(obj[k], tokens, pattern)}`).join(',')}}`;
+    }
+    if (typeof val === 'string' && pattern) {
+        return JSON.stringify(val.replace(pattern, (m) => tokens.get(m.toLowerCase()) ?? m));
+    }
+    return JSON.stringify(val);
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * The canonical string a plan hash is computed over.
+ *
+ * - Covers every node's (EntityName, SourceKey, Action)
+ * - Covers every edge's (FromKey, ToKey, Policy)
+ * - Covers every FieldChange (Field, Kind, OldValue, NewValue, Reason), with encrypted values masked
+ * - EXCLUDES TargetKey values (so re-planning does not drift on pre-minted UUIDs)
+ * - Immune to array ordering of nodes, edges, or field changes
+ */
+export function CanonicalPlanPayload(plan) {
+    const tokens = mintedKeyTokens(plan.Nodes);
+    const pattern = tokens.size > 0 ? new RegExp([...tokens.keys()].sort((a, b) => b.length - a.length).map(escapeRegExp).join('|'), 'gi') : null;
+    // 1. Canonicalize and sort nodes
+    const sortedNodes = [...plan.Nodes]
+        .map((n) => {
+        const sortedChanges = [...n.FieldChanges]
+            .sort((a, b) => a.Field.localeCompare(b.Field))
+            .map(MaskSensitiveFieldChange)
+            .map((fc) => ({
+            Field: fc.Field,
+            Kind: fc.Kind,
+            OldValue: canonicalizeValue(fc.OldValue, tokens, pattern),
+            NewValue: canonicalizeValue(fc.NewValue, tokens, pattern),
+            Reason: fc.Reason || '',
+        }));
+        return {
+            EntityName: n.EntityName,
+            SourceKey: FormatCompositeKey(n.SourceKey),
+            Action: n.Action,
+            FieldChanges: sortedChanges,
+        };
+    })
+        .sort((a, b) => {
+        const cmp = a.EntityName.localeCompare(b.EntityName);
+        if (cmp !== 0)
+            return cmp;
+        return a.SourceKey.localeCompare(b.SourceKey);
+    });
+    // 2. Canonicalize and sort edges
+    const sortedEdges = [...plan.Edges]
+        .map((e) => ({
+        FromKey: e.FromKey,
+        ToKey: e.ToKey,
+        Policy: e.Policy,
+    }))
+        .sort((a, b) => {
+        const cmp = a.FromKey.localeCompare(b.FromKey);
+        if (cmp !== 0)
+            return cmp;
+        const cmp2 = a.ToKey.localeCompare(b.ToKey);
+        if (cmp2 !== 0)
+            return cmp2;
+        return a.Policy.localeCompare(b.Policy);
+    });
+    // 3. Form canonical string
+    return JSON.stringify({
+        Nodes: sortedNodes,
+        Edges: sortedEdges,
+    });
+}
+//# sourceMappingURL=ClonePlanHash.js.map

package/dist/ClonePlanHash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClonePlanHash.js","sourceRoot":"","sources":["../src/ClonePlanHash.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAKH,kBAAkB,GACrB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,gGAAgG;AAChG,SAAS,SAAS,CAAC,GAAiD;IAChE,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;IAChG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACrC,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,KAAsB;IAC3C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,8FAA8F;IAC9F,+FAA+F;IAC/F,2CAA2C;IAC3C,MAAM,KAAK,GAAG,KAAK;SACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,UAAU,KAAK,kBAAkB,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC;SAChF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtE,KAAK,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,KAAK,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QAC3E,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;YACxC,MAAM,CAAC,GAAG,KAAK,EAAE,WAAW,EAAE,CAAC;YAC/B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;QACnF,CAAC,CAAC,CAAC;IACP,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CAAC,GAAY,EAAE,MAA2B,EAAE,OAAsB;IACxF,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACpC,OAAO,EAAE,CAAC;IACd,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC1B,IAAI,GAAG,YAAY,IAAI,EAAE,CAAC;YACtB,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC;QAC7B,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QAClF,CAAC;QACD,MAAM,GAAG,GAAG,GAA8B,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAClH,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAC9B,OAAO,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACvD,CAAC;AAWD;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAwB;IACzD,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE9I,iCAAiC;IACjC,MAAM,WAAW,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;SAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACP,MAAM,aAAa,GAAG,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC;aACpC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;aAC9C,GAAG,CAAC,wBAAwB,CAAC;aAC7B,GAAG,CAAC,CAAC,EAAoB,EAAE,EAAE,CAAC,CAAC;YAC5B,KAAK,EAAE,EAAE,CAAC,KAAK;YACf,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,QAAQ,EAAE,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC;YACzD,QAAQ,EAAE,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC;YACzD,MAAM,EAAE,EAAE,CAAC,MAAM,IAAI,EAAE;SAC1B,CAAC,CAAC,CAAC;QAER,OAAO;YACH,UAAU,EAAE,CAAC,CAAC,UAAU;YACxB,SAAS,EAAE,kBAAkB,CAAC,CAAC,CAAC,SAAS,CAAC;YAC1C,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,YAAY,EAAE,aAAa;SAC9B,CAAC;IACN,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACX,MAAM,GAAG,GAAG,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACrD,IAAI,GAAG,KAAK,CAAC;YAAE,OAAO,GAAG,CAAC;QAC1B,OAAO,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEP,iCAAiC;IACjC,MAAM,WAAW,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;SAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACT,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,MAAM,EAAE,CAAC,CAAC,MAAM;KACnB,CAAC,CAAC;SACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACX,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAC/C,IAAI,GAAG,KAAK,CAAC;YAAE,OAAO,GAAG,CAAC;QAC1B,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC5C,IAAI,IAAI,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAC5B,OAAO,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEP,2BAA2B;IAC3B,OAAO,IAAI,CAAC,SAAS,CAAC;QAClB,KAAK,EAAE,WAAW;QAClB,KAAK,EAAE,WAAW;KACrB,CAAC,CAAC;AACP,CAAC"}

package/dist/ClonePolicyResolver.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @file ClonePolicyResolver.ts
+ * 8-tier precedence hierarchy for clone edge policy resolution.
+ * Evaluates Built-in -> Constraint -> Child Entity -> Relationship -> Root Entity -> Preset -> Request.
+ * Enforces:
+ * - A child entity marked NotCloneable (or AllowCreateAPI=false) is skipped everywhere, unconditionally.
+ * - Name heuristics (runs, logs, per-user state) skip a child only when no configuration names that edge.
+ * - Unlisted relationships are Skip: each configuration opts in to what it copies. There are no
+ *   entity-specific defaults.
+ * - A self-relationship is Deep only when its join column is a hierarchy (IsHierarchy) field.
+ * - A unique FK makes Reference impossible, so it turns Reference into Deep; it never overrides Skip.
+ * - Locked edges ignore preset and request overrides (LOCKED_EDGE_OVERRIDE_IGNORED).
+ * @see plans/record-cloning/README.md §4.4, §5.3–§5.5, §13.1
+ */
+import { CloneEdgeKind, CloneEdgePolicy, CloneWarning } from './types.js';
+export interface EdgePolicyResolutionContext {
+    FromKey: string;
+    ToKey: string;
+    Kind: CloneEdgeKind;
+    ParentEntityName: string;
+    ChildEntityName: string;
+    /**
+     * The clone root's entity. A bare child-entity key in the root's `Relationships` applies only to
+     * edges from this entity; below it, only relationship-ID and `Child.JoinField` keys match. Left out,
+     * the edge is taken to start at the root.
+     */
+    RootEntityName?: string;
+    JoinField: string;
+    RelationshipID?: string;
+    CollectionName?: string;
+    IsSoftLink?: boolean;
+    CurrentDepth: number;
+    MaxDepth: number;
+    IsUniqueFK?: boolean;
+    /** The child's join column is flagged IsHierarchy (a parent/child tree within one entity). */
+    IsHierarchyField?: boolean;
+    IsWriteOnce?: boolean;
+    ChildEntityConfig?: {
+        NotCloneable?: boolean;
+        NotCloneableReason?: string;
+        AllowCreateAPI?: boolean;
+    };
+    RelationshipConfig?: {
+        Policy?: CloneEdgePolicy;
+        Locked?: boolean;
+    };
+    RootEntityConfig?: {
+        Relationships?: Record<string, {
+            Policy?: CloneEdgePolicy;
+            Locked?: boolean;
+        }>;
+        Descendants?: Record<string, {
+            Policy?: CloneEdgePolicy;
+            Locked?: boolean;
+        }>;
+    };
+    /**
+     * The `Relationships` of the entity the edge starts from, for edges below the root: a prompt's
+     * template follows `MJ: Templates`' own configuration. The root's configuration still wins.
+     */
+    ParentEntityConfig?: {
+        Relationships?: Record<string, {
+            Policy?: CloneEdgePolicy;
+            Locked?: boolean;
+        }>;
+    };
+    PresetConfig?: {
+        EdgeOverrides?: Array<{
+            RelationshipID?: string;
+            ChildEntityName?: string;
+            Policy: CloneEdgePolicy;
+        }>;
+    };
+    RequestOverrides?: Array<{
+        FromKey?: string;
+        ToKey?: string;
+        RelationshipID?: string;
+        Policy: CloneEdgePolicy;
+    }>;
+    AllowUserOverrides?: boolean;
+}
+export interface EdgePolicyResolutionResult {
+    Policy: CloneEdgePolicy;
+    PolicySource: 'BuiltIn' | 'Constraint' | 'Entity' | 'Relationship' | 'Descendant' | 'Request';
+    Locked: boolean;
+    Warnings: CloneWarning[];
+}
+/**
+ * Resolves the edge traversal policy according to the 8-tier precedence hierarchy.
+ */
+export declare function ResolveEdgePolicy(ctx: EdgePolicyResolutionContext): EdgePolicyResolutionResult;
+/** Whether an edge from `parentEntityName` starts at the root's entity (ignoring case); true when the root isn't given. */
+export declare function IsEdgeFromRoot(parentEntityName: string, rootEntityName: string | undefined | null): boolean;
+/**
+ * An entry of a `Relationships` or `Descendants` bag by key, ignoring case, as the validator
+ * matches keys: a miscased column (`AgentId` for `AgentID`) must not validate clean and then
+ * silently fall back to the default policy.
+ */
+export declare function BagEntry<T>(bag: Record<string, T> | undefined | null, key: string | undefined | null): T | undefined;
+//# sourceMappingURL=ClonePolicyResolver.d.ts.map