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

package/dist/services/PushService.js

@@ -15,18 +15,40 @@ import { SQLLogger } from '../lib/sql-logger.js';
 import { TransactionManager } from '../lib/transaction-manager.js';
 import { JsonWriteHelper } from '../lib/json-write-helper.js';
 import { RecordDependencyAnalyzer, groupRecordsByGraphId } from '../lib/record-dependency-analyzer.js';
-import { GraphProviderPool } from '../lib/graph-provider-pool.js';
+import { GraphProviderPool, probeIndependentInstances } from '../lib/graph-provider-pool.js';
+import { resolveDirectoryMode, graphBatchSizeFor, isolatedModeWarning, unusedBatchSizeWarning, } from '../lib/push-write-mode.js';
+import { PushAbortedError, describeCommitFailure, describeRollbackOutcome } from '../lib/push-outcome.js';
 import { JsonPreprocessor } from '../lib/json-preprocessor.js';
 import { findEntityDirectories } from '../lib/provider-utils.js';
 import { DeletionAuditor } from '../lib/deletion-auditor.js';
 import { describeMissingEntitySubclass } from '../lib/entity-subclass-guard.js';
 import { DeletionReportGenerator } from '../lib/deletion-report-generator.js';
 import { resolveCollectionRelationship } from '../lib/collection-resolver.js';
