@memberjunction/core 6.2.0-edge.1 → 6.2.0-edge.2

package/dist/generic/JSONType-interfaces/IEntityConfiguration.d.ts

@@ -31,6 +31,13 @@ export interface IEntityConfiguration {
      * Controls whether attachments are permitted and sets entity-level upload policies.
      */
     Attachments?: IEntityAttachmentsConfiguration;
+    /**
+     * Record cloning configuration.
+     * Omitted or Enabled=false means the entity cannot be a clone ROOT.
+     * It may still be cloned as a child of another root when that root's relationship
+     * policy says Deep, unless NotCloneable is true.
+     */
+    Clone?: IEntityCloneConfiguration;
 }
 /**
  * Configuration for entity-level file attachments.
@@ -117,4 +124,177 @@ export interface IEntityFormConfiguration {
      */
     PrimaryRelatedBudget?: number;
 }
+/**
+ * Configuration for record cloning at the entity level.
+ * @see plans/record-cloning/README.md §4.1
+ */
+export interface IEntityCloneConfiguration {
+    /** Schema version of this section. Default 1. */
+    Version?: 1;
+    /** Master switch for cloning this entity as a ROOT. Default false. */
+    Enabled?: boolean;
+    /** Hard refusal: this entity's rows are never created by the clone engine, as root or as child. Overrides every relationship policy. Use for audit, run, credential and metadata entities. */
+    NotCloneable?: boolean;
+    /** Shown to users and returned in warnings when NotCloneable or Enabled=false. */
+    NotCloneableReason?: string;
+    /** Authorization name checked with ancestors. Default 'Clone Records'; resolved per §9.1. */
+    RequiredAuthorization?: string;
+    /** Caps. Defaults 3 and 500. A plan that exceeds either is Blocked. */
+    MaxDepth?: number;
+    MaxRecords?: number;
+    /** IS-A subtype rows. Default 'include'. */
+    Subtypes?: 'include' | 'exclude';
+    /** Self-referencing IsHierarchy fields. Default 'subtree'. */
+    Hierarchy?: 'subtree' | 'node';
+    /** Inbound polymorphic EntityID/RecordID rows (tags, attachments, notes...). Default 'skip'. */
+    SoftLinks?: 'skip' | 'include';
+    Naming?: ICloneNamingConfig;
+    Fields?: ICloneFieldRules;
+    /** Per-relationship policy, keyed by "<RelatedEntityName>" or "<RelatedEntityName>.<JoinField>" when an entity has two FKs to the same target. Overrides the relationship's own bag when Locked is false there. */
+    Relationships?: Record<string, ICloneRelationshipPolicy>;
+    /** Rules applied to descendant rows cloned under THIS root, keyed by descendant entity name. Lets a root shape its children without editing the child entity's bag. */
+    Descendants?: Record<string, ICloneDescendantConfig>;
+    Hooks?: ICloneHookConfig;
+    /** Route the ROOT through an existing creation path instead of a raw Save. Children still clone through the engine against the created root. */
+    CreationPath?: ICloneCreationPath;
+    /** Offer "create derived record" (BasedOnID-style inheritance) as an alternative to copying. */
+    Derivation?: {
+        Field: string;
+        Label?: string;
+        Description?: string;
+    };
+    /** Persisted embedding columns. Default 'copy' when EmbeddingModelID matches the configured model, else regenerate. */
+    Embeddings?: 'copy' | 'regenerate';
+    /** The entity's own server class refuses creates by other user types (Users, Roles). The planner blocks early with the entity's reason. */
+    RequiredUserType?: 'Owner';
+    /** How much the UI may change. Default 'all'. 'none' = confirm only. */
+    UserEditable?: 'none' | 'fields' | 'scope' | 'all';
+    Presets?: IClonePreset[];
+    UI?: {
+        Label?: string;
+        Icon?: string;
+        ConfirmationMessage?: string;
+        DefaultPreset?: string;
+        /** FK fields the panel offers as retarget pickers (CompanyID → another company). */
+        RetargetFields?: string[];
+    };
+}
+export interface ICloneNamingConfig {
+    /** Template for the name field and any string unique field with no other rule. '{Name}' interpolates the source value; '{n}' the collision counter. Default 'Copy of {Name}'. */
+    Template?: string;
+    /** Fields the template applies to. Default: the entity's NameField plus every IsUnique string field not otherwise handled. */
+    Fields?: string[];
+    /** suffix = apply Template and probe for collisions appending ' {n}'; increment = numeric/versioned bump; prompt = user must supply; none = leave untouched. Default 'suffix'. */
+    Strategy?: 'suffix' | 'increment' | 'prompt' | 'none';
+}
+export interface ICloneFieldRules {
+    /** Never copied; take the column default. Beyond the always-excluded set (PK, __mj_*, identity, computed, virtual, denied-create). */
+    Exclude?: string[];
+    /** Literal stamps applied after the copy. Values pass through BaseEntity.Set and validation. */
+    Reset?: Record<string, unknown>;
+    /** Set to the cloning user's ID. */
+    Ownership?: string[];
+    /** The user must supply a value; un-suffixable uniques such as Email. Missing → plan Blocked. */
+    PromptFor?: string[];
+    /** Server-minted values (numbers, slugs): blanked so the entity's Save hook allocates. */
+    ServerAllocated?: string[];
+    /** Rich rewrites. Evaluated per row with the source row as fields, plus clone context (user, now, root, keyMap) — see §7.5. */
+    Rules?: Record<string, unknown>;
+    /** JSON columns that embed record IDs, one entry per column. */
+    JsonRemap?: IJsonRemapColumn[];
+    /** Columns that must be cleared together (all-or-nothing CHECK pairs). Each group is cleared as a unit when any member is reset. */
+    ClearTogether?: string[][];
+    /** Unique keys the metadata cannot see: composite and filtered indexes. See §7.3. */
+    UniqueKeys?: Array<{
+        Fields: string[];
+        Scope: 'Global' | 'Parent' | 'LiveState';
+        ScopeField?: string;
+    }>;
+    /** Drift guard (§13.3): every field must appear in Copy, Exclude, Reset, Ownership, PromptFor, ServerAllocated or JsonRemap, or validation fails. Default false. */
+    Strict?: boolean;
+    /** Explicit copy allow-list, used with Strict. */
+    Copy?: string[];
+}
+export interface IJsonRemapSpec {
+    /** Path selector: dot segments and [*] for arrays, e.g. 'layout.content[*].componentState.config.viewId'. */
+    Path: string;
+    /** remap = rewrite via key map when the target is in the clone set, else per OnMissing; reuse = leave; regenerate = new UUID; null = set null; drop = remove element/key. */
+    Mode: 'remap' | 'reuse' | 'regenerate' | 'null' | 'drop';
+    /** Entity the ID refers to, for remap. */
+    TargetEntityName?: string;
+    /** For remap when the referenced record was not cloned: reuse the original (default) or drop the element and count it. */
+    OnMissing?: 'reuse' | 'drop';
+    /** Remove arrays and objects left empty by a drop. Default true. */
+    CleanEmptyContainers?: boolean;
+}
+/** One JSON column to rewrite: explicit rules, a shipped preset, or both (the preset's rules run first). An entry with neither is invalid. */
+export interface IJsonRemapColumn {
+    /** The JSON column. */
+    Field: string;
+    Rules?: IJsonRemapSpec[];
+    /** A shipped rule set for a known payload shape. */
+    Preset?: 'dashboard-ui-config' | 'scheduled-job-configuration';
+}
+export interface ICloneRelationshipPolicy {
+    Policy?: 'Deep' | 'Reference' | 'Skip';
+    /** UI may not change it. */
+    Locked?: boolean;
+    MaxRecords?: number;
+    /** Write the source's positional values after the last Add instead of letting the collection renumber. Default false. */
+    PreserveSequence?: boolean;
+    /** Formula over the child row (fields.X); only rows evaluating true are cloned. */
+    IncludeWhen?: string;
+    /** Rows left out even when the edge is Deep, e.g. per-device or per-person settings. A row matching any entry is not cloned, nor are its descendants. */
+    ExcludeRows?: ICloneRowExclusion[];
+    Fields?: ICloneFieldRules;
+}
+/** Matches a child row by one field: equal to one of `Equals`, or a string starting with one of `StartsWith` (case-sensitive). */
+export interface ICloneRowExclusion {
+    Field: string;
+    Equals?: Array<string | number | boolean>;
+    StartsWith?: string[];
+}
+export interface ICloneDescendantConfig {
+    Fields?: ICloneFieldRules;
+    Naming?: ICloneNamingConfig;
+}
+export interface ICloneHookConfig {
+    /** Entity Actions (Create/Update invocations) during the clone save. Default 'fire', as for any create. */
+    EntityActions?: 'suppress' | 'fire';
+    /** Entity AI Actions. Default 'suppress': each can be a paid model call per cloned row. */
+    AIActions?: 'suppress' | 'fire';
+    /** Children the entity's own server Save() creates. The engine never clones these, and warns if a relationship policy tries. */
+    ServerGeneratedChildren?: string[];
+    /** Values set before the save to keep expensive hooks quiet, restored on the row after the clone when RestoreAfterSave is true. */
+    PreSaveOverrides?: Record<string, unknown>;
+    RestoreAfterSave?: string[];
+    /** Action run once per created ROOT after commit, with the new key. */
+    PostCloneAction?: string;
+}
+export interface ICloneCreationPath {
+    Kind: 'Action' | 'RemoteOperation';
+    Name: string;
+    /** Source field or formula → input param. */
+    InputMapping: Record<string, string>;
+    /** Output param holding the created key. */
+    OutputKeyParam: string;
+}
+/**
+ * A named clone scope a user can pick instead of adjusting options one by one.
+ * `Options` apply as if the request had sent them (so `UserEditable` still limits them);
+ * `Relationships` override edge policies by related entity name, like `Clone.Relationships`.
+ */
+export interface IClonePreset {
+    /** Stable identifier sent by clients in `Options.Preset`. */
+    Key: string;
+    /** Name shown in the preset picker. */
+    Label: string;
+    Description?: string;
+    /** Plan options this preset sets, e.g. `{ "MaxDepth": 2 }`. */
+    Options?: Record<string, unknown>;
+    /** Edge policy overrides, keyed by related entity name. */
+    Relationships?: Record<string, {
+        Policy: 'Deep' | 'Reference' | 'Skip';
+    }>;
+}
 //# sourceMappingURL=IEntityConfiguration.d.ts.map

