@memberjunction/metadata-sync 6.1.2 → 6.2.0-edge.0

package/dist/lib/graph-provider-pool.js

@@ -1,26 +1,61 @@
 /**
- * One independent provider per JSON-root graph for `mj sync push`.
+ * Provider assignment per JSON-root graph for `mj sync push`.
  *
- * Sibling graphs may run in parallel; a root and its nested relatedEntities share
- * one provider so every DB op in that graph uses the same connection. Mixing the
- * host connection with a graph instance in the same tree is a deadlock (child FK
- * waits on an uncommitted parent).
+ * Two modes, fixed when the pool is built. A pool never mixes them.
  *
- * Drain: a graph is released at the end of a batch when (a) it will not appear
- * at a later level, or (b) its TransactionDepth is 0 (Save already committed,
- * so a fresh instance at the next level is safe). Graphs with leftover depth
- * stay live until their last level. Peak live independent instances is therefore
- * bounded by `--parallel-batch-size`, plus any still-open leftover-depth graphs.
+ * - **`host`** (atomic push, the default): every graph uses the host provider, inside the
+ *   push transaction. Nothing commits until the push commits. The host has ONE transaction
+ *   stack, so graphs must run one at a time: `obtain` throws if a second graph asks for the
+ *   host while another graph still holds it. The caller releases a graph with `drainBatch`.
+ *
+ * - **`independent`** (an entity directory using isolated transactions): each graph gets its own instance from
+ *   `CreateIndependentInstance()` (shared pool, own transaction stack), so sibling graphs can
+ *   run in parallel. A root and its nested relatedEntities share one instance, so every DB op
+ *   in that graph uses the same connection. Each `Save()` commits on its own, so this mode is
+ *   NOT atomic: `onGraphSettled` reports which graphs left committed rows behind.
+ *   If `CreateIndependentInstance` fails, `obtain` throws. It never falls back to the host,
+ *   because mixing the host connection with graph instances is a deadlock (child FK waits on
+ *   an uncommitted parent). The caller decides the mode up front (see `probeIndependentInstances`).
+ *
+ * Drain (independent mode): a graph is released at the end of a batch when (a) it will not
+ * appear at a later level, or (b) its TransactionDepth is 0 (Save already committed, so a fresh
+ * instance at the next level is safe). Graphs with leftover depth stay live until their last
+ * level. Peak live independent instances is therefore bounded by the batch size, plus any
+ * still-open leftover-depth graphs.
  */
