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

package/src/__tests__/RSUProgressBridge.test.ts

@@ -0,0 +1,250 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtempSync, rmSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { RSUProgressBridge } from '../integration/RSUProgressBridge.js';
+import type { RSUObserverEvent } from '@memberjunction/schema-engine';
+import type { IntegrationProgressEvent, IntegrationRunManifest, IntegrationRunResult } from '@memberjunction/integration-progress-artifacts';
+
+/**
+ * The bridge is what makes an RSU run tailable: `IntegrationRunKind` has always had an 'RSU' kind
+ * and the resolver has always mapped it to an 'RSU' subscription channel, but nothing published to
+ * it. These tests drive the observer with the events the pipeline emits and assert the durable
+ * artifact that comes out — reading the real JSONL, not a mocked emitter, because the artifact IS
+ * the deliverable.
+ */
+describe('RSUProgressBridge', () => {
+    let rootDir: string;
+    let bridge: RSUProgressBridge;
+
+    beforeEach(() => {
+        rootDir = mkdtempSync(join(tmpdir(), 'rsu-bridge-'));
+        // The bridge is a BaseSingleton, so every test in this file shares ONE instance. Reset()
+        // returns it to idle (dropping an emitter or heartbeat a prior test left in flight) and
+        // Configure() repoints artifacts at this test's temp dir. Without both, one test's in-flight
+        // run would be inherited by the next and its writes would land in a deleted directory.
+        bridge = RSUProgressBridge.Instance;
+        bridge.Reset();
+        bridge.Configure({ rootDir });
+    });
+
+    afterEach(async () => {
+        // Drain FIRST. The emitter writes through chained promises, and `Reset()` only drops this
+        // bridge's reference to it — it cannot cancel a write already queued. A test that starts a run
+        // without awaiting `settle()` would otherwise have its manifest.json land after the rmSync
+        // below, surfacing as an unhandled ENOENT that fails the suite while every test still reports
+        // as passing. Then Reset, so no heartbeat interval outlives the test or keeps the process up.
+        await settle();
+        bridge.Reset();
+        rmSync(rootDir, { recursive: true, force: true });
+    });
+
+    const RUN_START: RSUObserverEvent = {
+        Kind: 'run.start',
+        ItemCount: 2,
+        Descriptions: ['add Orders', 'add OrderItems'],
+        AffectedTables: ['Orders', 'OrderItems'],
+        StepTotal: 12,
+    };
+
+    /** The emitter's writes are chained promises; let them drain before reading from disk. */
+    async function settle(): Promise<void> {
+        await new Promise(resolve => setTimeout(resolve, 50));
+    }
+
+    function runDir(): string {
+        return join(rootDir, bridge.CurrentRunID ?? '');
+    }
+
+    function readEvents(dir: string): IntegrationProgressEvent[] {
+        return readFileSync(join(dir, 'progress.jsonl'), 'utf-8')
+            .split('\n')
+            .filter(Boolean)
+            .map(line => JSON.parse(line) as IntegrationProgressEvent);
+    }
+
+    it('is a singleton, so a resolver can reach the in-flight run to tail it', async () => {
+        // The point of the singleton. Previously the bridge was constructed inside
+        // RegisterRSUProgressBridge and the only surviving reference was the observer closure handed
+        // to RuntimeSchemaManager -- so CurrentRunID, whose whole purpose is letting a caller that
+        // triggered an RSU hand its client a run to tail, was unreachable from any caller.
+        expect(RSUProgressBridge.Instance).toBe(bridge);
+
+        bridge.Observe(RUN_START);
+        expect(RSUProgressBridge.Instance.CurrentRunID).toBe(bridge.CurrentRunID);
+        expect(RSUProgressBridge.Instance.CurrentRunID).toMatch(/^rsu-/);
+        await settle();
+    });
+
+    it('Reset returns the bridge to idle without emitting a terminal event', async () => {
+        bridge.Observe(RUN_START);
+        expect(bridge.CurrentRunID).not.toBeNull();
+        await settle();
+
+        bridge.Reset();
+
+        // Idle again, and the next run starts clean rather than inheriting the abandoned emitter.
+        expect(bridge.CurrentRunID).toBeNull();
+    });
+
+    it('opens a run tagged RSU carrying the batch context, and exposes its ID to tail', async () => {
+        bridge.Observe(RUN_START);
+        const dir = runDir();
+        expect(bridge.CurrentRunID).toMatch(/^rsu-/);
+        await settle();
+
+        const manifest = JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf-8')) as IntegrationRunManifest;
+        // The run kind is what routes this onto the 'RSU' subscription channel.
+        expect(manifest.runKind).toBe('RSU');
+        expect(manifest.triggerType).toBe('Pipeline');
+        expect(manifest.context).toMatchObject({
+            itemCount: 2,
+            affectedTables: ['Orders', 'OrderItems'],
+            stepTotal: 12,
+        });
+
+        const events = readEvents(dir);
+        expect(events[0].eventType).toBe('run.start');
+        expect(events[0].message).toContain('2 migration(s)');
+    });
+
+    it('records each step as a stage, with its position in the determinate sequence', async () => {
+        bridge.Observe(RUN_START);
+        const dir = runDir();
+        bridge.Observe({ Kind: 'step.start', Name: 'RunCodeGen', StepIndex: 4, StepTotal: 12 });
+        bridge.Observe({ Kind: 'step.end', Name: 'RunCodeGen', Status: 'success', DurationMs: 91_000, Message: 'ok' });
+        await settle();
+
+        const events = readEvents(dir);
+        const start = events.find(e => e.eventType === 'stage.start' && e.stage === 'RunCodeGen');
+        const done = events.find(e => e.eventType === 'stage.complete' && e.stage === 'RunCodeGen');
+
+        expect(start?.message).toBe('step 4 of 12');
+        expect(done).toBeDefined();
+        // Steps are not a countable unit — counts belong to migrations, emitted once at run end.
+        expect(done?.counts).toBeUndefined();
+    });
+
+    it('records a failed step as a stage error without terminating the run', async () => {
+        bridge.Observe(RUN_START);
+        const dir = runDir();
+        bridge.Observe({
+            Kind: 'step.end',
+            Name: 'ExecuteMigration',
+            Status: 'failed',
+            DurationMs: 120,
+            Message: 'FK violation on Orders',
+        });
+        await settle();
+
+        const err = readEvents(dir).find(e => e.eventType === 'stage.error');
+        expect(err?.stage).toBe('ExecuteMigration');
+        expect(err?.message).toBe('FK violation on Orders');
+        expect(err?.data).toMatchObject({ code: 'RSU_STEP_FAILED' });
+        // A per-item failure does not abort the batch, so the run must still be open.
+        expect(existsSync(join(dir, 'result.json'))).toBe(false);
+        expect(bridge.CurrentRunID).not.toBeNull();
+    });
+
+    it('completes the run with the migration quartet as the authoritative counts', async () => {
+        bridge.Observe(RUN_START);
+        const dir = runDir();
+        bridge.Observe({ Kind: 'run.end', Success: true, SuccessCount: 2, FailureCount: 0, TotalCount: 2 });
+        await settle();
+
+        const result = JSON.parse(readFileSync(join(dir, 'result.json'), 'utf-8')) as IntegrationRunResult;
+        expect(result.success).toBe(true);
+        expect(result.exitReason).toBe('completed');
+        // Counts are in MIGRATIONS (2), not steps.
+        expect(result.aggregateCounts).toMatchObject({ processed: 2, succeeded: 2, failed: 0 });
+        // Idle again — nothing to tail.
+        expect(bridge.CurrentRunID).toBeNull();
+    });
+
+    it('fails the run naming the step that broke it', async () => {
+        bridge.Observe(RUN_START);
+        const dir = runDir();
+        bridge.Observe({
+            Kind: 'run.end',
+            Success: false,
+            SuccessCount: 1,
+            FailureCount: 1,
+            TotalCount: 2,
+            ErrorMessage: 'FK violation on Orders',
+            ErrorStep: 'ExecuteMigration',
+        });
+        await settle();
+
+        const result = JSON.parse(readFileSync(join(dir, 'result.json'), 'utf-8')) as IntegrationRunResult;
+        expect(result.success).toBe(false);
+        expect(result.exitReason).toBe('failed');
+        expect(result.errors?.[0].message).toContain('ExecuteMigration');
+        expect(result.errors?.[0].message).toContain('FK violation on Orders');
+        expect(result.errors?.[0].code).toBe('rsu-pipeline-failed');
+    });
+
+    it('treats a second run.start as a NEW run and closes the abandoned one', async () => {
+        // RunPipelineBatchWithRetry re-enters the pipeline, so a retry legitimately starts a fresh
+        // run. What must not happen is the previous run staying in-flight forever.
+        bridge.Observe(RUN_START);
+        const firstDir = runDir();
+        bridge.Observe(RUN_START);
+        const secondDir = runDir();
+        await settle();
+
+        expect(secondDir).not.toBe(firstDir);
+        const abandoned = JSON.parse(readFileSync(join(firstDir, 'result.json'), 'utf-8')) as IntegrationRunResult;
+        expect(abandoned.success).toBe(false);
+        expect(abandoned.errors?.[0].code).toBe('rsu-run-abandoned');
+        // The new run is open and untouched by the abandonment.
+        expect(existsSync(join(secondDir, 'result.json'))).toBe(false);
+    });
+
+    it('reports liveness while a long step is in flight, and stops at step.end', async () => {
+        // CodeGen and compile run for minutes with no intermediate observer event. Without a
+        // heartbeat the stream goes silent for the whole step and a watcher cannot distinguish
+        // "compiling" from "hung".
+        vi.useFakeTimers();
+        try {
+            bridge.Observe(RUN_START);
+            const dir = runDir();
+            bridge.Observe({ Kind: 'step.start', Name: 'CodeGen', StepIndex: 5, StepTotal: 12 });
+
+            vi.advanceTimersByTime(95_000); // three 30s ticks
+            bridge.Observe({ Kind: 'step.end', Name: 'CodeGen', Status: 'success', DurationMs: 95_000, Message: 'ok' });
+            vi.advanceTimersByTime(120_000); // no further ticks once the step closed
+
+            vi.useRealTimers();
+            await settle();
+
+            const beats = readEvents(dir).filter(e => e.eventType === 'progress.heartbeat');
+            expect(beats).toHaveLength(3);
+            expect(beats[0].stage).toBe('CodeGen');
+            expect(beats[0].message).toMatch(/still running/);
+        } finally {
+            vi.useRealTimers();
+        }
+    });
+
+    it('does not drop the position label for a zero-based step index', async () => {
+        // `stepIndex && stepTotal` would silently omit the label at index 0.
+        bridge.Observe(RUN_START);
+        const dir = runDir();
+        bridge.Observe({ Kind: 'step.start', Name: 'ValidateEnvironment', StepIndex: 0, StepTotal: 12 });
+        await settle();
+
+        const start = readEvents(dir).find(e => e.stage === 'ValidateEnvironment');
+        expect(start?.message).toBe('step 0 of 12');
+    });
+
+    it('ignores step and run.end events that arrive with no run open', async () => {
+        // Defensive: an observer registered mid-run would see a trailing run.end for a run it never
+        // saw start. That must be a no-op, not a crash.
+        expect(() => {
+            bridge.Observe({ Kind: 'step.start', Name: 'AcquireLock' });
+            bridge.Observe({ Kind: 'step.end', Name: 'AcquireLock', Status: 'success', DurationMs: 1, Message: 'ok' });
+            bridge.Observe({ Kind: 'run.end', Success: true, SuccessCount: 1, FailureCount: 0, TotalCount: 1 });
+        }).not.toThrow();
+        expect(bridge.CurrentRunID).toBeNull();
+    });
+});