package/dist/generic/JSONType-interfaces/IEntityConfiguration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IEntityConfiguration.d.ts","sourceRoot":"","sources":["../../../src/generic/JSONType-interfaces/IEntityConfiguration.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,oBAAoB;IACjC;;;OAGG;IACH,EAAE,CAAC,EAAE,sBAAsB,CAAC;IAE5B;;;OAGG;IACH,WAAW,CAAC,EAAE,+BAA+B,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC5C;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B;;OAEG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAEjC;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACnC;;;OAGG;IACH,IAAI,CAAC,EAAE,wBAAwB,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACrC;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC;IAE3C;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC;IAEjD;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACjC"}
+{"version":3,"file":"IEntityConfiguration.d.ts","sourceRoot":"","sources":["../../../src/generic/JSONType-interfaces/IEntityConfiguration.ts"],"names":[],"mappings":"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"}

package/dist/generic/JSONType-interfaces/IEntityFieldConfiguration.d.ts

@@ -14,6 +14,11 @@ export interface IEntityFieldConfiguration {
      * Hierarchy and tree structure configuration for self-referencing foreign keys.
      */
     Hierarchy?: IEntityFieldHierarchyConfig;
+    /**
+     * Record cloning configuration for this field.
+     * @see plans/record-cloning/README.md §4.3
+     */
+    Clone?: IEntityFieldCloneConfiguration;
 }
 /**
  * Hierarchy options to explicitly declare recursive tree hierarchies.
@@ -28,4 +33,27 @@ export interface IEntityFieldHierarchyConfig {
      */
     MaxDepth?: number;
 }
