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

package/dist/ClonePolicyResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClonePolicyResolver.d.ts","sourceRoot":"","sources":["../src/ClonePolicyResolver.ts"],"names":[],"mappings":"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"}

package/dist/ClonePolicyResolver.js

@@ -0,0 +1,247 @@
+/**
+ * @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 { EvaluateExclusionClass } from './ExclusionClasses.js';
+/**
+ * Resolves the edge traversal policy according to the 8-tier precedence hierarchy.
+ */
+export function ResolveEdgePolicy(ctx) {
+    const warnings = [];
+    const configuredPolicy = ctx.RelationshipConfig?.Policy ??
+        rootRelationship(ctx)?.Policy ??
+        BagEntry(ctx.RootEntityConfig?.Descendants, ctx.ChildEntityName)?.Policy ??
+        parentRelationship(ctx)?.Policy;
+    // TIER 0 / EXCLUSION. Explicit NotCloneable and AllowCreateAPI=false win unconditionally.
+    // The name heuristics only apply when no configuration says what to do with this edge.
+    const exclusion = EvaluateExclusionClass({
+        EntityName: ctx.ChildEntityName,
+        NotCloneable: ctx.ChildEntityConfig?.NotCloneable,
+        NotCloneableReason: ctx.ChildEntityConfig?.NotCloneableReason,
+        AllowCreateAPI: ctx.ChildEntityConfig?.AllowCreateAPI,
+        HeuristicsOnly: false,
+    });
+    const heuristic = configuredPolicy
+        ? { Excluded: false }
+        : EvaluateExclusionClass({ EntityName: ctx.ChildEntityName, HeuristicsOnly: true });
+    for (const result of [exclusion, heuristic]) {
+        if (!result.Excluded)
+            continue;
+        // Say so only when something would otherwise copy these rows. Unlisted relationships are
+        // skipped anyway, and a note for each of them buries the warnings that matter.
+        return {
+            Policy: 'Skip',
+            PolicySource: 'Entity',
+            Locked: true,
+            Warnings: wouldCopy(ctx, configuredPolicy)
+                ? [
+                    {
+                        Code: 'NOT_CLONEABLE',
+                        Severity: 'Warning',
+                        NodeKey: ctx.ToKey,
+                        Message: result.Reason || `Child entity '${ctx.ChildEntityName}' is excluded or NotCloneable.`,
+                    },
+                ]
+                : [],
+        };
+    }
+    // 1. Engine Built-in Default
+    let policy = 'Skip';
+    let policySource = 'BuiltIn';
+    let locked = false;
+    switch (ctx.Kind) {
+        case 'IsASubtype':
+        case 'Embedded':
+        case 'Collection':
+            policy = 'Deep';
+            break;
+        case 'Relationship':
+            // Unlisted one-to-many relationships are not followed: CodeGen creates one for every FK,
+            // so following them by default copies (and grafts rows onto) records the clone doesn't own.
+            policy = 'Skip';
+            break;
+        case 'ForwardFK':
+        case 'SelfPointer':
+            policy = 'Reference';
+            break;
+        case 'InboundFK':
+        case 'SoftLink':
+            policy = 'Skip';
+            break;
+        case 'Hierarchy':
+            // A self-relationship is a tree only when its join column is flagged IsHierarchy.
+            policy = ctx.IsHierarchyField ? 'Deep' : 'Skip';
+            break;
+        default:
+            policy = 'Skip';
+            break;
+    }
+    // 2. Constraint-derived decisions are applied at the end: a unique FK only rules out Reference.
+    // 3. Child Entity Bag (already handled NotCloneable above)
+    // 4. Relationship Bag (IEntityRelationshipConfiguration.Clone)
+    if (ctx.RelationshipConfig) {
+        if (ctx.RelationshipConfig.Locked) {
+            locked = true;
+        }
+        if (ctx.RelationshipConfig.Policy) {
+            policy = ctx.RelationshipConfig.Policy;
+            policySource = 'Relationship';
+        }
+    }
+    // 4b. The parent entity's own configuration, below the root
+    const parentMatch = parentRelationship(ctx);
+    if (parentMatch) {
+        if (parentMatch.Locked)
+            locked = true;
+        if (parentMatch.Policy) {
+            policy = parentMatch.Policy;
+            policySource = 'Entity';
+        }
+    }
+    // 5. Root Entity Bag (Relationships & Descendants)
+    if (ctx.RootEntityConfig) {
+        const relMatch = rootRelationship(ctx);
+        if (relMatch) {
+            if (relMatch.Locked)
+                locked = true;
+            if (relMatch.Policy) {
+                policy = relMatch.Policy;
+                policySource = 'Descendant';
+            }
+        }
+        const descMatch = BagEntry(ctx.RootEntityConfig.Descendants, ctx.ChildEntityName);
+        if (descMatch) {
+            if (descMatch.Locked)
+                locked = true;
+            if (descMatch.Policy) {
+                policy = descMatch.Policy;
+                policySource = 'Descendant';
+            }
+        }
+    }
+    // 6. Preset (a Locked edge keeps its configured policy)
+    if (ctx.PresetConfig?.EdgeOverrides) {
+        const presetOverride = ctx.PresetConfig.EdgeOverrides.find((o) => (ctx.RelationshipID && o.RelationshipID === ctx.RelationshipID) ||
+            (o.ChildEntityName && o.ChildEntityName === ctx.ChildEntityName));
+        if (presetOverride && locked) {
+            warnings.push({
+                Code: 'LOCKED_EDGE_OVERRIDE_IGNORED',
+                Severity: 'Warning',
+                NodeKey: ctx.ToKey,
+                Message: `Preset policy '${presetOverride.Policy}' for edge to '${ctx.ChildEntityName}' was ignored because the edge is locked.`,
+            });
+        }
+        else if (presetOverride) {
+            policy = presetOverride.Policy;
+            policySource = 'Descendant';
+        }
+    }
+    // 7. Request Overrides
+    if (ctx.RequestOverrides && ctx.RequestOverrides.length > 0) {
+        const reqOverride = ctx.RequestOverrides.find((o) => {
+            if (o.RelationshipID && ctx.RelationshipID && o.RelationshipID === ctx.RelationshipID) {
+                return true;
+            }
+            if (o.FromKey && o.ToKey && o.FromKey === ctx.FromKey && o.ToKey === ctx.ToKey) {
+                return true;
+            }
+            return false;
+        });
+        if (reqOverride) {
+            if (locked) {
+                // Locked edge: user override is ignored with warning
+                warnings.push({
+                    Code: 'LOCKED_EDGE_OVERRIDE_IGNORED',
+                    Severity: 'Warning',
+                    NodeKey: ctx.ToKey,
+                    Message: `Override to '${reqOverride.Policy}' for edge to '${ctx.ChildEntityName}' was ignored because the edge is locked.`,
+                });
+            }
+            else {
+                policy = reqOverride.Policy;
+                policySource = 'Request';
+            }
+        }
+    }
+    // Unique FK: the child row can belong to one parent only, so pointing the copy at the same
+    // child (Reference) is impossible. Deep is the only way to follow it; Skip is always safe.
+    if (ctx.IsUniqueFK && policy === 'Reference') {
+        policy = 'Deep';
+        policySource = 'Constraint';
+        warnings.push({
+            Code: 'CONSTRAINT_FORCED_DEEP',
+            Severity: 'Warning',
+            NodeKey: ctx.ToKey,
+            Message: `Unique FK constraint on '${ctx.JoinField}' makes Reference impossible; the child is copied instead.`,
+        });
+    }
+    return {
+        Policy: policy,
+        PolicySource: policySource,
+        Locked: locked,
+        Warnings: warnings,
+    };
+}
+/**
+ * The root's entry for this edge: by relationship ID or "<Child>.<JoinField>" at any depth, by bare
+ * child name only on edges from the root's entity. A child can hang from several entities in the walk
+ * (AI Agent Actions from the agent by AgentID and from a copied prompt by CompactPromptID); a bare key
+ * written for the root's own rows must not copy another record's rows that point at a copied one.
+ */
+function rootRelationship(ctx) {
+    const rels = ctx.RootEntityConfig?.Relationships;
+    if (!rels)
+        return undefined;
+    return ((ctx.RelationshipID ? BagEntry(rels, ctx.RelationshipID) : undefined) ??
+        BagEntry(rels, `${ctx.ChildEntityName}.${ctx.JoinField}`) ??
+        (IsEdgeFromRoot(ctx.ParentEntityName, ctx.RootEntityName) ? BagEntry(rels, ctx.ChildEntityName) : undefined));
+}
+/** Whether an edge from `parentEntityName` starts at the root's entity (ignoring case); true when the root isn't given. */
+export function IsEdgeFromRoot(parentEntityName, rootEntityName) {
+    return !rootEntityName || parentEntityName.toLowerCase() === rootEntityName.toLowerCase();
+}
+/** The parent entity's own entry for this edge: by relationship ID, "<Child>.<JoinField>", or child name. */
+function parentRelationship(ctx) {
+    const rels = ctx.ParentEntityConfig?.Relationships;
+    if (!rels)
+        return undefined;
+    return (ctx.RelationshipID ? BagEntry(rels, ctx.RelationshipID) : undefined) ?? BagEntry(rels, `${ctx.ChildEntityName}.${ctx.JoinField}`) ?? BagEntry(rels, ctx.ChildEntityName);
+}
+/**
+ * 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 function BagEntry(bag, key) {
+    if (!bag || !key)
+        return undefined;
+    if (key in bag)
+        return bag[key];
+    const target = key.toLowerCase();
+    const found = Object.keys(bag).find((k) => k.toLowerCase() === target);
+    return found === undefined ? undefined : bag[found];
+}
+/** Whether anything asks for this edge to be copied: configuration, the edge kind's default, a preset or the request. */
+function wouldCopy(ctx, configuredPolicy) {
+    if (configuredPolicy === 'Deep')
+        return true;
+    if (configuredPolicy === undefined) {
+        const deepByDefault = ctx.Kind === 'IsASubtype' || ctx.Kind === 'Embedded' || ctx.Kind === 'Collection' || (ctx.Kind === 'Hierarchy' && ctx.IsHierarchyField === true);
+        if (deepByDefault)
+            return true;
+    }
+    const preset = ctx.PresetConfig?.EdgeOverrides?.some((o) => o.Policy === 'Deep' && ((ctx.RelationshipID && o.RelationshipID === ctx.RelationshipID) || o.ChildEntityName === ctx.ChildEntityName));
+    const request = ctx.RequestOverrides?.some((o) => o.Policy === 'Deep' && ((o.RelationshipID && o.RelationshipID === ctx.RelationshipID) || (o.FromKey === ctx.FromKey && o.ToKey === ctx.ToKey)));
+    return !!preset || !!request;
+}
+//# sourceMappingURL=ClonePolicyResolver.js.map