package/src/__tests__/ReactivateRefreshMessage.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from 'vitest';
+import { BuildReactivateMessage } from '../integration/SchemaRefreshLaunch.js';
+import type { SchemaRefreshSummaryLike } from '../integration/SchemaRefreshLaunch.js';
+
+/**
+ * Reactivation is committed BEFORE the refresh runs, so no refresh outcome — running, failed, or
+ * clean — may ever read as "resume didn't work". These pin that, plus the two reporting bugs the
+ * create/update paths already fixed and reactivate had kept its own copy of:
+ *
+ *   1. A detached run's placeholder zeros must not be reported as findings ("0 created, 0 updated"
+ *      tells an operator the source had nothing new, when in fact nothing has been looked at yet).
+ *   2. A pipeline that fails RETURNS with every count at zero rather than throwing, so counts alone
+ *      read identically to a clean no-op run.
+ */
+function summary(over: Partial<SchemaRefreshSummaryLike> = {}): SchemaRefreshSummaryLike {
+    return {
+        RunID: 'connector-1783000000000-abc123',
+        InProgress: false,
+        Succeeded: true,
+        ObjectsCreated: 12,
+        ObjectsUpdated: 3,
+        UnresolvedObjects: ['Widgets'],
+        ...over,
+    };
+}
+
+describe('BuildReactivateMessage', () => {
+    it('leads with the reactivation on every path', () => {
+        const paths = [
+            BuildReactivateMessage(undefined),
+            BuildReactivateMessage(summary({ InProgress: true, ObjectsCreated: 0, ObjectsUpdated: 0, UnresolvedObjects: [] })),
+            BuildReactivateMessage(summary()),
+            BuildReactivateMessage(summary({ Succeeded: false, FailureMessage: 'boom' })),
+        ];
+        for (const msg of paths) expect(msg).toMatch(/^Reactivated/);
+    });
+
+    it('names the run to tail — and reports NO counts — for a detached refresh', () => {
+        const msg = BuildReactivateMessage(summary({
+            InProgress: true,
+            ObjectsCreated: 0,
+            ObjectsUpdated: 0,
+            UnresolvedObjects: [],
+        }));
+
+        expect(msg).toContain('connector-1783000000000-abc123');
+        expect(msg).toMatch(/running/i);
+        expect(msg).not.toMatch(/\d+ created/);
+        expect(msg).not.toMatch(/\d+ updated/);
+        expect(msg).not.toMatch(/PK-unresolved/);
+    });
+
+    it('reports real counts when the caller asked to block', () => {
+        const msg = BuildReactivateMessage(summary());
+        expect(msg).toContain('12 created');
+        expect(msg).toContain('3 updated');
+        expect(msg).toContain('1 PK-unresolved');
+        expect(msg).not.toMatch(/running/i);
+    });
+
+    it('never reports a FAILED refresh as a zero-count success', () => {
+        // The old inline message formatted counts unconditionally, so a pipeline that failed at
+        // ConnectionTest produced "Reactivated, schema refresh: 0 created, 0 updated,
+        // 0 PK-unresolved" — indistinguishable from a source with nothing new.
+        const msg = BuildReactivateMessage(summary({
+            Succeeded: false,
+            FailureMessage: 'ConnectionTest failed: No Totara credentials found',
+            ObjectsCreated: 0,
+            ObjectsUpdated: 0,
+            UnresolvedObjects: [],
+        }));
+
+        expect(msg).toMatch(/FAILED/);
+        expect(msg).toContain('No Totara credentials found');
+        expect(msg).not.toMatch(/0 created/);
+        // ...and still says the connection is active, because it is.
+        expect(msg).toMatch(/^Reactivated/);
+    });
+
+    it('says nothing about a refresh that was never requested', () => {
+        const msg = BuildReactivateMessage(undefined);
+        expect(msg).toBe('Reactivated');
+        expect(msg).not.toMatch(/refresh/i);
+    });
+});