+/**
+ * Record cloning configuration for an entity field.
+ * @see plans/record-cloning/README.md §4.3
+ */
+export interface IEntityFieldCloneConfiguration {
+    /** Copy (default) | Reset (column default, or Value) | Suffix (naming template) | Prompt | Ownership | ServerAllocated | Remap (FK inside the set → new key) | RemapJSON | Transform */
+    Policy?: 'Copy' | 'Reset' | 'Suffix' | 'Prompt' | 'Ownership' | 'ServerAllocated' | 'Remap' | 'RemapJSON' | 'Transform';
+    Value?: unknown;
+    JsonRemap?: IJsonRemapSpec[];
+    Transform?: unknown;
+}
+export interface IJsonRemapSpec {
+    /** Path selector: dot segments and [*] for arrays, e.g. 'layout.content[*].componentState.config.viewId'. */
+    Path: string;
+    /** remap = rewrite via key map when the target is in the clone set, else per OnMissing; reuse = leave; regenerate = new UUID; null = set null; drop = remove element/key. */
+    Mode: 'remap' | 'reuse' | 'regenerate' | 'null' | 'drop';
+    /** Entity the ID refers to, for remap. */
+    TargetEntityName?: string;
+    /** For remap when the referenced record was not cloned: reuse the original (default) or drop the element and count it. */
+    OnMissing?: 'reuse' | 'drop';
+    /** Remove arrays and objects left empty by a drop. Default true. */
+    CleanEmptyContainers?: boolean;
+}
 //# sourceMappingURL=IEntityFieldConfiguration.d.ts.map

