@memberjunction/integration-engine 6.1.0-edge.2 → 6.1.0-edge.4

package/dist/FieldMapValidation.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Start-of-run validation for the MJ side of a field map.
+ *
+ * A field map's `DestinationFieldName` is the MJ column, in BOTH directions — pull writes it,
+ * push reads it back out to build the external payload. Nothing checks that the column exists.
+ * `BaseEntity.Set` looks the field up and, when it finds nothing, returns without doing anything
+ * and without saying anything: the value is dropped for every record, the entity is never dirtied
+ * by it, the save succeeds, and the run reports the rows as written. The observable result is a
+ * column's worth of data that never arrives, on a sync that reports success — and if that field is
+ * a key field, every record is re-created on the next run because it can never be matched again.
+ *
+ * This is the cheap check that turns that into one warning per map per run: the map is metadata,
+ * so it is verifiable the moment the run knows its entity, long before the first record is fetched.
+ * The decision is kept pure so it is tested without a provider or an entity.
+ */
+/** The parts of a field map this validation reads. */
+export type ValidatableFieldMap = {
+    SourceFieldName: string;
+    DestinationFieldName: string;
+    Status?: string | null;
+    IsKeyField?: boolean | null;
+};
+/** One map that cannot bind, with the detail an operator needs to fix it. */
+export type UnbindableFieldMap = {
+    SourceFieldName: string;
+    DestinationFieldName: string;
+    IsKeyField: boolean;
+};
+/**
+ * Returns the ACTIVE field maps whose destination column does not exist on the target entity.
+ *
+ * Matching is case-insensitive, because `BaseEntity` resolves field names case-insensitively — a
+ * map that differs only in casing binds fine and is not a finding. An empty `entityFieldNames`
+ * means the caller could not resolve the entity at all; that is a different (already reported)
+ * condition, so nothing is returned rather than flagging every map.
+ */
+export declare function FindUnbindableFieldMaps(fieldMaps: readonly ValidatableFieldMap[], entityFieldNames: readonly string[]): UnbindableFieldMap[];
+/** The operator-facing sentence for a set of unbindable maps on one entity map. */
+export declare function DescribeUnbindableFieldMaps(unbindable: readonly UnbindableFieldMap[], externalObjectName: string, entityName: string): string;
+//# sourceMappingURL=FieldMapValidation.d.ts.map

package/dist/FieldMapValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldMapValidation.d.ts","sourceRoot":"","sources":["../src/FieldMapValidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,sDAAsD;AACtD,MAAM,MAAM,mBAAmB,GAAG;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,kBAAkB,GAAG;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACnC,SAAS,EAAE,SAAS,mBAAmB,EAAE,EACzC,gBAAgB,EAAE,SAAS,MAAM,EAAE,GACpC,kBAAkB,EAAE,CAgBtB;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CACvC,UAAU,EAAE,SAAS,kBAAkB,EAAE,EACzC,kBAAkB,EAAE,MAAM,EAC1B,UAAU,EAAE,MAAM,GACnB,MAAM,CAaR"}

package/dist/FieldMapValidation.js

