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

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.
@@ -62,10 +75,10 @@ export declare class EntityField {
         };
     };
     private _entityFieldInfo;
-    private _OldValue;
-    private _Value;
-    private _NeverSet;
-    private _NotLoaded;
+    private _oldValue;
+    private _value;
+    private _neverSet;
+    private _notLoaded;
     /**
      * True when the source this entity was hydrated from OMITTED this field's key — most
      * commonly because field-level security stripped it before the payload reached us, but
@@ -90,7 +103,7 @@ export declare class EntityField {
      * clears the flag.
      */
     MarkNotLoaded(): void;
-    private _CreateSuppressed;
+    private _createSuppressed;
     /**
      * True when field-level security bars this user from supplying the field's value on INSERT,
      * so the save path must omit it and let the column take its database default.
@@ -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,13 +537,16 @@ 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
      * `SetEntityName()` from `Metadata.EntityByName` and used as the source of truth for
      * field definitions and schema details throughout this class.
      */
-    private _EntityInfo;
+    private _entityInfo;
     /**
      * Runtime field instances for this record — one `EntityField` per column in `_EntityInfo.Fields`.
      * Each holds the current value, old value, dirty state, and per-field validation.
@@ -490,7 +562,7 @@ export declare abstract class BaseEntity<T = unknown> {
      * `BaseEntity` are reserved for paths that have already triggered hydration or paths that
      * deliberately want to inspect hydration state (e.g., `Dirty` getter).
      */
-    private _Fields;
+    private _fields;
     /**
      * Tracks whether `_Fields` has been populated. `false` while in "raw mode" (data accessible
      * via `_raw` but no EntityField instances built yet); flips to `true` after the first call to
@@ -674,6 +746,17 @@ export declare abstract class BaseEntity<T = unknown> {
      * loaded record. Reset to false on NewRecord() and init().
      */
     private _childEntityDiscoveryDone;
+    /**
+     * Set only while this record's parent loads it because the parent's subtype rule named it
+     * (see {@link tryLinkHintedChildEntity}); read by {@link InnerLoad}.
+     */
+    private _subtypeHintProbe;
+    /**
+     * Set only while {@link AttachToParent} loads this record as the parent it promotes. Child
+     * discovery then doesn't ask the subtype rule: the child row being added doesn't exist yet, so
+     * a hint would name it and miss.
+     */
+    private _skipSubtypeLoadHint;
     /**
      * For **overlapping** subtype parents (AllowMultipleSubtypes = true), stores
      * the list of child entity type names that have records for this PK.
@@ -700,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}.
      *
@@ -773,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
@@ -837,10 +934,32 @@ export declare abstract class BaseEntity<T = unknown> {
      * This ensures that Save/Delete operations always delegate to the leaf entity,
      * running the full validation and event chain at every level.
      *
+     * For a disjoint parent, the entity's subtype rule is asked first (see
+     * {@link resolveSubtypeLoadHint}); when it names a child, that child's load, which
+     * happens anyway, checks the answer, and the discovery query runs only on a miss.
+     *
      * Must be called AFTER a record is loaded (PK must be available).
      * Skipped for entities that are not parent types or have already been discovered.
      */
     protected InitializeChildEntity(): Promise<void>;
+    /**
+     * Finds and links the one child of a loaded disjoint parent.
+     *
+     * Without a hint this is one discovery query plus the child's load. With a hint from the
+     * entity's subtype rule, the child's load checks the hint, and the discovery query runs
+     * only when that load comes back empty or wasn't tried.
+     *
+     * For well-formed data the outcome is the one the discovery query alone would give: a hint
+     * changes the number of round trips, not which child is linked or whether the load succeeds.
+     * Three benign exceptions:
+     * - a failure reading the hinted child's row falls back to the discovery query, so a transient
+     *   failure now recovers (a lasting one reads the row twice, then fails as before);
+     * - when the data breaks the disjoint rule with two child rows, the discovery query's
+     *   unordered `UNION ALL` links either one, where a hint links the one the rule names;
+     * - a provider without `FindISAChildEntity` links nothing without a hint, and the hinted child
+     *   with one.
+     */
+    private initializeDisjointChildEntity;
     /**
      * Uses the provider's FindISAChildEntity method (single UNION ALL query) to
      * determine which child entity type, if any, has a record with our PK value.
@@ -860,13 +979,127 @@ export declare abstract class BaseEntity<T = unknown> {
      * Creates the child entity instance, wires up the shared instance chain
      * (child._parentEntity = this, this._childEntity = child), loads the
      * child's data, and recursively discovers further children.
+     *
+     * @returns true when the child's row loaded and the child is linked; false when the load
+     *   came back empty, in which case the link is undone.
      */
     private createAndLinkChildEntity;