package/dist/ClonePolicyResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClonePolicyResolver.js","sourceRoot":"","sources":["../src/ClonePolicyResolver.ts"],"names":[],"mappings":"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"}

package/dist/EffectiveOptions.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @file EffectiveOptions.ts
+ * Resolves the options a clone plan actually runs with from the root entity's clone
+ * configuration and the caller's request.
+ *
+ * - The entity's `Configuration.Clone` supplies every default.
+ * - **Narrowing** scope (lower caps; excluding subtypes, soft links or the hierarchy subtree) is
+ *   allowed when `UserEditable` is `'scope'` or `'all'` (the default), or for an override holder.
+ * - **Widening** scope (higher caps; including what the configuration leaves out) needs the
+ *   `Clone Records: Override Scope` authorization, whatever `UserEditable` says.
+ * - Entity Actions fire by default and AI Actions are suppressed; the configuration's `Hooks`
+ *   changes either. Changing that from a request, in either direction, needs
+ *   `Clone Records: Fire Hooks`: suppressing automations is as consequential as firing them.
+ *
+ * Every ignored request value produces a warning, so the review shows what was not applied.
+ *
+ * @see plans/record-cloning/README.md §4.1, §9.4
+ */
+import type { CloneRequestOptions, ClonePlan, CloneWarning } from './types.js';
+/** The subset of `IEntityCloneConfiguration` this resolver reads. */
+export interface EffectiveOptionsConfig {
+    MaxDepth?: number;
+    MaxRecords?: number;
+    Subtypes?: 'include' | 'exclude';
+    Hierarchy?: 'subtree' | 'node';
+    SoftLinks?: 'skip' | 'include';
+    Embeddings?: 'copy' | 'regenerate';
+    UserEditable?: 'none' | 'fields' | 'scope' | 'all';
+    Hooks?: {
+        EntityActions?: 'suppress' | 'fire';
+        AIActions?: 'suppress' | 'fire';
+    };
+}
+export type EffectiveCloneOptions = ClonePlan['EffectiveOptions'];
+/** What the caller is authorized to do beyond the entity's configuration. */
+export interface CloneOptionGrants {
+    /** Holds `Clone Records: Fire Hooks`: may change whether Entity Actions / AI Actions run. */
+    CanFireHooks: boolean;
+    /** Holds `Clone Records: Override Scope`. */
+    CanOverrideScope: boolean;
+}
+/** Built-in defaults when neither the entity nor the request says otherwise. */
+export declare const DEFAULT_CLONE_MAX_DEPTH = 3;
+export declare const DEFAULT_CLONE_MAX_RECORDS = 500;
+/** Entity Actions on the cloned rows run, as they would for any create. */
+export declare const DEFAULT_CLONE_ENTITY_ACTIONS: 'suppress' | 'fire';
+/** AI Actions stay off unless configured: each can be a paid model call per cloned row. */
+export declare const DEFAULT_CLONE_AI_ACTIONS: 'suppress' | 'fire';
+export interface EffectiveOptionsResult {
+    Options: EffectiveCloneOptions;
+    Warnings: CloneWarning[];
+    /** Options changed beyond the configuration under an authorization (Override Scope, Fire Hooks); recorded on the clone log. */
+    Overrides: string[];
+}
+/**
+ * Merges the request's options onto the entity's configured defaults under the rules above.
+ * @param config The root entity's clone configuration, or null when it has none.
+ * @param request The options the caller sent.
+ * @param grants What the caller is authorized to do beyond the configuration.
+ */
+export declare function ResolveEffectiveCloneOptions(config: EffectiveOptionsConfig | null | undefined, request: CloneRequestOptions | null | undefined, grants: CloneOptionGrants): EffectiveOptionsResult;
+/** A preset in the documented `Clone.Presets` array shape. */
+export interface NormalizedClonePreset {
+    Key: string;
+    Label: string;
+    Description?: string;
+    Options?: CloneRequestOptions;
+    Relationships?: Record<string, {
+        Policy: 'Deep' | 'Reference' | 'Skip';
+    }>;
+}
+/**
+ * Reads `Clone.Presets` defensively. The documented shape is an array of `{ Key, Label, ... }`;
+ * the legacy keyed-object form (`{ "<key>": { Description, Relationships } }`) is still accepted,
+ * with the object key as `Key`. Anything else yields no presets rather than an exception.
+ */
+export declare function NormalizeClonePresets(presets: unknown): NormalizedClonePreset[];
+//# sourceMappingURL=EffectiveOptions.d.ts.map

