@memberjunction/server 6.1.0-edge.2 → 6.1.0-edge.3

package/dist/resolvers/IntegrationDiscoveryResolver.js

@@ -19,12 +19,14 @@ import { UUIDsEqual } from "@memberjunction/global";
 import { CronExpressionHelper } from "@memberjunction/scheduling-engine";
 import { ConnectorFactory, IntegrationEngine, IntegrationSchemaSync, decideSchemaLimitViolations, IntegrationConnectorCreationPipeline, IntegrationActionGenerator } from "@memberjunction/integration-engine";
 import { IntegrationEngineBase } from "@memberjunction/integration-engine-base";
+import { buildIntegrationLLMPKCallback } from "@memberjunction/core-entities-server";
 import { SchemaBuilder, TypeMapper, SchemaEvolution } from "@memberjunction/integration-schema-builder";
 import { RuntimeSchemaManager } from "@memberjunction/schema-engine";
-import { IntegrationProgressReader } from "@memberjunction/integration-progress-artifacts";
+import { IntegrationProgressEmitter, IntegrationProgressReader } from "@memberjunction/integration-progress-artifacts";
 import { ResolverBase } from "../generic/ResolverBase.js";
 import { IntegrationCustomColumnPromoter } from "../integration/CustomColumnPromoter.js";
 import { ComputeCascadeRemovalSet, ComputeRemovedDependencyWarnings, DisableUnselectedEntityMaps, ReenableFieldMapsForEntityMap, ResetPullWatermarks, SetEntityMapEnabled } from "../integration/EntityMapLifecycle.js";
+import { BuildCreateConnectionMessage, BuildDetachedRefreshMessage, BuildUpdateConnectionMessage } from "../integration/SchemaRefreshLaunch.js";
 import { RequireSystemUser } from "../directives/RequireSystemUser.js";
 import { UserCache } from "@memberjunction/generic-database-provider";
 // ─── RSU Pipeline Output Types ──────────────────────────────────────────────
@@ -1074,6 +1076,18 @@ __decorate([
     Field(),
     __metadata("design:type", String)
 ], CreateConnectionPipelineSummary.prototype, "RunID", void 0);