-// Parallelism is across JSON-root graphs (independent Actions), not flattened rows.
-// Nested relatedEntities share the root's provider so parent+child stay on one TX.
-// Default 10 — never 1. 1 was a wrong workaround for mixed-provider hangs;
-// callers can pass --parallel-batch-size 1 for debugging.
-const PARALLEL_BATCH_SIZE = 10;
+function emptyPushTotals() {
+    return { created: 0, updated: 0, unchanged: 0, deleted: 0, skipped: 0, deferred: 0, errors: 0 };
+}
+function addPushTotals(totals, result) {
+    totals.created += result.created;
+    totals.updated += result.updated;
+    totals.unchanged += result.unchanged;
+    totals.deleted += result.deleted;
+    totals.skipped += result.skipped;
+    totals.deferred += result.deferred;
+    totals.errors += result.errors;
+}
+/** The status a committed write is reported with, or undefined when the result wrote nothing. */
+function committedStatusOf(result) {
+    if (result.isDuplicate || result.isDeletedRecord) {
+        return undefined;
+    }
+    if (result.status === 'updated') {
+        return 'updated';
+    }
+    if (result.status === 'created' || result.status === 'deferred') {
+        return 'created';
+    }
+    return undefined;
+}
 export class PushService {
     constructor(syncEngine, contextUser, stateManager) {
         this.warnings = [];
@@ -35,6 +57,20 @@ export class PushService {
         this.deferredFileWrites = new Map();
         this.deferredRecords = [];
         this.confirmedCollections = new Set();
+        /** Write mode per entity directory, resolved once at the start of the push. */
+        this.directoryModes = new Map();
+        /** The directory being processed right now, and how it writes. */
+        this.writeMode = 'shared';
+        this.graphBatchSize = 1;
+        /** Counts so far, so a failed push can still report what it did. */
+        this.runningTotals = emptyPushTotals();
+        /** Non-atomic mode: creates and updates that were committed outside the push transaction. */
+        this.committedWrites = [];
+        /** Incremental state, applied only after the push commits. Keyed by path relative to the sync root. */
+        this.pendingChecksums = new Map();
+        this.pushedEntityDirs = [];
+        /** Errors whose record was already sent to onRecordError, so a caller does not report it twice. */
+        this.reportedRecordErrors = new WeakSet();
         this.syncEngine = syncEngine;
         this.contextUser = contextUser;
         this.stateManager = stateManager;
@@ -133,9 +169,15 @@ export class PushService {
         if (options.include && options.exclude) {
             throw new Error('Cannot specify both --include and --exclude options. Please use one or the other.');
         }
-        // Reset deferred tracking for this push operation
+        // Reset per-push tracking
         this.deferredFileWrites.clear();
         this.deferredRecords = [];
+        this.committedWrites = [];
+        this.pendingChecksums.clear();
+        this.pushedEntityDirs = [];
+        this.directoryModes.clear();
+        this.runningTotals = emptyPushTotals();
+        this.sqlLogFilePath = undefined;
         const fileBackupManager = new FileBackupManager();
         // Load sync config for SQL logging settings and autoCreateMissingRecords flag
         // If dir option is specified, load from that directory, otherwise use original CWD
@@ -156,54 +198,15 @@ export class PushService {
             callbacks?.onLog?.(`SQL logging config: ${JSON.stringify(this.syncConfig?.sqlLogging)}`);
         }
         const sqlLogger = new SQLLogger(this.syncConfig);
-        const transactionManager = new TransactionManager(sqlLogger);
+        // The push transaction lives on the same provider every atomic save runs on.
+        const transactionManager = new TransactionManager(sqlLogger, this.hostProvider());
         if (options.verbose) {
             callbacks?.onLog?.(`SQLLogger enabled status: ${sqlLogger.enabled}`);
         }
         // Setup SQL logging session with the provider if enabled
         let sqlLoggingSession = null;
         try {
-            // Initialize SQL logger if enabled and not dry-run
-            if (sqlLogger.enabled && !options.dryRun) {
-                const provider = Metadata.Provider; // global-provider-ok: metadata sync operates on the configured provider only
-                if (options.verbose) {
-                    callbacks?.onLog?.(`SQL logging enabled: ${sqlLogger.enabled}`);
-                    callbacks?.onLog?.(`Provider type: ${provider?.constructor?.name || 'Unknown'}`);
-                    callbacks?.onLog?.(`Has CreateSqlLogger: ${typeof provider?.CreateSqlLogger === 'function'}`);
-                }
-                if (provider && typeof provider.CreateSqlLogger === 'function') {
-                    // Generate filename with timestamp
-                    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-                    const filename = this.syncConfig?.sqlLogging?.formatAsMigration
-                        ? `MetadataSync_Push_${timestamp}.sql`
-                        : `push_${timestamp}.sql`;
-                    // Use .sql-log-push directory in the config directory (where sync was initiated)
-                    const outputDir = path.join(configDir, this.syncConfig?.sqlLogging?.outputDirectory || './sql-log-push');
-                    const filepath = path.join(outputDir, filename);
-                    // Ensure the directory exists
-                    await fs.ensureDir(path.dirname(filepath));
-                    // Create the SQL logging session
-                    sqlLoggingSession = await provider.CreateSqlLogger(filepath, {
-                        formatAsMigration: this.syncConfig?.sqlLogging?.formatAsMigration || false,
-                        description: 'MetadataSync push operation',
-                        statementTypes: "mutations",
-                        prettyPrint: true,
-                        // batchSeparator is intentionally omitted — CreateSqlLogger injects the platform-appropriate
-                        // separator automatically (GO for SQL Server, nothing for PostgreSQL) via PlatformBatchSeparator.
-                        filterPatterns: this.syncConfig?.sqlLogging?.filterPatterns,
-                        filterType: this.syncConfig?.sqlLogging?.filterType,
-                        verboseOutput: this.syncConfig?.sqlLogging?.verboseOutput || false,
-                    });
-                    if (options.verbose) {
-                        callbacks?.onLog?.(`📝 SQL logging enabled: ${filepath}`);
-                    }
-                }
-                else {
-                    if (options.verbose) {
-                        callbacks?.onWarn?.('SQL logging requested but provider does not support it');
-                    }
-                }
-            }
+            sqlLoggingSession = await this.startSqlLogging(sqlLogger, options, configDir, callbacks);
             // Find entity directories to process
             // Note: If options.dir is specified, configDir already points to that directory
             // So we don't need to pass it as specificDir
@@ -211,32 +214,8 @@ export class PushService {
             if (entityDirs.length === 0) {
                 throw new Error('No entity directories found');
             }
-            // Preload entities and cache files.
-            // We pass the SyncEngine's provider explicitly rather than reaching for
-            // Metadata.Provider — `mj sync` is single-process so they resolve to the
-            // same instance today, but routing through SyncEngine keeps the wiring
-            // self-consistent and makes future provider plumbing trivial.
-            // Preload is internal plumbing — emit its progress only in verbose mode so a
-            // normal run jumps straight from validation to per-directory results.
-            if (options.verbose) {
-                callbacks?.onLog?.('⚡ Preloading metadata and caching files...');
-            }
-            this.syncMetadataEngine.setEntityDirs(entityDirs);
-            await this.syncMetadataEngine.Config(true, this.contextUser, this.syncEngine.getProvider());
-            for (const warning of this.syncMetadataEngine.drainWarnings()) {
-                callbacks?.onWarn?.(`   ⚠️  ${warning}`);
-            }
-            if (options.verbose) {
-                const delegations = this.syncMetadataEngine.getDelegationSummary();
-                if (delegations.length > 0) {
-                    const donorCount = new Set(delegations.map(d => d.engineClassName)).size;
-                    callbacks?.onLog?.(`   ↪ Reused in-memory caches for ${delegations.length} ${delegations.length === 1 ? 'entity' : 'entities'} already loaded by ${donorCount} ${donorCount === 1 ? 'engine' : 'engines'}`);
-                    for (const d of delegations.sort((a, b) => a.entityName.localeCompare(b.entityName))) {
-                        callbacks?.onLog?.(`      • ${d.entityName} ← ${d.engineClassName}`);
-                    }
-                }
-                callbacks?.onLog?.('✓ Preload completed successfully\n');
-            }
+            await this.applyWritePlan(entityDirs, options, callbacks);
+            await this.preloadMetadata(entityDirs, options, callbacks);
             if (options.verbose) {
                 callbacks?.onLog?.(`Found ${entityDirs.length} entity ${entityDirs.length === 1 ? 'directory' : 'directories'} to process`);
             }
@@ -247,14 +226,6 @@ export class PushService {
                     callbacks?.onLog?.('📁 File backup manager initialized');
                 }
             }
-            // Process each entity directory
-            let totalCreated = 0;
-            let totalUpdated = 0;
-            let totalUnchanged = 0;
-            let totalDeleted = 0;
-            let totalSkipped = 0;
-            let totalDeferred = 0;
-            let totalErrors = 0;
             // PHASE 0: Audit all deletions across all entities (if any exist)
             let deletionAudit = null;
             try {
@@ -268,24 +239,7 @@ export class PushService {
             if (!options.dryRun && deletionAudit) {
                 const shouldProceed = await this.promptForConfirmation(deletionAudit, callbacks);
                 if (!shouldProceed) {
-                    callbacks?.onLog?.('\n❌ Push operation cancelled by user.\n');
-                    // Clean up SQL logging session and file if it was created
-                    if (sqlLoggingSession) {
-                        const sqlLogPath = sqlLoggingSession.filePath;
-                        try {
-                            await sqlLoggingSession.dispose();
-                            // Delete the empty SQL log file since no operations occurred
-                            if (await fs.pathExists(sqlLogPath)) {
-                                await fs.remove(sqlLogPath);
-                                if (options.verbose) {
-                                    callbacks?.onLog?.(`🗑️  Removed empty SQL log file: ${sqlLogPath}`);
-                                }
-                            }
-                        }
-                        catch (cleanupError) {
-                            callbacks?.onWarn?.(`Failed to clean up SQL logging session: ${cleanupError}`);
-                        }
-                    }
+                    await this.cancelPush(sqlLoggingSession, options, callbacks);
                     return {
                         created: 0,
                         updated: 0,
@@ -299,128 +253,14 @@ export class PushService {
                     };
                 }
             }
-            // Host TX wraps Phase 2 deletions and Phase 2.5 deferred records.
-            // Phase 1 graph writes go to independent instances (or, if those are
-            // unavailable, ALL graphs share this host TX — never a mix).
+            // One host transaction wraps the whole push. In atomic mode (the default) Phase 1 saves run
+            // on the host too, one graph at a time. A directory using isolated transactions commits on
+            // independent instances as it goes (see lib/push-write-mode.ts).
             if (!options.dryRun) {
                 await transactionManager.beginTransaction();
             }
-            try {
-                // PHASE 1: Process creates/updates for all entities
-                if (options.verbose) {
-                    callbacks?.onLog?.('📝 Processing creates and updates...\n');
-                }
-                for (const [dirIdx, entityDir] of entityDirs.entries()) {
-                    // "X of N" position prefix — only when there's more than one directory, so a
-                    // single-directory push stays uncluttered.
-                    const progressPrefix = entityDirs.length > 1 ? `[${dirIdx + 1}/${entityDirs.length}] ` : '';
-                    const entityConfig = await loadEntityConfig(entityDir);
-                    if (!entityConfig) {
-                        const warning = `Skipping ${entityDir} - no valid entity configuration`;
-                        this.warnings.push(warning);
-                        callbacks?.onWarn?.(warning);
-                        totalSkipped++; // Count skipped directories
-                        continue;
-                    }
-                    // Show folder with spinner at start. The folder header is redundant in a
-                    // normal run (the per-directory result line below names the directory), so
-                    // it's verbose-only; the live spinner still shows "[X/N] Processing <dir>…".
-                    const dirName = path.relative(process.cwd(), entityDir) || '.';
-                    if (options.verbose) {
-                        callbacks?.onLog?.(`\n📁 ${dirName}:`);
-                    }
-                    // Use onProgress for animated spinner if available
-                    if (callbacks?.onProgress) {
-                        callbacks.onProgress(`${progressPrefix}Processing ${dirName}...`);
-                    }
-                    else {
-                        callbacks?.onLog?.(`   ⏳ Processing...`);
-                    }
-                    if (options.verbose && callbacks?.onLog) {
-                        callbacks.onLog(`Processing ${entityConfig.entity} in ${entityDir}`);
-                    }
-                    const result = await this.processEntityDirectory(entityDir, entityConfig, options, fileBackupManager, callbacks, configDir);
-                    // Per-directory result: one compact line (always), naming the directory and
-                    // its changes — or "no changes" for a clean dir. The detailed per-status
-                    // breakdown is verbose-only since the final summary box already aggregates it.
-                    const dirTotal = result.created + result.updated + result.unchanged + result.deleted + result.skipped;
-                    const { text: dirSummary, changed: dirChanged } = this.formatDirectorySummary(progressPrefix, dirName, result, dirTotal);
-                    if (callbacks?.onProgress && callbacks?.onSuccess) {
-                        callbacks.onSuccess(dirSummary, dirChanged);
-                    }
-                    else {
-                        callbacks?.onLog?.(`   ${dirSummary}`);
-                    }
-                    if (options.verbose && (dirTotal > 0 || result.errors > 0)) {
-                        callbacks?.onLog?.(`   Total processed: ${dirTotal} records`);
-                        if (result.created > 0) {
-                            callbacks?.onLog?.(`   ✓ Created: ${result.created}`);
-                        }
-                        if (result.updated > 0) {
-                            callbacks?.onLog?.(`   ✓ Updated: ${result.updated}`);
-                        }
-                        if (result.deleted > 0) {
-                            callbacks?.onLog?.(`   ✓ Deleted: ${result.deleted}`);
-                        }
-                        if (result.deferred > 0) {
-                            callbacks?.onLog?.(`   ⏳ Deferred: ${result.deferred}`);
-                        }
-                        if (result.unchanged > 0) {
-                            callbacks?.onLog?.(`   - Unchanged: ${result.unchanged}`);
-                        }
-                        if (result.skipped > 0) {
-                            callbacks?.onLog?.(`   - Skipped: ${result.skipped}`);
-                        }
-                        if (result.errors > 0) {
-                            callbacks?.onLog?.(`   ✗ Errors: ${result.errors}`);
-                        }
-                    }
-                    totalCreated += result.created;
-                    totalUpdated += result.updated;
-                    totalUnchanged += result.unchanged;
-                    totalDeleted += result.deleted;
-                    totalSkipped += result.skipped;
-                    totalDeferred += result.deferred;
-                    totalErrors += result.errors;
-                }
-                // PHASE 2: Process deletions in reverse dependency order (if any exist)
-                if (deletionAudit && totalErrors === 0) {
-                    const deletionResult = await this.processDeletionsFromAudit(deletionAudit, options, callbacks);
-                    totalDeleted += deletionResult.deleted;
-                    totalErrors += deletionResult.errors;
-                }
-                // PHASE 2.5: Process deferred records (for circular dependencies)
-                if (this.deferredRecords.length > 0 && totalErrors === 0) {
-                    const deferredResult = await this.processDeferredRecords(options, callbacks);
-                    totalCreated += deferredResult.created;
-                    totalUpdated += deferredResult.updated;
-                    totalErrors += deferredResult.errors;
-                }
-                // Commit transaction if successful
-                if (!options.dryRun && totalErrors === 0) {
-                    await transactionManager.commitTransaction();
-                }
-                // PHASE 3: Write deferred files with updated deletion timestamps
-                if (!options.dryRun && totalErrors === 0 && this.deferredFileWrites.size > 0) {
-                    await this.writeDeferredFiles(options, callbacks);
-                }
-            }
-            catch (error) {
-                // Rollback transaction on error.
-                if (!options.dryRun) {
-                    callbacks?.onLog?.('\n⚠️  Rolling back database transaction due to error...');
-                    const rolledBack = await transactionManager.rollbackTransaction();
-                    if (rolledBack) {
-                        callbacks?.onLog?.('✓ Database transaction rolled back successfully\n');
-                    }
-                    else {
-                        callbacks?.onLog?.('❌ Database transaction rollback failed\n');
-                    }
-                }
-                throw error;
-            }
-            // Commit file backups if successful and not in dry-run mode
-            if (!options.dryRun && totalErrors === 0) {
+            const totals = await this.runPushInTransaction({ entityDirs, deletionAudit, options, fileBackupManager, callbacks, configDir }, transactionManager);
+            if (!options.dryRun) {
                 await fileBackupManager.cleanup();
                 if (options.verbose) {
                     callbacks?.onLog?.('✅ File backups committed');
@@ -443,13 +283,7 @@ export class PushService {
                 }
             }
             return {
-                created: totalCreated,
-                updated: totalUpdated,
-                unchanged: totalUnchanged,
-                deleted: totalDeleted,
-                skipped: totalSkipped,
-                deferred: totalDeferred,
-                errors: totalErrors,
+                ...totals,
                 warnings: this.warnings,
                 sqlLogPath,
                 changeLog: this.changeDetails
@@ -478,6 +312,381 @@ export class PushService {
             throw error;
         }
     }
+    /** Open the SQL logging session when the config asks for one and this is not a dry run. */
+    async startSqlLogging(sqlLogger, options, configDir, callbacks) {
+        let sqlLoggingSession = null;
+        if (sqlLogger.enabled && !options.dryRun) {
+            const provider = Metadata.Provider; // global-provider-ok: metadata sync operates on the configured provider only
+            if (options.verbose) {
+                callbacks?.onLog?.(`SQL logging enabled: ${sqlLogger.enabled}`);
+                callbacks?.onLog?.(`Provider type: ${provider?.constructor?.name || 'Unknown'}`);
+                callbacks?.onLog?.(`Has CreateSqlLogger: ${typeof provider?.CreateSqlLogger === 'function'}`);
+            }
+            if (provider && typeof provider.CreateSqlLogger === 'function') {
+                // Generate filename with timestamp
+                const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+                const filename = this.syncConfig?.sqlLogging?.formatAsMigration
+                    ? `MetadataSync_Push_${timestamp}.sql`
+                    : `push_${timestamp}.sql`;
+                // Use .sql-log-push directory in the config directory (where sync was initiated)
+                const outputDir = path.join(configDir, this.syncConfig?.sqlLogging?.outputDirectory || './sql-log-push');
+                const filepath = path.join(outputDir, filename);
+                // Ensure the directory exists
+                await fs.ensureDir(path.dirname(filepath));
+                // Create the SQL logging session
+                this.sqlLogFilePath = filepath;
+                sqlLoggingSession = await provider.CreateSqlLogger(filepath, {
+                    formatAsMigration: this.syncConfig?.sqlLogging?.formatAsMigration || false,
+                    description: 'MetadataSync push operation',
+                    statementTypes: "mutations",
+                    prettyPrint: true,
+                    // batchSeparator is intentionally omitted — CreateSqlLogger injects the platform-appropriate
+                    // separator automatically (GO for SQL Server, nothing for PostgreSQL) via PlatformBatchSeparator.
+                    filterPatterns: this.syncConfig?.sqlLogging?.filterPatterns,
+                    filterType: this.syncConfig?.sqlLogging?.filterType,
+                    verboseOutput: this.syncConfig?.sqlLogging?.verboseOutput || false,
+                });
+                if (options.verbose) {
+                    callbacks?.onLog?.(`📝 SQL logging enabled: ${filepath}`);
+                }
+            }
+            else {
+                if (options.verbose) {
+                    callbacks?.onWarn?.('SQL logging requested but provider does not support it');
+                }
+            }
+        }
+        return sqlLoggingSession;
+    }
+    /**
+     * Preload entity metadata and cache the files on disk.
+     *
+     * The SyncEngine's provider is passed explicitly rather than reaching for Metadata.Provider —
+     * `mj sync` is single-process so they resolve to the same instance today, but routing through
+     * SyncEngine keeps the wiring self-consistent.
+     */
+    async preloadMetadata(entityDirs, options, callbacks) {
+        // We pass the SyncEngine's provider explicitly rather than reaching for
+        // Metadata.Provider — `mj sync` is single-process so they resolve to the
+        // same instance today, but routing through SyncEngine keeps the wiring
+        // self-consistent and makes future provider plumbing trivial.
+        // Preload is internal plumbing — emit its progress only in verbose mode so a
+        // normal run jumps straight from validation to per-directory results.
+        if (options.verbose) {
+            callbacks?.onLog?.('⚡ Preloading metadata and caching files...');
+        }
+        this.syncMetadataEngine.setEntityDirs(entityDirs);
+        await this.syncMetadataEngine.Config(true, this.contextUser, this.syncEngine.getProvider());
+        for (const warning of this.syncMetadataEngine.drainWarnings()) {
+            callbacks?.onWarn?.(`   ⚠️  ${warning}`);
+        }
+        if (options.verbose) {
+            const delegations = this.syncMetadataEngine.getDelegationSummary();
+            if (delegations.length > 0) {
+                const donorCount = new Set(delegations.map(d => d.engineClassName)).size;
+                callbacks?.onLog?.(`   ↪ Reused in-memory caches for ${delegations.length} ${delegations.length === 1 ? 'entity' : 'entities'} already loaded by ${donorCount} ${donorCount === 1 ? 'engine' : 'engines'}`);
+                for (const d of delegations.sort((a, b) => a.entityName.localeCompare(b.entityName))) {
+                    callbacks?.onLog?.(`      • ${d.entityName} ← ${d.engineClassName}`);
+                }
+            }
+            callbacks?.onLog?.('✓ Preload completed successfully\n');
+        }
+    }
+    /** The user declined the deletion prompt: drop an empty SQL log and say nothing happened. */
+    async cancelPush(sqlLoggingSession, options, callbacks) {
+        callbacks?.onLog?.('\n❌ Push operation cancelled by user.\n');
+        // Clean up SQL logging session and file if it was created
+        if (sqlLoggingSession) {
+            const sqlLogPath = sqlLoggingSession.filePath;
+            try {
+                await sqlLoggingSession.dispose();
+                // Delete the empty SQL log file since no operations occurred
+                if (await fs.pathExists(sqlLogPath)) {
+                    await fs.remove(sqlLogPath);
+                    if (options.verbose) {
+                        callbacks?.onLog?.(`🗑️  Removed empty SQL log file: ${sqlLogPath}`);
+                    }
+                }
+            }
+            catch (cleanupError) {
+                callbacks?.onWarn?.(`Failed to clean up SQL logging session: ${cleanupError}`);
+            }
+        }
+    }
+    /**
+     * Decide, once and up front, how each entity directory writes: shared by default, isolated where
+     * the entity (or the root, or the CLI flag) asks for it. Deciding it here means a push can never
+     * discover mid-file that it must change topology, which is the mixed-provider deadlock.
+     */
+    async applyWritePlan(entityDirs, options, callbacks) {
+        const isolated = [];
+        for (const entityDir of entityDirs) {
+            const entityConfig = await loadEntityConfig(entityDir);
+            const resolved = resolveDirectoryMode({
+                isolatedFlag: options.isolatedTransactions,
+                entityIsolated: entityConfig?.push?.isolatedTransactions,
+                rootIsolated: this.syncConfig?.push?.isolatedTransactions,
+            });
+            this.directoryModes.set(entityDir, resolved.mode);
+            if (resolved.mode === 'isolated') {
+                isolated.push(path.relative(process.cwd(), entityDir) || entityDir);
+            }
+            if (options.verbose) {
+                callbacks?.onLog?.(`   ${path.relative(process.cwd(), entityDir) || entityDir}: ${resolved.mode} (from ${resolved.source})`);
+            }
+        }
+        if (isolated.length > 0) {
+            await this.confirmIsolatedTransactions(isolated, options, callbacks);
+        }
+        else if (options.parallelBatchSize !== undefined && options.parallelBatchSize !== 1) {
+            this.addWarning(unusedBatchSizeWarning(options.parallelBatchSize), callbacks);
+        }
+    }
+    /**
+     * Isolation needs independent provider instances. Without them every directory runs shared,
+     * because the alternative — some graphs on the host, some on their own connection — is the
+     * deadlock the graph pool exists to prevent.
+     */
+    async confirmIsolatedTransactions(isolated, options, callbacks) {
+        const reason = await probeIndependentInstances(this.hostProvider());
+        if (reason) {
+            this.addWarning(`Independent provider instances are not available (${reason}), so every directory runs in the shared ` +
+                `push transaction: one transaction, one graph at a time.`, callbacks);
+            for (const dir of this.directoryModes.keys()) {
+                this.directoryModes.set(dir, 'shared');
+            }
+            return;
+        }
+        if (!options.dryRun) {
+            this.addWarning(isolatedModeWarning(isolated, graphBatchSizeFor('isolated', options.parallelBatchSize)), callbacks);
+        }
+    }
+    /** Adopt one directory's mode for the work about to run in it. */
+    useDirectoryMode(entityDir, options) {
+        this.writeMode = this.directoryModes.get(entityDir) ?? 'shared';
+        this.graphBatchSize = graphBatchSizeFor(this.writeMode, options.parallelBatchSize);
+    }
+    addWarning(message, callbacks) {
+        this.warnings.push(message);
+        callbacks?.onWarn?.(`⚠️  ${message}`);
+    }
+    /** The process-wide provider that owns the push transaction. */
+    hostProvider() {
+        return Metadata.Provider; // global-provider-ok: mj sync is single-process; this provider owns the push transaction
+    }
+    /**
+     * Run every phase inside the push transaction, commit it, then do the post-commit work.
+     * Never returns or throws with the transaction still open.
+     */
+    async runPushInTransaction(run, transactionManager) {
+        let committed = false;
+        try {
+            const totals = await this.runPushPhases(run);
+            if (!run.options.dryRun) {
+                await this.commitPushTransaction(transactionManager);
+                committed = true;
+                // PHASE 3: files that contained deletions, then the incremental state
+                await this.writeDeferredFiles(run.options, run.callbacks);
+                await this.persistIncrementalState(run.configDir);
+            }
+            return totals;
+        }
+        catch (error) {
+            if (committed) {
+                throw await this.failAfterCommit(error, run);
+            }
+            throw await this.abortPush(error, transactionManager, run);
+        }
+        finally {
+            await this.ensureTransactionClosed(transactionManager, run.callbacks);
+        }
+    }
+    /** Phases 1, 2 and 2.5. Any failure throws; counted errors only survive a dry run. */
+    async runPushPhases(run) {
+        const { options, callbacks } = run;
+        if (options.verbose) {
+            callbacks?.onLog?.('📝 Processing creates and updates...\n');
+        }
+        // PHASE 1: creates and updates
+        const totals = await this.processAllEntityDirectories(run);
+        // PHASE 2: deletions in reverse dependency order
+        if (run.deletionAudit && totals.errors === 0) {
+            const deletionResult = await this.processDeletionsFromAudit(run.deletionAudit, options, callbacks);
+            totals.deleted += deletionResult.deleted;
+            totals.errors += deletionResult.errors;
+        }
+        // PHASE 2.5: deferred records (circular dependencies)
+        if (this.deferredRecords.length > 0 && totals.errors === 0) {
+            const deferredResult = await this.processDeferredRecords(options, callbacks);
+            totals.created += deferredResult.created;
+            totals.updated += deferredResult.updated;
+            totals.errors += deferredResult.errors;
+        }
+        if (!options.dryRun && totals.errors > 0) {
+            throw new Error(`${totals.errors} record error${totals.errors === 1 ? '' : 's'} occurred; the push was not committed.`);
+        }
+        return totals;
+    }
+    async commitPushTransaction(transactionManager) {
+        try {
+            await transactionManager.commitTransaction();
+        }
+        catch (error) {
+            throw new Error(describeCommitFailure(error, this.hostProvider()?.PlatformKey), { cause: error });
+        }
+    }
+    /** Roll back, say truthfully what is left in the database, and wrap the failure. */
+    async abortPush(error, transactionManager, run) {
+        const { options, callbacks } = run;
+        let rolledBack = true;
+        if (!options.dryRun) {
+            callbacks?.onWarn?.('\n⚠️  Rolling back database transaction due to error...');
+            rolledBack = await transactionManager.rollbackTransaction();
+            await this.writeFilesWithCommittedRecords(run);
+            for (const line of describeRollbackOutcome(rolledBack, this.committedWrites, configManager.getOriginalCwd())) {
+                callbacks?.onWarn?.(line);
+            }
+        }
+        return new PushAbortedError({
+            modes: [...new Set(this.directoryModes.values())],
+            rolledBack,
+            committedWrites: [...this.committedWrites],
+            totals: { ...this.runningTotals },
+            sqlLogPath: this.sqlLogFilePath,
+            cause: error,
+        });
+    }
+    /**
+     * A file whose write was deferred to Phase 3 — it contains deletions — never reaches that phase
+     * when the push fails. In an isolated directory its creates are committed all the same, so write
+     * it now and keep it: otherwise the primary keys those rows were given exist only in the
+     * database, and the next push creates them a second time.
+     */
+    async writeFilesWithCommittedRecords(run) {
+        const committedFiles = new Set(this.committedWrites.map((w) => w.filePath));
+        for (const deferred of this.deferredFileWrites.values()) {
+            if (!committedFiles.has(deferred.filePath)) {
+                continue;
+            }
+            try {
+                const payload = deferred.isArray ? deferred.records : deferred.records[0];
+                await JsonWriteHelper.writeOrderedRecordData(deferred.filePath, payload);
+                this.syncMetadataEngine.invalidateCachedFile(deferred.filePath);
+                run.fileBackupManager.releaseBackup(deferred.filePath);
+                run.callbacks?.onWarn?.(`   kept ${path.relative(configManager.getOriginalCwd(), deferred.filePath) || deferred.filePath}: ` +
+                    `it holds records that are committed`);
+            }
+            catch (writeError) {
+                run.callbacks?.onWarn?.(`Failed to write ${deferred.filePath} after a partial push: ${writeError instanceof Error ? writeError.message : String(writeError)}`);
+            }
+        }
+    }
+    /**
+     * The database already committed, so the metadata files must keep what they were written with.
+     * Drop the file backups so the caller's error path does not restore stale files.
+     */
+    async failAfterCommit(error, run) {
+        await run.fileBackupManager.cleanup();
+        const message = error instanceof Error ? error.message : String(error);
+        run.callbacks?.onWarn?.(`⚠️  The database changes were committed, but a step after the commit failed: ${message}. ` +
+            `Some metadata files or the incremental state may not match the database; run the push again to bring them in line.`);
+        return error;
+    }
+    async ensureTransactionClosed(transactionManager, callbacks) {
+        if (!transactionManager.isInTransaction) {
+            return;
+        }
+        const rolledBack = await transactionManager.rollbackTransaction();
+        callbacks?.onWarn?.(rolledBack
+            ? '⚠️  The push transaction was still open when the push ended, so it was rolled back.'
+            : '❌ The push transaction was still open when the push ended, and rolling it back failed.');
+    }
+    /** Apply incremental checksums and push timestamps. Called only after the push commits. */
+    async persistIncrementalState(syncRootDir) {
+        if (!this.stateManager) {
+            return;
+        }
+        for (const [relativePath, checksum] of this.pendingChecksums) {
+            this.stateManager.setFileChecksum(relativePath, checksum);
+        }
+        const pushedAt = new Date().toISOString();
+        for (const relativeEntityDir of this.pushedEntityDirs) {
+            this.stateManager.setLastPushTimestamp(relativeEntityDir, pushedAt);
+        }
+        await this.stateManager.pruneStaleChecksums(syncRootDir);
+        await this.stateManager.save();
+    }
+    /** PHASE 1 over every entity directory, in order. */
+    async processAllEntityDirectories(run) {
+        const { entityDirs, options, callbacks } = run;
+        const totals = emptyPushTotals();
+        for (const [dirIdx, entityDir] of entityDirs.entries()) {
+            // "X of N" position prefix — only when there's more than one directory.
+            const progressPrefix = entityDirs.length > 1 ? `[${dirIdx + 1}/${entityDirs.length}] ` : '';
+            const entityConfig = await loadEntityConfig(entityDir);
+            if (!entityConfig) {
+                const warning = `Skipping ${entityDir} - no valid entity configuration`;
+                this.warnings.push(warning);
+                callbacks?.onWarn?.(warning);
+                totals.skipped++;
+                continue;
+            }
+            const dirName = path.relative(process.cwd(), entityDir) || '.';
+            this.useDirectoryMode(entityDir, options);
+            this.announceDirectory(dirName, progressPrefix, entityConfig.entity, entityDir, options, callbacks);
+            const result = await this.processEntityDirectory(entityDir, entityConfig, options, run.fileBackupManager, callbacks, run.configDir);
+            this.reportDirectoryResult(progressPrefix, dirName, result, options, callbacks);
+            addPushTotals(totals, result);
+            addPushTotals(this.runningTotals, result);
+        }
+        return totals;
+    }
+    announceDirectory(dirName, progressPrefix, entityName, entityDir, options, callbacks) {
+        // The folder header is verbose-only; the live spinner still shows "[X/N] Processing <dir>…".
+        if (options.verbose) {
+            callbacks?.onLog?.(`\n📁 ${dirName}:`);
+        }
+        if (callbacks?.onProgress) {
+            callbacks.onProgress(`${progressPrefix}Processing ${dirName}...`);
+        }
+        else {
+            callbacks?.onLog?.(`   ⏳ Processing...`);
+        }
+        if (options.verbose) {
+            callbacks?.onLog?.(`Processing ${entityName} in ${entityDir}`);
+        }
+    }
+    /** One compact line per directory, plus the per-status breakdown in verbose mode. */
+    reportDirectoryResult(progressPrefix, dirName, result, options, callbacks) {
+        const dirTotal = result.created + result.updated + result.unchanged + result.deleted + result.skipped;
+        const { text: dirSummary, changed: dirChanged } = this.formatDirectorySummary(progressPrefix, dirName, result, dirTotal);
+        if (callbacks?.onProgress && callbacks?.onSuccess) {
+            callbacks.onSuccess(dirSummary, dirChanged);
+        }
+        else {
+            callbacks?.onLog?.(`   ${dirSummary}`);
+        }
+        if (options.verbose && (dirTotal > 0 || result.errors > 0)) {
+            this.logDirectoryBreakdown(result, dirTotal, callbacks);
+        }
+    }
+    logDirectoryBreakdown(result, dirTotal, callbacks) {
+        const lines = [
+            [result.created, `   ✓ Created: ${result.created}`],
+            [result.updated, `   ✓ Updated: ${result.updated}`],
+            [result.deleted, `   ✓ Deleted: ${result.deleted}`],
+            [result.deferred, `   ⏳ Deferred: ${result.deferred}`],
+            [result.unchanged, `   - Unchanged: ${result.unchanged}`],
+            [result.skipped, `   - Skipped: ${result.skipped}`],
+            [result.errors, `   ✗ Errors: ${result.errors}`],
+        ];
+        callbacks?.onLog?.(`   Total processed: ${dirTotal} records`);
+        for (const [count, line] of lines) {
+            if (count > 0) {
+                callbacks?.onLog?.(line);
+            }
+        }
+    }
     async processEntityDirectory(entityDir, entityConfig, options, fileBackupManager, callbacks, syncRootDir) {
         let created = 0;
         let updated = 0;
@@ -563,18 +772,9 @@ export class PushService {
                 if (options.verbose) {
                     callbacks?.onLog?.(`   Analyzed ${analysisResult.sortedRecords.length} records (including nested)`);
                 }
-                // Create batch context for in-memory entity resolution
-                // Note: While JavaScript is single-threaded, async operations can interleave.
-                // Map operations themselves are atomic, but we ensure records are added to
-                // the context AFTER successful save to maintain consistency.
+                // Records are added to the batch context only AFTER a successful save (applyProcessResult),
+                // so later lookups in this file see consistent state.
                 const batchContext = new BatchContextIndex();
-                // One provider per JSON-root graph (Action + nested Action Params share a
-                // connection). Parallelize sibling roots only. Drain a graph when its last
-                // level finishes, or when TransactionDepth is already 0 (Save settled).
-                // Peak live independent instances is then the current batch plus any
-                // leftover-depth graphs still spanning later levels.
-                const hostProvider = Metadata.Provider; // global-provider-ok: host provider template for GraphProviderPool cloning
-                const graphPool = new GraphProviderPool(hostProvider, (msg) => callbacks?.onLog?.(msg));
                 const applyProcessResult = (result) => {
                     if (result.batchContextEntry) {
                         batchContext.set(result.batchContextEntry.key, result.batchContextEntry.entity);
@@ -601,83 +801,27 @@ export class PushService {
                         deleted++;
                     else if (result.status === 'skipped')
                         skipped++;
-                    else if (result.status === 'error') {
-                        // A non-throwing record error must not commit leftover graph depth —
-                        // the previous per-record release rolled that work back.
+                    else if (result.status === 'error')
                         errors++;
-                        graphPool.markFailed();
-                    }
                     else if (result.status === 'deferred') {
                         created++;
                         deferred++;
                     }
                 };
-                // Fail-fast: the first thrown record error aborts the file. That is
-                // intentional and matches the parallel path; it is a change from the
-                // old sequential fallback, which continued after onError.
-                let runError;
-                try {
-                    const levels = analysisResult.dependencyLevels && analysisResult.dependencyLevels.length > 0
-                        ? analysisResult.dependencyLevels
-                        : [analysisResult.sortedRecords];
-                    graphPool.noteLevels(levels);
-                    for (let levelIndex = 0; levelIndex < levels.length; levelIndex++) {
-                        const level = levels[levelIndex];
-                        const byGraph = groupRecordsByGraphId(level);
-                        const graphIds = Array.from(byGraph.keys());
-                        const batchSize = options.parallelBatchSize || PARALLEL_BATCH_SIZE;
-                        if (options.verbose && graphIds.length > 1) {
-                            callbacks?.onLog?.(`   Level ${levelIndex}: ${level.length} records in ${graphIds.length} graphs (parallel batch ${batchSize})`);
-                        }
-                        for (let i = 0; i < graphIds.length; i += batchSize) {
-                            const batchIds = graphIds.slice(i, i + batchSize);
-                            const batchResults = await Promise.all(batchIds.map(async (graphId) => {
-                                const recs = byGraph.get(graphId);
-                                const provider = await graphPool.obtain(graphId);
-                                const results = [];
-                                for (const flattenedRecord of recs) {
-                                    try {
-                                        const result = await this.processFlattenedRecord(flattenedRecord, entityDir, options, batchContext, callbacks, entityConfig, true, provider);
-                                        results.push({ success: true, result, record: flattenedRecord, graphId });
-                                    }
-                                    catch (error) {
-                                        graphPool.markFailed();
-                                        results.push({ success: false, error, record: flattenedRecord, graphId });
-                                        break;
-                                    }
-                                }
-                                return results;
-                            }));
-                            for (const graphResults of batchResults) {
-                                for (const batchResult of graphResults) {
-                                    if (batchResult.success === false) {
-                                        const err = batchResult.error;
-                                        const rec = batchResult.record;
-                                        callbacks?.onLog?.(`\n❌ Processing failed for ${rec.entityName} at ${rec.path}`);
-                                        callbacks?.onLog?.(`   ${err.message}\n`);
-                                        if (err.stack) {
-                                            callbacks?.onLog?.(`   Stack: ${err.stack}\n`);
-                                        }
-                                        throw err;
-                                    }
-                                    applyProcessResult(batchResult.result);
-                                }
-                            }
-                            const drainError = await graphPool.drainBatch(batchIds, levelIndex);
-                            if (drainError)
-                                throw drainError;
-                        }
-                    }
-                }
-                catch (e) {
-                    graphPool.markFailed();
-                    runError = e;
-                }
-                const settleError = await graphPool.releaseAll();
-                if (runError)
-                    throw runError;
-                if (settleError)
-                    throw settleError;
+                const levels = analysisResult.dependencyLevels && analysisResult.dependencyLevels.length > 0
+                    ? analysisResult.dependencyLevels
+                    : [analysisResult.sortedRecords];
+                await this.runFileGraphs({
+                    filePath,
+                    entityDir,
+                    entityConfig,
+                    options,
+                    callbacks,
+                    batchContext,
+                    levels,
+                    applyResult: applyProcessResult,
+                    errorCount: () => errors,
+                });
                 // Check if this file has any deletion records (including nested relatedEntities)
                 const hasDeletions = this.hasAnyDeletions(records);
                 // Write back to file (handles both single records and arrays)
@@ -703,14 +847,19 @@ export class PushService {
                         // Drop the cached snapshot — file on disk no longer matches it,
                         // and any later reader within this push must see fresh contents.
                         this.syncMetadataEngine.invalidateCachedFile(filePath);
+                        // Non-atomic: this file's records are already committed, so a later failure must
+                        // not restore the old file and lose their primary keys and sync blocks.
+                        if (this.writeMode === 'isolated') {
+                            fileBackupManager.releaseBackup(filePath);
+                        }
                     }
                 }
-                // Update stored checksum after successful processing (reuse cached value if available)
+                // Remember the checksum; it is stored only after the push commits (persistIncrementalState).
                 // Uses resolved content (after @include) so included-file changes are tracked.
                 if (this.stateManager && syncRootDir) {
                     const relativePath = path.relative(syncRootDir, filePath);
                     const checksum = cachedChecksum ?? this.syncEngine.calculateChecksum(fileData);
-                    this.stateManager.setFileChecksum(relativePath, checksum);
+                    this.pendingChecksums.set(relativePath, checksum);
                 }
             }
             catch (fileError) {
@@ -718,15 +867,149 @@ export class PushService {
                 throw fileError;
             }
         }
-        // Persist push timestamp for this entity directory after all files processed
+        // The push timestamp for this directory is stored only after the push commits.
         if (this.stateManager && syncRootDir) {
-            const relativeEntityDir = path.relative(syncRootDir, entityDir);
-            this.stateManager.setLastPushTimestamp(relativeEntityDir, new Date().toISOString());
-            await this.stateManager.pruneStaleChecksums(syncRootDir);
-            await this.stateManager.save();
+            this.pushedEntityDirs.push(path.relative(syncRootDir, entityDir));
         }
         return { created, updated, unchanged, deleted, skipped, deferred, errors };
     }
+    /**
+     * Run one file's JSON-root graphs, level by level. Atomic mode: one graph at a time on the host.
+     * Isolated mode: `graphBatchSize` graphs at once, each on its own independent instance.
+     * Fail-fast: the first failed record (thrown or `status: 'error'`) stops the file.
+     */
+    async runFileGraphs(run) {
+        const pendingWrites = new Map();
+        const pool = this.createGraphPool(pendingWrites, run.callbacks);
+        pool.noteLevels(run.levels);
+        let runError;
+        try {
+            for (let levelIndex = 0; levelIndex < run.levels.length; levelIndex++) {
+                await this.runGraphLevel(run, pool, pendingWrites, levelIndex);
+            }
+        }
+        catch (e) {
+            pool.markFailed();
+            runError = e;
+        }
+        const settleError = await pool.releaseAll();
+        if (runError)
+            throw runError;
+        if (settleError)
+            throw settleError;
+    }
+    createGraphPool(pendingWrites, callbacks) {
+        return new GraphProviderPool(this.hostProvider(), {
+            mode: this.writeMode === 'isolated' ? 'independent' : 'host',
+            log: (msg) => callbacks?.onLog?.(msg),
+            onGraphSettled: (graphId, outcome) => this.recordGraphOutcome(pendingWrites, graphId, outcome),
+        });
+    }
+    /** Non-atomic mode: a graph whose instance committed leaves its writes in the database. */
+    recordGraphOutcome(pendingWrites, graphId, outcome) {
+        const writes = pendingWrites.get(graphId);
+        pendingWrites.delete(graphId);
+        if (writes && outcome === 'committed') {
+            this.committedWrites.push(...writes);
+        }
+    }
+    async runGraphLevel(run, pool, pendingWrites, levelIndex) {
+        const byGraph = groupRecordsByGraphId(run.levels[levelIndex]);
+        const graphIds = Array.from(byGraph.keys());
+        const batchSize = this.graphBatchSize;
+        if (run.options.verbose && graphIds.length > 1) {
+            run.callbacks?.onLog?.(`   Level ${levelIndex}: ${run.levels[levelIndex].length} records in ${graphIds.length} graphs (batch ${batchSize}, ${this.writeMode})`);
+        }
+        for (let i = 0; i < graphIds.length; i += batchSize) {
+            const batchIds = graphIds.slice(i, i + batchSize);
+            const outcomes = await Promise.all(batchIds.map((graphId) => this.runGraph(run, pool, graphId, byGraph.get(graphId) ?? [])));
+            this.applyGraphOutcomes(run, pool, pendingWrites, outcomes.flat());
+            const drainError = await pool.drainBatch(batchIds, levelIndex);
+            if (drainError)
+                throw drainError;
+        }
+    }
+    /** One graph's records, in order, on the graph's provider. Stops at the first thrown error. */
+    async runGraph(run, pool, graphId, records) {
+        const provider = await pool.obtain(graphId);
+        const outcomes = [];
+        for (const record of records) {
+            try {
+                const result = await this.processFlattenedRecord(record, run.entityDir, run.options, run.batchContext, run.callbacks, run.entityConfig, true, provider);
+                // Read the depth NOW: a save that settled its own scope is already committed in isolated
+                // mode, and that is true whatever the rest of the graph goes on to do.
+                outcomes.push({ success: true, result, record, graphId, settled: provider.TransactionDepth === 0 });
+            }
+            catch (error) {
+                pool.markFailed();
+                outcomes.push({ success: false, error, record, graphId });
+                break;
+            }
+        }
+        return outcomes;
+    }
+    /**
+     * Apply a batch's results. Successful writes are tracked first, so a failure still reports
+     * what isolated graphs committed. Then the first thrown error, or any counted record
+     * error outside a dry run, stops the push.
+     */
+    applyGraphOutcomes(run, pool, pendingWrites, outcomes) {
+        let firstFailure;
+        for (const outcome of outcomes) {
+            if (outcome.success === false) {
+                firstFailure ??= outcome;
+                continue;
+            }
+            run.applyResult(outcome.result);
+            if (outcome.result.status === 'error') {
+                // A non-throwing record error must not commit leftover graph depth.
+                pool.markFailed();
+            }
+            this.trackPendingWrite(pendingWrites, run.filePath, outcome);
+        }
+        if (firstFailure) {
+            this.throwRecordFailure(firstFailure, run.callbacks);
+        }
+        const errorCount = run.errorCount();
+        if (!run.options.dryRun && errorCount > 0) {
+            throw new Error(`${errorCount} record${errorCount === 1 ? '' : 's'} in ${path.basename(run.filePath)} could not be pushed ` +
+                `(see the errors above). The push stops at the first failed record.`);
+        }
+    }
+    trackPendingWrite(pendingWrites, filePath, outcome) {
+        if (this.writeMode !== 'isolated') {
+            return; // shared: nothing commits before the push transaction does
+        }
+        const status = committedStatusOf(outcome.result);
+        if (!status) {
+            return;
+        }
+        const write = {
+            filePath,
+            entityName: outcome.record.entityName,
+            recordPath: outcome.record.path,
+            status,
+        };
+        if (outcome.settled) {
+            // Committed as it was saved. Reporting it now means a later rollback of the graph's leftover
+            // depth cannot make this write disappear from the report while its row is in the database.
+            this.committedWrites.push(write);
+            return;
+        }
+        const writes = pendingWrites.get(outcome.graphId) ?? [];
+        writes.push(write);
+        pendingWrites.set(outcome.graphId, writes);
+    }
+    throwRecordFailure(failure, callbacks) {
+        const err = failure.error instanceof Error ? failure.error : new Error(String(failure.error));
+        const rec = failure.record;
+        callbacks?.onLog?.(`\n❌ Processing failed for ${rec.entityName} at ${rec.path}`);
+        callbacks?.onLog?.(`   ${err.message}\n`);
+        if (err.stack) {
+            callbacks?.onLog?.(`   Stack: ${err.stack}\n`);
+        }
+        throw err;
+    }
     async processFlattenedRecord(flattenedRecord, entityDir, options, batchContext, callbacks, entityConfig, allowDefer = true, recordProvider) {
         const metadata = new Metadata(); // global-provider-ok: metadata sync operates on the configured provider only
         const { record, entityName, parentContext, id: recordId } = flattenedRecord;
@@ -1227,7 +1510,9 @@ export class PushService {
                 message: errorMessage,
             });
             // Throw error to trigger rollback and stop processing
-            throw new Error(`Failed to save ${entityName} record at ${flattenedRecord.path}: ${errorMessage}`);
+            const saveFailure = new Error(`Failed to save ${entityName} record at ${flattenedRecord.path}: ${errorMessage}`);
+            this.reportedRecordErrors.add(saveFailure);
+            throw saveFailure;
         }
         // Return batch context entry as a side effect instead of mutating directly.
         // The caller applies this sequentially after Promise.all() resolves, avoiding
@@ -1523,7 +1808,9 @@ export class PushService {
             messages.push('  • No deletions');
         }
         messages.push('');
-        messages.push('All operations will occur within a transaction and can be rolled back on error.');
+        for (const line of this.transactionBannerLines()) {
+            messages.push(line);
+        }
         messages.push('');
         messages.push('═'.repeat(80));
         messages.push('');
@@ -1547,6 +1834,19 @@ export class PushService {
      * Audit all deletions across all metadata files
      * This pre-processes all records to identify deletion dependencies and order
      */
+    /** What the deletion confirmation says about rollback. Must match the write mode. */
+    transactionBannerLines() {
+        const isolated = [...this.directoryModes.entries()].filter(([, mode]) => mode === 'isolated');
+        if (isolated.length === 0) {
+            return ['All creates, updates and deletes run in one database transaction. If anything fails, nothing is saved.'];
+        }
+        const names = isolated.map(([dir]) => path.relative(process.cwd(), dir) || dir).join(', ');
+        return [
+            'Deletes and deferred records run in one database transaction and are rolled back on error.',
+            `These directories use isolated transactions, so each create and update in them is committed as soon as it is`,
+            `saved and is NOT rolled back: ${names}.`,
+        ];
+    }
     async auditAllDeletions(entityDirs, options, callbacks) {
         // OPTIMIZATION: Quick scan to check if ANY deletions exist before doing expensive loading
         let hasAnyDeletions = false;
@@ -1838,11 +2138,23 @@ export class PushService {
                 }
             }
             catch (error) {
-                const err = error;
+                const err = error instanceof Error ? error : new Error(String(error));
                 callbacks?.onError?.(`   ✗ Failed to process deferred record: ${entityName} (${recordId})`);
                 callbacks?.onError?.(`     Error: ${err.message}`);
                 callbacks?.onError?.(`     Tip: Ensure all referenced records exist or remove the ?allowDefer flag`);
+                if (!this.reportedRecordErrors.has(err)) {
+                    callbacks?.onRecordError?.({
+                        entityName,
+                        path: flattenedRecord.path,
+                        primaryKey: recordId,
+                        message: `Deferred record could not be resolved: ${err.message}`,
+                    });
+                }
                 errors++;
+                if (!options.dryRun) {
+                    // Same as a thrown Phase 1 error: stop, and let push() roll the transaction back.
+                    throw new Error(`Failed to process deferred record ${entityName} (${recordId}): ${err.message}`, { cause: err });
+                }
             }
         }
         // Summary