package/src/__tests__/RealtimeBridgeResolver.test.ts

@@ -17,11 +17,19 @@ const h = vi.hoisted(() => ({
   stopRecording: vi.fn(async () => ({ EgressID: 'eg-1', RoomName: 'room-1', Status: 'EGRESS_COMPLETE' })),
 }));
 
+// These two are instantiated with `new` by the resolver, so they must be constructible. They were
+// `vi.fn(() => ({...}))`, which vitest 3 tolerated as a constructor but vitest 4 rejects with
+// "is not a constructor" — classes express the intent and work under both.
 vi.mock('@memberjunction/livekit-room-server', () => ({
-  LiveKitTokenService: vi.fn(() => ({ MintClientToken: h.mintClientToken })),
+  LiveKitTokenService: class {
+    MintClientToken = h.mintClientToken;
+  },
   // SetSessionFactory is exercised by the resolver's module-load binding of the realtime-session factory.
   LiveKitAgentRoomCoordinator: { Instance: { StartAgentRoomSession: vi.fn(), SetSessionFactory: vi.fn() } },
-  LiveKitEgressService: vi.fn(() => ({ StartRoomRecording: h.startRecording, StopRecording: h.stopRecording })),
+  LiveKitEgressService: class {
+    StartRoomRecording = h.startRecording;
+    StopRecording = h.stopRecording;
+  },
 }));
 
 // Mock the agent factory so importing the resolver doesn't pull the heavy @memberjunction/ai-agents graph