package/dist/EffectiveOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EffectiveOptions.d.ts","sourceRoot":"","sources":["../src/EffectiveOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5E,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IACjC,SAAS,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IACnC,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,CAAC;IACnD,KAAK,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,UAAU,GAAG,MAAM,CAAA;KAAE,CAAC;CACpF;AAED,MAAM,MAAM,qBAAqB,GAAG,SAAS,CAAC,kBAAkB,CAAC,CAAC;AAElE,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAC9B,6FAA6F;IAC7F,YAAY,EAAE,OAAO,CAAC;IACtB,6CAA6C;IAC7C,gBAAgB,EAAE,OAAO,CAAC;CAC7B;AAED,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAC7C,2EAA2E;AAC3E,eAAO,MAAM,4BAA4B,EAAE,UAAU,GAAG,MAAe,CAAC;AACxE,2FAA2F;AAC3F,eAAO,MAAM,wBAAwB,EAAE,UAAU,GAAG,MAAmB,CAAC;AAExE,MAAM,WAAW,sBAAsB;IACnC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,+HAA+H;IAC/H,SAAS,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CACxC,MAAM,EAAE,sBAAsB,GAAG,IAAI,GAAG,SAAS,EACjD,OAAO,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,EAC/C,MAAM,EAAE,iBAAiB,GAC1B,sBAAsB,CA0FxB;AAED,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7E;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,qBAAqB,EAAE,CAyB/E"}