+__decorate([
+    Field(),
+    __metadata("design:type", Boolean)
+], CreateConnectionPipelineSummary.prototype, "InProgress", void 0);
+__decorate([
+    Field(),
+    __metadata("design:type", Boolean)
+], CreateConnectionPipelineSummary.prototype, "Succeeded", void 0);
+__decorate([
+    Field({ nullable: true }),
+    __metadata("design:type", String)
+], CreateConnectionPipelineSummary.prototype, "FailureMessage", void 0);
 __decorate([
     Field(),
     __metadata("design:type", Number)
@@ -1181,6 +1195,10 @@ __decorate([
     Field(() => Int, { nullable: true, description: 'Time budget (ms) for stage-2 streaming field discovery before it stops and uses what it gathered.' }),
     __metadata("design:type", Number)
 ], IntegrationSyncConfigInput.prototype, "DiscoveryTimeBudgetMs", void 0);
+__decorate([
+    Field(() => Int, { nullable: true, description: 'Per-page FetchChanges timeout (ms). Raise it for a connector that fans out one request per parent record, whose page time scales with BatchSize. Wins over the connector\'s own FetchChangesTimeoutMs; unset = the connector\'s value, else the framework default (30000).' }),
+    __metadata("design:type", Number)
+], IntegrationSyncConfigInput.prototype, "FetchTimeoutMs", void 0);
 __decorate([
     Field(() => Int, { nullable: true, description: 'Batch size for stage-2 streaming field discovery (records per FetchChanges page). Default 500.' }),
     __metadata("design:type", Number)
@@ -1234,6 +1252,10 @@ __decorate([
     Field(() => Int, { nullable: true }),
     __metadata("design:type", Number)
 ], IntegrationSyncConfigOutput.prototype, "DiscoveryTimeBudgetMs", void 0);
+__decorate([
+    Field(() => Int, { nullable: true }),
+    __metadata("design:type", Number)
+], IntegrationSyncConfigOutput.prototype, "FetchTimeoutMs", void 0);
 __decorate([
     Field(() => Int, { nullable: true }),
     __metadata("design:type", Number)
@@ -2083,7 +2105,7 @@ __decorate([
 IntegrationRunEventsOutput = __decorate([
     ObjectType()
 ], IntegrationRunEventsOutput);
-// Sync progress is now tracked inside IntegrationEngine itself via IntegrationEngine.GetSyncProgress()
+// Sync progress is now tracked inside IntegrationEngine itself via IntegrationEngine.GetSyncProgressAsync()
 let ConnectionSummaryOutput = class ConnectionSummaryOutput {
 };
 __decorate([
@@ -3372,9 +3394,33 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
         }
         return result;
     }
-    async runSchemaRefreshPipeline(companyIntegrationID, user, provider, universalPKConvention) {
+    async runSchemaRefreshPipeline(companyIntegrationID, user, provider, universalPKConvention, runID) {
+        // Sync lock (#3656).  This pipeline rewrites the very IO/IOF rows, field
+        // maps and DDL a sync reads, so it must not overlap a sync or another
+        // maintenance operation for the same connection.  The two other
+        // pipeline call sites — IntegrationRefreshConnectorSchema and
+        // IntegrationSchemaEvolution — already take this lock inline; this is
+        // the third and fourth (create/update/reactivate) finally taking it too.
+        if (!IntegrationEngine.AcquireMaintenanceLock(companyIntegrationID, 'schema refresh')) {
+            throw new Error('Schema refresh not started: a sync or another maintenance operation is currently running for this connection. Retry after it completes.');
+        }
+        try {
+            return await this.runSchemaRefreshPipelineLocked(companyIntegrationID, user, provider, universalPKConvention, runID);
+        }
+        finally {
+            IntegrationEngine.ReleaseMaintenanceLock(companyIntegrationID);
+        }
+    }
+    /** The body of {@link runSchemaRefreshPipeline}, run with the maintenance lock held. */
+    async runSchemaRefreshPipelineLocked(companyIntegrationID, user, provider, universalPKConvention, runID) {
         const { connector, companyIntegration } = await this.resolveConnector(companyIntegrationID, user, provider);
         const pipeline = new IntegrationConnectorCreationPipeline();
+        // SoftPKClassifier's LLM tier (universal → naming → statistical → LLM →
+        // synthetic) only runs when this callback is supplied.  It used to be
+        // wired by the CompanyIntegration save hook; with that hook gone
+        // (#3738) it is wired here, so the create/update/reactivate paths keep
+        // the same PK-inference quality they had before.
+        const llmInference = await buildIntegrationLLMPKCallback(user);
         const runOpts = {
             Connector: connector,
             CompanyIntegration: companyIntegration,
@@ -3383,6 +3429,10 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
             UniversalPKConvention: universalPKConvention || undefined,
             ConsoleMirror: true,
             TriggerType: 'Manual',
+            LLMInference: llmInference ?? undefined,
+            // Caller-supplied runID: lets the detached path hand a tailable ID back to the client
+            // BEFORE the pipeline has done any work. Omitted ⇒ the pipeline generates its own.
+            RunID: runID,
         };
         const result = await pipeline.Run(runOpts);
         // Refresh in-memory caches so downstream queries (object picker,
@@ -3391,6 +3441,9 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
         await IntegrationEngine.Instance.Config(true, user, provider);
         return {
             RunID: result.RunID,
+            InProgress: false,
+            Succeeded: result.Success,
+            FailureMessage: result.FailureMessage,
             ObjectsCreated: result.PersistResult?.ObjectsCreated ?? 0,
             ObjectsUpdated: result.PersistResult?.ObjectsUpdated ?? 0,
             FieldsCreated: result.PersistResult?.FieldsCreated ?? 0,
@@ -3406,6 +3459,88 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
             })),
         };
     }
+    /**
+     * Launches the schema-refresh pipeline WITHOUT awaiting it and returns a summary carrying the
+     * tailable `RunID` and `InProgress: true`.
+     *
+     * Why: the pipeline is a live vendor introspect — minutes on a large catalog (HubSpot: 130
+     * objects). Awaiting it inline holds the create/update mutation open for that entire time, so the
+     * connection wizard's Finish button sits on an indeterminate spinner with no way to tell progress
+     * from a hang. The pipeline already writes a complete, durable, per-run event stream keyed by its
+     * runID; the only thing missing was handing that ID to the caller BEFORE the work starts. Hence
+     * the caller-supplied runID.
+     *
+     * Trade-off the caller opts into: the mutation no longer reports what the refresh found (counts
+     * are placeholder zeros) and a refresh failure no longer surfaces in the mutation's Message — both
+     * live on the run stream instead. That is why `awaitSchemaRefresh` defaults to true.
+     *
+     * ON CREATE this is the only refresh that runs. #3738 removed the activation hook that used to
+     * fire the same pipeline inside `Save()`, awaited — which had made the create mutation pay a full
+     * introspect before ever reaching this method, and had run it BEFORE the connection test, so a
+     * rejected connection was rolled back with its discovered schema already written.
+     *
+     * Belt and braces: if the launch below IS coalesced onto some other run for this connection (a
+     * concurrent refresh, a repeat click), the pipeline publishes a terminal alias run under `runID`
+     * naming the run that served it — so the ID handed back here is tailable in every case.
+     */
+    startSchemaRefreshPipelineDetached(companyIntegrationID, user, provider, universalPKConvention) {
+        const runID = IntegrationProgressEmitter.newRunID('connector');
+        // Deliberately not awaited. Once the pipeline is running it records every outcome on this
+        // run's artifact stream under `runID` itself — but it can also throw BEFORE it ever
+        // constructs its emitter (connector-driver resolution, a missing Integration row), and in
+        // the blocking path that throw surfaced in the mutation's Message. Detached, the caller has
+        // already been handed `runID` and has nothing but the stream to watch, so a pre-emitter
+        // throw must be published onto that stream — otherwise the run never appears at all and a
+        // tailer waits forever on a run ID that will never produce an event.
+        void this.runSchemaRefreshPipeline(companyIntegrationID, user, provider, universalPKConvention, runID)
+            .catch(err => this.publishDetachedLaunchFailure(runID, companyIntegrationID, err));
+        return {
+            RunID: runID,
+            InProgress: true,
+            // Not known yet — the run has only just been launched.
+            Succeeded: false,
+            ObjectsCreated: 0,
+            ObjectsUpdated: 0,
+            FieldsCreated: 0,
+            FieldsUpdated: 0,
+            UnresolvedObjects: [],
+            PKVerdicts: [],
+        };
+    }
+    /**
+     * Terminates a detached run that failed BEFORE the pipeline could open its own artifact stream.
+     *
+     * The pipeline constructs its emitter inside `Run()`, so anything that throws on the way there —
+     * connector-driver resolution (`No connector registered for driver class "X"`), a missing
+     * Integration row, a CompanyIntegration that vanished — produces no run directory at all. In the
+     * blocking path that throw surfaced in the mutation's Message. Detached, the caller has already
+     * been handed the run ID and has only the stream to watch, so the failure has to be published
+     * there or the run is invisible forever.
+     *
+     * Only ever called on the rejection path: if the pipeline got far enough to build its own emitter
+     * it terminates its own run, and a pipeline that completed never reaches here.
+     */
+    publishDetachedLaunchFailure(runID, companyIntegrationID, err) {
+        const message = this.formatError(err);
+        LogError(`Detached schema refresh (run ${runID}) failed: ${message}`);
+        try {
+            const emitter = new IntegrationProgressEmitter({
+                runID,
+                runKind: 'ConnectorCreation',
+                companyIntegrationID,
+                triggerType: 'Manual',
+                startedAt: new Date().toISOString(),
+            });
+            emitter.runStart('Detached schema refresh launch');
+            emitter.stageError('Launch', message, { code: 'schema-refresh-launch-failed' });
+            void emitter.fail(`Schema refresh could not start: ${message}`, 'schema-refresh-launch-failed')
+                .catch(e => LogError(`Detached schema refresh (run ${runID}): failure artifact write failed — ${e}`));
+        }
+        catch (e) {
+            // Progress reporting must never mask the original failure, which is already logged above.
+            LogError(`Detached schema refresh (run ${runID}): could not open failure artifact — ${e}`);
+        }
+    }
     /**
      * Rolls back a freshly created connection by deleting both the CompanyIntegration and Credential records.
      */
@@ -3556,7 +3691,7 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
     /**
      * Creates a CompanyIntegration with a linked Credential entity for encrypted credential storage.
      */
-    async IntegrationCreateConnection(input, testConnection, runSchemaRefresh, universalPKConvention, ctx) {
+    async IntegrationCreateConnection(input, testConnection, runSchemaRefresh, universalPKConvention, awaitSchemaRefresh, ctx) {
         try {
             const user = this.getAuthenticatedUser(ctx);
             const md = GetReadWriteProvider(ctx.providers, { allowFallbackToReadOnly: true });
@@ -3579,12 +3714,20 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
             ci.IntegrationID = input.IntegrationID;
             ci.CompanyID = input.CompanyID;
             ci.CredentialID = credentialID;
-            ci.IsActive = true;
+            // Created INACTIVE on purpose (#3738).  A connection is not marked
+            // active until its credential has had a chance to prove itself in
+            // step 3 below — so nothing downstream ever observes an active row
+            // backed by a password that is about to be rejected and rolled back.
+            ci.IsActive = false;
             ci.Name = input.CredentialName; // Name is required on CompanyIntegration
             if (input.ExternalSystemID)
                 ci.ExternalSystemID = input.ExternalSystemID;
             if (input.Configuration)
                 ci.Configuration = input.Configuration;
+            // Whether the refresh runs detached (this resolver owns it and returns a tailable RunID)
+            // or inline below. No save-side refresh exists to coordinate with any more — #3738 removed
+            // the activation hook, so every refresh on this path is one this method asked for.
+            const ownSchemaRefresh = runSchemaRefresh && !awaitSchemaRefresh;
             const saved = await ci.Save();
             if (!saved) {
                 const validationErrors = ci.LatestResult?.Message || 'Unknown validation error';
@@ -3607,12 +3750,27 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
                 testPassed = true;
                 testMessage = testResult.Message;
             }
+            // 3b. Credential has proven itself (or the caller declined a test,
+            // which is the pre-existing default) — activate.  Ordering matters:
+            // this save is what makes the connection usable, and it must not
+            // happen while the credential is still unverified.
+            ci.IsActive = true;
+            if (!await ci.Save()) {
+                await this.rollbackCreatedConnection(ci, credential);
+                return {
+                    Success: false,
+                    Message: `Failed to activate CompanyIntegration: ${ci.LatestResult?.Message || 'Unknown error'}`,
+                };
+            }
             // 4. Auto-run schema refresh pipeline (intermittent server-side period).
             // Fires whenever runSchemaRefresh=true, regardless of whether the
             // caller also asked for a test.  The wizard may have tested separately
             // and just be hitting Create to save.
             let schemaRefreshSummary;
-            if (runSchemaRefresh) {
+            if (ownSchemaRefresh) {
+                schemaRefreshSummary = this.startSchemaRefreshPipelineDetached(ci.ID, user, md, universalPKConvention);
+            }
+            else if (runSchemaRefresh) {
                 try {
                     const refreshResult = await this.runSchemaRefreshPipeline(ci.ID, user, md, universalPKConvention);
                     schemaRefreshSummary = refreshResult;
@@ -3626,9 +3784,7 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
             if (testConnection || schemaRefreshSummary) {
                 return {
                     Success: true,
-                    Message: schemaRefreshSummary
-                        ? `Connection created${testConnection ? ', test passed' : ''}, schema refresh: ${schemaRefreshSummary.ObjectsCreated} created, ${schemaRefreshSummary.ObjectsUpdated} updated, ${schemaRefreshSummary.UnresolvedObjects.length} PK-unresolved`
-                        : 'Connection created and test passed',
+                    Message: BuildCreateConnectionMessage(testConnection, schemaRefreshSummary),
                     CompanyIntegrationID: ci.ID,
                     CredentialID: credentialID,
                     ConnectionTestSuccess: testPassed,
@@ -3651,7 +3807,7 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
     /**
      * Updates credential values and/or configuration on an existing CompanyIntegration.
      */
-    async IntegrationUpdateConnection(companyIntegrationID, credentialValues, configuration, externalSystemID, testConnection, runSchemaRefresh, universalPKConvention, ctx) {
+    async IntegrationUpdateConnection(companyIntegrationID, credentialValues, configuration, externalSystemID, testConnection, runSchemaRefresh, universalPKConvention, awaitSchemaRefresh, ctx) {
         try {
             const user = this.getAuthenticatedUser(ctx);
             const md = GetReadWriteProvider(ctx.providers, { allowFallbackToReadOnly: true });
@@ -3700,13 +3856,14 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
             // Fires whenever runSchemaRefresh=true, regardless of whether the
             // caller also asked for a test — the wizard may have tested separately
             // already and is just hitting Update to save edits.
+            if (runSchemaRefresh && !awaitSchemaRefresh) {
+                const detached = this.startSchemaRefreshPipelineDetached(companyIntegrationID, user, md, universalPKConvention);
+                return { Success: true, Message: BuildDetachedRefreshMessage(detached.RunID) };
+            }
             if (runSchemaRefresh) {
                 try {
                     const refreshResult = await this.runSchemaRefreshPipeline(companyIntegrationID, user, md, universalPKConvention);
-                    return {
-                        Success: true,
-                        Message: `Updated, schema refresh: ${refreshResult.ObjectsCreated} created, ${refreshResult.ObjectsUpdated} updated, ${refreshResult.UnresolvedObjects.length} PK-unresolved`,
-                    };
+                    return { Success: true, Message: BuildUpdateConnectionMessage(refreshResult) };
                 }
                 catch (refreshErr) {
                     LogError(`IntegrationUpdateConnection: pipeline error — ${refreshErr}`);
@@ -3751,6 +3908,7 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
             set('crossLayerPipeline', config.CrossLayerPipeline);
             set('partitionReconcile', config.PartitionReconcile);
             set('discoveryTimeBudgetMs', config.DiscoveryTimeBudgetMs);
+            set('fetchTimeoutMs', config.FetchTimeoutMs);
             set('discoveryBatchSize', config.DiscoveryBatchSize);
             set('discoveryMaxRecords', config.DiscoveryMaxRecords);
             set('deactivateAbsent', config.DeactivateAbsent);
@@ -3812,6 +3970,7 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
             CrossLayerPipeline: bool(cfg.crossLayerPipeline),
             PartitionReconcile: bool(cfg.partitionReconcile),
             DiscoveryTimeBudgetMs: num(cfg.discoveryTimeBudgetMs),
+            FetchTimeoutMs: num(cfg.fetchTimeoutMs),
             DiscoveryBatchSize: num(cfg.discoveryBatchSize),
             DiscoveryMaxRecords: num(cfg.discoveryMaxRecords),
             DeactivateAbsent: bool(cfg.deactivateAbsent),
@@ -3907,8 +4066,13 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
     }
     /**
      * Reactivates a previously deactivated CompanyIntegration by setting IsActive=true.
+     *
+     * Before #3738 this mutation inherited a full schema refresh from the
+     * CompanyIntegration save hook, with no way to decline it.  The refresh is
+     * now this resolver's own, explicit step — same default behaviour, but
+     * visible in the API and suppressible with `runSchemaRefresh: false`.
      */
-    async IntegrationReactivateConnection(companyIntegrationID, ctx) {
+    async IntegrationReactivateConnection(companyIntegrationID, runSchemaRefresh, ctx) {
         try {
             const user = this.getAuthenticatedUser(ctx);
             const md = GetReadWriteProvider(ctx.providers, { allowFallbackToReadOnly: true });
@@ -3919,6 +4083,22 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
             ci.IsActive = true;
             if (!await ci.Save())
                 return { Success: false, Message: `Failed to reactivate: ${ci.LatestResult?.Message ?? 'Unknown error'}` };
+            if (runSchemaRefresh) {
+                try {
+                    const refreshResult = await this.runSchemaRefreshPipeline(companyIntegrationID, user, md);
+                    return {
+                        Success: true,
+                        Message: `Reactivated, schema refresh: ${refreshResult.ObjectsCreated} created, ${refreshResult.ObjectsUpdated} updated, ${refreshResult.UnresolvedObjects.length} PK-unresolved`,
+                    };
+                }
+                catch (refreshErr) {
+                    // Refresh failure does NOT undo the reactivation — the
+                    // connection is active, only discovery failed, and the
+                    // operator can re-run IntegrationRefreshConnectorSchema.
+                    LogError(`IntegrationReactivateConnection: pipeline error — ${refreshErr}`);
+                    return { Success: true, Message: `Reactivated (schema refresh failed: ${this.formatError(refreshErr)})` };
+                }
+            }
             return { Success: true, Message: 'Reactivated' };
         }
         catch (e) {
@@ -4266,11 +4446,7 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
             // Step 3: Build schema and RSU pipeline input
             const { schemaOutput, rsuInput } = await this.buildSchemaForConnector(input.CompanyIntegrationID, objects, validatedPlatform, user, skipGitCommit, skipRestart, provider);
             // Step 4: Inject integration post-restart payload into RSU input.
-            const { join } = await import('node:path');
-            const rsuWorkDir = process.env.RSU_WORK_DIR || process.cwd();
-            const pendingWorkDir = join(rsuWorkDir, '.rsu_pending');
-            const pendingFilePath = join(pendingWorkDir, `${Date.now()}.json`);
-            // Build per-object field map for pending file (null = all fields).
+            // Build per-object field map for the pending payload (null = all fields).
             // resolved.sourceObjects is order-aligned with resolvedNames after the
             // resolveSourceObjectsToNames refactor — pair them directly instead
             // of looking up by ID (which broke for name-only selections).
@@ -4300,13 +4476,12 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
                 ScheduleTimezone: input.ScheduleTimezone,
                 StartSync: input.StartSync,
                 FullSync: effectiveFullSync,
-                SyncScope: input.SyncScope ?? 'created',
+                SyncScope: input.SyncScope === 'all' ? 'all' : 'created',
                 UnselectedAction: (input.UnselectedAction ?? 'disable'),
                 CreatedAt: new Date().toISOString(),
             };
-            rsuInput.PostRestartFiles = [
-                { Path: pendingFilePath, Content: JSON.stringify(pendingPayload, null, 2) }
-            ];
+            rsuInput.PendingWork = [pendingPayload];
+            rsuInput.ContextUser = user;
             // Step 5: Run pipeline (restart kills process at the end).
             // Retrying variant — an install should not die because the migration hit a dropped
             // connection or a transient lock; it only replays while nothing has been applied.
@@ -4316,12 +4491,9 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
             const pipelineSteps = batchResult.Results[0]?.Steps.map((s) => ({
                 Name: s.Name, Status: s.Status, DurationMs: s.DurationMs, Message: s.Message, StepIndex: s.StepIndex, StepTotal: s.StepTotal,
             }));
-            // If pipeline failed, clean up pending file and return error
+            // Pending work is registered only for migrations that succeeded, so a
+            // failed pipeline has nothing to clean up.
             if (!migrationSucceeded) {
-                try {
-                    (await import('node:fs')).unlinkSync(pendingFilePath);
-                }
-                catch { /* may not exist */ }
                 return {
                     Success: false,
                     Message: `Pipeline failed: ${batchResult.Results[0]?.ErrorMessage ?? 'unknown error'}`,
@@ -4365,10 +4537,10 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
                         console.warn(`[Integration] Schedule creation failed: ${schedErr}`);
                     }
                 }
-                try {
-                    (await import('node:fs')).unlinkSync(pendingFilePath);
+                // The work just happened inline (no restart), so close out its durable rows.
+                for (const pendingWorkID of batchResult.Results[0]?.PendingWorkIDs ?? []) {
+                    await rsm.CompletePendingWork(pendingWorkID, user);
                 }
-                catch { /* already consumed */ }
                 return {
                     Success: true,
                     Message: `Applied ${objects.length} object(s) — ${entityMapsCreated.length} entity maps created${syncRunID ? ', sync started' : ''}${scheduledJobID ? ', schedule created' : ''}`,
@@ -4849,14 +5021,56 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
             return { Success: false, Message: this.formatError(e) };
         }
     }
+    /**
+     * Enqueue a sync for worker execution (PR 1 item 8) instead of running it in this
+     * process. Creates the run row with `Status='Queued'` and returns its ID immediately —
+     * so the caller gets a real, trackable RunID with no fire-and-forget polling window,
+     * and the sync survives this process going away before it starts.
+     *
+     * Requires a process running the integration sync worker (`integrationSyncWorker.enabled`);
+     * without one, rows accumulate in the queue unexecuted.
+     */
+    async IntegrationEnqueueSync(companyIntegrationID, fullSync, entityMapIDs, syncDirection, ctx) {
+        try {
+            const user = this.getAuthenticatedUser(ctx);
+            const provider = GetReadWriteProvider(ctx.providers);
+            await IntegrationEngine.Instance.Config(false, user, provider);
+            // Same upfront gates as IntegrationStartSync — refusing here beats queueing work
+            // that the engine will only refuse later, in another process, out of the caller's sight.
+            const ciCheck = await provider.GetEntityObject('MJ: Company Integrations', user);
+            if (await ciCheck.InnerLoad(CompositeKey.FromID(companyIntegrationID)) && ciCheck.IsActive === false) {
+                return { Success: false, Message: 'Connector is deactivated (IsActive=false); sync not enqueued' };
+            }
+            const maintenance = IntegrationEngine.GetMaintenanceLock(companyIntegrationID);
+            if (maintenance) {
+                return { Success: false, Message: `Sync not enqueued: ${maintenance.Reason} is in progress for this connection (since ${maintenance.AcquiredAt.toISOString()}). Retry after it completes.` };
+            }
+            const syncOptions = {};
+            if (fullSync)
+                syncOptions.FullSync = true;
+            if (entityMapIDs?.length)
+                syncOptions.EntityMapIDs = entityMapIDs;
+            if (syncDirection)
+                syncOptions.SyncDirection = syncDirection;
+            const runID = await IntegrationEngine.Instance.EnqueueSync(companyIntegrationID, user, 'Manual', Object.keys(syncOptions).length > 0 ? syncOptions : undefined, provider);
+            return { Success: true, Message: 'Sync enqueued', RunID: runID };
+        }
+        catch (e) {
+            LogError(`IntegrationEnqueueSync error: ${e}`);
+            return { Success: false, Message: this.formatError(e) };
+        }
+    }
     /**
      * Cancels a running sync by marking its status as Cancelled.
      */
     async IntegrationCancelSync(companyIntegrationID, ctx) {
         try {
-            this.getAuthenticatedUser(ctx);
-            // Signal the engine to abort the running sync
-            const cancelled = IntegrationEngine.CancelSync(companyIntegrationID);
+            const user = this.getAuthenticatedUser(ctx);
+            const provider = GetReadWriteProvider(ctx.providers);
+            // DB-backed cancel (durable runs): stamps CancelRequestedAt on the live run row, so
+            // the request reaches the owning process wherever it is — this server, another API
+            // node, or a worker — via its heartbeat/boundary checks. No in-memory signal.
+            const cancelled = await IntegrationEngine.CancelSyncAsync(companyIntegrationID, user, provider);
             if (!cancelled) {
                 return { Success: false, Message: 'No active sync found for this connector' };
             }
@@ -5395,8 +5609,11 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
     }
     async IntegrationGetSyncProgress(companyIntegrationID, ctx) {
         try {
-            this.getAuthenticatedUser(ctx);
-            const syncProgress = IntegrationEngine.GetSyncProgress(companyIntegrationID);
+            const user = this.getAuthenticatedUser(ctx);
+            const provider = GetReadOnlyProvider(ctx.providers, { allowFallbackToReadWrite: true });
+            // DB-backed progress (durable runs): reads ProgressJSON from the live run row, so
+            // progress is visible from ANY process — not just the one executing the sync.
+            const syncProgress = await IntegrationEngine.GetSyncProgressAsync(companyIntegrationID, user, provider);
             if (syncProgress) {
                 return {
                     Success: true,
@@ -5840,16 +6057,12 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
                     return obj;
                 });
                 const { schemaOutput, rsuInput } = await this.buildSchemaForConnector(connInput.CompanyIntegrationID, objects, validatedPlatform, user, skipGitCommit, skipRestart, provider, sourceSchema);
-                // Build per-object field map for pending file
+                // Build per-object field map for the pending payload
                 const sourceObjectFields = {};
                 for (const name of resolvedNames) {
                     sourceObjectFields[name] = fieldsByName.get(name.toLowerCase()) ?? null;
                 }
                 // Inject post-restart pending work payload
-                const { join } = await import('node:path');
-                const rsuWorkDir = process.env.RSU_WORK_DIR || process.cwd();
-                const pendingWorkDir = join(rsuWorkDir, '.rsu_pending');
-                const pendingFilePath = join(pendingWorkDir, `${Date.now()}_${connInput.CompanyIntegrationID}.json`);
                 const pendingPayload = {
                     CompanyIntegrationID: connInput.CompanyIntegrationID,
                     SourceObjectNames: resolvedNames,
@@ -5859,15 +6072,15 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
                     ScheduleTimezone: connInput.ScheduleTimezone,
                     StartSync: input.StartSync,
                     FullSync: input.FullSync ?? false,
-                    SyncScope: input.SyncScope ?? 'created',
-                    SyncDirection: input.SyncDirection,
-                    ScheduleSyncDirection: input.ScheduleSyncDirection,
+                    SyncScope: input.SyncScope === 'all' ? 'all' : 'created',
+                    // Unrecognized directions fall back to undefined = "use the entity map's own SyncDirection"
+                    SyncDirection: input.SyncDirection && isValidSyncDirection(input.SyncDirection) ? input.SyncDirection : undefined,
+                    ScheduleSyncDirection: input.ScheduleSyncDirection && isValidSyncDirection(input.ScheduleSyncDirection) ? input.ScheduleSyncDirection : undefined,
                     UnselectedAction: (input.UnselectedAction ?? 'disable'),
                     CreatedAt: new Date().toISOString(),
                 };
-                rsuInput.PostRestartFiles = [
-                    { Path: pendingFilePath, Content: JSON.stringify(pendingPayload, null, 2) }
-                ];
+                rsuInput.PendingWork = [pendingPayload];
+                rsuInput.ContextUser = user;
                 return {
                     connInput,
                     connector,
@@ -5876,7 +6089,6 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
                     objects,
                     schemaOutput,
                     rsuInput,
-                    pendingFilePath,
                 };
             }));
             // Separate successes and failures
@@ -5927,11 +6139,8 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
                         Message: pipelineResult?.ErrorMessage ?? 'Pipeline failed',
                         Warnings: build.schemaOutput.Warnings.length > 0 ? build.schemaOutput.Warnings : undefined,
                     });
-                    // Clean up pending file on failure
-                    try {
-                        (await import('node:fs')).unlinkSync(build.pendingFilePath);
-                    }
-                    catch { /* may not exist */ }
+                    // No pending-work cleanup needed — rows are registered only for
+                    // migrations that succeeded.
                     continue;
                 }
                 const connResult = {
@@ -5967,11 +6176,10 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
                         if (scheduleResult)
                             connResult.ScheduledJobID = scheduleResult;
                     }
-                    // Clean up pending file
-                    try {
-                        (await import('node:fs')).unlinkSync(build.pendingFilePath);
+                    // The work just happened inline (no restart), so close out its durable rows.
+                    for (const pendingWorkID of pipelineResult.PendingWorkIDs ?? []) {
+                        await rsm.CompletePendingWork(pendingWorkID, user);
                     }
-                    catch { /* already consumed */ }
                     connResult.Message = `Applied ${build.objects.length} object(s) — ${entityMapsCreated.length} entity maps created${syncRunID ? ', sync started' : ''}`;
                 }
                 connectorResults.push(connResult);
@@ -6476,26 +6684,21 @@ let IntegrationDiscoveryResolver = class IntegrationDiscoveryResolver extends Re
                 // ApplyAll uses. default: created DISABLED (user enables after the refresh);
                 // autoEnableNewObjects opts in. Removal was already handled in Phase 3 → 'ignore'.
                 if (newObjects.length > 0 && !skipRestart) {
-                    const { join } = await import('node:path');
-                    const rsuWorkDir = process.env.RSU_WORK_DIR || process.cwd();
-                    const pendingFilePath = join(rsuWorkDir, '.rsu_pending', `${Date.now()}-evolution.json`);
-                    rsuInput.PostRestartFiles = [
-                        ...(rsuInput.PostRestartFiles ?? []),
+                    rsuInput.PendingWork = [
+                        ...(rsuInput.PendingWork ?? []),
                         {
-                            Path: pendingFilePath,
-                            Content: JSON.stringify({
-                                CompanyIntegrationID: companyIntegrationID,
-                                SourceObjectNames: newObjects,
-                                SourceObjectFields: Object.fromEntries(newObjects.map(n => [n, null])),
-                                SchemaName: schemaName,
-                                StartSync: false,
-                                SyncScope: 'created',
-                                UnselectedAction: 'ignore',
-                                CreateDisabled: !autoEnableNewObjects,
-                                CreatedAt: new Date().toISOString(),
-                            }, null, 2),
+                            CompanyIntegrationID: companyIntegrationID,
+                            SourceObjectNames: newObjects,
+                            SourceObjectFields: Object.fromEntries(newObjects.map(n => [n, null])),
+                            SchemaName: schemaName,
+                            StartSync: false,
+                            SyncScope: 'created',
+                            UnselectedAction: 'ignore',
+                            CreateDisabled: !autoEnableNewObjects,
+                            CreatedAt: new Date().toISOString(),
                         },
                     ];
+                    rsuInput.ContextUser = user;
                 }
                 const rsm = RuntimeSchemaManager.Instance;
                 const batchResult = await rsm.RunPipelineBatch([rsuInput]);
@@ -6753,9 +6956,10 @@ __decorate([
     __param(1, Arg("testConnection", () => Boolean, { defaultValue: false })),
     __param(2, Arg("runSchemaRefresh", () => Boolean, { defaultValue: true, description: "When true (default) and TestConnection succeeds, automatically runs IntegrationConnectorCreationPipeline (live introspect → persist Declared/Discovered/Custom → SoftPKClassifier). The intermittent server-side work the wizard's Forward step represents." })),
     __param(3, Arg("universalPKConvention", { nullable: true, description: "Optional vendor-wide PK hint (e.g. 'id' for HubSpot). Improves SoftPKClassifier convergence." })),
-    __param(4, Ctx()),
+    __param(4, Arg("awaitSchemaRefresh", () => Boolean, { defaultValue: true, description: "When false, the schema refresh is launched detached and this mutation returns immediately with SchemaRefresh.RunID + InProgress=true — tail that run instead of blocking on a minutes-long live introspect. The introspect happens exactly once either way, and always AFTER the connection test, so a failed test rolls back a connection that left no discovered schema behind. Default true preserves the blocking behaviour (counts returned inline)." })),
+    __param(5, Ctx()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [CreateConnectionInput, Boolean, Boolean, String, Object]),
+    __metadata("design:paramtypes", [CreateConnectionInput, Boolean, Boolean, String, Boolean, Object]),
     __metadata("design:returntype", Promise)
 ], IntegrationDiscoveryResolver.prototype, "IntegrationCreateConnection", null);
 __decorate([
@@ -6767,9 +6971,10 @@ __decorate([
     __param(4, Arg("testConnection", () => Boolean, { defaultValue: false })),
     __param(5, Arg("runSchemaRefresh", () => Boolean, { defaultValue: true, description: "When true (default) and TestConnection succeeds, automatically runs IntegrationConnectorCreationPipeline. Same intermittent server-side step as the create flow." })),
     __param(6, Arg("universalPKConvention", { nullable: true, description: "Optional vendor-wide PK hint (e.g. 'id' for HubSpot)" })),
-    __param(7, Ctx()),
+    __param(7, Arg("awaitSchemaRefresh", () => Boolean, { defaultValue: true, description: "When false, the schema refresh is launched detached and this mutation returns immediately with the run ID to tail instead of blocking on a minutes-long live introspect. Default true preserves the blocking behaviour." })),
+    __param(8, Ctx()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, String, String, String, Boolean, Boolean, String, Object]),
+    __metadata("design:paramtypes", [String, String, String, String, Boolean, Boolean, String, Boolean, Object]),
     __metadata("design:returntype", Promise)
 ], IntegrationDiscoveryResolver.prototype, "IntegrationUpdateConnection", null);
 __decorate([
@@ -6819,9 +7024,10 @@ __decorate([
 __decorate([
     Mutation(() => MutationResultOutput),
     __param(0, Arg("companyIntegrationID")),
-    __param(1, Ctx()),
+    __param(1, Arg("runSchemaRefresh", () => Boolean, { defaultValue: true, description: "When true (default), re-runs IntegrationConnectorCreationPipeline after reactivating so the catalog reflects the source as it is now. Pass false to reactivate without a live scan — useful when the catalog is known-current, or when the source is large enough that discovery should be scheduled separately." })),
+    __param(2, Ctx()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:paramtypes", [String, Boolean, Object]),
     __metadata("design:returntype", Promise)
 ], IntegrationDiscoveryResolver.prototype, "IntegrationReactivateConnection", null);
 __decorate([
@@ -6883,6 +7089,18 @@ __decorate([
     __metadata("design:paramtypes", [String, String, Boolean, Array, String, Object]),
     __metadata("design:returntype", Promise)
 ], IntegrationDiscoveryResolver.prototype, "IntegrationStartSync", null);
+__decorate([
+    Mutation(() => StartSyncOutput),
+    RequireSystemUser(),
+    __param(0, Arg("companyIntegrationID")),
+    __param(1, Arg("fullSync", () => Boolean, { defaultValue: false, description: 'If true, ignores watermarks and re-fetches all records from the source' })),
+    __param(2, Arg("entityMapIDs", () => [String], { nullable: true, description: 'Optional: sync only these entity maps. If omitted, syncs all maps for the connector.' })),
+    __param(3, Arg("syncDirection", () => String, { nullable: true, description: 'Override sync direction: Pull | Push | Bidirectional. If omitted, each entity map\'s own SyncDirection is used.' })),
+    __param(4, Ctx()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Boolean, Array, String, Object]),
+    __metadata("design:returntype", Promise)
+], IntegrationDiscoveryResolver.prototype, "IntegrationEnqueueSync", null);
 __decorate([
     Mutation(() => MutationResultOutput),
     __param(0, Arg("companyIntegrationID")),