@@ -0,0 +1,58 @@
+/**
+ * Start-of-run validation for the MJ side of a field map.
+ *
+ * A field map's `DestinationFieldName` is the MJ column, in BOTH directions — pull writes it,
+ * push reads it back out to build the external payload. Nothing checks that the column exists.
+ * `BaseEntity.Set` looks the field up and, when it finds nothing, returns without doing anything
+ * and without saying anything: the value is dropped for every record, the entity is never dirtied
+ * by it, the save succeeds, and the run reports the rows as written. The observable result is a
+ * column's worth of data that never arrives, on a sync that reports success — and if that field is
+ * a key field, every record is re-created on the next run because it can never be matched again.
+ *
+ * This is the cheap check that turns that into one warning per map per run: the map is metadata,
+ * so it is verifiable the moment the run knows its entity, long before the first record is fetched.
+ * The decision is kept pure so it is tested without a provider or an entity.
+ */
+/**
+ * Returns the ACTIVE field maps whose destination column does not exist on the target entity.
+ *
+ * Matching is case-insensitive, because `BaseEntity` resolves field names case-insensitively — a
+ * map that differs only in casing binds fine and is not a finding. An empty `entityFieldNames`
+ * means the caller could not resolve the entity at all; that is a different (already reported)
+ * condition, so nothing is returned rather than flagging every map.
+ */
+export function FindUnbindableFieldMaps(fieldMaps, entityFieldNames) {
+    if (entityFieldNames.length === 0)
+        return [];
+    const known = new Set(entityFieldNames.map(n => n.toLowerCase()));
+    const unbindable = [];
+    for (const fm of fieldMaps) {
+        if (fm.Status !== 'Active')
+            continue; // an inactive map is never applied
+        const dest = fm.DestinationFieldName;
+        if (!dest)
+            continue; // no destination is a different defect
+        if (known.has(dest.toLowerCase()))
+            continue;
+        unbindable.push({
+            SourceFieldName: fm.SourceFieldName,
+            DestinationFieldName: dest,
+            IsKeyField: fm.IsKeyField === true,
+        });
+    }
+    return unbindable;
+}
+/** The operator-facing sentence for a set of unbindable maps on one entity map. */
+export function DescribeUnbindableFieldMaps(unbindable, externalObjectName, entityName) {
+    const pairs = unbindable.map(u => `${u.SourceFieldName} -> ${u.DestinationFieldName}${u.IsKeyField ? ' (KEY)' : ''}`);
+    const keyCount = unbindable.filter(u => u.IsKeyField).length;
+    return (`${unbindable.length} active field map(s) for '${externalObjectName}' target a column that does not exist ` +
+        `on '${entityName}': ${pairs.join(', ')}. Those values are silently dropped for every record — the write ` +
+        `succeeds without them` +
+        (keyCount > 0
+            ? `, and because ${keyCount === 1 ? 'one of them is a KEY field' : `${keyCount} of them are KEY fields`}, ` +
+                `records cannot be matched on a later run and will be re-created.`
+            : `.`) +
+        ` Apply the schema so the column exists, or point the map at a column that does.`);
+}
+//# sourceMappingURL=FieldMapValidation.js.map

package/dist/FieldMapValidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldMapValidation.js","sourceRoot":"","sources":["../src/FieldMapValidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiBH;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CACnC,SAAyC,EACzC,gBAAmC;IAEnC,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC7C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAClE,MAAM,UAAU,GAAyB,EAAE,CAAC;IAC5C,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QACzB,IAAI,EAAE,CAAC,MAAM,KAAK,QAAQ;YAAE,SAAS,CAAa,mCAAmC;QACrF,MAAM,IAAI,GAAG,EAAE,CAAC,oBAAoB,CAAC;QACrC,IAAI,CAAC,IAAI;YAAE,SAAS,CAA8B,uCAAuC;QACzF,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YAAE,SAAS;QAC5C,UAAU,CAAC,IAAI,CAAC;YACZ,eAAe,EAAE,EAAE,CAAC,eAAe;YACnC,oBAAoB,EAAE,IAAI;YAC1B,UAAU,EAAE,EAAE,CAAC,UAAU,KAAK,IAAI;SACrC,CAAC,CAAC;IACP,CAAC;IACD,OAAO,UAAU,CAAC;AACtB,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,2BAA2B,CACvC,UAAyC,EACzC,kBAA0B,EAC1B,UAAkB;IAElB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,eAAe,OAAO,CAAC,CAAC,oBAAoB,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACtH,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC;IAC7D,OAAO,CACH,GAAG,UAAU,CAAC,MAAM,6BAA6B,kBAAkB,wCAAwC;QAC3G,OAAO,UAAU,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,mEAAmE;QAC1G,uBAAuB;QACvB,CAAC,QAAQ,GAAG,CAAC;YACT,CAAC,CAAC,iBAAiB,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,4BAA4B,CAAC,CAAC,CAAC,GAAG,QAAQ,yBAAyB,IAAI;gBACzG,kEAAkE;YACpE,CAAC,CAAC,GAAG,CAAC;QACV,iFAAiF,CACpF,CAAC;AACN,CAAC"}

package/dist/FieldMappingEngine.d.ts

@@ -1,17 +1,5 @@
 import type { ICompanyIntegrationFieldMap } from './entity-types.js';
 import type { ExternalRecord, MappedRecord } from './types.js';