package/dist/EffectiveOptions.js

@@ -0,0 +1,156 @@
+/**
+ * @file EffectiveOptions.ts
+ * Resolves the options a clone plan actually runs with from the root entity's clone
+ * configuration and the caller's request.
+ *
+ * - The entity's `Configuration.Clone` supplies every default.
+ * - **Narrowing** scope (lower caps; excluding subtypes, soft links or the hierarchy subtree) is
+ *   allowed when `UserEditable` is `'scope'` or `'all'` (the default), or for an override holder.
+ * - **Widening** scope (higher caps; including what the configuration leaves out) needs the
+ *   `Clone Records: Override Scope` authorization, whatever `UserEditable` says.
+ * - Entity Actions fire by default and AI Actions are suppressed; the configuration's `Hooks`
+ *   changes either. Changing that from a request, in either direction, needs
+ *   `Clone Records: Fire Hooks`: suppressing automations is as consequential as firing them.
+ *
+ * Every ignored request value produces a warning, so the review shows what was not applied.
+ *
+ * @see plans/record-cloning/README.md §4.1, §9.4
+ */
+/** Built-in defaults when neither the entity nor the request says otherwise. */
+export const DEFAULT_CLONE_MAX_DEPTH = 3;
+export const DEFAULT_CLONE_MAX_RECORDS = 500;
+/** Entity Actions on the cloned rows run, as they would for any create. */
+export const DEFAULT_CLONE_ENTITY_ACTIONS = 'fire';
+/** AI Actions stay off unless configured: each can be a paid model call per cloned row. */
+export const DEFAULT_CLONE_AI_ACTIONS = 'suppress';
+/**
+ * Merges the request's options onto the entity's configured defaults under the rules above.
+ * @param config The root entity's clone configuration, or null when it has none.
+ * @param request The options the caller sent.
+ * @param grants What the caller is authorized to do beyond the configuration.
+ */
+export function ResolveEffectiveCloneOptions(config, request, grants) {
+    const warnings = [];
+    const overrides = [];
+    const editable = config?.UserEditable ?? 'all';
+    const mayNarrow = editable === 'scope' || editable === 'all' || grants.CanOverrideScope;
+    const narrowIgnored = (option, value) => {
+        warnings.push({
+            Code: 'OPTION_OVERRIDE_IGNORED',
+            Severity: 'Warning',
+            Field: option,
+            Message: `${option} = ${String(value)} was ignored: this entity's clone configuration sets UserEditable to '${editable}'.`,
+        });
+    };
+    const widenIgnored = (option, value, configured) => {
+        warnings.push({
+            Code: 'SCOPE_OVERRIDE_FORBIDDEN',
+            Severity: 'Warning',
+            Field: option,
+            Message: `${option} = ${String(value)} was ignored: going beyond the configured ${String(configured)} needs the 'Clone Records: Override Scope' authorization.`,
+        });
+    };
+    /** A two-valued scope switch where `wide` copies more than the other value. */
+    const scope = (option, requested, configured, wide) => {
+        if (requested === undefined || requested === configured)
+            return configured;
+        if (requested === wide) {
+            if (grants.CanOverrideScope) {
+                overrides.push(option);
+                return requested;
+            }
+            widenIgnored(option, requested, configured);
+            return configured;
+        }
+        if (mayNarrow)
+            return requested;
+        narrowIgnored(option, requested);
+        return configured;
+    };
+    const cap = (option, requested, configured) => {
+        if (requested === undefined || !Number.isFinite(requested) || Math.floor(requested) === configured)
+            return configured;
+        const value = Math.max(1, Math.floor(requested));
+        if (value > configured) {
+            if (grants.CanOverrideScope) {
+                overrides.push(option);
+                return value;
+            }
+            widenIgnored(option, requested, configured);
+            return configured;
+        }
+        if (mayNarrow)
+            return value;
+        narrowIgnored(option, requested);
+        return configured;
+    };
+    /** A choice that is neither wider nor narrower, governed by UserEditable alone. */
+    const choice = (option, requested, configured) => {
+        if (requested === undefined || requested === configured)
+            return configured;
+        if (mayNarrow)
+            return requested;
+        narrowIgnored(option, requested);
+        return configured;
+    };
+    const hook = (option, requested, configured) => {
+        if (requested === undefined || requested === configured)
+            return configured;
+        if (grants.CanFireHooks) {
+            overrides.push(option);
+            return requested;
+        }
+        warnings.push({
+            Code: 'HOOKS_FORBIDDEN',
+            Severity: 'Warning',
+            Field: option,
+            Message: `${option} = ${requested} was ignored: changing whether they run needs the 'Clone Records: Fire Hooks' authorization. They ${configured === 'fire' ? 'run' : 'stay suppressed'} as configured.`,
+        });
+        return configured;
+    };
+    const options = {
+        MaxDepth: cap('MaxDepth', request?.MaxDepth, config?.MaxDepth ?? DEFAULT_CLONE_MAX_DEPTH),
+        MaxRecords: cap('MaxRecords', request?.MaxRecords, config?.MaxRecords ?? DEFAULT_CLONE_MAX_RECORDS),
+        Subtypes: scope('Subtypes', request?.Subtypes, config?.Subtypes ?? 'include', 'include'),
+        Hierarchy: scope('Hierarchy', request?.Hierarchy, config?.Hierarchy ?? 'subtree', 'subtree'),
+        SoftLinks: scope('SoftLinks', request?.SoftLinks, config?.SoftLinks ?? 'skip', 'include'),
+        Embeddings: choice('Embeddings', request?.Embeddings, config?.Embeddings ?? 'copy'),
+        EntityActions: hook('EntityActions', request?.EntityActions, config?.Hooks?.EntityActions ?? DEFAULT_CLONE_ENTITY_ACTIONS),
+        AIActions: hook('AIActions', request?.AIActions, config?.Hooks?.AIActions ?? DEFAULT_CLONE_AI_ACTIONS),
+    };
+    return { Options: options, Warnings: warnings, Overrides: overrides };
+}
+/**
+ * Reads `Clone.Presets` defensively. The documented shape is an array of `{ Key, Label, ... }`;
+ * the legacy keyed-object form (`{ "<key>": { Description, Relationships } }`) is still accepted,
+ * with the object key as `Key`. Anything else yields no presets rather than an exception.
+ */
+export function NormalizeClonePresets(presets) {
+    const toPreset = (raw, fallbackKey) => {
+        if (!raw || typeof raw !== 'object')
+            return null;
+        const p = raw;
+        const key = typeof p.Key === 'string' && p.Key ? p.Key : typeof p.Name === 'string' && p.Name ? p.Name : fallbackKey;
+        if (!key)
+            return null;
+        return {
+            Key: key,
+            Label: typeof p.Label === 'string' && p.Label ? p.Label : key,
+            Description: typeof p.Description === 'string' ? p.Description : undefined,
+            Options: p.Options && typeof p.Options === 'object' ? p.Options : undefined,
+            Relationships: p.Relationships && typeof p.Relationships === 'object'
+                ? p.Relationships
+                : undefined,
+        };
+    };
+    if (Array.isArray(presets)) {
+        return presets.map((p) => toPreset(p)).filter((p) => p !== null);
+    }
+    if (presets && typeof presets === 'object') {
+        return Object.entries(presets)
+            .map(([key, p]) => toPreset(p, key))
+            .filter((p) => p !== null);
+    }
+    return [];
+}
+//# sourceMappingURL=EffectiveOptions.js.map