package/dist/generic/JSONType-interfaces/IEntityFieldConfiguration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IEntityFieldConfiguration.d.ts","sourceRoot":"","sources":["../../../src/generic/JSONType-interfaces/IEntityFieldConfiguration.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACtC;;OAEG;IACH,SAAS,CAAC,EAAE,2BAA2B,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IACxC;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB"}
+{"version":3,"file":"IEntityFieldConfiguration.d.ts","sourceRoot":"","sources":["../../../src/generic/JSONType-interfaces/IEntityFieldConfiguration.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACtC;;OAEG;IACH,SAAS,CAAC,EAAE,2BAA2B,CAAC;IAExC;;;OAGG;IACH,KAAK,CAAC,EAAE,8BAA8B,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IACxC;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC3C,wLAAwL;IACxL,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,iBAAiB,GAAG,OAAO,GAAG,WAAW,GAAG,WAAW,CAAC;IACxH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC3B,6GAA6G;IAC7G,IAAI,EAAE,MAAM,CAAC;IACb,6KAA6K;IAC7K,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;IACzD,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0HAA0H;IAC1H,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,oEAAoE;IACpE,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAClC"}

package/dist/generic/JSONType-interfaces/IEntityRelationshipConfiguration.d.ts

@@ -32,6 +32,11 @@ export interface IEntityRelationshipConfiguration {
      * Null = the parent entity's related-role ranker decides.
      */
     UI?: IEntityRelationshipUIConfiguration;
+    /**
+     * Clone policy for rows of RelatedEntity that point at this entity through RelatedEntityJoinField.
+     * @see plans/record-cloning/README.md §4.2
+     */
+    Clone?: ICloneRelationshipPolicy;
 }
 /**
  * How this relationship appears on the parent entity's generated form.
@@ -72,4 +77,75 @@ export interface IEntityRelationshipUIConfiguration {
      */
     sortKey?: number;
 }
+/**
+ * Clone policy for rows of RelatedEntity that point at this entity through RelatedEntityJoinField.
+ * @see plans/record-cloning/README.md §4.2
+ */
+export interface ICloneRelationshipPolicy {
+    Policy?: 'Deep' | 'Reference' | 'Skip';
+    /** UI may not change it. */
+    Locked?: boolean;
+    MaxRecords?: number;
+    /** Write the source's positional values after the last Add instead of letting the collection renumber. Default false. */
+    PreserveSequence?: boolean;
+    /** Formula over the child row (fields.X); only rows evaluating true are cloned. */
+    IncludeWhen?: string;
+    /** Rows left out even when the edge is Deep, e.g. per-device or per-person settings. A row matching any entry is not cloned, nor are its descendants. */
+    ExcludeRows?: ICloneRowExclusion[];
+    Fields?: ICloneFieldRules;
+}
+/** Matches a child row by one field: equal to one of `Equals`, or a string starting with one of `StartsWith` (case-sensitive). */
+export interface ICloneRowExclusion {
+    Field: string;
+    Equals?: Array<string | number | boolean>;
+    StartsWith?: string[];
+}
+export interface ICloneFieldRules {
+    /** Never copied; take the column default. Beyond the always-excluded set (PK, __mj_*, identity, computed, virtual, denied-create). */
+    Exclude?: string[];
+    /** Literal stamps applied after the copy. Values pass through BaseEntity.Set and validation. */
+    Reset?: Record<string, unknown>;
+    /** Set to the cloning user's ID. */
+    Ownership?: string[];
+    /** The user must supply a value; un-suffixable uniques such as Email. Missing → plan Blocked. */
+    PromptFor?: string[];
+    /** Server-minted values (numbers, slugs): blanked so the entity's Save hook allocates. */
+    ServerAllocated?: string[];
+    /** Rich rewrites. Evaluated per row with the source row as fields, plus clone context (user, now, root, keyMap) — see §7.5. */
+    Rules?: Record<string, unknown>;
+    /** JSON columns that embed record IDs, one entry per column. */
+    JsonRemap?: IJsonRemapColumn[];
+    /** Columns that must be cleared together (all-or-nothing CHECK pairs). Each group is cleared as a unit when any member is reset. */
+    ClearTogether?: string[][];
+    /** Unique keys the metadata cannot see: composite and filtered indexes. See §7.3. */
+    UniqueKeys?: Array<{
+        Fields: string[];
+        Scope: 'Global' | 'Parent' | 'LiveState';
+        ScopeField?: string;
+    }>;
+    /** Drift guard (§13.3): every field must appear in Copy, Exclude, Reset, Ownership, PromptFor, ServerAllocated or JsonRemap, or validation fails. Default false. */
+    Strict?: boolean;
+    /** Explicit copy allow-list, used with Strict. */
+    Copy?: string[];
+}
+export interface IJsonRemapSpec {
+    /** Path selector: dot segments and [*] for arrays, e.g. 'layout.content[*].componentState.config.viewId'. */
+    Path: string;
+    /** remap = rewrite via key map when the target is in the clone set, else per OnMissing; reuse = leave; regenerate = new UUID; null = set null; drop = remove element/key. */
+    Mode: 'remap' | 'reuse' | 'regenerate' | 'null' | 'drop';
+    /** Entity the ID refers to, for remap. */
+    TargetEntityName?: string;
+    /** For remap when the referenced record was not cloned: reuse the original (default) or drop the element and count it. */
+    OnMissing?: 'reuse' | 'drop';
+    /** Remove arrays and objects left empty by a drop. Default true. */
+    CleanEmptyContainers?: boolean;
+}
+/** One JSON column to rewrite: explicit rules, a shipped preset, or both (the preset's rules run first). An entry with neither is invalid. */
+export interface IJsonRemapColumn {
+    /** The JSON column. */
+    Field: string;
+    Rules?: IJsonRemapSpec[];
+    /** A shipped rule set for a known payload shape. */
+    Preset?: 'dashboard-ui-config' | 'scheduled-job-configuration';
+}
 //# sourceMappingURL=IEntityRelationshipConfiguration.d.ts.map