-/**
- * Engine responsible for applying field-level mappings and transformations from external records to
- * MJ entity fields.
- *
- * The per-value transform pipeline (direct / regex / split / combine / lookup / format / coerce /
- * substring / custom) is owned by the shared {@link FieldTransformEngine} in `@memberjunction/global`
- * and reused here, so integration sync and the rules-based bulk-update processor run the *exact same*
- * transform implementation — one place to fix, one place to extend. This engine keeps only the
- * integration-specific concerns: source flattening, field-map iteration, and unmapped-field overflow
- * capture. See the Field Rules guide in `@memberjunction/global` for the shared engine, and
- * `EntityFieldRules` in `@memberjunction/core` for the metadata-aware entity-update sibling.
- */
 export declare class FieldMappingEngine {
     /** The shared transform pipeline. Holds its own LRU cache of compiled custom expressions. */
     private readonly transformEngine;
@@ -24,7 +12,7 @@ export declare class FieldMappingEngine {
      * @param entityName - Target MJ entity name
      * @returns Array of mapped records with transformed field values
      */
-    Apply(records: ExternalRecord[], fieldMaps: ICompanyIntegrationFieldMap[], entityName: string): MappedRecord[];
+    Apply(records: ExternalRecord[], fieldMaps: ICompanyIntegrationFieldMap[], entityName: string, excludedSourceNames?: ReadonlySet<string>): MappedRecord[];
     /**
      * Maps a single external record through all active field mappings.
      */

package/dist/FieldMappingEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FieldMappingEngine.d.ts","sourceRoot":"","sources":["../src/FieldMappingEngine.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/D;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAkB;IAC3B,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA8B;IAE9D;;;;;;;;OAQG;IACI,KAAK,CACR,OAAO,EAAE,cAAc,EAAE,EACzB,SAAS,EAAE,2BAA2B,EAAE,EACxC,UAAU,EAAE,MAAM,GACnB,YAAY,EAAE;IAKjB;;OAEG;IACH,OAAO,CAAC,eAAe;IAyCvB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;CAWjC"}
+{"version":3,"file":"FieldMappingEngine.d.ts","sourceRoot":"","sources":["../src/FieldMappingEngine.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAkB/D,qBAAa,kBAAkB;IAC3B,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA8B;IAE9D;;;;;;;;OAQG;IACI,KAAK,CACR,OAAO,EAAE,cAAc,EAAE,EACzB,SAAS,EAAE,2BAA2B,EAAE,EACxC,UAAU,EAAE,MAAM,EAClB,mBAAmB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAC1C,YAAY,EAAE;IAMjB;;OAEG;IACH,OAAO,CAAC,eAAe;IAqDvB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;CAWjC"}

package/dist/FieldMappingEngine.js

@@ -1,5 +1,6 @@
 import { FieldTransformEngine } from '@memberjunction/global';
 import { computeUnmappedFields } from './CustomOverflow.js';
+import { StripExcludedFields } from './SyncDirectives.js';
 import { flattenRecord, hasNestedObject } from './RecordFlatten.js';
 /**
  * Engine responsible for applying field-level mappings and transformations from external records to
@@ -13,6 +14,8 @@ import { flattenRecord, hasNestedObject } from './RecordFlatten.js';
  * capture. See the Field Rules guide in `@memberjunction/global` for the shared engine, and
  * `EntityFieldRules` in `@memberjunction/core` for the metadata-aware entity-update sibling.
  */
+/** Shared empty set for the common no-exclusions call. */
+const EMPTY_EXCLUSIONS = new Set();
 export class FieldMappingEngine {
     constructor() {
         /** The shared transform pipeline. Holds its own LRU cache of compiled custom expressions. */
@@ -27,14 +30,26 @@ export class FieldMappingEngine {
      * @param entityName - Target MJ entity name
      * @returns Array of mapped records with transformed field values
      */
-    Apply(records, fieldMaps, entityName) {
+    Apply(records, fieldMaps, entityName, excludedSourceNames) {
         const activeMaps = fieldMaps.filter(fm => fm.Status === 'Active');
-        return records.map(record => this.MapSingleRecord(record, activeMaps, entityName));
+        const excluded = excludedSourceNames ?? EMPTY_EXCLUSIONS;
+        return records.map(record => this.MapSingleRecord(record, activeMaps, entityName, excluded));
     }
     /**
      * Maps a single external record through all active field mappings.
      */
-    MapSingleRecord(record, fieldMaps, entityName) {
+    MapSingleRecord(record, fieldMaps, entityName, excludedSourceNames) {
+        // Field-level exclusions strip BEFORE flatten and BEFORE mapping, so an excluded
+        // key reaches neither MappedFields, nor computeUnmappedFields (-> CustomOverflow),
+        // nor the content hash (whose basis is MappedFields). Deactivating a field map
+        // does NOT do this - the unmapped key would flow into overflow instead.
+        // No-exclusions and no-match paths return the original object: zero allocation.
+        if (excludedSourceNames.size > 0) {
+            const stripped = StripExcludedFields(record.Fields, excludedSourceNames);
+            if (stripped !== record.Fields) {
+                record = { ...record, Fields: stripped };
+            }
+        }
         // Flatten nested source objects to scalar columns (e.g. checkin_question.id →
         // checkin_question_id) BEFORE mapping. The match keys on the mapped PK VALUE
         // (MatchEngine.FindByKeyFields), so an object-valued source field would produce a

package/dist/FieldMappingEngine.js.map

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

package/dist/IntegrationConnectorCreationPipeline.d.ts

@@ -45,6 +45,29 @@ export interface ConnectorCreationPipelineOptions {
      * false so it never disables what it didn't look at. Threaded to PersistDiscoveredSchema.
      */
     DeactivateAbsent?: boolean;
+    /**
+     * Hard ceiling for the WHOLE run. Default {@link DEFAULT_RUN_DEADLINE_MS}; 0 disables it.
+     *
+     * Every other budget in this system bounds something INSIDE a stage, and none of them can preempt
+     * an `await` that never settles. A connector's `outOfTime()` is only checked BETWEEN requests; an
+     * HTTP abort signal governs only its own request; the discovery sample budget is spent by the code
+     * reading the stream. There is always one more layer able to stall — and when one does, this
+     * pipeline waits on it forever.
+     *
+     * Forever is literal. `complete()` and `fail()` are the only writers of `result.json` and both sit
+     * inside the try/catch around the stages, so a stage that never returns reaches neither. Since
+     * `isInFlight` is computed as "result.json is absent", the run then reports itself running for the
+     * rest of time: no client can learn otherwise and no retry clears it.
+     *
+     * Observed live 2026-08-12 three times on one connector: ConnectionTest completes in ~1s, Introspect
+     * starts, and the event stream is flat for ten minutes and counting — against a reference run that
+     * finished the entire pipeline in 3m53s.
+     *
+     * This does NOT stop the stalled work; a promise is not cancellable, so it keeps running until the
+     * process ends. It stops WAITING on it, so the run fails honestly, writes its artifact, and becomes
+     * retryable. A reported failure you can act on beats silence you cannot.
+     */
+    RunDeadlineMs?: number;
 }
 /** Outcome of a single pipeline invocation. */
 export interface ConnectorCreationPipelineResult {
@@ -84,8 +107,41 @@ export interface ConnectorCreationPipelineResult {
  * `__mj.Entity`. The pipeline emits `entity.skipped-no-pk` events for visibility.
  */
 export declare class IntegrationConnectorCreationPipeline {
-    /** In-flight runs by CompanyIntegrationID — coalesces a concurrent duplicate onto the same promise. */
+    /**
+     * In-flight runs by CompanyIntegrationID — coalesces a concurrent duplicate onto the same promise.
+     *
+     * Carries `at` because the entry is removed in a `finally`, which only fires when the promise
+     * SETTLES. A run that hangs therefore owns this slot forever, and every later refresh for that
+     * connector takes the `if (inFlight) return inFlight` path and attaches to a promise that will
+     * never resolve. No new run starts, no run.start is emitted, nothing reaches the workspace log —
+     * from outside the request simply vanishes, and the connector is unrefreshable until the process
+     * restarts.
+     *
+     * That is the whole explanation for behaviour that looked random for two days: a fresh process
+     * discovers in ~4 minutes; one hang poisons the slot; every attempt after it hangs; a restart
+     * clears the map and it "works again" until the next hang. Observed live 2026-08-12 — a run stuck
+     * at EventCount 5 with healthy runs on either side of it.
+     *
+     * Coalescing is right for concurrent callers, but it is only SAFE if runs terminate, and nothing
+     * guarantees that. So the entry expires: past {@link IN_FLIGHT_MAX_AGE_MS} a caller stops trusting
+     * it and runs fresh. That does not stop the stalled work (a promise is not cancellable) — it stops
+     * one hang from costing every future attempt.
+     */
     private static readonly inFlightRuns;
+    /**
+     * How long a coalescing entry may be trusted before a new caller runs fresh instead of joining it.
+     *
+     * Generous on purpose: a legitimate large discovery must still coalesce, and re-running one is
+     * expensive. This is not a run deadline — it bounds how long ONE hang can hijack other people's
+     * requests, nothing more.
+     */
+    private static readonly IN_FLIGHT_MAX_AGE_MS;
+    /**
+     * Default whole-run ceiling. Deliberately far above any healthy run — the reference Totara run
+     * completes in under four minutes and a large Salesforce-backed catalog in tens — so this only ever
+     * fires on work that has genuinely stopped, never on work that is merely big.
+     */
+    private static readonly DEFAULT_RUN_DEADLINE_MS;
     /** Just-completed runs by CompanyIntegrationID — coalesces a *sequential* duplicate within the window. */
     private static readonly recentRuns;
     /** Default coalesce window (ms) when the env override is unset/invalid. */
@@ -106,8 +162,43 @@ export declare class IntegrationConnectorCreationPipeline {
      * per CompanyIntegration and hand both callers the same result — no double introspect/persist/
      * classify, no double live API calls, and the resolver still gets a real summary. A legitimate
      * re-refresh later (outside the window) runs fresh.
+     *
+     * COALESCING vs. A CALLER-SUPPLIED `RunID`. A coalesced call never reaches `runInternal`, so
+     * `opts.RunID` is not the ID of the run that served it. That is fine for a caller who awaits the
+     * result (it gets the real `RunID` back), but NOT for a caller that already handed `opts.RunID` to
+     * a client as "the run to tail" — for that client, the ID would resolve to a run directory that
+     * never gets created, and `IntegrationTailRunEvents` would answer "Run not found" forever, which
+     * is indistinguishable from "the run hasn't opened its stream yet". So whenever a caller supplied
+     * a `RunID` and coalescing served a different run, we publish a terminal ALIAS run under the
+     * requested ID pointing at the run that actually did the work. See {@link honourRequestedRunID}.
      */
     Run(opts: ConnectorCreationPipelineOptions): Promise<ConnectorCreationPipelineResult>;
+    /**
+     * Keeps a caller-supplied `opts.RunID` tailable even when coalescing served the call from a
+     * DIFFERENT run.
+     *
+     * Why this exists: `IntegrationCreateConnection`/`IntegrationUpdateConnection` can launch the
+     * refresh detached — they mint a run ID, hand it to the client as "tail this", and only then call
+     * `Run()`. On create, the connection's `IsActive` false→true Save has ALREADY awaited a full
+     * pipeline run for the same CompanyIntegration (MJCompanyIntegrationEntityServer), so the
+     * resolver's call lands inside the coalesce window every time. Without this, the minted ID names
+     * a run directory that is never created: the detached promise RESOLVES (so the launcher's
+     * rejection handler never fires) and the client polls `IntegrationTailRunEvents` forever on
+     * `Run '<id>' not found`, which reads exactly like "not started yet".
+     *
+     * So: publish a real, terminal, one-stage run under the requested ID whose events name the run
+     * that actually did the work. The tail resolves, carries the served run's outcome, and
+     * `data.servedByRunID` lets a client hop to the full stream. The returned result is the served
+     * run unchanged — a caller that awaits still gets the true `RunID`.
+     */
+    private honourRequestedRunID;
+    /**
+     * Writes the alias run described in {@link honourRequestedRunID}. Best-effort: an artifact-write
+     * failure must never turn a schema refresh that genuinely succeeded into a thrown error, so this
+     * only logs. The alias mirrors the served run's success/failure so a client tailing it cannot
+     * read a failed refresh as a clean one.
+     */
+    private publishCoalescedAlias;
     /** Drops recent-run entries older than the coalesce window so the map stays bounded. */
     private static pruneRecentRuns;
     private runInternal;

package/dist/IntegrationConnectorCreationPipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IntegrationConnectorCreationPipeline.d.ts","sourceRoot":"","sources":["../src/IntegrationConnectorCreationPipeline.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"IntegrationConnectorCreationPipeline.d.ts","sourceRoot":"","sources":["../src/IntegrationConnectorCreationPipeline.ts"],"names":[],"mappings":"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"}

package/dist/IntegrationConnectorCreationPipeline.js

@@ -1,4 +1,4 @@
-import { Metadata } from '@memberjunction/core';
+import { LogError, Metadata } from '@memberjunction/core';
 import { IntegrationProgressEmitter, } from '@memberjunction/integration-progress-artifacts';
 import { SoftPKClassifier, } from '@memberjunction/integration-pk-classifier';
 import { IntegrationEngineBase } from '@memberjunction/integration-engine-base';
@@ -21,8 +21,41 @@ import { IntegrationSchemaSync } from './IntegrationSchemaSync.js';
  * `__mj.Entity`. The pipeline emits `entity.skipped-no-pk` events for visibility.
  */
 export class IntegrationConnectorCreationPipeline {
-    /** In-flight runs by CompanyIntegrationID — coalesces a concurrent duplicate onto the same promise. */
+    /**
+     * In-flight runs by CompanyIntegrationID — coalesces a concurrent duplicate onto the same promise.
+     *
+     * Carries `at` because the entry is removed in a `finally`, which only fires when the promise
+     * SETTLES. A run that hangs therefore owns this slot forever, and every later refresh for that
+     * connector takes the `if (inFlight) return inFlight` path and attaches to a promise that will
+     * never resolve. No new run starts, no run.start is emitted, nothing reaches the workspace log —
+     * from outside the request simply vanishes, and the connector is unrefreshable until the process
+     * restarts.
+     *
+     * That is the whole explanation for behaviour that looked random for two days: a fresh process
+     * discovers in ~4 minutes; one hang poisons the slot; every attempt after it hangs; a restart
+     * clears the map and it "works again" until the next hang. Observed live 2026-08-12 — a run stuck
+     * at EventCount 5 with healthy runs on either side of it.
+     *
+     * Coalescing is right for concurrent callers, but it is only SAFE if runs terminate, and nothing
+     * guarantees that. So the entry expires: past {@link IN_FLIGHT_MAX_AGE_MS} a caller stops trusting
+     * it and runs fresh. That does not stop the stalled work (a promise is not cancellable) — it stops
+     * one hang from costing every future attempt.
+     */
     static { this.inFlightRuns = new Map(); }
+    /**
+     * How long a coalescing entry may be trusted before a new caller runs fresh instead of joining it.
+     *
+     * Generous on purpose: a legitimate large discovery must still coalesce, and re-running one is
+     * expensive. This is not a run deadline — it bounds how long ONE hang can hijack other people's
+     * requests, nothing more.
+     */
+    static { this.IN_FLIGHT_MAX_AGE_MS = 20 * 60_000; }
+    /**
+     * Default whole-run ceiling. Deliberately far above any healthy run — the reference Totara run
+     * completes in under four minutes and a large Salesforce-backed catalog in tens — so this only ever
+     * fires on work that has genuinely stopped, never on work that is merely big.
+     */
+    static { this.DEFAULT_RUN_DEADLINE_MS = 45 * 60_000; }
     /** Just-completed runs by CompanyIntegrationID — coalesces a *sequential* duplicate within the window. */
     static { this.recentRuns = new Map(); }
     /** Default coalesce window (ms) when the env override is unset/invalid. */
@@ -46,6 +79,15 @@ export class IntegrationConnectorCreationPipeline {
      * per CompanyIntegration and hand both callers the same result — no double introspect/persist/
      * classify, no double live API calls, and the resolver still gets a real summary. A legitimate
      * re-refresh later (outside the window) runs fresh.
+     *
+     * COALESCING vs. A CALLER-SUPPLIED `RunID`. A coalesced call never reaches `runInternal`, so
+     * `opts.RunID` is not the ID of the run that served it. That is fine for a caller who awaits the
+     * result (it gets the real `RunID` back), but NOT for a caller that already handed `opts.RunID` to
+     * a client as "the run to tail" — for that client, the ID would resolve to a run directory that
+     * never gets created, and `IntegrationTailRunEvents` would answer "Run not found" forever, which
+     * is indistinguishable from "the run hasn't opened its stream yet". So whenever a caller supplied
+     * a `RunID` and coalescing served a different run, we publish a terminal ALIAS run under the
+     * requested ID pointing at the run that actually did the work. See {@link honourRequestedRunID}.
      */
     async Run(opts) {
         const ciID = opts.CompanyIntegration?.ID;
@@ -53,21 +95,109 @@ export class IntegrationConnectorCreationPipeline {
             return this.runInternal(opts); // no key to de-dup on — run directly
         const cls = IntegrationConnectorCreationPipeline;
         const inFlight = cls.inFlightRuns.get(ciID);
-        if (inFlight)
-            return inFlight; // a concurrent run is already going — share it
+        if (inFlight) {
+            if (Date.now() - inFlight.at < cls.IN_FLIGHT_MAX_AGE_MS) {
+                // A concurrent run is already going — share it, but THROUGH honourRequestedRunID so a
+                // caller that supplied its own RunID still gets that ID published as a tailable alias.
+                // Returning `inFlight.promise` directly (as this branch did before the rebase) discards
+                // the requested ID, which is exactly the defect #3354 fixed: the client polls a run
+                // directory that is never created and reads "Run not found" forever, indistinguishable
+                // from "hasn't started yet".
+                return this.honourRequestedRunID(opts, await inFlight.promise);
+            }
+            // Too old to be believed. Evicted rather than awaited: joining it is how one hang made a
+            // connector permanently unrefreshable. The stalled work carries on unattended — nothing
+            // here can cancel it — but this caller gets a real run instead of inheriting the stall.
+            LogError(`[ConnectorCreationPipeline] Discarding an in-flight run for ${ciID} that has not settled in ` +
+                `${Math.round((Date.now() - inFlight.at) / 60000)}min — starting a fresh run. The previous run is ` +
+                `stuck and will never terminate; its artifact stays in-flight until the workspace restarts.`);
+            cls.inFlightRuns.delete(ciID);
+        }
         cls.pruneRecentRuns();
         const recent = cls.recentRuns.get(ciID);
         if (recent)
-            return recent.result; // a run just completed (within the window) — reuse it
+            return this.honourRequestedRunID(opts, recent.result); // just completed — reuse it
         const promise = this.runInternal(opts);
-        cls.inFlightRuns.set(ciID, promise);
+        cls.inFlightRuns.set(ciID, { promise, at: Date.now() });
         try {
             const result = await promise;
             cls.recentRuns.set(ciID, { result, at: Date.now() });
             return result;
         }
         finally {
-            cls.inFlightRuns.delete(ciID);
+            // Only clear the slot if it is still OURS. An eviction above may have handed it to a newer
+            // run; deleting blindly would drop that entry and let a third caller start yet another
+            // duplicate.
+            if (cls.inFlightRuns.get(ciID)?.promise === promise) {
+                cls.inFlightRuns.delete(ciID);
+            }
+        }
+    }
+    /**
+     * Keeps a caller-supplied `opts.RunID` tailable even when coalescing served the call from a
+     * DIFFERENT run.
+     *
+     * Why this exists: `IntegrationCreateConnection`/`IntegrationUpdateConnection` can launch the
+     * refresh detached — they mint a run ID, hand it to the client as "tail this", and only then call
+     * `Run()`. On create, the connection's `IsActive` false→true Save has ALREADY awaited a full
+     * pipeline run for the same CompanyIntegration (MJCompanyIntegrationEntityServer), so the
+     * resolver's call lands inside the coalesce window every time. Without this, the minted ID names
+     * a run directory that is never created: the detached promise RESOLVES (so the launcher's
+     * rejection handler never fires) and the client polls `IntegrationTailRunEvents` forever on
+     * `Run '<id>' not found`, which reads exactly like "not started yet".
+     *
+     * So: publish a real, terminal, one-stage run under the requested ID whose events name the run
+     * that actually did the work. The tail resolves, carries the served run's outcome, and
+     * `data.servedByRunID` lets a client hop to the full stream. The returned result is the served
+     * run unchanged — a caller that awaits still gets the true `RunID`.
+     */
+    async honourRequestedRunID(opts, served) {
+        const requested = opts.RunID;
+        if (!requested || requested === served.RunID)
+            return served;
+        await this.publishCoalescedAlias(requested, opts, served);
+        return served;
+    }
+    /**
+     * Writes the alias run described in {@link honourRequestedRunID}. Best-effort: an artifact-write
+     * failure must never turn a schema refresh that genuinely succeeded into a thrown error, so this
+     * only logs. The alias mirrors the served run's success/failure so a client tailing it cannot
+     * read a failed refresh as a clean one.
+     */
+    async publishCoalescedAlias(requestedRunID, opts, served) {
+        try {
+            const emitter = new IntegrationProgressEmitter({
+                runID: requestedRunID,
+                runKind: 'ConnectorCreation',
+                integrationID: opts.CompanyIntegration.IntegrationID,
+                companyIntegrationID: opts.CompanyIntegration.ID,
+                triggerType: opts.TriggerType ?? 'Pipeline',
+                startedAt: new Date().toISOString(),
+                expectedStages: ['Coalesced'],
+                context: { servedByRunID: served.RunID, coalesced: true },
+            }, { rootDir: opts.ArtifactRootDir, consoleMirror: opts.ConsoleMirror });
+            const pointer = `A schema refresh for this connection was already running (or had just ` +
+                `completed), so this request was served by run ${served.RunID} instead of starting a ` +
+                `second live introspect. Tail that run for the full event stream.`;
+            emitter.runStart(pointer);
+            emitter.stageComplete('Coalesced', { processed: 1, succeeded: served.Success ? 1 : 0 });
+            if (served.Success) {
+                const p = served.PersistResult;
+                await emitter.complete(`${pointer} Outcome: ${p?.ObjectsCreated ?? 0} objects created, ` +
+                    `${p?.ObjectsUpdated ?? 0} updated, ${served.UnresolvedObjects.length} unresolved PKs.`);
+            }
+            else {
+                emitter.stageError('Coalesced', served.FailureMessage ?? 'no reason reported', {
+                    code: 'coalesced-run-failed',
+                    servedByRunID: served.RunID,
+                });
+                await emitter.fail(`${pointer} That run FAILED: ${served.FailureMessage ?? 'no reason reported'}`, 'coalesced-run-failed');
+            }
+            await emitter.flush();
+        }
+        catch (err) {
+            console.warn(`[IntegrationConnectorCreationPipeline] Could not publish coalesced-run alias ` +
+                `${requestedRunID} → ${served.RunID}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     /** Drops recent-run entries older than the coalesce window so the map stays bounded. */
@@ -98,12 +228,44 @@ export class IntegrationConnectorCreationPipeline {
             rootDir: opts.ArtifactRootDir,
             consoleMirror: opts.ConsoleMirror,
         });
+        const startedMs = Date.now();
         emitter.runStart(`Connector creation pipeline started for ${opts.CompanyIntegration.Integration ?? '(integration)'} run=${runID}`);
+        // THE RUN MUST END. Raced rather than awaited: a stage that never settles cannot be cancelled,
+        // but it can be stopped being waited on — which is the difference between a run that fails and
+        // one that is in-flight forever. See RunDeadlineMs.
+        const deadlineMs = opts.RunDeadlineMs ?? IntegrationConnectorCreationPipeline.DEFAULT_RUN_DEADLINE_MS;
+        // The default is 45min, but RunDeadlineMs is a public knob and a caller may set seconds — in
+        // which case rounding to minutes reported the failure as a "deadline of 0min", which reads as
+        // a bug in the pipeline rather than the limit the caller actually asked for.
+        const deadlineLabel = deadlineMs >= 60_000
+            ? `${Math.round(deadlineMs / 60_000)}min`
+            : `${(deadlineMs / 1000).toFixed(deadlineMs % 1000 === 0 ? 0 : 1)}s`;
+        let deadlineTimer;
+        const withDeadline = async (stage, work) => {
+            if (deadlineMs <= 0)
+                return work;
+            const remaining = deadlineMs - (Date.now() - startedMs);
+            if (remaining <= 0) {
+                throw new Error(`Run deadline of ${deadlineLabel} exceeded before stage "${stage}" could start.`);
+            }
+            return Promise.race([
+                work,
+                new Promise((_, reject) => {
+                    deadlineTimer = setTimeout(() => reject(new Error(`Stage "${stage}" did not finish within the run deadline of ` +
+                        `${deadlineLabel}. The work may still be running on this ` +
+                        `process — it cannot be cancelled — but the run is being failed so it stops ` +
+                        `reporting itself in-flight and can be retried.`)), remaining);
+                    // Never hold the process open for a deadline nobody is waiting on.
+                    deadlineTimer.unref?.();
+                }),
+            ]).finally(() => { if (deadlineTimer)
+                clearTimeout(deadlineTimer); });
+        };
         try {
-            await this.StageConnectionTest(emitter, opts);
-            const sourceSchema = await this.StageIntrospect(emitter, opts);
-            const persistResult = await this.StagePersist(emitter, opts, sourceSchema);
-            const { verdicts, unresolved } = await this.StagePKClassify(emitter, opts);
+            await withDeadline('ConnectionTest', this.StageConnectionTest(emitter, opts));
+            const sourceSchema = await withDeadline('Introspect', this.StageIntrospect(emitter, opts));
+            const persistResult = await withDeadline('Persist', this.StagePersist(emitter, opts, sourceSchema));
+            const { verdicts, unresolved } = await withDeadline('PKClassify', this.StagePKClassify(emitter, opts));
             emitter.stageComplete('Pipeline', {
                 processed: persistResult.ObjectsCreated + persistResult.ObjectsUpdated,
                 succeeded: verdicts.filter(v => v.Confident).length,
@@ -303,6 +465,19 @@ export class IntegrationConnectorCreationPipeline {
         for (const fieldLog of persistResult.FieldMergeLog) {
             emitter.fieldAdded(fieldLog.ObjectName, fieldLog.FieldName, fieldLog.EffectiveSource);
         }
+        // A comprehensive refresh deactivates declared objects/fields it did not observe. That is
+        // the intended behaviour, but it is also the point where a connector's declared field stops
+        // being materialized by every later apply — so say which ones, on the progress stream the
+        // caller is already reading, instead of only in a server console line.
+        if (persistResult.ObjectsDeactivated.length > 0 || persistResult.FieldsDeactivated.length > 0) {
+            emitter.warning('Persist', 'DECLARED_ROWS_DEACTIVATED', `${persistResult.ObjectsDeactivated.length} object(s) and ${persistResult.FieldsDeactivated.length} ` +
+                `field(s) were declared but not observed by this authoritative discovery, so they were deactivated ` +
+                `(never deleted) and will not be materialized by a later apply until they are observed again or ` +
+                `re-enabled.`, {
+                objects: persistResult.ObjectsDeactivated,
+                fields: persistResult.FieldsDeactivated,
+            });
+        }
         emitter.stageComplete('Persist', {
             processed: persistResult.ObjectsCreated + persistResult.ObjectsUpdated,
             succeeded: persistResult.ObjectsCreated + persistResult.ObjectsUpdated,