package/dist/EffectiveOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EffectiveOptions.js","sourceRoot":"","sources":["../src/EffectiveOptions.ts"],"names":[],"mappings":"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"}

package/dist/ExclusionClasses.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file ExclusionClasses.ts
+ * Classification and detection of non-cloneable and transient entity classes.
+ * @see plans/record-cloning/README.md §5.3
+ */
+export type ExclusionCategory = 'RunLogAudit' | 'PublishArtifactOrVersion' | 'ComputedOutput' | 'LiveCredentialsOrExternalHandle' | 'PersonalOrRespondentData' | 'PerUserState' | 'CreateDisallowed' | 'SoftDeleted';
+export interface ExclusionEvaluation {
+    Excluded: boolean;
+    Category?: ExclusionCategory;
+    Reason?: string;
+}
+/**
+ * Checks whether an entity belongs to an exclusion class based on its configuration,
+ * metadata flags, and naming patterns.
+ */
+export declare function EvaluateExclusionClass(params: {
+    EntityName: string;
+    NotCloneable?: boolean;
+    NotCloneableReason?: string;
+    AllowCreateAPI?: boolean;
+    /**
+     * true: evaluate only the name heuristics; false: only the explicit NotCloneable / AllowCreateAPI
+     * rules; omitted: both. Callers skip the heuristics when a configuration names the edge.
+     */
+    HeuristicsOnly?: boolean;
+}): ExclusionEvaluation;
+//# sourceMappingURL=ExclusionClasses.d.ts.map

