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

package/dist/ClonePlanner.js

@@ -0,0 +1,870 @@
+/**
+ * @file ClonePlanner.ts
+ * Computes deterministic clone plans for entity records using graph traversal.
+ * Enforces caps, permissions, unique key classification, field transformations, and plan hashing.
+ * @see plans/record-cloning/README.md §5, §7, §13.1
+ */
+import { CompositeKey, Metadata, RunView, } from '@memberjunction/core';
+import { DependencyGraphWalker } from '@memberjunction/record-graph';
+import { DetectIntraPlanCollisions, GenerateUUID, MapFieldsForClone, ResolveEdgePolicy, ResolveEffectiveCloneOptions, NormalizeClonePresets, FieldMetaFromEntity, CloneConfigMetaFromEntity, CloneConfigValidator, IsRenameField, NameCollisionPrefix, RowMatchesExclusion, BagEntry, IsEdgeFromRoot, } from '@memberjunction/record-cloning-base';
+import { EscapeSQLString } from '@memberjunction/global';
+import { CloneAuthorizer } from './CloneAuthorization.js';
+import { ComputeClonePlanHash } from './ClonePlanHash.js';
+import { DeriveTargetKey, IsUuidColumn, KeyStrategyFor, ToRecordKeyString } from './CloneKeys.js';
+/**
+ * Fields the user may not read or may not supply on create, for entities with field-level security.
+ * The mapper leaves them out, so a clone never copies a value its user couldn't see or set.
+ */
+function fieldLevelDenials(entity, user) {
+    if (!entity.EnableFieldLevelSecurity)
+        return undefined;
+    const deniedRead = entity.GetDeniedReadFields(user);
+    const deniedCreate = entity.GetDeniedCreateFields(user);
+    const names = (denied) => entity.Fields.filter((f) => denied.has(f.Name.toLowerCase())).map((f) => f.Name);
+    return { DeniedReadFields: names(deniedRead), DeniedCreateFields: names(deniedCreate) };
+}
+/** The requested root key as a record-id string, whatever shape the request used. */
+function requestedKeyString(key) {
+    if (typeof key === 'string')
+        return ToRecordKeyString(key);
+    if (key && typeof key === 'object') {
+        if (Array.isArray(key.KeyValuePairs))
+            return ToRecordKeyString(key);
+        // The { Field: value } shorthand.
+        return ToRecordKeyString({ KeyValuePairs: Object.entries(key).map(([FieldName, Value]) => ({ FieldName, Value })) });
+    }
+    return '';
+}
+export class ClonePlanner {
+    constructor(options) {
+        this._provider = options?.Provider;
+    }
+    get Provider() {
+        return this._provider ?? Metadata.Provider;
+    }
+    /**
+     * Generates a fully calculated ClonePlan for the requested record.
+     */
+    async Plan(request, contextUser) {
+        const md = this.Provider;
+        const entityName = request.EntityName || request.Roots?.[0]?.EntityName;
+        if (!entityName) {
+            throw new Error(`RecordCloneRequest must specify EntityName or Roots.`);
+        }
+        const sourceRecordKey = request.SourceRecordKey || request.Roots?.[0]?.Key;
+        if (!sourceRecordKey) {
+            throw new Error(`RecordCloneRequest must specify SourceRecordKey or Roots.`);
+        }
+        const rootEntityInfo = md.EntityByName(entityName);
+        if (!rootEntityInfo) {
+            throw new Error(`Entity '${entityName}' not found in metadata.`);
+        }
+        const warnings = [];
+        let planBlocked = false;
+        const rootConfig = rootEntityInfo.CloneConfig ?? null;
+        const authorizer = new CloneAuthorizer(md);
+        // The configuration is checked here, not only in the Entities form: an invalid bag (a bad
+        // policy, a cap that isn't a positive integer, a rule on a missing field) blocks the plan.
+        if (rootConfig) {
+            const findings = CloneConfigValidator.Validate(CloneConfigMetaFromEntity(rootEntityInfo, { ...rootConfig, Enabled: true }), md.Entities.map((e) => ({ Name: e.Name, Fields: [] })));
+            for (const finding of findings) {
+                // A key for an entity reached through a descendant is valid configuration; the
+                // Entities form's Validate still notes it, but every plan needn't repeat it.
+                if (finding.Severity === 'Warning' && finding.PropertyPath.startsWith('Relationships['))
+                    continue;
+                // A relationship key that matches nothing only means that edge isn't configured
+                // (a stale key, say): report it, but don't refuse every clone of the entity over it.
+                const blocking = finding.Severity === 'Error' && !finding.PropertyPath.startsWith('Relationships[');
+                warnings.push({
+                    Code: 'CONFIG_INVALID',
+                    Severity: blocking ? 'Error' : 'Warning',
+                    Field: finding.PropertyPath,
+                    Message: `Clone configuration for '${entityName}': ${finding.Message}`,
+                });
+                if (blocking)
+                    planBlocked = true;
+            }
+        }
+        // A preset (Clone.Presets, looked up by Key) contributes options under the request's own
+        // options and edge policy overrides by related entity name.
+        const presetKey = request.Preset || request.Options?.Preset;
+        const preset = presetKey ? NormalizeClonePresets(rootConfig?.Presets).find((p) => p.Key === presetKey) : undefined;
+        if (presetKey && !preset) {
+            warnings.push({
+                Code: 'OPTION_OVERRIDE_IGNORED',
+                Severity: 'Warning',
+                Field: 'Preset',
+                Message: `Preset '${presetKey}' is not defined for '${entityName}'.`,
+            });
+        }
+        // A preset is configured by the entity's owner, so its options act as configuration (they may
+        // widen scope for anyone); only the request's own options go through the override rules.
+        const configWithPreset = preset?.Options ? { ...(rootConfig ?? {}), ...preset.Options } : rootConfig;
+        const presetEdgeOverrides = preset?.Relationships
+            ? Object.entries(preset.Relationships).map(([ChildEntityName, cfg]) => ({ ChildEntityName, Policy: cfg.Policy }))
+            : undefined;
+        // The entity's configuration supplies the defaults; UserEditable and the Fire Hooks
+        // authorization decide which request values may change them (plan §4.1, §9.4).
+        const resolved = ResolveEffectiveCloneOptions(configWithPreset, request.Options, {
+            CanFireHooks: authorizer.CanFireHooks(contextUser),
+            CanOverrideScope: authorizer.CanOverrideScope(contextUser),
+        });
+        const effectiveOptions = resolved.Options;
+        warnings.push(...resolved.Warnings);
+        // Per-edge request overrides follow the same rule as the scope options: Skip and
+        // Reference narrow the copy (allowed when UserEditable permits, or for an override
+        // holder); Deep widens it and needs Clone Records: Override Scope.
+        const canOverrideScope = authorizer.CanOverrideScope(contextUser);
+        const editable = rootConfig?.UserEditable ?? 'all';
+        const mayNarrowEdges = editable === 'scope' || editable === 'all' || canOverrideScope;
+        const edgeOverrides = (request.EdgeOverrides ?? []).filter((o) => {
+            if (o.Policy === 'Deep' ? canOverrideScope : mayNarrowEdges)
+                return true;
+            warnings.push({
+                Code: o.Policy === 'Deep' ? 'SCOPE_OVERRIDE_FORBIDDEN' : 'OPTION_OVERRIDE_IGNORED',
+                Severity: 'Warning',
+                Field: 'EdgeOverrides',
+                Message: o.Policy === 'Deep'
+                    ? `Copying a relationship the configuration leaves out needs the 'Clone Records: Override Scope' authorization.`
+                    : `Relationship overrides were ignored: this entity's clone configuration sets UserEditable to '${editable}'.`,
+            });
+            return false;
+        });
+        const maxDepth = effectiveOptions.MaxDepth;
+        const maxRecords = effectiveOptions.MaxRecords;
+        // An entity is a clone ROOT only when its configuration enables it (plan §4.1).
+        if (rootConfig?.Enabled !== true || rootConfig?.NotCloneable === true) {
+            warnings.push({
+                Code: 'NOT_CLONEABLE',
+                Severity: 'Error',
+                Message: rootConfig?.NotCloneableReason
+                    || `Cloning is not enabled for '${entityName}'. Set Configuration.Clone.Enabled on its MJ: Entities record.`,
+            });
+            planBlocked = true;
+        }
+        const rootAuth = authorizer.CanCloneEntity(rootEntityInfo, contextUser);
+        if (!rootAuth.Granted) {
+            warnings.push({
+                Code: 'FORBIDDEN',
+                Severity: 'Error',
+                Message: `Cloning '${entityName}' requires the '${rootAuth.Name}' authorization.`,
+            });
+            planBlocked = true;
+        }
+        // Verify root authorization / RequiredUserType
+        if (rootConfig?.RequiredUserType && contextUser.Type?.trim() !== rootConfig.RequiredUserType?.trim()) {
+            warnings.push({
+                Code: 'REQUIRED_USER_TYPE_MISMATCH',
+                Severity: 'Error',
+                Message: `Cloning entity '${entityName}' requires user type '${rootConfig.RequiredUserType}', current user is '${contextUser.Type}'.`,
+            });
+            planBlocked = true;
+        }
+        const rootPerms = rootEntityInfo.GetUserPermisions(contextUser);
+        if (!rootPerms.CanCreate) {
+            warnings.push({
+                Code: 'NO_CREATE_PERMISSION',
+                Severity: 'Error',
+                Message: `User '${contextUser.Email || contextUser.Name}' lacks CanCreate permission on root entity '${entityName}'.`,
+            });
+            planBlocked = true;
+        }
+        // Refused before anything is planned: an empty plan that still names the requested record.
+        const refusedPlan = () => ({
+            PlanVersion: 1,
+            EffectiveOptions: effectiveOptions,
+            Hash: '',
+            // Name the requested record even though nothing was walked, so the refusal log says which.
+            Roots: [requestedKeyString(sourceRecordKey)],
+            RootEntityName: entityName,
+            RootSourceKey: requestedKeyString(sourceRecordKey),
+            RootTargetKey: '',
+            Nodes: [],
+            Edges: [],
+            Excluded: [],
+            Counts: {
+                ByEntity: { [entityName]: { Create: 0, Reference: 0, Skip: 0 } },
+                Create: 0,
+                Total: 0,
+            },
+            Warnings: warnings,
+            Blocked: true,
+        });
+        if (planBlocked)
+            return refusedPlan();
+        const key = new CompositeKey();
+        if (sourceRecordKey instanceof CompositeKey) {
+            key.KeyValuePairs = sourceRecordKey.KeyValuePairs.map((kvp) => ({
+                FieldName: kvp.FieldName,
+                Value: kvp.Value,
+            }));
+        }
+        else if (typeof sourceRecordKey === 'object' &&
+            sourceRecordKey !== null &&
+            'KeyValuePairs' in sourceRecordKey &&
+            Array.isArray(sourceRecordKey.KeyValuePairs)) {
+            key.KeyValuePairs = sourceRecordKey.KeyValuePairs.map((kvp) => ({
+                FieldName: kvp.FieldName,
+                Value: kvp.Value,
+            }));
+        }
+        else if (typeof sourceRecordKey === 'string') {
+            key.LoadFromURLSegment(rootEntityInfo, sourceRecordKey);
+        }
+        else {
+            key.LoadFromEntityInfoAndRecord(rootEntityInfo, sourceRecordKey);
+        }
+        const walker = new DependencyGraphWalker(md);
+        const candidateEdges = [];
+        const excludedNodes = [];
+        // Traverse graph with EdgePolicy callback
+        const rootNode = await walker.WalkDependents(entityName, key, {
+            MaxDepth: maxDepth,
+            RequireTrackRecordChanges: false,
+            IncludeSubtypes: effectiveOptions.Subtypes === 'include',
+            IncludeSoftLinks: effectiveOptions.SoftLinks === 'include',
+            FollowHierarchies: effectiveOptions.Hierarchy === 'subtree',
+            // A copy missing rows it should have (a Flow agent without its steps) looks complete, so say so.
+            OnLoadFailure: (failure) => {
+                if (failure.Decision !== 'Deep')
+                    return;
+                const edge = failure.Edge;
+                warnings.push({
+                    Code: 'CHILD_ROWS_UNREADABLE',
+                    Severity: 'Warning',
+                    NodeKey: `${edge.SourceEntityName}::${edge.SourceKey.ToConcatenatedString()}`,
+                    Message: `Couldn't read the ${edge.TargetEntityName} rows (by ${edge.JoinField}) of this ${edge.SourceEntityName} record, so the copy leaves them out: ${failure.Message}`,
+                });
+            },
+            EdgePolicy: (candidate) => {
+                const targetEntity = md.EntityByName(candidate.TargetEntityName);
+                const joinFieldInfo = targetEntity?.Fields.find((f) => f.Name.toLowerCase() === candidate.JoinField.toLowerCase());
+                // Check server-generated children on parent
+                const sourceEnt = md.EntityByName(candidate.SourceEntityName);
+                const parentConfig = sourceEnt?.CloneConfig ?? null;
+                if (parentConfig?.Hooks?.ServerGeneratedChildren?.includes(candidate.TargetEntityName)) {
+                    warnings.push({
+                        Code: 'SERVER_GENERATED_CHILD_SKIPPED',
+                        Severity: 'Warning',
+                        Message: `Relationship to '${candidate.TargetEntityName}' skipped because parent creates it in server Save() hooks.`,
+                    });
+                    excludedNodes.push({
+                        EntityName: candidate.TargetEntityName,
+                        SourceKey: candidate.TargetKey ? candidate.TargetKey.ToConcatenatedString() : '',
+                        Reason: `Skipped because parent creates it in server Save() hooks.`,
+                    });
+                    return 'Skip';
+                }
+                const relPolicy = candidate.Relationship?.CloneConfig ?? undefined;
+                const targetConfig = targetEntity?.CloneConfig ?? null;
+                // Up a hierarchy is the parent the row hangs from: a pointer to keep, never a
+                // subtree to copy. Configuration keys name the downward relationship, so they don't apply.
+                const upward = candidate.Kind === 'Hierarchy' && candidate.HierarchyDirection === 'Up';
+                const resolution = upward ? { Policy: 'Reference', PolicySource: 'BuiltIn', Locked: true, Warnings: [] } : ResolveEdgePolicy({
+                    FromKey: `${candidate.SourceEntityName}::${candidate.SourceKey.ToConcatenatedString()}`,
+                    ToKey: `${candidate.TargetEntityName}::${candidate.TargetKey ? candidate.TargetKey.ToConcatenatedString() : 'pending'}`,
+                    Kind: candidate.Kind,
+                    ParentEntityName: candidate.SourceEntityName,
+                    ChildEntityName: candidate.TargetEntityName,
+                    RootEntityName: entityName,
+                    JoinField: candidate.JoinField,
+                    RelationshipID: candidate.Relationship?.ID,
+                    RelationshipConfig: relPolicy,
+                    // Enabled=false only means "not a clone root"; NotCloneable is what keeps a child out.
+                    ChildEntityConfig: {
+                        NotCloneable: targetConfig?.NotCloneable === true,
+                        NotCloneableReason: targetConfig?.NotCloneableReason,
+                        AllowCreateAPI: targetEntity?.AllowCreateAPI,
+                    },
+                    IsHierarchyField: joinFieldInfo?.IsHierarchy === true,
+                    RootEntityConfig: rootConfig ? {
+                        Relationships: rootConfig.Relationships,
+                    } : undefined,
+                    // Below the root, the parent entity's own configuration applies too.
+                    ParentEntityConfig: candidate.SourceEntityName !== entityName && parentConfig?.Relationships
+                        ? { Relationships: parentConfig.Relationships }
+                        : undefined,
+                    PresetConfig: presetEdgeOverrides ? {
+                        EdgeOverrides: presetEdgeOverrides,
+                    } : undefined,
+                    RequestOverrides: edgeOverrides.map((o) => ({
+                        RelationshipID: o.RelationshipID,
+                        Policy: o.Policy,
+                    })),
+                    IsUniqueFK: joinFieldInfo?.IsUnique,
+                    CurrentDepth: candidate.Depth,
+                    MaxDepth: maxDepth,
+                });
+                warnings.push(...resolution.Warnings);
+                candidateEdges.push({
+                    FromKey: `${candidate.SourceEntityName}::${candidate.SourceKey.ToConcatenatedString()}`,
+                    ToKey: `${candidate.TargetEntityName}::${candidate.TargetKey ? candidate.TargetKey.ToConcatenatedString() : 'pending'}`,
+                    Kind: candidate.Kind,
+                    RelatedEntityName: candidate.TargetEntityName,
+                    Policy: resolution.Policy,
+                    PolicySource: resolution.PolicySource,
+                    Locked: resolution.Locked,
+                    JoinField: candidate.JoinField,
+                    RelationshipID: candidate.Relationship?.ID,
+                });
+                if (resolution.Policy === 'Skip') {
+                    excludedNodes.push({
+                        EntityName: candidate.TargetEntityName,
+                        SourceKey: candidate.TargetKey ? candidate.TargetKey.ToConcatenatedString() : '',
+                        Reason: `Edge policy resolved to Skip from ${resolution.PolicySource}`,
+                    });
+                }
+                return resolution.Policy;
+            },
+        }, contextUser);
+        // A root the walker couldn't load (a wrong ID, row-level security, no read permission) comes
+        // back empty. Planning it anyway would create a row from defaults and link it to a source
+        // that isn't there, so refuse. The message doesn't say which, so it can't reveal a hidden row.
+        if (!rootNode.RecordData || Object.keys(rootNode.RecordData).length === 0) {
+            warnings.push({
+                Code: 'SOURCE_NOT_FOUND',
+                Severity: 'Error',
+                Message: `The '${entityName}' record to clone wasn't found, or you can't read it.`,
+            });
+            // Nothing to map: planning on an empty row would only invent a Create node.
+            return refusedPlan();
+        }
+        // Flatten graph nodes, leaving out rows a relationship's ExcludeRows names (and everything under them)
+        const flatGraphNodes = this.dropExcludedRows(walker.FlattenTopological(rootNode), rootConfig, entityName, excludedNodes, warnings);
+        // Build concrete edges connecting discovered graph nodes
+        const edges = [];
+        for (const depNode of flatGraphNodes) {
+            if (depNode.DiscoveringEdge) {
+                const disc = depNode.DiscoveringEdge;
+                // Up and down a hierarchy share (from, entity, join field), so prefer the candidate
+                // for this exact target row when there is one.
+                const sameEdge = (c) => c.FromKey === disc.FromKey &&
+                    c.RelatedEntityName === disc.TargetEntityName &&
+                    c.JoinField.toLowerCase() === disc.JoinField.toLowerCase();
+                const cand = candidateEdges.find((c) => sameEdge(c) && c.ToKey === disc.ToKey) ?? candidateEdges.find(sameEdge);
+                edges.push({
+                    FromKey: disc.FromKey,
+                    ToKey: disc.ToKey,
+                    Kind: disc.Kind,
+                    RelatedEntityName: disc.TargetEntityName,
+                    Policy: cand?.Policy ?? 'Deep',
+                    PolicySource: cand?.PolicySource ?? 'Entity',
+                    Locked: cand?.Locked ?? false,
+                    JoinField: disc.JoinField,
+                    RelationshipID: disc.Relationship?.ID ?? cand?.RelationshipID,
+                });
+            }
+        }
+        for (const cand of candidateEdges) {
+            if (!edges.some(e => e.FromKey === cand.FromKey && e.ToKey === cand.ToKey && e.JoinField.toLowerCase() === cand.JoinField.toLowerCase())) {
+                edges.push(cand);
+            }
+        }
+        // Identify which nodes are 'Reference' nodes vs 'Create' candidates
+        // Root node (depth 0) is always Create candidate.
+        // Child node is Reference if reached via a 'Reference' edge or if its parent is Reference.
+        const referenceNodeKeys = new Set();
+        for (const depNode of flatGraphNodes) {
+            const nodeKey = `${depNode.EntityName}::${depNode.RecordID}`;
+            if (depNode.Depth === 0) {
+                continue;
+            }
+            const disc = depNode.DiscoveringEdge;
+            const parentKey = disc ? disc.FromKey : null;
+            const isParentReference = parentKey ? (referenceNodeKeys.has(parentKey) || referenceNodeKeys.has(parentKey.split('::')[1] ?? '')) : false;
+            const matchingEdge = disc ? edges.find(e => e.FromKey === disc.FromKey &&
+                e.ToKey === disc.ToKey &&
+                e.JoinField.toLowerCase() === disc.JoinField.toLowerCase()) : null;
+            const edgePolicy = matchingEdge?.Policy ?? (disc?.Kind === 'ForwardFK' || disc?.Kind === 'SelfPointer' ? 'Reference' : 'Deep');
+            if (isParentReference || edgePolicy === 'Reference') {
+                referenceNodeKeys.add(nodeKey);
+                referenceNodeKeys.add(depNode.RecordID);
+            }
+        }
+        // Check MaxRecords cap (only counts created nodes per spec §5.5)
+        const createCandidateNodes = flatGraphNodes.filter(n => !referenceNodeKeys.has(`${n.EntityName}::${n.RecordID}`));
+        if (createCandidateNodes.length > maxRecords) {
+            warnings.push({
+                Code: 'CAP_EXCEEDED',
+                Severity: 'Error',
+                Message: `Clone plan creates ${createCandidateNodes.length} records, which exceeds the configured MaxRecords cap of ${maxRecords}.`,
+            });
+            planBlocked = true;
+        }
+        // Allocate target keys for Created nodes (see CloneKeys.ts). Minted UUID keys go first and
+        // into the key map, so derived keys (composite or natural) can remap their FK columns to them.
+        const keyMap = {};
+        const targetKeys = new Map();
+        const unchangedKeyNodes = new Set();
+        const createNodes = flatGraphNodes.filter((n) => !referenceNodeKeys.has(`${n.EntityName}::${n.RecordID}`));
+        for (const depNode of createNodes) {
+            if (KeyStrategyFor(depNode.EntityInfo) !== 'mint')
+                continue;
+            const nodeKey = `${depNode.EntityName}::${depNode.RecordID}`;
+            const targetUuid = GenerateUUID();
+            targetKeys.set(nodeKey, targetUuid);
+            // Single-column key: map the source value (and the record id) to the new UUID so FK columns remap.
+            const sourceValue = String(depNode.RecordKey?.KeyValuePairs?.[0]?.Value ?? '');
+            for (const k of [depNode.RecordID, sourceValue]) {
+                if (!k)
+                    continue;
+                keyMap[k] = targetUuid;
+                keyMap[`${depNode.EntityName}::${k}`] = targetUuid;
+            }
+        }
+        // Rows whose key the database assigns: FK key columns pointing at them are filled at save.
+        const serverAssigned = new Set();
+        for (const depNode of createNodes) {
+            if (KeyStrategyFor(depNode.EntityInfo) !== 'server')
+                continue;
+            const sourceValue = String(depNode.RecordKey?.KeyValuePairs?.[0]?.Value ?? '');
+            if (sourceValue)
+                serverAssigned.add(`${depNode.EntityName}::${sourceValue}`);
+        }
+        for (const depNode of createNodes) {
+            const nodeKey = `${depNode.EntityName}::${depNode.RecordID}`;
+            const strategy = KeyStrategyFor(depNode.EntityInfo);
+            if (strategy === 'server') {
+                targetKeys.set(nodeKey, null); // the database assigns it on insert
+            }
+            else if (strategy === 'derived') {
+                const derived = DeriveTargetKey(depNode.EntityInfo, depNode.RecordKey, keyMap, serverAssigned);
+                const pks = depNode.EntityInfo.PrimaryKeys ?? [];
+                const onlyKey = pks.length === 1 ? depNode.EntityInfo.Fields.find((f) => f.Name === pks[0].Name) ?? pks[0] : null;
+                if (!derived.Changed && onlyKey && IsUuidColumn(onlyKey)) {
+                    // A single UUID key that is also an FK (an IS-A subtype) whose parent is not in the
+                    // clone: mint it; saving the subtype creates its parent row under the same ID.
+                    const targetUuid = GenerateUUID();
+                    targetKeys.set(nodeKey, targetUuid);
+                    keyMap[depNode.RecordID] = targetUuid;
+                    keyMap[`${depNode.EntityName}::${String(depNode.RecordKey.KeyValuePairs[0]?.Value ?? '')}`] = targetUuid;
+                    continue;
+                }
+                targetKeys.set(nodeKey, ToRecordKeyString(derived.Key));
+                if (!derived.Changed)
+                    unchangedKeyNodes.add(nodeKey);
+            }
+        }
+        // Retarget: point a root foreign key at another record. Only the fields the entity offers
+        // for it (Clone.UI.RetargetFields) apply; they then go through the field-override rules.
+        const retargetable = new Set((rootConfig?.UI?.RetargetFields ?? []).map((f) => f.toLowerCase()));
+        const retargetOverrides = {};
+        for (const r of request.Options?.Retarget ?? []) {
+            if (r.EntityName === entityName && retargetable.has(r.Field.toLowerCase())) {
+                retargetOverrides[r.Field] = r.Value;
+            }
+            else {
+                warnings.push({
+                    Code: 'OPTION_OVERRIDE_IGNORED',
+                    Severity: 'Warning',
+                    Field: r.Field,
+                    Message: `Retarget of '${r.EntityName}.${r.Field}' was ignored: the entity's clone configuration doesn't offer that field for retargeting.`,
+                });
+            }
+        }
+        // Naming for each row, and the names already taken, so a repeat clone doesn't collide at save.
+        const cloneConfigOf = (e) => e.CloneConfig ?? null;
+        // A request may pick the naming only where the configuration lets it edit fields, like any
+        // other request value: with UserEditable 'none' a caller can't ask for 'none' and keep the name.
+        const requestNaming = ['fields', 'all'].includes(rootConfig?.UserEditable ?? 'all');
+        const namingFor = (depNode) => {
+            if (depNode.Depth === 0) {
+                return {
+                    Template: (requestNaming ? request.Options?.Naming?.Template || request.Options?.NamingTemplate : undefined) || rootConfig?.Naming?.Template,
+                    Strategy: (requestNaming ? request.Options?.Naming?.Strategy || request.Options?.NamingStrategy : undefined) || rootConfig?.Naming?.Strategy || 'suffix',
+                    Context: { UserName: contextUser.Name },
+                };
+            }
+            const template = BagEntry(rootConfig?.Descendants, depNode.EntityName)?.Naming?.Template || cloneConfigOf(depNode.EntityInfo)?.Naming?.Template;
+            return {
+                Template: template,
+                Strategy: BagEntry(rootConfig?.Descendants, depNode.EntityName)?.Naming?.Strategy || cloneConfigOf(depNode.EntityInfo)?.Naming?.Strategy || (template ? 'suffix' : 'none'),
+                Context: { UserName: contextUser.Name },
+            };
+        };
+        const existingNames = await this.loadExistingNames(createNodes, namingFor, contextUser);
+        // Map nodes
+        const nodes = [];
+        const plannedNodesForCollisionCheck = [];
+        for (const depNode of flatGraphNodes) {
+            const nodeKey = `${depNode.EntityName}::${depNode.RecordID}`;
+            const isReference = referenceNodeKeys.has(nodeKey);
+            const entInfo = depNode.EntityInfo;
+            const isRoot = depNode.Depth === 0;
+            const disc = depNode.DiscoveringEdge;
+            const viaEdge = disc ? edges.find(e => e.FromKey === disc.FromKey &&
+                e.ToKey === disc.ToKey &&
+                e.JoinField.toLowerCase() === disc.JoinField.toLowerCase()) ?? null : null;
+            if (isReference) {
+                const planNode = {
+                    Key: nodeKey,
+                    NodeKey: nodeKey,
+                    EntityName: depNode.EntityName,
+                    SourceKey: depNode.RecordID,
+                    TargetKey: null,
+                    Action: 'Reference',
+                    Reason: 'Referenced existing record',
+                    Depth: depNode.Depth,
+                    ParentKey: disc ? disc.FromKey : null,
+                    Via: viaEdge,
+                    DisplayName: (depNode.RecordData?.[entInfo.NameField?.Name || 'Name'] ? String(depNode.RecordData[entInfo.NameField?.Name || 'Name']) : null) || depNode.EntityName,
+                    FieldChanges: [],
+                    Warnings: [],
+                    Route: 'Sidecar',
+                };
+                nodes.push(planNode);
+                continue;
+            }
+            const perms = entInfo.GetUserPermisions(contextUser);
+            let nodeBlocked = false;
+            if (!perms.CanCreate) {
+                warnings.push({
+                    Code: 'NO_CREATE_PERMISSION',
+                    Severity: 'Error',
+                    NodeKey: nodeKey,
+                    Message: `User lacks CanCreate permission on entity '${depNode.EntityName}'.`,
+                });
+                nodeBlocked = true;
+                planBlocked = true;
+            }
+            // Every created row is checked against its own entity's clone authorization (plan §9.1).
+            // The root's own check ran above; repeating it would only duplicate the warning.
+            const nodeAuth = isRoot ? rootAuth : authorizer.CanCloneEntity(entInfo, contextUser);
+            if (!isRoot && !nodeAuth.Granted) {
+                warnings.push({
+                    Code: 'FORBIDDEN',
+                    Severity: 'Error',
+                    NodeKey: nodeKey,
+                    Message: `Copying '${depNode.EntityName}' rows requires the '${nodeAuth.Name}' authorization. Set that relationship to Reference or Skip, or ask for the authorization.`,
+                });
+                nodeBlocked = true;
+                planBlocked = true;
+            }
+            const targetKey = targetKeys.get(nodeKey) ?? null;
+            // A derived key with no remapped column equals the source key; saving would collide.
+            if (unchangedKeyNodes.has(nodeKey)) {
+                warnings.push({
+                    Code: 'TARGET_KEY_UNCHANGED',
+                    Severity: 'Error',
+                    NodeKey: nodeKey,
+                    Message: `A copy of this '${depNode.EntityName}' row would keep the same primary key (${depNode.EntityInfo.PrimaryKeys.map((k) => k.Name).join(', ')}), because none of its key columns point at a record being cloned. Skip that relationship, or clone it from a parent whose key it contains.`,
+                });
+                nodeBlocked = true;
+                planBlocked = true;
+            }
+            const fieldMappingResult = MapFieldsForClone({
+                EntityName: depNode.EntityName,
+                Fields: FieldMetaFromEntity(entInfo),
+                SourceRecord: depNode.RecordData,
+                CurrentUserId: contextUser.ID,
+                KeyMap: keyMap,
+                NamingOptions: {
+                    ...namingFor(depNode),
+                    UserName: contextUser.Name,
+                    ExistingNamesByField: existingNames.get(depNode.EntityName),
+                },
+                FieldRules: (() => {
+                    const entConfig = entInfo.CloneConfig ?? null;
+                    const descConfig = !isRoot ? BagEntry(rootConfig?.Descendants, depNode.EntityName) : undefined;
+                    const entOwnership = entConfig?.Fields?.Ownership || entConfig?.Ownership;
+                    const descOwnership = descConfig?.Fields?.Ownership || descConfig?.Ownership;
+                    const combinedOwnership = [
+                        ...(entOwnership || []),
+                        ...(descOwnership || []),
+                    ];
+                    const combinedExclude = [
+                        ...(entConfig?.Fields?.Exclude || []),
+                        ...(descConfig?.Fields?.Exclude || []),
+                    ];
+                    const combinedReset = {
+                        ...(entConfig?.Fields?.Reset || {}),
+                        ...(descConfig?.Fields?.Reset || {}),
+                    };
+                    const combinedServerAllocated = [
+                        ...(entConfig?.Fields?.ServerAllocated || []),
+                        ...(descConfig?.Fields?.ServerAllocated || []),
+                    ];
+                    const combinedPromptFor = [
+                        ...(entConfig?.Fields?.PromptFor || []),
+                        ...(descConfig?.Fields?.PromptFor || []),
+                    ];
+                    const hasRules = combinedOwnership.length > 0 ||
+                        combinedExclude.length > 0 ||
+                        Object.keys(combinedReset).length > 0 ||
+                        combinedServerAllocated.length > 0 ||
+                        combinedPromptFor.length > 0 ||
+                        entConfig?.Fields?.Rules ||
+                        descConfig?.Fields?.Rules ||
+                        entConfig?.Fields?.JsonRemap;
+                    if (!hasRules)
+                        return undefined;
+                    return {
+                        Exclude: combinedExclude.length > 0 ? combinedExclude : undefined,
+                        Reset: Object.keys(combinedReset).length > 0 ? combinedReset : undefined,
+                        Ownership: combinedOwnership.length > 0 ? combinedOwnership : undefined,
+                        ServerAllocated: combinedServerAllocated.length > 0 ? combinedServerAllocated : undefined,
+                        PromptFor: combinedPromptFor.length > 0 ? combinedPromptFor : undefined,
+                        Rules: (descConfig?.Fields?.Rules ?? entConfig?.Fields?.Rules),
+                        JsonRemap: entConfig?.Fields?.JsonRemap,
+                    };
+                })(),
+                RequestOverrides: isRoot ? { ...(request.FieldOverrides ?? request.Options?.FieldOverrides ?? {}), ...retargetOverrides } : undefined,
+                PromptedValues: isRoot ? (request.PromptedValues ?? request.Options?.PromptedValues) : undefined,
+                RequestFieldsEditable: ['fields', 'all'].includes(rootConfig?.UserEditable ?? 'all'),
+                FLS: fieldLevelDenials(entInfo, contextUser),
+                IsRoot: isRoot,
+                HierarchyParentField: entInfo.Fields.find((f) => f.IsHierarchy)?.Name,
+                // Undefined keeps the root under its current parent; a value (or null) moves it.
+                NewParentKey: isRoot ? request.Options?.NewParentKey : undefined,
+            });
+            // IS-A subtype and embedded rows need their own save recipe (AttachToParent, the owner's
+            // FK), which this release doesn't implement: routing them through a collection would
+            // insert a second parent row or write a column the peer doesn't have. Refuse instead.
+            if (disc && (disc.Kind === 'IsASubtype' || disc.Kind === 'Embedded') && viaEdge?.Policy === 'Deep') {
+                warnings.push({
+                    Code: 'EDGE_KIND_UNSUPPORTED',
+                    Severity: 'Error',
+                    NodeKey: nodeKey,
+                    Message: `Copying ${disc.Kind === 'IsASubtype' ? 'IS-A subtype' : 'embedded'} rows ('${depNode.EntityName}') isn't supported yet. Set Subtypes to exclude, or that relationship to Reference or Skip.`,
+                });
+                planBlocked = true;
+                nodeBlocked = true;
+            }
+            // Prompted fields are the ones the user must supply (Email on a user clone): without a
+            // value the copy would carry the source's, so the plan can't run until they're entered.
+            if (isRoot) {
+                const prompted = request.PromptedValues ?? request.Options?.PromptedValues ?? {};
+                for (const field of rootConfig?.Fields?.PromptFor ?? []) {
+                    const value = prompted[field];
+                    if (value === undefined || value === null || (typeof value === 'string' && value.trim() === '')) {
+                        warnings.push({
+                            Code: 'UNIQUE_PROMPT_REQUIRED',
+                            Severity: 'Error',
+                            NodeKey: nodeKey,
+                            Field: field,
+                            Message: `Enter a value for '${field}': the copy can't reuse the source's.`,
+                        });
+                        planBlocked = true;
+                    }
+                }
+            }
+            for (const field of fieldMappingResult.NamingFailures) {
+                warnings.push({
+                    Code: 'NAME_UNAVAILABLE',
+                    Severity: 'Error',
+                    NodeKey: nodeKey,
+                    Field: field,
+                    Message: `No free value for '${field}' fits the column: every candidate is taken or too long. Enter a name, or clear an existing copy.`,
+                });
+                planBlocked = true;
+            }
+            for (const ignored of fieldMappingResult.IgnoredRequestValues) {
+                warnings.push({
+                    Code: 'OPTION_OVERRIDE_IGNORED',
+                    Severity: 'Warning',
+                    NodeKey: nodeKey,
+                    Field: ignored.Field,
+                    Message: `${ignored.Kind === 'Prompt' ? 'Prompted value' : 'Override'} for '${ignored.Field}' was ignored: ${ignored.Reason}.`,
+                });
+            }
+            const planNode = {
+                Key: nodeKey,
+                NodeKey: nodeKey,
+                EntityName: depNode.EntityName,
+                SourceKey: depNode.RecordID,
+                TargetKey: targetKey,
+                Action: nodeBlocked ? 'Blocked' : 'Create',
+                Reason: nodeBlocked ? 'Permission error' : 'Clone record',
+                Depth: depNode.Depth,
+                ParentKey: depNode.DiscoveringEdge ? depNode.DiscoveringEdge.FromKey : null,
+                Via: viaEdge,
+                DisplayName: (depNode.RecordData?.[entInfo.NameField?.Name || 'Name'] ? String(depNode.RecordData[entInfo.NameField?.Name || 'Name']) : null) || depNode.EntityName,
+                FieldChanges: fieldMappingResult.FieldChanges,
+                Warnings: [],
+                Route: isRoot ? 'RootSave' : 'Collection',
+            };
+            nodes.push(planNode);
+            plannedNodesForCollisionCheck.push({
+                NodeKey: planNode.NodeKey ?? planNode.Key,
+                EntityName: planNode.EntityName,
+                ParentKey: planNode.ParentKey,
+                Values: fieldMappingResult.MappedValues,
+            });
+        }
+        // Intra-plan collision detection across siblings
+        const uniqueKeysByEntity = {};
+        for (const depNode of flatGraphNodes) {
+            const nodeKey = `${depNode.EntityName}::${depNode.RecordID}`;
+            if (referenceNodeKeys.has(nodeKey)) {
+                continue;
+            }
+            if (!uniqueKeysByEntity[depNode.EntityName]) {
+                const uqs = [];
+                if (depNode.EntityInfo.CloneConfig?.Fields?.UniqueKeys && depNode.EntityInfo.CloneConfig.Fields.UniqueKeys.length > 0) {
+                    uqs.push(...depNode.EntityInfo.CloneConfig.Fields.UniqueKeys);
+                }
+                else {
+                    // Metadata flags every column of a composite unique constraint IsUnique (Action
+                    // Params: Name and ActionID, unique together), so the flagged columns form one key.
+                    // A copy whose FK column is remapped then never collides with its source.
+                    const flagged = depNode.EntityInfo.Fields.filter((f) => f.IsUnique && !f.IsPrimaryKey).map((f) => f.Name);
+                    if (flagged.length > 0)
+                        uqs.push({ Fields: flagged, Scope: 'Global' });
+                }
+                uniqueKeysByEntity[depNode.EntityName] = uqs;
+            }
+        }
+        const intraPlanCollisions = DetectIntraPlanCollisions(plannedNodesForCollisionCheck, uniqueKeysByEntity);
+        if (intraPlanCollisions.length > 0) {
+            for (const col of intraPlanCollisions) {
+                warnings.push({
+                    Code: 'INTRA_PLAN_COLLISION',
+                    Severity: 'Error',
+                    NodeKey: col.NodeKeyB,
+                    Message: `Intra-plan collision detected between '${col.NodeKeyA}' and '${col.NodeKeyB}' on unique fields: [${col.Fields.join(', ')}].`,
+                });
+                planBlocked = true;
+            }
+        }
+        // Calculate Plan Hash (ignoring TargetKey values)
+        const planHash = ComputeClonePlanHash({
+            Nodes: nodes,
+            Edges: edges,
+            Excluded: excludedNodes,
+        });
+        const byEntity = {};
+        for (const n of nodes) {
+            if (!byEntity[n.EntityName]) {
+                byEntity[n.EntityName] = { Create: 0, Reference: 0, Skip: 0 };
+            }
+            if (n.Action === 'Create')
+                byEntity[n.EntityName].Create++;
+            else if (n.Action === 'Reference')
+                byEntity[n.EntityName].Reference++;
+            else if (n.Action === 'Skip')
+                byEntity[n.EntityName].Skip++;
+        }
+        const createCount = nodes.filter((n) => n.Action === 'Create').length;
+        // The root's own planned key; empty when the database assigns it on insert.
+        const rootTargetKey = targetKeys.get(`${entityName}::${key.ToConcatenatedString()}`) ?? '';
+        return {
+            PlanVersion: 1,
+            Hash: planHash,
+            PlanHash: planHash,
+            Roots: [`${entityName}::${key.ToConcatenatedString()}`],
+            RootEntityName: entityName,
+            RootSourceKey: key.ToConcatenatedString(),
+            RootTargetKey: rootTargetKey,
+            Nodes: nodes,
+            Edges: edges,
+            Excluded: excludedNodes,
+            Counts: {
+                ByEntity: byEntity,
+                Create: createCount,
+                Total: nodes.length,
+            },
+            Warnings: warnings,
+            Blocked: planBlocked,
+            EffectiveOptions: effectiveOptions,
+            Overrides: resolved.Overrides,
+            Reason: request.Options?.Reason,
+        };
+    }
+    /**
+     * Values already taken in each field a clone renames, per entity, found with one prefix query
+     * per (entity, field). Without them the rename can't avoid "Sales (copy)" on the second clone.
+     */
+    async loadExistingNames(createNodes, namingFor, contextUser) {
+        const prefixes = new Map();
+        for (const node of createNodes) {
+            const naming = namingFor(node);
+            for (const field of FieldMetaFromEntity(node.EntityInfo).filter(IsRenameField)) {
+                const value = node.RecordData?.[field.Name];
+                if (value === null || value === undefined || value === '')
+                    continue;
+                // LIKE wildcards and SQL Server's [ ] classes can't be escaped portably (PostgreSQL's
+                // provider rewrites [word] even inside literals), so match on the text before the first
+                // one. That only widens the lookup; names are compared exactly afterwards.
+                const full = NameCollisionPrefix(String(value), { ...naming, MaxLength: field.MaxLength });
+                if (!full)
+                    continue; // this strategy doesn't rename
+                const prefix = full.split(/[[\]%_\\]/)[0]; // may be '' — then every value is read
+                const k = `${node.EntityName}\u0000${field.Name}`;
+                if (!prefixes.has(k))
+                    prefixes.set(k, { entity: node.EntityName, field: field.Name, prefixes: new Set() });
+                prefixes.get(k).prefixes.add(prefix);
+            }
+        }
+        const result = new Map();
+        const rv = RunView.FromMetadataProvider(this.Provider);
+        for (const { entity, field, prefixes: set } of prefixes.values()) {
+            const all = [...set];
+            const taken = new Set();
+            for (let i = 0; i < all.length; i += 50) {
+                const filter = all.slice(i, i + 50).map((p) => (p ? `${field} LIKE '${EscapeSQLString(p)}%'` : `${field} IS NOT NULL`)).join(' OR ');
+                const res = await rv.RunView({ EntityName: entity, Fields: [field], ExtraFilter: `(${filter})`, ResultType: 'simple', MaxRows: 5000 }, contextUser);
+                for (const row of res?.Success ? res.Results ?? [] : []) {
+                    if (row[field] !== null && row[field] !== undefined)
+                        taken.add(String(row[field]));
+                }
+            }
+            if (!result.has(entity))
+                result.set(entity, {});
+            result.get(entity)[field] = taken;
+        }
+        return result;
+    }
+    /**
+     * Drops rows matching their relationship's `ExcludeRows`, with every row discovered beneath them.
+     * The rule is looked up in the same order as the edge's policy (`ResolveEdgePolicy`): the
+     * relationship's own bag, then the root's entry by relationship ID, `Child.JoinField`, then
+     * `Child`. One Info warning per relationship.
+     */
+    dropExcludedRows(nodes, rootConfig, rootEntityName, excludedNodes, warnings) {
+        const dropped = new Set();
+        const counts = new Map();
+        // Keyed by entity and record, as the walker's edge keys are: a bare record ID can repeat across entities.
+        const isDropped = (key) => dropped.has(key);
+        const kept = [];
+        for (const node of nodes) {
+            const edge = node.DiscoveringEdge;
+            if (!edge) {
+                kept.push(node);
+                continue;
+            }
+            // Same chain as ResolveEdgePolicy: the relationship's own bag, the root's entry (by
+            // relationship ID, Child.JoinField, Child), then, below the root, the parent entity's own
+            // entry. Descendants entries carry field rules, not row exclusions. A bare child key in the
+            // root's bag applies only to edges from the root's entity.
+            const entryIn = (bag, bareKey) => (edge.Relationship?.ID ? BagEntry(bag, edge.Relationship.ID)?.ExcludeRows : undefined) ??
+                BagEntry(bag, `${edge.TargetEntityName}.${edge.JoinField}`)?.ExcludeRows ??
+                (bareKey ? BagEntry(bag, edge.TargetEntityName)?.ExcludeRows : undefined);
+            const parentBag = edge.SourceEntityName !== rootEntityName ? this.Provider.EntityByName(edge.SourceEntityName)?.CloneConfig?.Relationships : undefined;
+            const rules = edge.Relationship?.CloneConfig?.ExcludeRows ??
+                entryIn(rootConfig?.Relationships, IsEdgeFromRoot(edge.SourceEntityName, rootEntityName)) ??
+                entryIn(parentBag, true);
+            const matched = RowMatchesExclusion(node.RecordData ?? {}, rules);
+            if (!matched && !isDropped(edge.FromKey)) {
+                kept.push(node);
+                continue;
+            }
+            dropped.add(`${node.EntityName}::${node.RecordID}`);
+            excludedNodes.push({
+                EntityName: node.EntityName,
+                SourceKey: node.RecordID,
+                Reason: matched ? 'Row matches the relationship\'s ExcludeRows.' : 'Parent row was excluded.',
+            });
+            if (matched)
+                counts.set(node.EntityName, (counts.get(node.EntityName) ?? 0) + 1);
+        }
+        for (const [entityName, count] of counts) {
+            warnings.push({
+                Code: 'ROWS_EXCLUDED',
+                Severity: 'Info',
+                Message: `${count} ${entityName} row${count === 1 ? '' : 's'} left out by the configuration (per-person or per-device data).`,
+            });
+        }
+        return kept;
+    }
+}
+//# sourceMappingURL=ClonePlanner.js.map