+    /**
+     * Creates an unlinked child entity instance through this entity's provider, so the child
+     * shares the same connection (correct in multi-provider scenarios — never the global default).
+     */
+    private createChildEntityObject;
+    /**
+     * Links `childEntity` into this entity's chain and loads its row under the shared key.
+     *
+     * @returns true when the row loaded and the child is linked; false when the load came back
+     *   empty, in which case the link is undone.
+     */
+    private linkAndLoadChildEntity;
+    /**
+     * Tries to link the child that the subtype rule named, by loading its row directly. That
+     * load is the check on the hint.
+     *
+     * The hint isn't tried when the child object can't be created or the user can't read that
+     * entity: the discovery-only path decides those cases, so a hint can neither expose a child
+     * nor fail a load that works without it. A failure READING the hinted row is logged and
+     * treated the same way: the discovery path runs, and reads the row again only if the discovery
+     * query finds it. A failure after the row was read (the child's hydration, its eager
+     * companions, its own child discovery) propagates, as it does on the discovery-only path.
+     *
+     * @returns `'Linked'` when the hinted child loaded and is linked, `'NotFound'` when its load
+     *   came back empty, and `'NotTried'` when it wasn't loaded or reading its row failed.
+     */
+    private tryLinkHintedChildEntity;
+    /**
+     * Creates the child object the subtype rule named, or returns null when the user can't read
+     * that entity. A failure to create it is logged and returns null too, so the discovery-only
+     * path decides.
+     */
+    private createReadableHintedChild;
+    /**
+     * Asks the entity's subtype rule which child a LOADED record has, without running a query.
+     *
+     * - A registered {@link EntitySubtypeResolver} owns the rule. It gives a hint only when its
+     *   class overrides {@link EntitySubtypeResolver.ResolveLoadHint}. A resolver that doesn't
+     *   gives none, and the `SubtypeSelector` isn't consulted in its place: at create time the
+     *   resolver overrides the selector, so the selector may not describe the same rule.
+     * - Otherwise a `SubtypeSelector` that sets `UseForLoadedRecords` is walked through rows that
+     *   loaded `BaseEngine` caches already hold. A hop that isn't cached gives no hint, not a query.
+     * - An entity with no rule gets no hint. The single-child fallback of
+     *   {@link ResolveSubtypeEntityName} is a default for new records, not a rule about existing ones.
+     * - While {@link AttachToParent} loads this record, no rule is asked: the child row being added
+     *   doesn't exist yet.
+     *
+     * An answer of "no subtype" also gives no hint: only the discovery query can tell whether an
+     * older record still has a child row.
+     *
+     * @returns A declared IsA child's entity name, or null when there is no usable hint. Never throws.
+     */
+    private resolveSubtypeLoadHint;
+    /**
+     * The resolver to ask for load hints for an entity, decided once per registration and cached:
+     * null when the registered class doesn't override {@link EntitySubtypeResolver.ResolveLoadHint},
+     * which is read from the class without constructing it, or when constructing it failed.
+     */
+    private static loadHintResolverFor;
+    /** Whether a registered resolver class overrides `ResolveLoadHint`, read from its prototype. */
+    private static overridesResolveLoadHint;
+    /**
+     * Constructs the registered resolver once, to ask it for load hints. A failure is logged and
+     * gives null; since the answer is cached, that is once per entity.
+     */
+    private static constructLoadHintResolver;
+    /**
+     * Asks the resolver for a load hint. A resolver that throws or rejects gives no hint for that
+     * record, and is logged once per entity rather than per record.
+     */
+    private askResolverForLoadHint;
+    /**
+     * Walks the `SubtypeSelector` path through engine caches only. A path that isn't valid for
+     * this entity's metadata is logged once and gives no hint; the create path throws on it instead.
+     */
+    private evaluateSelectorForLoadHint;
+    /**
+     * Turns a rule's answer into a declared child's canonical entity name. Empty means no subtype,
+     * which gives no hint. A name that isn't a declared IsA child is logged once and gives no hint.
+     */
+    private declaredChildForLoadHint;
+    /**
+     * Reports a hint the data didn't bear out: the hinted child's row wasn't there.
+     *
+     * When the discovery query finds no child either, that is a normal state, not an error: core
+     * never creates a subtype row on save, so a typed record can exist without one (saved through
+     * a generic form or an import, or older than its type's subtype). It logs one verbose line per
+     * entity and hinted child. When the discovery query finds a DIFFERENT child, the rule and the
+     * data disagree, and each such load costs an extra round trip until one of them is fixed; that
+     * is logged as an error, once per entity, hinted child and child found.
+     */
+    private reportSubtypeLoadHintMiss;
+    /** Keys of load-hint messages already logged, so each is reported once rather than per record. */
+    private static _loggedSubtypeLoadHintMessages;
+    /** Runs `log` the first time `key` is seen (case-insensitively), and not again until the caches are cleared. */
+    private static logSubtypeLoadHintOnce;
+    private static errorText;
     private static _subtypeLookupCache;