package/dist/ExclusionClasses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExclusionClasses.d.ts","sourceRoot":"","sources":["../src/ExclusionClasses.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,iBAAiB,GACvB,aAAa,GACb,0BAA0B,GAC1B,gBAAgB,GAChB,iCAAiC,GACjC,0BAA0B,GAC1B,cAAc,GACd,kBAAkB,GAClB,aAAa,CAAC;AAEpB,MAAM,WAAW,mBAAmB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AA6BD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,mBAAmB,CAmDtB"}

package/dist/ExclusionClasses.js

@@ -0,0 +1,81 @@
+/**
+ * @file ExclusionClasses.ts
+ * Classification and detection of non-cloneable and transient entity classes.
+ * @see plans/record-cloning/README.md §5.3
+ */
+/**
+ * Known heuristic patterns matching operational runs, audit logs, caches, etc.
+ */
+const RUN_LOG_AUDIT_PATTERNS = [
+    /\bRuns?\b/i,
+    /\bRun Details?\b/i,
+    /\bRun Steps?\b/i,
+    /\bLogs?\b/i,
+    /\bChanges?\b/i,
+    /\bCache\b/i,
+    /\bWatermarks?\b/i,
+    /\bHistories\b/i,
+    /\bHistory\b/i,
+    /\bAudit\b/i,
+    /\bSnapshots?\b/i,
+];
+/**
+ * Known heuristic patterns matching per-user runtime state.
+ */
+const PER_USER_STATE_PATTERNS = [
+    /\bUser States?\b/i,
+    /\bUser Preferences?\b/i,
+    /\bFavorites?\b/i,
+    /\bNotifications?\b/i,
+];
+/**
+ * Checks whether an entity belongs to an exclusion class based on its configuration,
+ * metadata flags, and naming patterns.
+ */
+export function EvaluateExclusionClass(params) {
+    const { EntityName, NotCloneable, NotCloneableReason, AllowCreateAPI, HeuristicsOnly } = params;
+    const explicit = HeuristicsOnly !== true;
+    const heuristics = HeuristicsOnly !== false;
+    // 1. Explicit NotCloneable configuration
+    if (explicit && NotCloneable) {
+        return {
+            Excluded: true,
+            Category: 'RunLogAudit',
+            Reason: NotCloneableReason ||
+                `Entity '${EntityName}' is explicitly configured as NotCloneable.`,
+        };
+    }
+    // 2. AllowCreateAPI false: can never be created
+    if (explicit && AllowCreateAPI === false) {
+        return {
+            Excluded: true,
+            Category: 'CreateDisallowed',
+            Reason: `Entity '${EntityName}' has AllowCreateAPI=false in metadata and cannot be created.`,
+        };
+    }
+    if (!heuristics)
+        return { Excluded: false };
+    // 3. Heuristic: Run / Log / Audit / History patterns
+    for (const pattern of RUN_LOG_AUDIT_PATTERNS) {
+        if (pattern.test(EntityName)) {
+            return {
+                Excluded: true,
+                Category: 'RunLogAudit',
+                Reason: `Entity '${EntityName}' matches operational log, run, or history pattern.`,
+            };
+        }
+    }
+    // 4. Heuristic: per-user runtime state. A configuration that names the edge (checked by the
+    //    caller) is the only way to copy it; there is no entity-specific exception.
+    for (const pattern of PER_USER_STATE_PATTERNS) {
+        if (pattern.test(EntityName)) {
+            return {
+                Excluded: true,
+                Category: 'PerUserState',
+                Reason: `Entity '${EntityName}' represents transient per-user state.`,
+            };
+        }
+    }
+    return { Excluded: false };
+}
+//# sourceMappingURL=ExclusionClasses.js.map

