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

package/LICENSE

@@ -0,0 +1,183 @@
+Business Source License 1.1
+
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB plc.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Blue Cypress, Inc.
+
+Licensed Work:        MemberJunction.
+                      The Licensed Work is (c) 2023-2026 Blue Cypress, Inc.
+
+Additional Use Grant: Subject to the terms of this License, Licensor grants
+                      you the following additional rights to make Production
+                      Use of the Licensed Work.
+
+                      1. Internal Use
+
+                      You may make production use of the Licensed Work for
+                      your own internal business or organizational operations.
+
+                      2. Nonprofit Use
+
+                      If you are a Nonprofit, you may make production use of
+                      the Licensed Work for the operations and activities of
+                      your Organizational Family.
+
+                      3. MemberJunction Certified Program Use
+
+                      If you are authorized by Licensor under the
+                      MemberJunction Certified Program to provide professional
+                      services using the Licensed Work, you may make
+                      production use of the Licensed Work in providing such
+                      professional services to a client, provided that:
+
+                      (a) the Licensed Work is deployed in, and the applicable
+                      production use occurs within, an environment owned,
+                      leased, licensed, subscribed to, or otherwise controlled
+                      by that client; and
+
+                      (b) the production use is for that client's own internal
+                      business or organizational operations or is otherwise
+                      independently permitted to that client under this
+                      Additional Use Grant.
+
+                      4. Definitions Applicable to the Additional Use Grant
+
+                      "Affiliate" means, with respect to a specified Person,
+                      any other Person that directly or indirectly Controls,
+                      is Controlled by, or is under common Control with such
+                      specified Person.
+
+                      "Control" (including the terms "Controls," "Controlled
+                      by," and "under common Control with") means the direct
+                      or indirect possession of the power to direct or cause
+                      the direction of the management and policies of a
+                      Person, whether through ownership of voting interests,
+                      by contract, or otherwise.
+
+                      "Organizational Family" means, with respect to a Person,
+                      (a) such Person and its Affiliates, and (b) any
+                      nonprofit organization, governmental entity, chapter,
+                      division, local affiliate, regional affiliate, state
+                      affiliate, national affiliate, or other entity that is
+                      formally affiliated with such Person through governing
+                      documents, a charter, bylaws, a membership agreement, or
+                      another written organizational instrument, and is
+                      recognized under such documents as part of the same
+                      organizational structure.
+
+                      "Nonprofit" means a Person recognized by the Internal
+                      Revenue Service as exempt from federal income taxation
+                      under Section 501(c)(3), 501(c)(4), 501(c)(5), or
+                      501(c)(6) of the Internal Revenue Code, or a foreign
+                      organization recognized under substantially equivalent
+                      laws.
+
+                      A Person claiming eligibility as a Nonprofit shall, upon
+                      Licensor's reasonable request, provide documentation
+                      reasonably sufficient to demonstrate that it qualifies
+                      as a Nonprofit. If such Person materially misrepresents,
+                      or is unable to demonstrate, its qualification as a
+                      Nonprofit, the rights granted to such Person under
+                      Section 2 of this Additional Use Grant shall terminate.
+
+                      "MemberJunction Certified Program" means Licensor's
+                      then-current program for certifying and authorizing a
+                      Person to provide professional services using the
+                      Licensed Work.
+
+                      "Person" means any individual, corporation, limited
+                      liability company, partnership, association, nonprofit
+                      organization, governmental entity, or other legal or
+                      organizational entity.
+
+Change Date:          Four (4) years from the date the Licensed Work is first
+                      made available.
+
+Change License:       MIT License.
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact Blue Cypress, Inc.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

package/README.md

@@ -1,4 +1,99 @@
 # @memberjunction/record-cloning
-Seed release published over OIDC to prove trusted publishing is configured for
-this package. It contains no code and is tagged `seed`, never `latest`.
-Real releases are published by .github/workflows/publish.yml.
+
+Server-side engine for cloning an entity record together with the graph of records around it:
+owned child rows and the references it points at. (A Deep IS-A subtype or embedded row blocks the
+plan with `EDGE_KIND_UNSUPPORTED` in this release.) It copies what the entity's
+`Configuration.Clone` bag allows, re-points foreign keys at the new rows, and saves everything in
+one transaction with full provenance.
+
+Pure logic lives in [`@memberjunction/record-cloning-base`](../base/README.md): policy resolution,
+the field mapper, naming, JSON remap, validation and the contract types. Graph traversal comes from
+[`@memberjunction/record-graph`](../../RecordGraph/README.md). The design is in
+[`plans/record-cloning/README.md`](../../../plans/record-cloning/README.md).
+
+## Flow: Describe → Plan → Execute
+
+| Step | What happens | Writes |
+|---|---|---|
+| **Describe** | Whether the user may clone this entity and what the UI may offer: presets, `UserEditable`, relationships with their default policy, and the Fire Hooks / Override Scope flags. | nothing |
+| **Plan** | `ClonePlanner` walks the graph (`DependencyGraphWalker`), resolves each edge to `Deep`, `Reference` or `Skip`, runs the field pipeline on every row, applies `MaxDepth`/`MaxRecords` caps and authorization checks, and hashes the result. | nothing |
+| **Execute** | Plans again. Refuses with `BLOCKED`/`FORBIDDEN` when the plan is blocked, or `PLAN_CHANGED` when the hash differs from the `ExpectedPlanHash` the user reviewed. Otherwise `CloneMaterializer` builds the in-memory graph and `CloneExecutor` saves it. | the clone and its provenance |
+
+- **`ClonePlanner`** produces a deterministic `ClonePlan` (nodes, edges, field changes, warnings, `Blocked`).
+- **`CloneMaterializer`** turns the plan into unsaved entity objects: the root, children in the
+  parent's writable collection (or one declared with `BaseEntity.DeclareRelatedRecordsDynamic`),
+  prerequisites for forward-FK targets, and sidecars.
+- **`CloneExecutor`** sets a clone context on each staged row (`SetCloneContext`), then saves
+  prerequisites, `root.Save()` and sidecars inside `RunInEntityTransaction`, followed by the provenance.
+
+## Entry points
+
+**Remote operations** (`src/operations.ts`): `RecordClone.Describe`, `RecordClone.Plan`,
+`RecordClone.Execute` and `RecordClone.GetLineage`. Each server class extends the operation class
+CodeGen emits into `@memberjunction/core-entities`. The input/output contracts are the types in
+`metadata/remote-operations/types/record-clone-*.ts`. `Plan` output masks encrypted values.
+`GetLineage` reads `ClonedFrom` record links in both directions.
+
+**Programmatic API**, server-side:
+
+```typescript
+import { LogError } from '@memberjunction/core';
+import { RecordCloneEngine } from '@memberjunction/record-cloning';
+
+const engine = new RecordCloneEngine(provider);
+const plan = await engine.Plan({ EntityName: 'MJ: AI Agents', SourceRecordKey: key }, contextUser);
+if (!plan.Blocked) {
+    const result = await engine.Clone(
+        { EntityName: 'MJ: AI Agents', SourceRecordKey: key, Options: { Preset: 'deep-prompts' } },
+        contextUser
+    );
+    if (!result.Success) LogError(result.ErrorMessage);
+}
+```
+
+`Clone` returns the plan without writing anything when `Options.DryRun` is true. `Describe` and
+`GetLineage` are also available.
+
+**Actions** (`packages/Actions/CoreActions/src/custom/record-cloning/`):
+- `Clone Record`: `EntityName`, `RecordID`, optional `Options` JSON and `DryRun`. Outputs
+  `NewRecordID`, `CloneLogID`, `CreatedCount` and `Warnings`.
+- `Clone Records`: takes `RecordIDs` instead and requires `Clone Records: Batch`. Each root is its
+  own clone and transaction. The `Results` output reports each root, and the result code is
+  `PARTIAL` when only some roots succeed.
+
+**Record processes**: the `Clone` work type is `CloneRecordProcessor`. `RecordCloningStartup`
+(`@RegisterForStartup`) registers it with `RecordProcessorRegistry` at server boot. The run's
+`Configuration` JSON supplies `Options`, `EdgeOverrides`, `FieldOverrides` and `DryRun`. It requires
+`Clone Records: Batch`.
+
+## Authorization (`CloneAuthorization.ts`)
+
+`CloneAuthorizer` checks every created row against its entity's clone authorization. That is
+`Configuration.Clone.RequiredAuthorization` if set. Otherwise it is `Clone Records: <Entity Name>`
+if that authorization exists, and otherwise `Clone Records in Platform Schema` (for `__mj`) or
+`Clone Records in Custom Schemas`. Checks walk ancestors, so a holder of `Clone Records` passes all
+of them. `Clone Records: Fire Hooks` lets a request change whether Entity Actions and AI Actions fire.
+`Clone Records: Override Scope` lets a request widen a clone with a `Deep` override. An authorization
+missing from metadata grants nothing. The planner also requires `CanCreate` on every created entity and
+the root's `RequiredUserType`, if set.
+
+## Provenance
+
+A successful clone writes, in the same transaction:
+- a Record Change per new row (for entities that track record changes), with `Source = 'Clone'` and `ChangeContext` JSON
+- one `MJ: Record Clone Logs` header (masked plan, options, counts, `InitiatedByUserID` = the cloner)
+- one `MJ: Record Clone Log Items` row per planned node (`Created` / `Referenced` / `Skipped`)
+- one `MJ: Record Links` row per new record, with `LinkType = 'ClonedFrom'` (Source = clone, Target = original)
+- a `Record Cloned` audit log entry, when the entity's clone authorization has `UseAuditLog` (every shipped one does)
+
+If the log or a link fails to save, the whole clone rolls back. The log, log items and links are
+saved as the **system user** when one is available, because they are the platform's record, not the
+cloner's data. The audit entry is recorded as the cloner. Refused and failed runs still get a log
+(`Cancelled` / `Error`) and, under the same `UseAuditLog` rule, an audit entry, written outside any transaction.
+
+## Transactions
+
+A clone is all or nothing. If the provider lacks `SupportsEntityTransactions` and
+`BeginEntityTransaction`, `Execute` refuses before writing anything and returns `EXECUTION_ERROR`.
+It still records a refusal log. Run clones on the server, through the remote operations, the
+actions or a record process.

package/dist/CloneAuthorization.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file CloneAuthorization.ts
+ * Server-side authorization checks for record cloning.
+ *
+ * Resolution for an entity (plan §9.1): `Configuration.Clone.RequiredAuthorization` when set;
+ * else the per-entity leaf `Clone Records: <Entity Name>` when one exists; else the schema
+ * node (`Clone Records in Platform Schema` for `__mj`, `Clone Records in Custom Schemas`
+ * otherwise). Every check walks ancestors, so a `Clone Records` holder passes them all.
+ *
+ * @see plans/record-cloning/README.md §9
+ */
+import { AuthorizationInfo, EntityInfo, IMetadataProvider, UserInfo } from '@memberjunction/core';
+/** Name of the authorization that allows firing Entity Actions / AI Actions during a clone. */
+export declare const FIRE_HOOKS_AUTHORIZATION = "Clone Records: Fire Hooks";
+/** Name of the authorization that allows widening a clone beyond the entity's configured scope. */
+export declare const OVERRIDE_SCOPE_AUTHORIZATION = "Clone Records: Override Scope";
+/** Name of the authorization that allows cloning several records in one request (the `Clone Records` action). */
+export declare const BATCH_AUTHORIZATION = "Clone Records: Batch";
+/** Outcome of one authorization check, in the shape `RecordClone.Describe` returns. */
+export interface CloneAuthorizationResult {
+    /** The authorization that was checked. */
+    Name: string;
+    /** Whether the user holds it (directly or through an ancestor). */
+    Granted: boolean;
+}
+/**
+ * Evaluates the clone authorizations for one provider. Create one per request; it only reads
+ * the provider's cached `Authorizations` list.
+ */
+export declare class CloneAuthorizer {
+    private readonly provider;
+    private readonly evaluator;
+    constructor(provider: IMetadataProvider);
+    /** The authorization that governs creating rows of `entity` in a clone. */
+    ResolveAuthorizationName(entity: EntityInfo): string;
+    /** Whether `user` may clone rows of `entity`. */
+    CanCloneEntity(entity: EntityInfo, user: UserInfo): CloneAuthorizationResult;
+    /** Whether `user` may fire Entity Actions and AI Actions during a clone. */
+    CanFireHooks(user: UserInfo): boolean;
+    /** Whether `user` may widen a clone beyond the entity's configured scope. */
+    CanOverrideScope(user: UserInfo): boolean;
+    /** Whether `user` may clone several records in one request. */
+    CanBatchClone(user: UserInfo): boolean;
+    /** An authorization missing from metadata grants nothing: the check fails closed. */
+    private userHolds;
+    /** The authorization a clone of `entity` is checked against, or undefined when it isn't seeded. */
+    EntityAuthorization(entity: EntityInfo): AuthorizationInfo | undefined;
+    private find;
+}
+//# sourceMappingURL=CloneAuthorization.d.ts.map

package/dist/CloneAuthorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloneAuthorization.d.ts","sourceRoot":"","sources":["../src/CloneAuthorization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAA0B,iBAAiB,EAAE,UAAU,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE1H,+FAA+F;AAC/F,eAAO,MAAM,wBAAwB,8BAA8B,CAAC;AAEpE,mGAAmG;AACnG,eAAO,MAAM,4BAA4B,kCAAkC,CAAC;AAE5E,iHAAiH;AACjH,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAK1D,uFAAuF;AACvF,MAAM,WAAW,wBAAwB;IACrC,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,eAAe;IAGL,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAF5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;gBAEtB,QAAQ,EAAE,iBAAiB;IAE/D,2EAA2E;IACpE,wBAAwB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM;IAY3D,iDAAiD;IAC1C,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,GAAG,wBAAwB;IAKnF,4EAA4E;IACrE,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO;IAI5C,6EAA6E;IACtE,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO;IAIhD,+DAA+D;IACxD,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO;IAI7C,qFAAqF;IACrF,OAAO,CAAC,SAAS;IAMjB,mGAAmG;IAC5F,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,iBAAiB,GAAG,SAAS;IAI7E,OAAO,CAAC,IAAI;CAIf"}

package/dist/CloneAuthorization.js

@@ -0,0 +1,75 @@
+/**
+ * @file CloneAuthorization.ts
+ * Server-side authorization checks for record cloning.
+ *
+ * Resolution for an entity (plan §9.1): `Configuration.Clone.RequiredAuthorization` when set;
+ * else the per-entity leaf `Clone Records: <Entity Name>` when one exists; else the schema
+ * node (`Clone Records in Platform Schema` for `__mj`, `Clone Records in Custom Schemas`
+ * otherwise). Every check walks ancestors, so a `Clone Records` holder passes them all.
+ *
+ * @see plans/record-cloning/README.md §9
+ */
+import { AuthorizationEvaluator } from '@memberjunction/core';
+/** Name of the authorization that allows firing Entity Actions / AI Actions during a clone. */
+export const FIRE_HOOKS_AUTHORIZATION = 'Clone Records: Fire Hooks';
+/** Name of the authorization that allows widening a clone beyond the entity's configured scope. */
+export const OVERRIDE_SCOPE_AUTHORIZATION = 'Clone Records: Override Scope';
+/** Name of the authorization that allows cloning several records in one request (the `Clone Records` action). */
+export const BATCH_AUTHORIZATION = 'Clone Records: Batch';
+/** Schema that holds MemberJunction's own entities. */
+const PLATFORM_SCHEMA = '__mj';
+/**
+ * Evaluates the clone authorizations for one provider. Create one per request; it only reads
+ * the provider's cached `Authorizations` list.
+ */
+export class CloneAuthorizer {
+    constructor(provider) {
+        this.provider = provider;
+        this.evaluator = new AuthorizationEvaluator();
+    }
+    /** The authorization that governs creating rows of `entity` in a clone. */
+    ResolveAuthorizationName(entity) {
+        const configured = entity.CloneConfig?.RequiredAuthorization?.trim();
+        if (configured)
+            return configured;
+        const leaf = `Clone Records: ${entity.Name}`;
+        if (this.find(leaf))
+            return leaf;
+        return entity.SchemaName?.trim().toLowerCase() === PLATFORM_SCHEMA
+            ? 'Clone Records in Platform Schema'
+            : 'Clone Records in Custom Schemas';
+    }
+    /** Whether `user` may clone rows of `entity`. */
+    CanCloneEntity(entity, user) {
+        const name = this.ResolveAuthorizationName(entity);
+        return { Name: name, Granted: this.userHolds(name, user) };
+    }
+    /** Whether `user` may fire Entity Actions and AI Actions during a clone. */
+    CanFireHooks(user) {
+        return this.userHolds(FIRE_HOOKS_AUTHORIZATION, user);
+    }
+    /** Whether `user` may widen a clone beyond the entity's configured scope. */
+    CanOverrideScope(user) {
+        return this.userHolds(OVERRIDE_SCOPE_AUTHORIZATION, user);
+    }
+    /** Whether `user` may clone several records in one request. */
+    CanBatchClone(user) {
+        return this.userHolds(BATCH_AUTHORIZATION, user);
+    }
+    /** An authorization missing from metadata grants nothing: the check fails closed. */
+    userHolds(name, user) {
+        const auth = this.find(name);
+        if (!auth)
+            return false;
+        return this.evaluator.UserCanExecuteWithAncestors(auth, user, this.provider.Authorizations ?? []);
+    }
+    /** The authorization a clone of `entity` is checked against, or undefined when it isn't seeded. */
+    EntityAuthorization(entity) {
+        return this.find(this.ResolveAuthorizationName(entity));
+    }
+    find(name) {
+        const target = name.trim().toLowerCase();
+        return (this.provider.Authorizations ?? []).find((a) => a.Name?.trim().toLowerCase() === target);
+    }
+}
+//# sourceMappingURL=CloneAuthorization.js.map

package/dist/CloneAuthorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloneAuthorization.js","sourceRoot":"","sources":["../src/CloneAuthorization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,sBAAsB,EAA8D,MAAM,sBAAsB,CAAC;AAE1H,+FAA+F;AAC/F,MAAM,CAAC,MAAM,wBAAwB,GAAG,2BAA2B,CAAC;AAEpE,mGAAmG;AACnG,MAAM,CAAC,MAAM,4BAA4B,GAAG,+BAA+B,CAAC;AAE5E,iHAAiH;AACjH,MAAM,CAAC,MAAM,mBAAmB,GAAG,sBAAsB,CAAC;AAE1D,uDAAuD;AACvD,MAAM,eAAe,GAAG,MAAM,CAAC;AAU/B;;;GAGG;AACH,MAAM,OAAO,eAAe;IAGxB,YAAoC,QAA2B;QAA3B,aAAQ,GAAR,QAAQ,CAAmB;QAF9C,cAAS,GAAG,IAAI,sBAAsB,EAAE,CAAC;IAEQ,CAAC;IAEnE,2EAA2E;IACpE,wBAAwB,CAAC,MAAkB;QAC9C,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,EAAE,qBAAqB,EAAE,IAAI,EAAE,CAAC;QACrE,IAAI,UAAU;YAAE,OAAO,UAAU,CAAC;QAElC,MAAM,IAAI,GAAG,kBAAkB,MAAM,CAAC,IAAI,EAAE,CAAC;QAC7C,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAEjC,OAAO,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,eAAe;YAC9D,CAAC,CAAC,kCAAkC;YACpC,CAAC,CAAC,iCAAiC,CAAC;IAC5C,CAAC;IAED,iDAAiD;IAC1C,cAAc,CAAC,MAAkB,EAAE,IAAc;QACpD,MAAM,IAAI,GAAG,IAAI,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC;QACnD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;IAC/D,CAAC;IAED,4EAA4E;IACrE,YAAY,CAAC,IAAc;QAC9B,OAAO,IAAI,CAAC,SAAS,CAAC,wBAAwB,EAAE,IAAI,CAAC,CAAC;IAC1D,CAAC;IAED,6EAA6E;IACtE,gBAAgB,CAAC,IAAc;QAClC,OAAO,IAAI,CAAC,SAAS,CAAC,4BAA4B,EAAE,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED,+DAA+D;IACxD,aAAa,CAAC,IAAc;QAC/B,OAAO,IAAI,CAAC,SAAS,CAAC,mBAAmB,EAAE,IAAI,CAAC,CAAC;IACrD,CAAC;IAED,qFAAqF;IAC7E,SAAS,CAAC,IAAY,EAAE,IAAc;QAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QACxB,OAAO,IAAI,CAAC,SAAS,CAAC,2BAA2B,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;IACtG,CAAC;IAED,mGAAmG;IAC5F,mBAAmB,CAAC,MAAkB;QACzC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5D,CAAC;IAEO,IAAI,CAAC,IAAY;QACrB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACzC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,CAAC;IACrG,CAAC;CACJ"}

package/dist/CloneExecutor.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file CloneExecutor.ts
+ * Executes deterministic clone plans inside an atomic database transaction.
+ * Materializes graphs, verifies plan hash stability, enforces root.Save() arbitration,
+ * and writes provenance: Record Changes, a Clone Log with one item per planned row, ClonedFrom
+ * Record Links, and a Record Cloned audit entry. Refused and failed runs are logged too.
+ * @see plans/record-cloning/README.md §6, §8, §10, §13.1
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { ClonePlan, RecordCloneResult } from '@memberjunction/record-cloning-base';
+export interface CloneExecutorOptions {
+    Provider?: IMetadataProvider;
+}
+export declare class CloneExecutor {
+    private _provider?;
+    constructor(options?: CloneExecutorOptions);
+    protected get Provider(): IMetadataProvider;
+    /**
+     * Executes a ClonePlan atomically.
+     */
+    Execute(plan: ClonePlan, contextUser: UserInfo): Promise<RecordCloneResult>;
+    /**
+     * Save options for the clone's own rows, from the plan's effective options: Entity Actions run
+     * by default and AI Actions don't, unless the entity's configuration (or a Fire Hooks holder's
+     * request) says otherwise.
+     */
+    private static saveOptionsFor;
+    /**
+     * Records a refused run (blocked, or the plan changed since review) as a Cancelled clone log,
+     * so every Execute leaves a trace. Written outside any transaction; never throws.
+     * @returns the log's ID, or null when it could not be written.
+     */
+    WriteRefusalLog(plan: ClonePlan, contextUser: UserInfo, reason: string): Promise<string | null>;
+    /**
+     * The identity provenance rows are saved as. Logs and lineage links are the platform's record
+     * of what happened, not the cloner's own data (the UI role may only read them), so they are
+     * written as the system user when this process has one. `InitiatedByUserID` still names the cloner.
+     */
+    private provenanceUser;
+    /** Clone log, one log item per plan node, ClonedFrom links, and the audit entry. Throws if the log or a link can't be saved. */
+    private writeSuccessProvenance;
+    /**
+     * Saves one clone log header. Returns whether it saved; failures are logged, never thrown, so the
+     * failure and refusal paths can call it after a rollback.
+     */
+    private writeLog;
+    /** One `Record Cloned` audit entry per Execute, as the cloner. Best effort, like all audit logging. */
+    private writeAudit;
+}
+//# sourceMappingURL=CloneExecutor.d.ts.map

package/dist/CloneExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloneExecutor.d.ts","sourceRoot":"","sources":["../src/CloneExecutor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAMH,iBAAiB,EAIjB,QAAQ,EAEX,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACH,SAAS,EAKT,iBAAiB,EACpB,MAAM,qCAAqC,CAAC;AAgC7C,MAAM,WAAW,oBAAoB;IACjC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED,qBAAa,aAAa;IACtB,OAAO,CAAC,SAAS,CAAC,CAAoB;gBAEnB,OAAO,CAAC,EAAE,oBAAoB;IAIjD,SAAS,KAAK,QAAQ,IAAI,iBAAiB,CAE1C;IAED;;OAEG;IACU,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAmLxF;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAO7B;;;;OAIG;IACU,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAO5G;;;;OAIG;YACW,cAAc;IAI5B,gIAAgI;YAClH,sBAAsB;IAsEpC;;;OAGG;YACW,QAAQ;IAmCtB,uGAAuG;YACzF,UAAU;CAqB3B"}