package/src/__tests__/ResolverBase.filterEscaping.test.ts

@@ -0,0 +1,147 @@
+// ResolverBase transitively pulls in type-graphql decorators, which need the
+// Reflect.metadata polyfill at import time.
+import 'reflect-metadata';
+import { describe, it, expect } from 'vitest';
+import type { DatabaseProviderBase, RunViewParams, RunViewResult, UserInfo } from '@memberjunction/core';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import type { UserPayload } from '../types.js';
+import type { RunViewByNameInput } from '../generic/RunViewResolver.js';
+import type { PubSubEngine } from 'type-graphql';
+
+/**
+ * Both of `ResolverBase`'s own filter builders interpolated client-supplied values into the
+ * `ExtraFilter` text they hand to `RunView`:
+ *
+ * - `findBy` — reachable through `UserByEmail`, `FileByName`, `UserViewsByName`, and the
+ *   other by-value single-record resolvers.
+ * - `RunViewByNameGeneric` — the inline `Name='<ViewName>'` lookup.
+ *
+ * `ExtraFilter` does pass through `SQLExpressionValidator`, which rejects stacked statements,
+ * `UNION`, comments and `WAITFOR` — so the residual exposure was a same-clause boolean
+ * tautology rather than arbitrary SQL. These tests pin the escaping that closes it, and the
+ * fail-closed rule on the unquoted (numeric/boolean) slot, where a string value would BE
+ * SQL with no quote to break out of.
+ */
+
+const ENTITY_NAME = 'MJ: Users';
+
+/** Captures what the resolver asked `RunView` for. */
+type Captured = { params: RunViewParams | null };
+
+/**
+ * Minimal provider: the entity/field metadata `findBy` reads, plus a `RunView` that records
+ * its params. `Sequence` stands in for a numeric field (`NeedsQuotes` is false only for
+ * Number and Boolean TS types).
+ */
+function fakeProvider(captured: Captured, rows: Record<string, unknown>[] = []): DatabaseProviderBase {
+    return {
+        Entities: [
+            {
+                Name: ENTITY_NAME,
+                Fields: [
+                    { Name: 'Email', NeedsQuotes: true },
+                    { Name: 'Name', NeedsQuotes: true },
+                    { Name: 'Sequence', NeedsQuotes: false },
+                    { Name: 'IsActive', NeedsQuotes: false },
+                ],
+            },
+            {
+                Name: 'MJ: User Views',
+                Fields: [{ Name: 'Name', NeedsQuotes: true }],
+            },
+        ],
+        RunView: async (params: RunViewParams): Promise<RunViewResult> => {
+            captured.params = params;
+            return { Success: true, Results: rows, RowCount: rows.length, TotalRowCount: rows.length, ErrorMessage: '' } as RunViewResult;
+        },
+    } as unknown as DatabaseProviderBase;
+}
+
+const fakeUser = () => ({ Email: 'tester@example.com' } as UserInfo);
+const fakePayload = () => ({ email: 'tester@example.com', userRecord: fakeUser() } as UserPayload);
+
+/** Reaches the protected `findBy`. */
+class Probe extends ResolverBase {
+    public FindBy(provider: DatabaseProviderBase, entity: string, params: Record<string, unknown>) {
+        return this.findBy(provider, entity, params, fakeUser());
+    }
+}
+
+describe('ResolverBase.findBy — ExtraFilter escaping', () => {
+    it('doubles a single quote in a quoted value', async () => {
+        const captured: Captured = { params: null };
+        await new Probe().FindBy(fakeProvider(captured), ENTITY_NAME, { Email: "o'brien@example.com" });
+
+        expect(captured.params?.ExtraFilter).toBe("Email = 'o''brien@example.com'");
+    });
+
+    it('renders a tautology attempt inert instead of terminating the literal', async () => {
+        const captured: Captured = { params: null };
+        // The payload closes the literal and appends its own predicate. Escaped, every quote
+        // it carries stays *inside* the literal, so the clause matches a (non-existent)
+        // address rather than every row.
+        await new Probe().FindBy(fakeProvider(captured), ENTITY_NAME, { Email: "x' OR '1'='1" });
+
+        expect(captured.params?.ExtraFilter).toBe("Email = 'x'' OR ''1''=''1'");
+        // Nothing outside the literal: exactly two unescaped quotes, the delimiters.
+        expect(captured.params?.ExtraFilter?.replace(/''/g, '')).toBe("Email = 'x OR 1=1'");
+    });
+
+    it('joins multiple params with AND, escaping each', async () => {
+        const captured: Captured = { params: null };
+        await new Probe().FindBy(fakeProvider(captured), ENTITY_NAME, { Email: "a'b", Name: "c'd" });
+
+        expect(captured.params?.ExtraFilter).toBe("Email = 'a''b' AND Name = 'c''d'");
+    });
+
+    it('leaves a genuinely numeric value unquoted', async () => {
+        const captured: Captured = { params: null };
+        await new Probe().FindBy(fakeProvider(captured), ENTITY_NAME, { Sequence: 42 });
+
+        expect(captured.params?.ExtraFilter).toBe('Sequence = 42');
+    });
+
+    it('rejects a string aimed at an unquoted (numeric) field rather than emitting it as SQL', async () => {
+        const captured: Captured = { params: null };
+        // There is no quote to escape in an unquoted slot — the value lands in the clause as
+        // SQL. The only safe handling is to refuse it.
+        await expect(
+            new Probe().FindBy(fakeProvider(captured), ENTITY_NAME, { Sequence: '1 OR 1=1' })
+        ).rejects.toThrow(/Sequence/);
+
+        expect(captured.params).toBeNull(); // never reached RunView
+    });
+
+    it('rejects a non-finite number in an unquoted field', async () => {
+        const captured: Captured = { params: null };
+        await expect(
+            new Probe().FindBy(fakeProvider(captured), ENTITY_NAME, { Sequence: Number.NaN })
+        ).rejects.toThrow(/Sequence/);
+    });
+
+    it('still rejects an unknown field name', async () => {
+        // Pre-existing behavior, pinned so the escaping rework cannot quietly drop it.
+        await expect(
+            new Probe().FindBy(fakeProvider({ params: null }), ENTITY_NAME, { NotAField: 'x' })
+        ).rejects.toThrow(/NotAField/);
+    });
+});
+
+describe('ResolverBase.RunViewByNameGeneric — view-name escaping', () => {
+    it('escapes the client-supplied view name', async () => {
+        const captured: Captured = { params: null };
+        const input = { ViewName: "My View' OR '1'='1" } as RunViewByNameInput;
+
+        // Empty Results short-circuits the method (returns null) once the lookup filter is built.
+        const result = await new Probe().RunViewByNameGeneric(
+            input,
+            fakeProvider(captured),
+            fakePayload(),
+            undefined as unknown as PubSubEngine // unused: the empty-result path returns before it is passed on
+        );
+
+        expect(result).toBeNull();
+        expect(captured.params?.EntityName).toBe('MJ: User Views');
+        expect(captured.params?.ExtraFilter).toBe("Name='My View'' OR ''1''=''1'");
+    });
+});