package/dist/ExclusionClasses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExclusionClasses.js","sourceRoot":"","sources":["../src/ExclusionClasses.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH;;GAEG;AACH,MAAM,sBAAsB,GAAG;IAC3B,YAAY;IACZ,mBAAmB;IACnB,iBAAiB;IACjB,YAAY;IACZ,eAAe;IACf,YAAY;IACZ,kBAAkB;IAClB,gBAAgB;IAChB,cAAc;IACd,YAAY;IACZ,iBAAiB;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,uBAAuB,GAAG;IAC5B,mBAAmB;IACnB,wBAAwB;IACxB,iBAAiB;IACjB,qBAAqB;CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAUtC;IACG,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,cAAc,EAAE,GAAG,MAAM,CAAC;IAChG,MAAM,QAAQ,GAAG,cAAc,KAAK,IAAI,CAAC;IACzC,MAAM,UAAU,GAAG,cAAc,KAAK,KAAK,CAAC;IAE5C,yCAAyC;IACzC,IAAI,QAAQ,IAAI,YAAY,EAAE,CAAC;QAC3B,OAAO;YACH,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,aAAa;YACvB,MAAM,EACF,kBAAkB;gBAClB,WAAW,UAAU,6CAA6C;SACzE,CAAC;IACN,CAAC;IAED,gDAAgD;IAChD,IAAI,QAAQ,IAAI,cAAc,KAAK,KAAK,EAAE,CAAC;QACvC,OAAO;YACH,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,kBAAkB;YAC5B,MAAM,EAAE,WAAW,UAAU,+DAA+D;SAC/F,CAAC;IACN,CAAC;IAED,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAE5C,qDAAqD;IACrD,KAAK,MAAM,OAAO,IAAI,sBAAsB,EAAE,CAAC;QAC3C,IAAI,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3B,OAAO;gBACH,QAAQ,EAAE,IAAI;gBACd,QAAQ,EAAE,aAAa;gBACvB,MAAM,EAAE,WAAW,UAAU,qDAAqD;aACrF,CAAC;QACN,CAAC;IACL,CAAC;IAED,4FAA4F;IAC5F,gFAAgF;IAChF,KAAK,MAAM,OAAO,IAAI,uBAAuB,EAAE,CAAC;QAC5C,IAAI,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3B,OAAO;gBACH,QAAQ,EAAE,IAAI;gBACd,QAAQ,EAAE,cAAc;gBACxB,MAAM,EAAE,WAAW,UAAU,wCAAwC;aACxE,CAAC;QACN,CAAC;IACL,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AAC/B,CAAC"}