+    /** Per entity (lowercased name): the resolver asked for load hints, decided once per registration. */
+    private static _subtypeLoadHintResolvers;
+    /** Indexes over engine-cached arrays, keyed by the live array itself; see {@link findEngineCachedRow}. */
+    private static _engineCachedRowIndexes;
     /**
-     * Clears the static memoization cache used by SubtypeSelector path evaluation.
+     * Clears the static caches IsA subtype resolution keeps: the create path's SubtypeSelector
+     * lookup memo, the per-entity decision about which resolver gives load hints, the indexes over
+     * engine-cached rows, and the record of load-hint messages already logged, so each can be
+     * reported again.
      */
     static ClearSubtypeLookupCache(): void;
+    /**
+     * The declared IsA child entity named `name`, matched the way metadata lookups match names
+     * (trimmed, case-insensitive), or undefined when this entity declares no such child. The one
+     * lookup behind {@link ResolveSubtypeEntityName}, {@link EnsureISAChild} and load hints: the
+     * create path throws on a miss, the load path logs it.
+     */
+    private findDeclaredChild;
     /**
      * Prospective counterpart to FindISAChildEntity.
      * Evaluates which IsA child subtype entity this record should have based on:
@@ -875,6 +1108,12 @@ export declare abstract class BaseEntity<T = unknown> {
      * 3. Unconditional single-child IsA fallback (ChildEntities.length === 1)
      * 4. Otherwise null (no subtype)
      *
+     * This is the create-time ladder, and steps 1 and 2 may query. When a record is loaded,
+     * BaseEntity asks a narrower, query-free version of it for a hint instead: the resolver's
+     * `ResolveLoadHint` (not `Resolve`) when its class overrides it, the selector only when it sets
+     * `UseForLoadedRecords` and only through rows that loaded `BaseEngine` caches hold, and never
+     * step 3.
+     *
      * @see plans/sync-composition-axes.md
      */
     ResolveSubtypeEntityName(): Promise<string | null>;
@@ -888,9 +1127,60 @@ 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
+     * name, and returns that column's value, or null when a hop's foreign key is empty, a target
+     * isn't found, or the terminal value is empty.
+     *
+     * @param path The dotted path, e.g. `ProductTypeID.ProductExtensionEntity`.
+     * @param findTarget Finds the record a foreign key points at. Create time passes a finder that
+     *   may query; load time passes one that reads engine caches only, so a hop missing from them
+     *   ends the walk with null instead of a query.
+     * @throws When the path doesn't fit this entity's metadata (a field isn't found, or a hop isn't
+     *   a foreign key).
+     */
     private evaluateSubtypeSelectorPath;
     private getSubtypePathTargetEntity;
+    /**
+     * Finds the record a `SubtypeSelector` hop points at among the entity objects that loaded
+     * `BaseEngine` caches already hold. Never queries, and never reads the create path's memo, whose
+     * entries can outlive a change to the row: engine caches are kept current by entity events.
+     *
+     * `pkValue` is one foreign-key column's value, matched against the first primary key of the
+     * cached rows' entity the way UUIDs compare (trimmed, case-insensitive).
+     *
+     * @returns The cached record, or null when no loaded engine holds it as an entity object.
+     */
+    private static findSubtypePathTargetInEngineCache;
+    /**
+     * Finds the row whose key is `key` in an engine's live cached array through an index over the
+     * array, not a scan per lookup. Keys are read with `Get()`, which leaves the rows an engine holds
+     * in raw mode unhydrated.
+     *
+     * The array is the engine's own and changes under the index: a refresh replaces it, and a save,
+     * delete or remote invalidation pushes a row, splices one out, or swaps one for a copy with the
+     * same key. So the index is keyed by the array itself, and rebuilt when the array's length or
+     * last element differs from when it was built, which every added or removed row changes. A hit
+     * is checked against the row now at that position, and a row that moved makes the index rebuild
+     * before the answer is trusted. A key that isn't indexed is a miss, which gives no hint on load
+     * and falls back to a query at create time, as for a row no engine caches.
+     */
+    private static findEngineCachedRow;
+    /** The index over `records`, rebuilt when the array's length or last element changed since it was built. */
+    private static currentEngineCachedRowIndex;
+    /** Indexes `records` by key. Anything that isn't an entity object (a `'simple'` cache holds plain rows) is skipped. */
+    private static buildEngineCachedRowIndex;
+    /** A cached row's key, normalized with `NormalizeUUID`; null for a row that isn't an entity object or has no key value. */
+    private static engineCachedRowKey;
     private captureChainDirtyState;
     private restoreChainDirtyState;
     /**
@@ -1008,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.
@@ -1228,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.
      *
@@ -1264,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.
      */