package/dist/generic/JSONType-interfaces/IEntityRelationshipConfiguration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IEntityRelationshipConfiguration.d.ts","sourceRoot":"","sources":["../../../src/generic/JSONType-interfaces/IEntityRelationshipConfiguration.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,gCAAgC;IAC7C;;;OAGG;IACH,EAAE,CAAC,EAAE,kCAAkC,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kCAAkC;IAC/C;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAEhC;;;;OAIG;IACH,IAAI,CAAC,EAAE;QACH,IAAI,EAAE,KAAK,CAAC;QACZ,MAAM,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IAEF;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"IEntityRelationshipConfiguration.d.ts","sourceRoot":"","sources":["../../../src/generic/JSONType-interfaces/IEntityRelationshipConfiguration.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,gCAAgC;IAC7C;;;OAGG;IACH,EAAE,CAAC,EAAE,kCAAkC,CAAC;IAExC;;;OAGG;IACH,KAAK,CAAC,EAAE,wBAAwB,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kCAAkC;IAC/C;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAEhC;;;;OAIG;IACH,IAAI,CAAC,EAAE;QACH,IAAI,EAAE,KAAK,CAAC;QACZ,MAAM,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IAEF;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACrC,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IACvC,4BAA4B;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yHAAyH;IACzH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yJAAyJ;IACzJ,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACnC,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAED,kIAAkI;AAClI,MAAM,WAAW,kBAAkB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAC1C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC7B,sIAAsI;IACtI,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,iGAAiG;IACjG,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,0FAA0F;IAC1F,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,+HAA+H;IAC/H,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,gEAAgE;IAChE,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,oIAAoI;IACpI,aAAa,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IAC3B,qFAAqF;IACrF,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxG,oKAAoK;IACpK,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC3B,6GAA6G;IAC7G,IAAI,EAAE,MAAM,CAAC;IACb,6KAA6K;IAC7K,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;IACzD,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0HAA0H;IAC1H,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,oEAAoE;IACpE,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,8IAA8I;AAC9I,MAAM,WAAW,gBAAgB;IAC7B,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,oDAAoD;IACpD,MAAM,CAAC,EAAE,qBAAqB,GAAG,6BAA6B,CAAC;CAClE"}

package/dist/generic/baseEntity.d.ts

@@ -9,6 +9,19 @@ import { EmbeddedRecord, type EmbeddedRecordOptions } from './embeddedRecord.js'
 import { EntitySavePlan } from './entitySavePlan.js';
 import { Subscription } from 'rxjs';
 import { z } from 'zod';
+/**
+ * A field's value and dirty-tracking state, as {@link EntityField.GetState} captures them.
+ */
+export interface EntityFieldState {
+    /** The field's value. */
+    Value: unknown;
+    /** The value the field is compared with to decide whether it's dirty. */
+    OldValue: unknown;
+    /** Whether the source the record was hydrated from omitted the field. See {@link EntityField.NotLoaded}. */
+    NotLoaded: boolean;
+    /** Whether the field has had no set since it was created or re-armed. */
+    NeverSet: boolean;
+}
 /**
  * Represents a field in an instance of the BaseEntity class. This class is used to store the value of the field, dirty state, as well as other run-time information about the field. The class encapsulates the underlying field metadata and exposes some of the more commonly
  * used properties from the entity field metadata.
@@ -189,9 +202,18 @@ export declare class EntityField {
     ResetOldValue(): void;
     /**
      * Restores the dirty-tracking baseline to a previously captured value.
-     * Used by graph rollback so a retried save still sees the pre-attempt dirty set.
      */
     RestoreOldValue(value: unknown): void;