+/**
+ * Checks once whether the host can create independent instances. Used to pick the pool mode
+ * before any graph runs, so a push never discovers mid-file that it has to switch topology.
+ * @returns `undefined` when independent instances work, otherwise the reason they do not.
+ */
+export async function probeIndependentInstances(host) {
+    let instance;
+    try {
+        instance = await host.CreateIndependentInstance();
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+    try {
+        await instance.ReleaseIndependentInstance();
+    }
+    catch {
+        /* the probe instance did no work; a failed release changes nothing */
+    }
+    return undefined;
+}
 export class GraphProviderPool {
-    constructor(host, log = () => undefined) {
+    constructor(host, options) {
         this.host = host;
-        this.log = log;
         this.providers = new Map();
         this.lastLevelByGraph = new Map();
-        this.independentUnavailable = false;
-        this.unavailableLogged = false;
         this.anyFailed = false;
+        this.mode = options.mode;
+        this.log = options.log ?? (() => undefined);
+        this.onGraphSettled = options.onGraphSettled;
+    }
+    get Mode() {
+        return this.mode;
     }
     /**
      * Record, per graphId, the highest dependency-level index it occupies so we
@@ -41,54 +76,44 @@ export class GraphProviderPool {
     get hasFailed() {
         return this.anyFailed;
     }
-    /**
-     * Provider for this graph. Never returns a mix: either every graph in the
-     * file gets its own independent instance, or (if the *first*
-     * CreateIndependentInstance fails) every graph uses the host.
-     *
-     * If independent instances already exist and a later CreateIndependentInstance
-     * throws, this throws rather than handing the rest of the file to the host.
-     * Mid-file topology change is the deadlock this pool exists to prevent.
-     *
-     * The host itself is never stored in the map, so release cannot
-     * RollbackTransaction the global push TX.
-     */
+    /** Provider for this graph. See the class comment for the per-mode rules. */
     async obtain(graphId) {
+        if (this.mode === 'host') {
+            return this.obtainHost(graphId);
+        }
         const existing = this.providers.get(graphId);
         if (existing)
             return existing;
-        if (this.independentUnavailable)
-            return this.host;
         try {
             const created = await this.host.CreateIndependentInstance();
             this.providers.set(graphId, created);
             return created;
         }
         catch (e) {
-            const reason = e.message;
-            if (this.providers.size > 0) {
-                throw new Error(`CreateIndependentInstance failed after ${this.providers.size} graph(s) already had independent instances (${reason}). ` +
-                    `Refusing mixed host + independent topology in one file.`);
-            }
-            this.independentUnavailable = true;
-            if (!this.unavailableLogged) {
-                this.unavailableLogged = true;
-                this.log(`⚠️  CreateIndependentInstance unavailable (${reason}); ` +
-                    `ALL graphs in this file use the host provider (inside the push transaction). ` +
-                    `Mixing host + independent instances in one file is a deadlock — we refuse that topology.`);
-            }
-            return this.host;
+            const reason = e instanceof Error ? e.message : String(e);
+            throw new Error(`CreateIndependentInstance failed for graph ${graphId} (${reason}). ` +
+                `Refusing to run this graph on the host provider: mixing host and independent instances is a deadlock.`);
         }
     }
+    obtainHost(graphId) {
+        if (this.hostHolder !== undefined && this.hostHolder !== graphId) {
+            throw new Error(`Graph ${graphId} asked for the host provider while graph ${this.hostHolder} still holds it. ` +
+                `In atomic mode graphs share one transaction stack and must run one at a time.`);
+        }
+        this.hostHolder = graphId;
+        return this.host;
+    }
     /**
-     * Commit-or-rollback + release graphs in this batch that are done:
-     * their last level is `levelIndex`, or TransactionDepth is already 0
-     * (Save settled; a fresh instance at a later level is safe).
-     * Leftover-depth graphs that still appear later stay live.
-     * Returns the first settle error so the caller cannot report success
-     * with uncommitted rows.
+     * Release graphs in this batch that are done. Host mode: frees the host for the next graph
+     * (the push transaction settles it later). Independent mode: commit-or-rollback + release the
+     * graphs whose last level is `levelIndex`, or whose TransactionDepth is already 0.
+     * Returns the first settle error so the caller cannot report success with uncommitted rows.
      */
     async drainBatch(graphIds, levelIndex) {
+        if (this.mode === 'host') {
+            this.releaseHost(graphIds);
+            return undefined;
+        }
         const ending = graphIds.filter((id) => {
             const last = this.lastLevelByGraph.get(id) ?? levelIndex;
             if (last === levelIndex)
@@ -98,52 +123,79 @@ export class GraphProviderPool {
         });
         return this.releaseGraphs(ending);
     }
-    /** Release every remaining independent instance. Safe to call from `finally`. */
+    /** Release every remaining graph. Safe to call from `finally`. */
     async releaseAll() {
+        if (this.mode === 'host') {
+            this.hostHolder = undefined;
+            return undefined;
+        }
         return this.releaseGraphs([...this.providers.keys()]);
     }
+    releaseHost(graphIds) {
+        if (this.hostHolder !== undefined && graphIds.includes(this.hostHolder)) {
+            this.hostHolder = undefined;
+        }
+    }
     async releaseGraphs(ids) {
         let settleError;
         for (const id of ids) {
             const provider = this.providers.get(id);
             this.providers.delete(id);
-            if (!provider || provider === this.host)
+            if (!provider)
                 continue;
+            const error = await this.settleAndRelease(id, provider);
+            settleError ??= error;
+        }
+        return settleError;
+    }
+    /** Settle one independent instance, report the outcome, and always release it. */
+    async settleAndRelease(id, provider) {
+        try {
+            const outcome = await this.settle(provider);
+            this.onGraphSettled?.(id, outcome);
+            return undefined;
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            this.anyFailed = true;
+            this.log(`Failed to settle graph ${id} transaction: ${error.message}`);
+            await this.rollbackQuietly(provider);
+            this.onGraphSettled?.(id, 'rolledBack');
+            return error;
+        }
+        finally {
             try {
-                if (provider.TransactionDepth > 0) {
-                    if (this.anyFailed) {
-                        // Explicit rollback at the call site — do not rely on
-                        // ReleaseIndependentInstance's implicit leftover-depth rollback.
-                        await provider.RollbackTransaction();
-                    }
-                    else {
-                        await provider.CommitTransaction();
-                    }
-                }
+                await provider.ReleaseIndependentInstance();
             }
-            catch (e) {
-                this.anyFailed = true;
-                settleError ??= e;
-                this.log(`Failed to settle graph ${id} transaction: ${e.message}`);
-                try {
-                    if (provider.TransactionDepth > 0) {
-                        await provider.RollbackTransaction();
-                    }
-                }
-                catch {
-                    /* still release */
-                }
+            catch {
+                /* pool-safe: handle already dropped */
             }
-            finally {
-                try {
-                    await provider.ReleaseIndependentInstance();
-                }
-                catch {
-                    /* pool-safe: handle already dropped */
-                }
+        }
+    }
+    /**
+     * Depth 0: every Save on this instance already committed. Leftover depth: commit it, or
+     * roll it back explicitly when the file failed (do not rely on ReleaseIndependentInstance).
+     */
+    async settle(provider) {
+        if (provider.TransactionDepth === 0) {
+            return 'committed';
+        }
+        if (this.anyFailed) {
+            await provider.RollbackTransaction();
+            return 'rolledBack';
+        }
+        await provider.CommitTransaction();
+        return 'committed';
+    }
+    async rollbackQuietly(provider) {
+        try {
+            if (provider.TransactionDepth > 0) {
+                await provider.RollbackTransaction();
             }
         }
-        return settleError;
+        catch {
+            /* still release */
+        }
     }
 }
 //# sourceMappingURL=graph-provider-pool.js.map

package/dist/lib/graph-provider-pool.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-provider-pool.js","sourceRoot":"","sources":["../../src/lib/graph-provider-pool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"graph-provider-pool.js","sourceRoot":"","sources":["../../src/lib/graph-provider-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA0BH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,IAAuB;IACrE,IAAI,QAA2B,CAAC;IAChC,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,IAAI,CAAC,yBAAyB,EAAE,CAAC;IACpD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,0BAA0B,EAAE,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;IACxE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,OAAO,iBAAiB;IAS5B,YACmB,IAAuB,EACxC,OAAiC;QADhB,SAAI,GAAJ,IAAI,CAAmB;QATzB,cAAS,GAAG,IAAI,GAAG,EAA6B,CAAC;QACjD,qBAAgB,GAAG,IAAI,GAAG,EAAkB,CAAC;QAKtD,cAAS,GAAG,KAAK,CAAC;QAMxB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAC/C,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,MAAyC;QAClD,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC;QAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC5B,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC;IACH,CAAC;IAED,iFAAiF;IACjF,UAAU;QACR,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,6EAA6E;IAC7E,KAAK,CAAC,MAAM,CAAC,OAAe;QAC1B,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAE9B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,yBAAyB,EAAE,CAAC;YAC5D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACrC,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,MAAM,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAC1D,MAAM,IAAI,KAAK,CACb,8CAA8C,OAAO,KAAK,MAAM,KAAK;gBACnE,uGAAuG,CAC1G,CAAC;QACJ,CAAC;IACH,CAAC;IAEO,UAAU,CAAC,OAAe;QAChC,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,KAAK,OAAO,EAAE,CAAC;YACjE,MAAM,IAAI,KAAK,CACb,SAAS,OAAO,4CAA4C,IAAI,CAAC,UAAU,mBAAmB;gBAC5F,+EAA+E,CAClF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC;QAC1B,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,QAAkB,EAAE,UAAkB;QACrD,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACzB,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YAC3B,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE;YACpC,MAAM,IAAI,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,UAAU,CAAC;YACzD,IAAI,IAAI,KAAK,UAAU;gBAAE,OAAO,IAAI,CAAC;YACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACxC,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC,gBAAgB,KAAK,CAAC,CAAC;QACtD,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAED,kEAAkE;IAClE,KAAK,CAAC,UAAU;QACd,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACzB,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;YAC5B,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACxD,CAAC;IAEO,WAAW,CAAC,QAAkB;QACpC,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACxE,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC9B,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,aAAa,CAAC,GAAa;QACvC,IAAI,WAA8B,CAAC;QACnC,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;YACrB,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACxC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC1B,IAAI,CAAC,QAAQ;gBAAE,SAAS;YAExB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;YACxD,WAAW,KAAK,KAAK,CAAC;QACxB,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,kFAAkF;IAC1E,KAAK,CAAC,gBAAgB,CAAC,EAAU,EAAE,QAA2B;QACpE,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,CAAC,cAAc,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;YACnC,OAAO,SAAS,CAAC;QACnB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,KAAK,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YACtB,IAAI,CAAC,GAAG,CAAC,0BAA0B,EAAE,iBAAiB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACvE,MAAM,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;YACrC,IAAI,CAAC,cAAc,EAAE,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;YACxC,OAAO,KAAK,CAAC;QACf,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC;gBACH,MAAM,QAAQ,CAAC,0BAA0B,EAAE,CAAC;YAC9C,CAAC;YAAC,MAAM,CAAC;gBACP,uCAAuC;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,MAAM,CAAC,QAA2B;QAC9C,IAAI,QAAQ,CAAC,gBAAgB,KAAK,CAAC,EAAE,CAAC;YACpC,OAAO,WAAW,CAAC;QACrB,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,QAAQ,CAAC,mBAAmB,EAAE,CAAC;YACrC,OAAO,YAAY,CAAC;QACtB,CAAC;QACD,MAAM,QAAQ,CAAC,iBAAiB,EAAE,CAAC;QACnC,OAAO,WAAW,CAAC;IACrB,CAAC;IAEO,KAAK,CAAC,eAAe,CAAC,QAA2B;QACvD,IAAI,CAAC;YACH,IAAI,QAAQ,CAAC,gBAAgB,GAAG,CAAC,EAAE,CAAC;gBAClC,MAAM,QAAQ,CAAC,mBAAmB,EAAE,CAAC;YACvC,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,mBAAmB;QACrB,CAAC;IACH,CAAC;CACF"}

package/dist/lib/json-subproperty-externalization.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Externalizing a property *inside* a JSON field.
+ *
+ * `pull.externalizeFields` names entity fields, so it can move a whole column into
+ * a side file (`TemplateText` → `templates/x.md`) but cannot reach a single property
+ * inside a JSON column. That is the wrong granularity whenever a column mixes
+ * hand-authored config with a machine-generated artifact: MJ Tests keep step budgets,
+ * oracles and the recorded `ReplayScript` in one `Configuration` blob, and
+ * externalizing the whole thing would bury the readable half.
+ *
+ * A dotted config field (`Configuration.ReplayScript`) externalizes just the leaf and
+ * leaves an `@file:` reference in its place. Push already resolves nested references
+ * when it walks a metadata object, so the value round-trips with no push-side change.
+ *
+ * The file IO stays in `FieldExternalizer` — it is injected here as `externalize`, so
+ * this module is only the JSON walk: find the leaf, hand it over, splice the reference
+ * back. Pattern placeholders, path preservation and the unchanged-content skip all come
+ * from that existing code.
+ */
+/** A sub-property externalization resolved against one field. */
+export interface SubPropertyExternalization {
+    /** Property path within the field's JSON, e.g. `['ReplayScript']`. */
+    path: string[];
+    /** The `@file:` pattern to externalize to. */
+    pattern: string;
+}
+/** Writes a value to a file and returns the `@file:` reference naming it. */
+export type ExternalizeLeaf = (value: unknown, pattern: string, existingRef?: string, leafName?: string) => Promise<string>;
+/**
+ * The one `FieldExternalizer` method this module needs. `recordData` is declared as a
+ * property bag rather than `BaseEntity` because that is all it is ever used for —
+ * `RecordProcessor` hands the pulled properties straight through, and the externalizer
+ * only reads `Name` / `ID` / field placeholders off it to build the filename.
+ */
+export interface FieldExternalizerLike {
+    externalizeField(fieldName: string, fieldValue: unknown, pattern: string, recordData: Record<string, unknown>, targetDir: string, existingFileReference?: string, mergeStrategy?: string, verbose?: boolean): Promise<string>;
+}
+/**
+ * Split an `externalizeFields` entry into the entity field it targets and the property
+ * path within that field. A name with no dot yields an empty path, which is how callers
+ * tell a whole-field config (the existing behavior) from a sub-property one.
+ */
+export declare function parseExternalizePath(configField: string): {
+    field: string;
+    path: string[];
+};
+/**
+ * The sub-property externalizations rooted at `fieldName`. Whole-field entries are
+ * excluded so they continue down the original code path untouched, and the legacy
+ * string-array config form yields nothing because it can only name whole fields.
+ */
+export declare function findSubPropertyExternalizations(fieldName: string, externalizeConfig: unknown): SubPropertyExternalization[];
+/** Read the value at `path`, or `undefined` if any step is missing or not an object. */
+export declare function getAtPath(value: unknown, path: string[]): unknown;
+/**
+ * Bind a `FieldExternalizer` into the `ExternalizeLeaf` shape this module walks with.
+ *
+ * The serialization here is load-bearing. `FieldExternalizer` writes `String(value)` and
+ * only pretty-prints when the field name hints at JSON, so handing it a parsed object
+ * would write the literal text `[object Object]`. Serializing first gives a diffable file
+ * and a stable string for the unchanged-content comparison that skips redundant writes.
+ */
+export declare function fieldExternalizerAdapter(externalizer: FieldExternalizerLike, recordProperties: Record<string, unknown>, targetDir: string, mergeStrategy?: string, verbose?: boolean): ExternalizeLeaf;
+/**
+ * Externalize each configured sub-property of `fieldValue`, returning the field value
+ * with `@file:` references in their place.
+ *
+ * A path the value does not carry is skipped entirely — no file, no key — so a record
+ * that never produced the artifact stays byte-identical. `existingFieldValue` is the
+ * same field as it currently stands in the metadata file; the reference found at each
+ * path is forwarded so `FieldExternalizer` can keep writing to the path already chosen
+ * there instead of relocating the file to the pattern's default.
+ *
+ * Returns the input unchanged when nothing is configured or the value is not JSON.
+ */
+export declare function externalizeSubProperties(fieldValue: unknown, configs: SubPropertyExternalization[], externalize: ExternalizeLeaf, existingFieldValue?: unknown): Promise<unknown>;
+//# sourceMappingURL=json-subproperty-externalization.d.ts.map

package/dist/lib/json-subproperty-externalization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-subproperty-externalization.d.ts","sourceRoot":"","sources":["../../src/lib/json-subproperty-externalization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,iEAAiE;AACjE,MAAM,WAAW,0BAA0B;IACvC,sEAAsE;IACtE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,6EAA6E;AAC7E,MAAM,MAAM,eAAe,GAAG,CAC1B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,KAChB,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IAClC,gBAAgB,CACZ,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,SAAS,EAAE,MAAM,EACjB,qBAAqB,CAAC,EAAE,MAAM,EAC9B,aAAa,CAAC,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,OAAO,GAClB,OAAO,CAAC,MAAM,CAAC,CAAC;CACtB;AAMD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAG3F;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC3C,SAAS,EAAE,MAAM,EACjB,iBAAiB,EAAE,OAAO,GAC3B,0BAA0B,EAAE,CAe9B;AAED,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CASjE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACpC,YAAY,EAAE,qBAAqB,EACnC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzC,SAAS,EAAE,MAAM,EACjB,aAAa,GAAE,MAAgB,EAC/B,OAAO,CAAC,EAAE,OAAO,GAClB,eAAe,CAcjB;AA+BD;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC1C,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,0BAA0B,EAAE,EACrC,WAAW,EAAE,eAAe,EAC5B,kBAAkB,CAAC,EAAE,OAAO,GAC7B,OAAO,CAAC,OAAO,CAAC,CA4BlB"}

package/dist/lib/json-subproperty-externalization.js

@@ -0,0 +1,139 @@
+/**
+ * Externalizing a property *inside* a JSON field.
+ *
+ * `pull.externalizeFields` names entity fields, so it can move a whole column into
+ * a side file (`TemplateText` → `templates/x.md`) but cannot reach a single property
+ * inside a JSON column. That is the wrong granularity whenever a column mixes
+ * hand-authored config with a machine-generated artifact: MJ Tests keep step budgets,
+ * oracles and the recorded `ReplayScript` in one `Configuration` blob, and
+ * externalizing the whole thing would bury the readable half.
+ *
+ * A dotted config field (`Configuration.ReplayScript`) externalizes just the leaf and
+ * leaves an `@file:` reference in its place. Push already resolves nested references
+ * when it walks a metadata object, so the value round-trips with no push-side change.
+ *
+ * The file IO stays in `FieldExternalizer` — it is injected here as `externalize`, so
+ * this module is only the JSON walk: find the leaf, hand it over, splice the reference
+ * back. Pattern placeholders, path preservation and the unchanged-content skip all come
+ * from that existing code.
+ */
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Split an `externalizeFields` entry into the entity field it targets and the property
+ * path within that field. A name with no dot yields an empty path, which is how callers
+ * tell a whole-field config (the existing behavior) from a sub-property one.
+ */
+export function parseExternalizePath(configField) {
+    const [field, ...path] = configField.split('.');
+    return { field, path };
+}
+/**
+ * The sub-property externalizations rooted at `fieldName`. Whole-field entries are
+ * excluded so they continue down the original code path untouched, and the legacy
+ * string-array config form yields nothing because it can only name whole fields.
+ */
+export function findSubPropertyExternalizations(fieldName, externalizeConfig) {
+    if (!Array.isArray(externalizeConfig)) {
+        return [];
+    }
+    const found = [];
+    for (const entry of externalizeConfig) {
+        if (!isPlainObject(entry) || typeof entry.field !== 'string' || typeof entry.pattern !== 'string') {
+            continue;
+        }
+        const { field, path } = parseExternalizePath(entry.field);
+        if (path.length > 0 && field === fieldName) {
+            found.push({ path, pattern: entry.pattern });
+        }
+    }
+    return found;
+}
+/** Read the value at `path`, or `undefined` if any step is missing or not an object. */
+export function getAtPath(value, path) {
+    let cursor = value;
+    for (const key of path) {
+        if (!isPlainObject(cursor)) {
+            return undefined;
+        }
+        cursor = cursor[key];
+    }
+    return cursor;
+}
+/**
+ * Bind a `FieldExternalizer` into the `ExternalizeLeaf` shape this module walks with.
+ *
+ * The serialization here is load-bearing. `FieldExternalizer` writes `String(value)` and
+ * only pretty-prints when the field name hints at JSON, so handing it a parsed object
+ * would write the literal text `[object Object]`. Serializing first gives a diffable file
+ * and a stable string for the unchanged-content comparison that skips redundant writes.
+ */
+export function fieldExternalizerAdapter(externalizer, recordProperties, targetDir, mergeStrategy = 'merge', verbose) {
+    return async (value, pattern, existingRef, leafName) => {
+        const serialized = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+        return externalizer.externalizeField(leafName ?? '', serialized, pattern, recordProperties, targetDir, existingRef, mergeStrategy, verbose);
+    };
+}
+/** A copy of `root` with `path` set to `leaf`. Untouched branches are shared, not cloned. */
+function withLeaf(root, path, leaf) {
+    const [head, ...rest] = path;
+    if (rest.length === 0) {
+        return { ...root, [head]: leaf };
+    }
+    const child = root[head];
+    if (!isPlainObject(child)) {
+        return root;
+    }
+    return { ...root, [head]: withLeaf(child, rest, leaf) };
+}
+/** JSON columns arrive as a string from the database and as an object from a metadata file. */
+function coerceToObject(value) {
+    if (isPlainObject(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        try {
+            const parsed = JSON.parse(value);
+            return isPlainObject(parsed) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Externalize each configured sub-property of `fieldValue`, returning the field value
+ * with `@file:` references in their place.
+ *
+ * A path the value does not carry is skipped entirely — no file, no key — so a record
+ * that never produced the artifact stays byte-identical. `existingFieldValue` is the
+ * same field as it currently stands in the metadata file; the reference found at each
+ * path is forwarded so `FieldExternalizer` can keep writing to the path already chosen
+ * there instead of relocating the file to the pattern's default.
+ *
+ * Returns the input unchanged when nothing is configured or the value is not JSON.
+ */
+export async function externalizeSubProperties(fieldValue, configs, externalize, existingFieldValue) {
+    if (!configs || configs.length === 0) {
+        return fieldValue;
+    }
+    const parsed = coerceToObject(fieldValue);
+    if (!parsed) {
+        return fieldValue;
+    }
+    const existing = coerceToObject(existingFieldValue);
+    let result = parsed;
+    for (const { path, pattern } of configs) {
+        const leaf = getAtPath(result, path);
+        if (leaf === undefined || leaf === null) {
+            continue;
+        }
+        const existingRef = existing ? getAtPath(existing, path) : undefined;
+        const reference = await externalize(leaf, pattern, typeof existingRef === 'string' ? existingRef : undefined, path[path.length - 1]);
+        result = withLeaf(result, path, reference);
+    }
+    return result;
+}
+//# sourceMappingURL=json-subproperty-externalization.js.map

package/dist/lib/json-subproperty-externalization.js.map

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

package/dist/lib/push-outcome.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview What a failed `mj sync push` left behind, and how to say so.
+ * @module push-outcome
+ */
+import type { PushWriteMode } from './push-write-mode.js';
+/** A create or update committed outside the push transaction (an isolated directory only). */
+export interface CommittedWrite {
+    /** Absolute path of the metadata file the record came from. */
+    filePath: string;
+    entityName: string;
+    /** Position of the record inside the file, e.g. `MJ: Actions[3]/MJ: Action Params[0]`. */
+    recordPath: string;
+    status: 'created' | 'updated';
+}
+/** What a push had done when it failed. Same shape as the successful result's counts. */
+export interface PushPartialTotals {
+    created: number;
+    updated: number;
+    unchanged: number;
+    deleted: number;
+    skipped: number;
+    deferred: number;
+    errors: number;
+}
+export interface PushAbortedDetails {
+    /** The write modes the directories processed so far were using. */
+    modes: PushWriteMode[];
+    /** Whether the push transaction was rolled back (or was never opened, as in a dry run). */
+    rolledBack: boolean;
+    /** Rows that are still in the database even though the push failed. */
+    committedWrites: CommittedWrite[];
+    /** Counts as far as the push got. Reported so a failed run is still machine-readable. */
+    totals: PushPartialTotals;
+    /** The SQL log for this run, when one was being written. Most wanted on a failure. */
+    sqlLogPath?: string;
+    cause: unknown;
+}
+/**
+ * Thrown by `PushService.push()` whenever a push fails after it started writing.
+ * The message is the original failure's message, so existing callers keep working;
+ * the extra fields let a caller say exactly what is and is not in the database.
+ */
+export declare class PushAbortedError extends Error {
+    /** The write modes in play when the push failed, e.g. `['shared']` or `['shared','isolated']`. */
+    readonly modes: PushWriteMode[];
+    readonly rolledBack: boolean;
+    readonly committedWrites: CommittedWrite[];
+    readonly totals: PushPartialTotals;
+    readonly sqlLogPath?: string;
+    constructor(details: PushAbortedDetails);
+    /** True only when nothing from this push is left in the database. */
+    get NothingCommitted(): boolean;
+}
+/**
+ * The lines that tell the user how a failed push ended. The first line is the summary;
+ * any further lines list the committed records, grouped by file.
+ */
+export declare function describeRollbackOutcome(rolledBack: boolean, committedWrites: CommittedWrite[], cwd: string): string[];
+/** One line per file, then one indented line per committed record. */
+export declare function describeCommittedWrites(committedWrites: CommittedWrite[], cwd: string): string[];
+/**
+ * Message for a failed COMMIT. On PostgreSQL, deferred foreign keys are checked at commit, so
+ * the failure is about the transaction as a whole and cannot be tied to one record.
+ */
+export declare function describeCommitFailure(cause: unknown, platform: string | undefined): string;
+//# sourceMappingURL=push-outcome.d.ts.map

package/dist/lib/push-outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-outcome.d.ts","sourceRoot":"","sources":["../../src/lib/push-outcome.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;CAC/B;AAED,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,2FAA2F;IAC3F,UAAU,EAAE,OAAO,CAAC;IACpB,uEAAuE;IACvE,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,yFAAyF;IACzF,MAAM,EAAE,iBAAiB,CAAC;IAC1B,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,kGAAkG;IAClG,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,cAAc,EAAE,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,kBAAkB;IAUvC,qEAAqE;IACrE,IAAI,gBAAgB,IAAI,OAAO,CAE9B;CACF;AAMD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBrH;AAED,sEAAsE;AACtE,wBAAgB,uBAAuB,CAAC,eAAe,EAAE,cAAc,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAehG;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAS1F"}