package/src/__tests__/SchemaRefreshLaunch.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from 'vitest';
+import { BuildCreateConnectionMessage, BuildDetachedRefreshMessage, BuildUpdateConnectionMessage } from '../integration/SchemaRefreshLaunch.js';
+import type { SchemaRefreshSummaryLike } from '../integration/SchemaRefreshLaunch.js';
+
+/**
+ * A detached schema refresh returns placeholder zero counts because it hasn't run yet. The one
+ * thing this message must never do is report those zeros as findings — "0 created, 0 updated"
+ * reads as "the refresh found nothing", which is the opposite of "still running".
+ */
+function summary(over: Partial<SchemaRefreshSummaryLike> = {}): SchemaRefreshSummaryLike {
+    return {
+        RunID: 'connector-1783000000000-abc123',
+        InProgress: false,
+        Succeeded: true,
+        ObjectsCreated: 12,
+        ObjectsUpdated: 3,
+        UnresolvedObjects: ['Widgets'],
+        ...over,
+    };
+}
+
+describe('BuildCreateConnectionMessage', () => {
+    it('reports the run ID to tail — and NO counts — for a detached refresh', () => {
+        const msg = BuildCreateConnectionMessage(true, summary({
+            InProgress: true,
+            ObjectsCreated: 0,
+            ObjectsUpdated: 0,
+            UnresolvedObjects: [],
+        }));
+
+        expect(msg).toContain('connector-1783000000000-abc123');
+        expect(msg).toMatch(/running/i);
+        // The placeholder zeros must not surface as results.
+        expect(msg).not.toMatch(/\d+ created/);
+        expect(msg).not.toMatch(/\d+ updated/);
+        expect(msg).not.toMatch(/PK-unresolved/);
+    });
+
+    it('reports real counts once the refresh has completed inline', () => {
+        const msg = BuildCreateConnectionMessage(true, summary());
+
+        expect(msg).toContain('12 created');
+        expect(msg).toContain('3 updated');
+        expect(msg).toContain('1 PK-unresolved');
+        expect(msg).not.toMatch(/running/i);
+        // A completed refresh needs no run ID in the message — the counts ARE the answer.
+        expect(msg).not.toContain('connector-1783000000000-abc123');
+    });
+
+    it('omits the test-passed clause when no connection test was requested', () => {
+        expect(BuildCreateConnectionMessage(false, summary())).not.toMatch(/test passed/);
+        expect(BuildCreateConnectionMessage(true, summary())).toMatch(/test passed/);
+    });
+
+    it('falls back to the test-only message when no refresh was requested', () => {
+        expect(BuildCreateConnectionMessage(true, undefined)).toBe('Connection created and test passed');
+    });
+
+    it('counts PK-unresolved objects, not just reports presence', () => {
+        const msg = BuildCreateConnectionMessage(false, summary({ UnresolvedObjects: ['A', 'B', 'C'] }));
+        expect(msg).toContain('3 PK-unresolved');
+    });
+});
+
+/**
+ * A pipeline that fails at ConnectionTest RETURNS — it does not throw — with every count at zero.
+ * Verified live: a real HubSpot refresh whose credential check failed produced
+ * "Updated, schema refresh: 0 created, 0 updated, 0 PK-unresolved", indistinguishable from a clean
+ * no-op run. These tests pin the distinction.
+ */
+describe('failed-refresh reporting', () => {
+    const failed = summary({
+        Succeeded: false,
+        FailureMessage: 'ConnectionTest failed: No HubSpot credentials found',
+        ObjectsCreated: 0,
+        ObjectsUpdated: 0,
+        UnresolvedObjects: [],
+    });
+
+    it('never reports a failed refresh as a zero-count success (create)', () => {
+        const msg = BuildCreateConnectionMessage(true, failed);
+        expect(msg).toMatch(/FAILED/);
+        expect(msg).toContain('No HubSpot credentials found');
+        expect(msg).not.toMatch(/0 created/);
+    });
+
+    it('never reports a failed refresh as a zero-count success (update)', () => {
+        const msg = BuildUpdateConnectionMessage(failed);
+        expect(msg).toMatch(/FAILED/);
+        expect(msg).toContain('No HubSpot credentials found');
+        expect(msg).not.toMatch(/0 created/);
+    });
+
+    it('points at the run when the pipeline reported no reason', () => {
+        const msg = BuildUpdateConnectionMessage(summary({ Succeeded: false, FailureMessage: undefined }));
+        expect(msg).toContain('connector-1783000000000-abc123');
+        expect(msg).toMatch(/no reason reported/);
+    });
+
+    it('still reports counts for a refresh that genuinely succeeded (update)', () => {
+        const msg = BuildUpdateConnectionMessage(summary());
+        expect(msg).toContain('12 created');
+        expect(msg).toContain('3 updated');
+        expect(msg).not.toMatch(/FAILED/);
+    });
+});
+
+describe('BuildDetachedRefreshMessage', () => {
+    it('names the run to tail', () => {
+        const msg = BuildDetachedRefreshMessage('connector-42-zz');
+        expect(msg).toContain('connector-42-zz');
+        expect(msg).toMatch(/running/i);
+    });
+});