@memberjunction/server 6.2.0-edge.5 → 6.2.0-edge.7

package/src/integration/RSUPostRestartProgress.ts

@@ -0,0 +1,359 @@
+/**
+ * @fileoverview The second half of an RSU run's progress stream — the half that happens in a
+ * different process from the first.
+ *
+ * The RSU pipeline restarts the API as one of its own steps. Everything after that restart —
+ * creating the entity maps and field maps, then starting the first sync — runs in the NEW process,
+ * from the durable pending-work queue. Until now none of it was observable: the pre-restart process
+ * died mid-run, so its emitter never wrote a terminal result and the run stayed flagged in-flight
+ * forever, while the post-restart work reported nothing at all. A client watching the setup journey
+ * saw the stream stop at "restart instance" and had no way to learn whether the connector ever
+ * became live.
+ *
+ * This module re-attaches to that same run and finishes it. Re-attaching (rather than opening a new
+ * run) is the entire point: the tail API returns strictly `seq > cursor`, and a fresh emitter
+ * restarts its sequence at 1 — so a brand-new run's events would sort BELOW the cursor of every
+ * client already tailing, permanently invisible to them, while the resolver echoed their unchanged
+ * cursor back and they polled forever receiving nothing.
+ *
+ * Correlation is by MANIFEST, not by checkpoint. The manifest is written when the run opens, minutes
+ * before the restart; the checkpoint is written in the last moments before the kill signal. Keying
+ * off the durable artifact and treating the checkpoint as enrichment means a lost checkpoint costs
+ * step numbers, not the whole re-attachment.
+ */
+import {
+    IntegrationProgressEmitter,
+    IntegrationProgressReader,
+    IntegrationRunResumeError,
+    SweepInterruptedRuns,
+} from '@memberjunction/integration-progress-artifacts';
+import type { EmitterOptions, IntegrationProgressEvent, IntegrationRunSnapshot } from '@memberjunction/integration-progress-artifacts';
+import { RuntimeSchemaManager } from '@memberjunction/schema-engine';
+import { LogError, LogStatus } from '@memberjunction/core';
+import { RESTART_STAGE } from './RSUProgressBridge.js';
+
+/** The two stages this module owns, in order. Named by the pipeline so the halves cannot drift. */
+const [ENTITY_MAPS_STAGE, START_SYNC_STAGE] = RuntimeSchemaManager.EXPECTED_STEPS_POST_RESTART;
+
+/**
+ * How many in-flight RSU runs to consider for a single connection before giving up.
+ *
+ * More than one can exist only when an earlier run's post-restart work never completed (its process
+ * died again, or its pending-work rows were consumed on a boot that then crashed). The newest is the
+ * one this pending-work item belongs to; the window is small so a pathological backlog cannot turn
+ * one item's re-attachment into a directory scan of the whole run history.
+ */
+const CANDIDATE_RUN_WINDOW = 25;
+
+/** Step position carried across the restart, when the checkpoint survived. */
+interface RestartPosition {
+    /** 1-based index of `RestartMJAPI`; the post-restart steps follow it. */
+    stepIndex?: number;
+    stepTotal?: number;
+}
+
+/**
+ * One re-attached RSU run. Emits the two post-restart stages into the run the pre-restart process
+ * opened, and terminates it exactly once.
+ *
+ * Obtained from {@link RSUPostRestartProgressSession}, never constructed directly — the session is
+ * what guarantees a run is attached (and terminated) once even when several pending-work items in
+ * one sweep belong to the same batch.
+ */
+export class RSUPostRestartProgress {
+    private entityMapsOpen = false;
+    private syncOpen = false;
+    private failed = false;
+    private readonly failures: string[] = [];
+
+    /** @internal — use {@link RSUPostRestartProgressSession.For}. */
+    public constructor(
+        private readonly emitter: IntegrationProgressEmitter,
+        private readonly position: RestartPosition
+    ) {}
+
+    /** The run being continued, so a caller can log or hand it to a client. */
+    public get RunID(): string {
+        return this.emitter.RunID;
+    }
+
+    /**
+     * "step 12 of 14" for a post-restart step, or undefined when the checkpoint did not survive.
+     *
+     * `offset` is the step's position AFTER `RestartMJAPI` (1 for CreateEntityMaps, 2 for StartSync).
+     * Derived from the checkpoint rather than recomputed, because the pipeline skips steps
+     * conditionally (`SkipGitCommit`) and a recomputed index would disagree with the one the client
+     * has already been shown.
+     */
+    private positionLabel(offset: number): string | undefined {
+        const { stepIndex, stepTotal } = this.position;
+        if (stepIndex == null || stepTotal == null) return undefined;
+        return `step ${stepIndex + offset} of ${stepTotal}`;
+    }
+
+    /** Opens the `CreateEntityMaps` stage for one pending-work item. */
+    public BeginEntityMaps(objectCount: number): void {
+        this.emitter.stageStart(ENTITY_MAPS_STAGE, this.positionLabel(1));
+        this.entityMapsOpen = true;
+        this.emitter.heartbeat(ENTITY_MAPS_STAGE, `Mapping ${objectCount} object(s)`, { processed: 0, totalKnown: objectCount });
+    }
+
+    /**
+     * Reports one object's entity map + field maps as done.
+     *
+     * A heartbeat rather than a `records.batch.complete`: heartbeat counts are explicitly excluded
+     * from the run's applied aggregate, so per-object liveness cannot double-count against the
+     * stage rollup that follows.
+     */
+    public ObjectMapped(objectName: string, processed: number, totalKnown: number): void {
+        this.emitter.heartbeat(ENTITY_MAPS_STAGE, `Mapped ${objectName} (${processed}/${totalKnown})`, { processed, totalKnown });
+    }
+
+    /**
+     * Closes `CreateEntityMaps` with the applied quartet, in OBJECTS.
+     *
+     * The run's aggregate is in objects, not migrations, for a resumed run: the migration quartet is
+     * emitted by `run.end`, which a restarting run by definition never reaches. Emitting both here
+     * would sum two different units into one number (2 migrations + 12 objects reported as
+     * "processed: 14"), so the migration counts stay in the terminal message instead.
+     */
+    public CompleteEntityMaps(processed: number, succeeded: number, failed: number): void {
+        if (!this.entityMapsOpen) return;
+        this.entityMapsOpen = false;
+        this.emitter.stageComplete(ENTITY_MAPS_STAGE, { processed, succeeded, failed, totalKnown: processed });
+    }
+
+    /**
+     * Closes `CreateEntityMaps` as an ERROR, naming the objects that were never mapped.
+     *
+     * Naming them is the requirement, not a nicety: when this half fails, those objects have tables
+     * in the database and no way to sync into them, and the operator's only signal that something
+     * needs re-applying is this message.
+     */
+    public FailEntityMaps(message: string, unmappedObjects: string[]): void {
+        this.entityMapsOpen = false;
+        this.failed = true;
+        const named = unmappedObjects.length > 0
+            ? ` Objects never mapped: ${unmappedObjects.slice(0, 20).join(', ')}${unmappedObjects.length > 20 ? ` (+${unmappedObjects.length - 20} more)` : ''}.`
+            : '';
+        const full = `${message}${named}`;
+        this.failures.push(full);
+        this.emitter.stageError(ENTITY_MAPS_STAGE, full, {
+            code: 'RSU_POST_RESTART_ENTITY_MAPS_FAILED',
+            unmappedObjects,
+        });
+    }
+
+    /** Opens the `StartSync` stage. */
+    public BeginStartSync(): void {
+        this.emitter.stageStart(START_SYNC_STAGE, this.positionLabel(2));
+        this.syncOpen = true;
+    }
+
+    /**
+     * Closes `StartSync`, carrying the sync run's ID so a client can hop from this stream to the
+     * sync's own.
+     *
+     * Deliberately carries NO `counts`: the records belong to the sync run, and counting them here
+     * would add another unit to this run's aggregate. `syncRunID` may be null when the sync was
+     * launched but its run row was not yet readable — the stage still completes, because the sync
+     * did start; the client simply has to find the run itself.
+     */
+    public CompleteStartSync(syncRunID: string | null): void {
+        if (!this.syncOpen) return;
+        this.syncOpen = false;
+        this.emitter.emit('stage.complete', {
+            stage: START_SYNC_STAGE,
+            level: 'info',
+            message: syncRunID ? `Sync started — run ${syncRunID}` : 'Sync started',
+            data: { syncRunID },
+        });
+    }
+
+    /** Closes `StartSync` as skipped — the caller asked for no initial sync. */
+    public SkipStartSync(reason: string): void {
+        if (!this.syncOpen) return;
+        this.syncOpen = false;
+        this.emitter.emit('stage.complete', {
+            stage: START_SYNC_STAGE,
+            level: 'info',
+            message: `Sync not started — ${reason}`,
+            data: { syncRunID: null, skipped: true, reason },
+        });
+    }
+
+    /** Closes `StartSync` as an error — the sync could not be launched. */
+    public FailStartSync(message: string): void {
+        this.syncOpen = false;
+        this.failed = true;
+        this.failures.push(message);
+        this.emitter.stageError(START_SYNC_STAGE, message, { code: 'RSU_POST_RESTART_SYNC_START_FAILED' });
+    }
+
+    /** Records a failure that happened outside either stage (connector resolution, for example). */
+    public RecordFailure(stage: string, message: string): void {
+        this.failed = true;
+        this.failures.push(message);
+        this.emitter.stageError(stage, message, { code: 'RSU_POST_RESTART_FAILED' });
+    }
+
+    /**
+     * Terminates the run. Idempotent — the emitter refuses a second terminal write, and the result
+     * file is created-not-truncated, so a duplicate call cannot rewrite an outcome a client has
+     * already read.
+     */
+    public async Finish(): Promise<void> {
+        // An unclosed stage would leave a client's stepper stuck on it forever; a run must never end
+        // with a stage still open.
+        if (this.entityMapsOpen) this.FailEntityMaps('Post-restart processing ended with entity-map creation still open', []);
+        if (this.syncOpen) this.FailStartSync('Post-restart processing ended with sync start still open');
+        if (this.failed) {
+            await this.emitter.fail(
+                `RSU post-restart work failed — ${this.failures.join(' | ')}`,
+                'rsu-post-restart-failed'
+            );
+        } else {
+            await this.emitter.complete('RSU pipeline complete — entity maps created and sync started');
+        }
+    }
+}
+
+/**
+ * Owns the re-attachments for ONE pass of the post-restart pending-work queue.
+ *
+ * A single RSU batch registers one pending-work row per input, so several rows in one sweep can
+ * belong to the same run. Attaching per row would try to resume — and terminate — the same run
+ * repeatedly; the second attempt would be refused as already-terminal and its work would go
+ * unreported. Memoizing by run ID makes the run's stream a single coherent continuation, with one
+ * `run.resumed` at the top and one terminal event at the bottom.
+ */
+export class RSUPostRestartProgressSession {
+    private readonly byRunID = new Map<string, RSUPostRestartProgress>();
+    private readonly byCompanyIntegrationID = new Map<string, RSUPostRestartProgress | null>();
+    /**
+     * Every run any session in this process re-attached to. Process-wide on purpose: the startup
+     * sweep that left restart-killed runs in flight and the pass that resumes them live in
+     * different places, and the one question that joins them — "did anything pick this run up?" —
+     * must survive the resuming pass throwing halfway.
+     */
+    private static readonly attachedRunIDs = new Set<string>();
+    public static get AttachedRunIDs(): ReadonlySet<string> {
+        return RSUPostRestartProgressSession.attachedRunIDs;
+    }
+
+    constructor(private readonly emitterOptions: EmitterOptions = {}) {}
+
+    /**
+     * The continuation handle for a connection's RSU run, or null when there is nothing to continue
+     * (no in-flight run for that connection, or it was already finished).
+     *
+     * Null is a normal outcome, not an error: pending work can legitimately be processed on a boot
+     * whose run artifact has been pruned, or after a retry that already closed the run. The caller
+     * does its work either way — progress reporting never gates the work itself.
+     */
+    public async For(companyIntegrationID: string): Promise<RSUPostRestartProgress | null> {
+        const cached = this.byCompanyIntegrationID.get(companyIntegrationID);
+        if (cached !== undefined) return cached;
+
+        const attached = await this.attach(companyIntegrationID);
+        this.byCompanyIntegrationID.set(companyIntegrationID, attached);
+        return attached;
+    }
+
+    /** Terminates every run this session re-attached to. Safe to call more than once. */
+    public async FinishAll(): Promise<void> {
+        for (const progress of this.byRunID.values()) {
+            await progress.Finish().catch(err => LogError(`[RSU] post-restart terminal write failed for run ${progress.RunID}: ${err}`));
+        }
+    }
+
+    private async attach(companyIntegrationID: string): Promise<RSUPostRestartProgress | null> {
+        try {
+            const reader = new IntegrationProgressReader(this.emitterOptions.rootDir);
+            const candidates = await reader.ListRuns(
+                { runKind: 'RSU', companyIntegrationID, inFlightOnly: true },
+                CANDIDATE_RUN_WINDOW
+            );
+            // A run this session already picked up no longer LOOKS killed-at-the-restart — its latest
+            // event is now the `run.resumed` this session wrote. So an already-attached run must be
+            // matched first, or the second pending-work item of the same batch would find nothing to
+            // report into and its work would go unobserved.
+            const snapshot = candidates.find(s => this.byRunID.has(s.manifest.runID))
+                ?? candidates.find(RSUPostRestartProgressSession.WasKilledAtRestart);
+            if (!snapshot) return null;
+
+            const runID = snapshot.manifest.runID;
+            const existing = this.byRunID.get(runID);
+            if (existing) return existing;
+
+            const checkpoint = await reader.LatestCheckpoint(runID);
+            const emitter = await IntegrationProgressEmitter.Resume(runID, this.emitterOptions);
+            emitter.RunResumed(
+                `Resumed after the RSU restart — continuing with ${RuntimeSchemaManager.EXPECTED_STEPS_POST_RESTART.join(' then ')}`,
+                { companyIntegrationID }
+            );
+            const progress = new RSUPostRestartProgress(emitter, RSUPostRestartProgressSession.PositionFrom(checkpoint));
+            this.byRunID.set(runID, progress);
+            RSUPostRestartProgressSession.attachedRunIDs.add(runID);
+            LogStatus(`[RSU] Re-attached to run ${runID} for connection ${companyIntegrationID}`);
+            return progress;
+        } catch (err: unknown) {
+            // A run that is already terminal, or has no manifest, is not an error condition worth
+            // failing the actual work over — the work still has to happen, unobserved.
+            if (err instanceof IntegrationRunResumeError) {
+                LogStatus(`[RSU] Not resuming progress for ${companyIntegrationID}: ${err.message}`);
+                return null;
+            }
+            LogError(`[RSU] Could not re-attach progress for ${companyIntegrationID}: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+
+    /**
+     * Whether a run's stream stops at the restart — which is the signature of a run this process is
+     * the continuation of.
+     *
+     * Checking the LAST stage, not the presence of the checkpoint, on purpose. The checkpoint is
+     * written in the moments before the kill signal and can be lost; the `stage.start RestartMJAPI`
+     * that precedes it cannot, because the pipeline waits on nothing between emitting it and dying.
+     * Requiring the checkpoint would trade a recoverable loss of step numbers for an unrecoverable
+     * loss of the whole continuation.
+     */
+    public static WasKilledAtRestart(snapshot: IntegrationRunSnapshot): boolean {
+        return snapshot.latestEvent?.stage === RESTART_STAGE;
+    }
+    /**
+     * Closes out the restart-killed runs the startup sweep left in flight that NO session then
+     * re-attached to — because there was no system user, or the pending work was stale and
+     * dropped, or it simply failed before reaching the run. Without this they would read as in
+     * flight forever, which is the state the sweep exists to end.
+     *
+     * Only the runs in `leftInFlight` (the sweep's `Skipped` list) are candidates: anything else
+     * in flight by now may be a run this process started, and is not ours to judge. A candidate
+     * a session attached to is live — its session terminates it — and is left alone.
+     */
+    public static async SweepUnattached(
+        leftInFlight: readonly string[],
+        rootDir?: string,
+        log: (message: string) => void = () => {},
+    ): Promise<{ Swept: string[]; Failed: string[]; Skipped: string[] }> {
+        if (leftInFlight.length === 0) return { Swept: [], Failed: [], Skipped: [] };
+        const candidates = new Set(leftInFlight);
+        return SweepInterruptedRuns(rootDir, log, snapshot => {
+            const runID = snapshot.manifest.runID;
+            return !candidates.has(runID) || RSUPostRestartProgressSession.attachedRunIDs.has(runID);
+        });
+    }
+
+    /** Reads the step position out of a restart checkpoint, tolerating a missing or partial one. */
+    public static PositionFrom(checkpoint: IntegrationProgressEvent | undefined): RestartPosition {
+        const state = checkpoint?.stage === RESTART_STAGE ? checkpoint.resumableState : undefined;
+        if (!state) return {};
+        const stepIndex = state.stepIndex;
+        const stepTotal = state.stepTotal;
+        return {
+            stepIndex: typeof stepIndex === 'number' ? stepIndex : undefined,
+            stepTotal: typeof stepTotal === 'number' ? stepTotal : undefined,
+        };
+    }
+}

package/src/integration/RSUProgressBridge.ts

@@ -24,6 +24,13 @@ import { BaseSingleton } from '@memberjunction/global';
 /** The emitter stage name used for run-level (non-step) events. */
 const RUN_STAGE = 'RSUPipeline';
 
+/**
+ * The pipeline step that kills this process. Named here because BOTH sides of the restart use it:
+ * this bridge closes the stage and checkpoints under it, and the post-restart consumer recognises a
+ * run as resumable by finding it as the run's last stage.
+ */
+export const RESTART_STAGE = 'RestartMJAPI';
+
 /**
  * How often an in-flight step reports that it is still alive.
  *
@@ -53,6 +60,15 @@ export class RSUProgressBridge extends BaseSingleton<RSUProgressBridge> {
     private currentRunID: string | null = null;
     /** Liveness timer for the step currently in flight — see {@link HEARTBEAT_INTERVAL_MS}. */
     private heartbeat: ReturnType<typeof setInterval> | null = null;
+    /**
+     * The stage the live heartbeat belongs to, held on the INSTANCE rather than only captured in
+     * the timer closure. A closure-only stage name is a leak waiting to happen: a timer that
+     * outlives its step (or its whole run) keeps firing with the name it was created with, and
+     * writes that stale name into whatever emitter the bridge is pointing at by then. Comparing the
+     * tick's captured name against this field makes that structurally impossible — a stopped or
+     * superseded heartbeat writes nothing.
+     */
+    private heartbeatStage: string | null = null;
     private emitterOptions: EmitterOptions = {};
 
     /** The one bridge for this process. */
@@ -96,8 +112,14 @@ export class RSUProgressBridge extends BaseSingleton<RSUProgressBridge> {
         this.currentRunID = null;
     }
 
-    /** The observer to hand to {@link RuntimeSchemaManager.PipelineObserver}. */
-    public readonly Observe = (event: RSUObserverEvent): void => {
+    /**
+     * The observer to hand to {@link RuntimeSchemaManager.PipelineObserver}.
+     *
+     * Returns a promise ONLY for `restart.pending` — the pipeline awaits that one (bounded) because
+     * the process is about to be killed and an unflushed write would be lost. Every other event
+     * stays fire-and-forget.
+     */
+    public readonly Observe = (event: RSUObserverEvent): void | Promise<void> => {
         switch (event.Kind) {
             case 'run.start':
                 return this.onRunStart(event);
@@ -105,24 +127,76 @@ export class RSUProgressBridge extends BaseSingleton<RSUProgressBridge> {
                 return this.onStepStart(event);
             case 'step.end':
                 return this.onStepEnd(event);
+            case 'restart.pending':
+                return this.onRestartPending(event);
             case 'run.end':
                 return this.onRunEnd(event);
         }
     };
 
+    /**
+     * Closes the `RestartMJAPI` stage and writes the checkpoint the next process re-attaches from,
+     * then FLUSHES — the caller awaits this, and pm2 kills the process moments later.
+     *
+     * Two separate things are written here, and they matter for different reasons:
+     *
+     *  - the `stage.complete` for `RestartMJAPI`, because `step.end` for that step is unreachable
+     *    (the process dies inside the step), so without it the stream ends on an open stage and a
+     *    determinate stepper stalls one short of the restart;
+     *  - the `checkpoint`, carrying the step position and the pending-work correlation, so the
+     *    consumer on the other side can resume the stepper where this process left it.
+     *
+     * The checkpoint is deliberately NOT the consumer's only way back to this run. Re-attachment
+     * keys off the MANIFEST — written minutes earlier, when the run opened — precisely because this
+     * write is the one racing a kill signal. If it is lost the run is still found and still
+     * resumed; only the step indices degrade to defaults.
+     */
+    private async onRestartPending(event: Extract<RSUObserverEvent, { Kind: 'restart.pending' }>): Promise<void> {
+        this.stopHeartbeat();
+        const emitter = this.emitter;
+        if (!emitter) return;
+        emitter.stageComplete(RESTART_STAGE);
+        emitter.checkpoint(RESTART_STAGE, {
+            runID: emitter.RunID,
+            remainingSteps: event.RemainingSteps,
+            stepIndex: event.StepIndex,
+            stepTotal: event.StepTotal,
+            companyIntegrationIDs: event.CompanyIntegrationIDs,
+            pendingWorkIDs: event.PendingWorkIDs,
+            migrationTotalCount: event.TotalCount,
+            migrationSuccessCount: event.SuccessCount,
+        });
+        // A failed flush must not stop the restart — the pipeline swallows this, but say so.
+        await emitter.flush().catch(err => LogError(`RSUProgressBridge: pre-restart flush failed — ${err}`));
+    }
+
     private onRunStart(event: Extract<RSUObserverEvent, { Kind: 'run.start' }>): void {
+        // Unconditional, and BEFORE the emitter check below. Stopping the previous run's liveness
+        // timer must not be reachable only via `closeCurrent`, whose call is gated on there being
+        // an emitter — that gate is the one path on which a live heartbeat could survive into the
+        // next run and stamp the previous run's stage name onto it.
+        this.stopHeartbeat();
         // A retry re-enters RunPipelineBatch, so it legitimately starts a NEW run. If a previous
         // emitter is still open (a throw escaped before run.end), close it rather than leak it.
         if (this.emitter) this.closeCurrent('Superseded by a new RSU run');
 
         const runID = IntegrationProgressEmitter.newRunID('rsu');
         this.currentRunID = runID;
+        const companyIntegrationIDs = event.CompanyIntegrationIDs ?? [];
         this.emitter = new IntegrationProgressEmitter(
             {
                 runID,
                 runKind: 'RSU',
                 triggerType: 'Pipeline',
                 startedAt: new Date().toISOString(),
+                // The run's IDENTITY, and the reason an RSU run is readable over the API at all: the
+                // run-artifact authorization check tests the caller against the connections on the
+                // manifest, and an RSU manifest never carried any. The plural field is the whole set
+                // (a batch may span connections); the singular one is populated ONLY for a
+                // single-connection run, so everything that reports "the" connection of a run keeps
+                // reporting one unambiguous answer rather than an arbitrary member of a set.
+                companyIntegrationIDs,
+                companyIntegrationID: companyIntegrationIDs.length === 1 ? companyIntegrationIDs[0] : undefined,
                 context: {
                     itemCount: event.ItemCount,
                     descriptions: event.Descriptions,
@@ -195,7 +269,12 @@ export class RSUProgressBridge extends BaseSingleton<RSUProgressBridge> {
     private startHeartbeat(stage: string): void {
         this.stopHeartbeat();
         const startedAt = Date.now();
+        this.heartbeatStage = stage;
         this.heartbeat = setInterval(() => {
+            // Guard on the INSTANCE's current stage, not just the captured one. A tick that fires
+            // after the heartbeat was stopped, or after a different step/run took over, must not
+            // write this step's name into someone else's stream.
+            if (this.heartbeatStage !== stage) return;
             const elapsedSec = Math.round((Date.now() - startedAt) / 1000);
             this.emitter?.heartbeat(stage, `${stage} still running — ${elapsedSec}s elapsed`);
         }, HEARTBEAT_INTERVAL_MS);
@@ -205,6 +284,10 @@ export class RSUProgressBridge extends BaseSingleton<RSUProgressBridge> {
 
     /** Stops the liveness timer. Safe to call when none is running. */
     private stopHeartbeat(): void {
+        // Deliberately unconditional on the stage: clearing the name is what disarms a tick that is
+        // already queued on the event loop, so it must happen even when there is no timer handle
+        // left to clear.
+        this.heartbeatStage = null;
         if (!this.heartbeat) return;
         clearInterval(this.heartbeat);
         this.heartbeat = null;

package/src/integration/RunArtifactAuthorization.ts

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Who may read an integration run artifact.
+ *
+ * A security boundary, kept in its own module so the rule is stated once, testable on its own, and
+ * not buried among a resolver's several thousand lines.
+ */
+import { IntegrationProgressReader } from '@memberjunction/integration-progress-artifacts';
+import type { IntegrationRunManifest } from '@memberjunction/integration-progress-artifacts';
+
+/**
+ * Answers "may the calling user read this one connection?".
+ *
+ * Supplied by the resolver, which implements it as a `RunView` on `MJ: Company Integrations` under
+ * the CALLER's context — so the data provider applies the same row-level security it applies to
+ * every other user-context read, and no row coming back means unauthorized.
+ */
+export type CompanyIntegrationReadCheck = (companyIntegrationID: string) => Promise<boolean>;
+
+/** The verdict, carrying the connection that blocked it so a denial can name it. */
+export interface RunArtifactAuthorizationResult {
+    Authorized: boolean;
+    /** The first connection the caller could not read. Absent when the run has no identity at all. */
+    DeniedCompanyIntegrationID?: string;
+}
+
+/**
+ * Authorizes a caller for a run artifact against EVERY connection the run touched.
+ *
+ * ── The rule ───────────────────────────────────────────────────────────────────────────────────
+ * A run is readable only if the caller is authorized for ALL of its connections. Not any — all.
+ *
+ * Most runs touch exactly one connection and the rule collapses to the obvious check. But a schema
+ * update (RSU) run is a BATCH: the pipeline takes N inputs, and those inputs may legitimately
+ * belong to different connectors. A run artifact is one undivided event stream — its migration
+ * descriptions, affected table names and error messages interleave every connection in the batch,
+ * and there is no mechanism to serve a caller a partial view of it. "Authorized for any one of
+ * them" would therefore hand connection A's schema-change descriptions to a user who only holds
+ * rights on connection B. AND is the only rule that cannot leak; a cross-tenant batch simply
+ * becomes readable to nobody but a caller holding rights to both, which is the correct conservative
+ * answer rather than a silent disclosure.
+ *
+ * A run with NO connection identity is denied: non-tenant-scoped artifacts are not exposed through
+ * the per-company endpoints, and that must not change as a side effect of runs gaining a set.
+ *
+ * Short-circuits on the first denial, so an unauthorized caller cannot use the number of permission
+ * lookups to probe which connections a run covers.
+ */
+export async function AuthorizeRunArtifact(
+    manifest: IntegrationRunManifest,
+    canReadCompanyIntegration: CompanyIntegrationReadCheck
+): Promise<RunArtifactAuthorizationResult> {
+    // Reads the SET, not the singular field: a batch spanning connections leaves the singular field
+    // deliberately empty, and testing only that would make such a run look connection-less — and so
+    // unreadable to everyone, including its rightful owner.
+    const companyIntegrationIDs = IntegrationProgressReader.CompanyIntegrationIDsFor(manifest);
+    if (companyIntegrationIDs.length === 0) {
+        return { Authorized: false };
+    }
+    for (const companyIntegrationID of companyIntegrationIDs) {
+        if (!await canReadCompanyIntegration(companyIntegrationID)) {
+            return { Authorized: false, DeniedCompanyIntegrationID: companyIntegrationID };
+        }
+    }
+    return { Authorized: true };
+}

package/src/integration/SchemaRefreshLaunch.ts

@@ -30,6 +30,15 @@ export interface SchemaRefreshSummaryLike {
     FailureMessage?: string;
     ObjectsCreated: number;
     ObjectsUpdated: number;
+    /**
+     * FIELD counts, not an optional nicety: a connector whose objects are PRESUPPOSED (declared in
+     * its own metadata) creates no objects on any run, so the object counts of a refresh that
+     * created 69 fields and updated 487 are "0 and 0" — which reads as "the refresh found nothing".
+     * Both counts were already carried on the pipeline result; only this type stopped them reaching
+     * the sentence.
+     */
+    FieldsCreated: number;
+    FieldsUpdated: number;
     UnresolvedObjects: string[];
 }
 
@@ -38,8 +47,9 @@ function describeFinishedRefresh(summary: SchemaRefreshSummaryLike): string {
     if (!summary.Succeeded) {
         return `schema refresh FAILED (${summary.FailureMessage ?? 'no reason reported'}) — see run ${summary.RunID}`;
     }
-    return `schema refresh: ${summary.ObjectsCreated} created, ` +
-        `${summary.ObjectsUpdated} updated, ${summary.UnresolvedObjects.length} PK-unresolved`;
+    return `schema refresh: ${summary.ObjectsCreated} objects created, ` +
+        `${summary.ObjectsUpdated} updated, ${summary.FieldsCreated} fields created, ` +
+        `${summary.FieldsUpdated} updated, ${summary.UnresolvedObjects.length} PK-unresolved`;
 }
 
 /**