+    /**
+     * Framework-internal: the field's value and dirty-tracking state, so a unit of work that rolls
+     * back can put them back with {@link RestoreState}.
+     */
+    GetState(): EntityFieldState;
+    /**
+     * Framework-internal: puts back a state {@link GetState} captured. It writes the state as it was,
+     * so the read-only and first-set rules of the {@link Value} setter don't apply.
+     */
+    RestoreState(state: EntityFieldState): void;
     /**
      * @deprecated No-op as of the active-status relocation. Active-status (deprecated/disabled)
      * assertions are now enforced at BaseEntity.Get/Set/SetMany — the entry points genuine code uses —
@@ -228,6 +250,46 @@ export interface RestoreContext {
      */
     Reason: string | null;
 }
+/**
+ * Context describing an in-progress clone operation on a BaseEntity.
+ *
+ * When set on an entity instance via {@link BaseEntity.SetCloneContext}
+ * prior to calling Save(), the data provider will write the resulting
+ * RecordChange row with `Source='Clone'` and the structured JSON
+ * `ChangeContext` column populated.
+ *
+ * @see plans/record-cloning/README.md §10.3
+ */
+export interface CloneContext {
+    /** ID of the RecordCloneLog row coordinating this clone operation. */
+    CloneLogID: string;
+    /** Entity name of the record being cloned. */
+    SourceEntityName: string;
+    /** Compact URL segment of the source key (bare value for single-column keys). */
+    SourceRecordID: string;
+    /** Entity name of the root record of the clone graph. */
+    RootEntityName: string;
+    /** Source key of the root record. */
+    RootSourceRecordID: string;
+    /** Target key of the root record after insertion. */
+    RootTargetRecordID: string;
+    /** Depth within the record graph (0 for root). */
+    Depth: number;
+    /** Relationship route traversed to reach this record. */
+    Route: 'RootSave' | 'Collection' | 'Embedded' | 'IsAChain' | 'Sidecar';
+    /** Kinds and field names only. Values are already in FullRecordJSON. */
+    FieldChangeSummary: Array<{
+        Kind: string;
+        Fields: string[];
+    }>;
+    /** Optional explanation entered at clone time. */
+    Reason?: string | null;
+}
+/**
+ * The `ChangeContext` JSON a clone writes on its Record Change rows (`IRecordChangeContext`,
+ * Kind 'Clone'). The one serializer every provider path uses, so the shape can't drift.
+ */
+export declare function SerializeCloneChangeContext(context: CloneContext): string;
 /**
  * Discriminator for the `Source` column of a RecordChange row.
  *
@@ -236,8 +298,10 @@ export interface RestoreContext {
  *   (records the platform discovers via direct SQL changes)
  * - `Restore`: produced by a user-initiated restore — paired with
  *   `RestoredFromID` and optional `RestoreReason` lineage columns
+ * - `Clone`: produced by a record clone operation — paired with
+ *   structured `ChangeContext` JSON provenance
  */
-export type RecordChangeSource = 'Internal' | 'External' | 'Restore';
+export type RecordChangeSource = 'Internal' | 'External' | 'Restore' | 'Clone';
 /**
  * Dialect-agnostic payload for a RecordChange row.
  *
@@ -294,6 +358,11 @@ export interface RecordChangePayload {
      * not enter one.
      */
     restoreReason: string | null;