@@ -1505,7 +1863,7 @@ export declare abstract class BaseEntity<T = unknown> {
      * Callers should gate this behind `EntityInfo.HasInactiveFields` so the common all-Active entity
      * skips the field lookup entirely.
      */
-    private AssertFieldActiveStatus;
+    private assertFieldActiveStatus;
     /**
      * Field-level security choke point for the strongly-typed accessor path. Throws when the
      * acting user may not READ the field.
@@ -1527,12 +1885,12 @@ export declare abstract class BaseEntity<T = unknown> {
      * build) reads `EntityField.Value` directly and never routes through here — that exemption
      * is load-bearing, not an oversight. Do not "fix" it.
      */
-    private AssertFieldReadable;
+    private assertFieldReadable;
     /**
      * Internal helper that sets a field value directly on THIS entity's own Fields array
      * without IS-A routing. Used by Set() for own-fields and for mirroring parent field values.
      */
-    private SetLocal;
+    private setLocal;
     /**
      * Returns the value of the field with the given name. If the field is a date, and the value is a string, it will be converted to a date object.
      *
@@ -1565,7 +1923,7 @@ export declare abstract class BaseEntity<T = unknown> {
      * a saved/loaded record. This enables entities populated via SetMany (e.g., IS-A parent
      * entities) to correctly recognize themselves as existing records.
      */
-    private UpdateSavedStateFromPrimaryKeys;
+    private updateSavedStateFromPrimaryKeys;
     /**
      * NOTE: Do not call this method directly. Use the {@link To} method instead
      *
@@ -1703,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.
@@ -1751,12 +2137,12 @@ export declare abstract class BaseEntity<T = unknown> {
      * @param options
      * @returns
      */
-    private _InnerSave;
+    private _innerSave;
     /**
      * Runs all registered PreSave hooks. If any hook returns false or a string
      * (error message), the save is rejected by throwing an Error.
      */
-    private RunPreSaveHooks;
+    private runPreSaveHooks;
     /**
      * Determines whether the parent entity should be deleted after this child entity
      * has been deleted. For overlapping subtype parents (AllowMultipleSubtypes = true),
@@ -1773,7 +2159,7 @@ export declare abstract class BaseEntity<T = unknown> {
      * Caches the entity record name in the provider's EntityRecordNameCache for faster lookups.
      * Called automatically after successful Load(), LoadFromData(), and Save() operations.
      */
-    private CacheRecordName;
+    private cacheRecordName;
     /**
      * Utility method that returns true if the given permission being checked is enabled for the current user, and false if not.
      * @param type
@@ -1878,6 +2264,14 @@ export declare abstract class BaseEntity<T = unknown> {
      * @returns true if success, false otherwise
      */
     InnerLoad(CompositeKey: CompositeKey, EntityRelationshipsToLoad?: string[]): Promise<boolean>;
+    /**
+     * The provider's read of the row {@link InnerLoad} loads. While this record is a subtype-hint
+     * probe, a throw from the read is recorded on the probe before it propagates, so the parent
+     * that asked can tell it apart from a failure after the row loaded.
+     */
+    private readRowForLoad;
+    /** The error {@link InnerLoad} logs when the provider finds no row for the key. */
+    private static logLoadFoundNoRow;
     /**
      * Re-fetches the current record from the database using its existing primary key, replacing all in-memory field values
      * with the latest data from the database. This is useful when you know (or suspect) the record has been modified externally
@@ -2040,7 +2434,7 @@ export declare abstract class BaseEntity<T = unknown> {
      * @param options
      * @returns
      */
-    private _InnerDelete;
+    private _innerDelete;
     /**
      * Checks if this entity has any child records in IS-A child entity tables.
      * Used for parent delete protection — a parent record cannot be deleted
@@ -2080,7 +2474,7 @@ export declare abstract class BaseEntity<T = unknown> {
      * Internal recursive helper for leaf entity resolution.
      * Walks down the child hierarchy until no more children are found.
      */
-    private static ResolveLeafEntityRecursive;
+    private static resolveLeafEntityRecursive;
     /**
      * Enforces disjoint subtype constraint during IS-A child entity creation.
      * A parent record can only be ONE child type at a time. Checks all sibling