+    /**
+     * When `source === 'Clone'`, serialized JSON bag carrying structured provenance
+     * (shape = `IRecordChangeContext`). Null otherwise.
+     */
+    changeContext: string | null;
 }
 export declare class DataObjectRelatedEntityParam {
     relatedEntityName: string;
@@ -468,6 +537,9 @@ export declare class BaseEntityEvent {
      */
     provider?: IMetadataProvider;
 }
+/**
+ * Base class used for all entity objects. This class is abstract and is sub-classes for each particular entity using the CodeGen tool. This class provides the basic functionality for loading, saving, and validating entity objects.
+ */
 export declare abstract class BaseEntity<T = unknown> {
     /**
      * Metadata describing this entity (name, fields, keys, relationships). Populated during
@@ -711,6 +783,12 @@ export declare abstract class BaseEntity<T = unknown> {
      * routing through the provider: participants stay ignorant of one another.
      */
     private _entityTransactionScope;
+    /**
+     * The unit of work this record is saved or deleted in, while it runs as part of a larger one: an
+     * IS-A chain's initiator sets it on each parent for the parent's write, and a graph sets it on
+     * each of its records. See {@link UnitOfWork}.
+     */
+    private _unitOfWork;
     /**
      * Companions registered on this entity, keyed by {@link EntityCompanion.Name}.
      *
@@ -784,6 +862,14 @@ export declare abstract class BaseEntity<T = unknown> {
      * This is called by Metadata.GetEntityObject() after constructing the entity.
      */
     InitializeParentEntity(): Promise<void>;
+    /**
+     * Points this child's disjoint parent back at this instance (`parent._childEntity = this`).
+     *
+     * Same gate as {@link InitializeParentEntity}: a parent that allows several subtypes keeps no
+     * single child. `NewRecord()` sets `_childEntity` to null, so this has to run AFTER the
+     * parent's `NewRecord()` — calling it before is wiped out.
+     */
+    private linkParentBackToThisChild;
     /**
      * IS-A PROMOTION (#3825): binds this NEW child record to an EXISTING parent row, so saving it
      * ADDS a subtype to a person/org/product that already exists instead of trying to create a
@@ -1041,6 +1127,14 @@ export declare abstract class BaseEntity<T = unknown> {
      * @returns The linked child BaseEntity, or null if no subtype applies.
      */
     EnsureISAChild(entityName?: string): Promise<BaseEntity | null>;
+    /**
+     * A new parent's child is new too: there is no row to read, so copy the parent's keys.
+     * A saved parent still reads (promotion's usual answer is "no row"), and that miss is not
+     * an error — the same way a subtype-hint probe treats an empty read (MJ#4859).
+     */
+    private loadOrMirrorChildRow;
+    /** Loads the child by the shared key. An empty result is an answer, not a logged error. */
+    private loadChildRowQuietly;
     private mirrorSharedKeysToChild;
     /**
      * Walks a `SubtypeSelector` path from this record to the column holding the subtype's entity
@@ -1204,6 +1298,18 @@ export declare abstract class BaseEntity<T = unknown> {
      * ```
      */
     protected DeclareRelatedRecords<TChild extends BaseEntity = BaseEntity>(options: RelatedRecordCollectionOptions): RelatedRecordCollection<TChild>;
+    /**
+     * Dynamically registers a database-sourced child collection companion on this entity instance.
+     * Used by generic composite persistence engines (Record Cloning, Metadata Sync) when a relationship
+     * has no static collection companion declared on the generated entity class.
+     *
+     * Refuses duplicate names or re-registering an already existing companion.
+     *
+     * @typeParam TChild - The child entity type.
+     * @param options - The collection declaration options.
+     * @returns The registered collection companion.
+     */
+    DeclareRelatedRecordsDynamic<TChild extends BaseEntity = BaseEntity>(options: RelatedRecordCollectionOptions): RelatedRecordCollection<TChild>;
     /**
      * Declares a 1:1 embedded peer on this entity, joined by an owner-held foreign key,
      * and registers it as a companion.
@@ -1424,20 +1530,33 @@ export declare abstract class BaseEntity<T = unknown> {
      */
     private deleteAsGraphNode;
     /**
-     * Captures saved/dirty baselines for every plan participant so a rolled-back
-     * graph can be retried without re-INSERTing a "saved" peer or skipping it.
+     * Captures each record's IS-A chain, from its leaf up to its root, so a unit of work that rolls
+     * back can put the chain back with {@link restoreChains}. A record in more than one chain is
+     * captured once.
      */
-    private captureGraphParticipants;
+    private static captureChains;
     /**
-     * Restores in-memory saved/dirty state after the database rolled the graph back.
+     * Puts back, after a rollback, what the unit of work changed in memory. See {@link restoreSnapshot}.
      */
-    private revertGraphParticipants;
+    private static restoreChains;
     /**
-     * After a graph node Save() the fields look clean and `_everSaved` is true.
-     * The DB rollback does not undo that. Restore the pre-attempt baseline so
-     * a retry still writes the peer and the owner FK still matches.
+     * Puts this record back as a snapshot captured it, after the unit of work that finalized it
+     * rolled back.
+     *
+     * A save's `finalizeSave()` rebuilds the record's fields from what its write returned, marks it
+     * saved and empties its result history. The database undid the write, so the record gets back
+     * its saved and loaded flags, its result history, and each field's value and tracking state. A
+     * field edited since then keeps the edit, and is compared with its captured baseline again, since
+     * that is what the database holds after the rollback. (A delete leaves nothing to put back: a
+     * record deleted inside a unit of work isn't reset until the unit commits.)
+     *
+     * The history matters to the caller: a save records its failure only when nothing else did,
+     * judged by the history's length when it started, which an emptied history would make wrong.
+     *
+     * A record still holding the captured field objects was never finalized, so nothing about it
+     * changed and it is left alone.
      */
-    private revertUncommittedGraphSave;
+    private restoreSnapshot;
     /**
      * Records a graph-level failure on this entity's result history.
      *
@@ -1460,6 +1579,49 @@ export declare abstract class BaseEntity<T = unknown> {
      * would replace the caller's real error with a secondary one that explains less.
      */
     private rollbackEntityTransactionScope;
+    /**
+     * The failure path of a save: rolls back the transaction scope this entity holds, if any, then
+     * settles this save's part in its unit of work (see {@link settleRollback}). `part` is null when
+     * this save took none (see `_innerSave`), and then only the scope is rolled back.
+     */
+    private rollbackChainSave;
+    /**
+     * Starts a unit of work's part in a {@link UnitOfWork}: joins `enclosing` when the unit runs
+     * inside one, and owns a new one when it doesn't. `snapshots` are the unit's records as they are
+     * before it writes them. They join the unit's, so that the outermost unit can put them back.
+     */
+    private static beginUnitOfWork;
+    /**
+     * Runs `work` on `record` as part of `unit` (see {@link UnitOfWork}), and gives the record back
+     * the unit it was in before, however `work` ends. Used for an IS-A parent's delete, which runs
+     * inside its child's chain, along with the graph of its companions if it has any.
+     */
+    private static inUnitOfWork;
+    /**
+     * After a unit of work rolls back: puts its records back as they were before it wrote them, and
+     * drops the deletes the rollback undid, so that nothing resets their records. The owner does this
+     * for everything the unit and the units nested in it wrote. A nested part does it for its own
+     * records only; when the owner then rolls back too, restoring them again changes nothing.
+     */
+    private static settleRollback;
+    /**
+     * After a unit of work commits: its owner resets the records it deleted. A nested part leaves
+     * them to the owner, since the enclosing unit can still roll back.
+     */
+    private static settleCommit;
+    /**
+     * Resets the records a unit of work deleted, once the unit has committed, as each record's own
+     * `Delete()` does when no unit of work is involved. See {@link UnitOfWork}.
+     *
+     * Last-deleted first, skipping a record that no longer reads as saved. `NewRecord()` on a record
+     * also resets every IS-A level above it, and relinks them. A chain's initiator records its delete
+     * after its parents do, so it's reset first, and its parents with it. Resetting a parent again
+     * after that would unlink it from its child and give it a key the child doesn't share.
+     *
+     * The unit has committed, so a reset that throws is logged and the rest still run: the deletes
+     * stand whatever happens here.
+     */
+    private static resetDeletedRecords;
     /**
      * Returns this provider to be used for a given instance of a BaseEntity derived subclass. If the provider is not set, the BaseEntity.Provider is returned.
      */
@@ -1899,6 +2061,34 @@ export declare abstract class BaseEntity<T = unknown> {
      * accidentally tagged as a restore.
      */
     ClearRestoreContext(): void;
+    private _cloneContext;
+    /**
+     * Returns the active clone context for the next save, if any.
+     *
+     * Read by the data provider when generating the RecordChange SQL: when
+     * non-null, the resulting RecordChange row is written with
+     * `Source='Clone'` and `ChangeContext` populated with structured JSON provenance.
+     * Returns null for ordinary saves.
+     */
+    get CloneContext(): CloneContext | null;
+    /**
+     * Marks the next Save() as part of a record clone operation.
+     *
+     * The provider will write a new RecordChange entry with `Source='Clone'`
+     * and `ChangeContext` populated with structured JSON provenance.
+     *
+     * The context persists on the entity until either (a) overwritten by a
+     * subsequent SetCloneContext() call or (b) explicitly cleared via
+     * ClearCloneContext(). It is NOT auto-cleared inside Save() because
+     * TransactionGroup execution is deferred.
+     *
+     * @param context Structured clone context. Throws if missing required fields.
+     */
+    SetCloneContext(context: CloneContext): void;
+    /**
+     * Clears any pending clone context. Safe to call when no context is set.
+     */
+    ClearCloneContext(): void;
     private _pendingSave$;
     /**
      * Saves the current state of the object to the database. Uses the active provider to handle the actual saving of the record.