@memberjunction/testing-integration 0.0.0 → 5.50.0

package/dist/ai-verify.js

@@ -0,0 +1,137 @@
+/**
+ * ai-verify.ts — deep persistence verifiers for the live-model integration tier (§8 prerequisite).
+ *
+ * Lifted verbatim from integration-test-scripts/lib/ai-bootstrap.ts so the graduated live-model bundles
+ * (prompt-runner, agent-runner, concurrent) read them from the package instead of the tsx harness. After a
+ * real prompt/agent run, these fetch the persisted records and assert the OUTPUT is correct — AI Prompt
+ * Runs, AI Agent Runs, AI Agent Run Steps (each terminal + CompletedAt set, never stuck at 'Running'), and
+ * the Action Execution Logs / child runs the steps point at via TargetLogID. This is the live end-to-end
+ * regression guard for the fire-and-forget BaseEntitySaveQueue.
+ *
+ * `settle` (the fire-and-forget landing delay) lives in test-runner.ts and is re-exported from the barrel.
+ */
+import { RunView } from '@memberjunction/core';
+import { Assert } from './test-runner.js';
+/** Truly-finished states whose row MUST carry a CompletedAt (the save-queue finalize guarantee). */
+const TERMINAL = new Set(['Completed', 'Failed', 'Cancelled']);
+/** An agent run "ran without error" if it completed or intentionally suspended (awaiting feedback/paused). */
+const RAN_OK = new Set(['Completed', 'AwaitingFeedback', 'Paused']);
+/** Fixed inter-attempt delay (ms) for the bounded poll. */
+const FETCH_POLL_INTERVAL_MS = 500;
+/** Default total poll budget (ms). Overridable per-run via MJ_IT_FETCH_POLL_MS for loaded boxes. */
+const FETCH_POLL_DEFAULT_BUDGET_MS = 12000;
+/** Resolve the poll budget from MJ_IT_FETCH_POLL_MS (positive finite ms), else the default. */
+function resolveFetchPollBudgetMs() {
+    const raw = Number(process.env.MJ_IT_FETCH_POLL_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : FETCH_POLL_DEFAULT_BUDGET_MS;
+}
+/** Fetches a single row by ID via the real RunView pipeline (BypassCache = true DB state), asserting one match. */
+async function fetchById(entity, id, user) {
+    // Bounded poll: the rows this verifies (Action Execution Logs, child AI Prompt Runs) are
+    // written by the agent loop's FIRE-AND-FORGET save queue, which can land AFTER the run
+    // handle returns — especially under the fast server-in-process transport. A single-shot read
+    // raced that write (agent-loop-live AL2). Budget is MJ_IT_FETCH_POLL_MS-tunable (default 12s).
+    const attempts = Math.max(1, Math.round(resolveFetchPollBudgetMs() / FETCH_POLL_INTERVAL_MS));
+    // The bound we ACTUALLY wait is attempts × interval, which can differ from the nominal env
+    // budget when it isn't a multiple of the interval (e.g. 700ms → 1 attempt → 500ms) — report
+    // the real bound, not the configured one.
+    const budgetMs = attempts * FETCH_POLL_INTERVAL_MS;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        const result = await new RunView().RunView({ EntityName: entity, ExtraFilter: `ID='${id}'`, ResultType: 'simple', BypassCache: true }, user);
+        Assert(result.Success, `RunView('${entity}') failed: ${result.ErrorMessage}`);
+        if (result.Results.length === 1) {
+            return result.Results[0];
+        }
+        if (result.Results.length > 1) {
+            Assert(false, `${entity} ${id}: expected 1 row, got ${result.Results.length}`);
+        }
+        await new Promise(r => setTimeout(r, FETCH_POLL_INTERVAL_MS));
+    }
+    // NOT a claim of data loss: on a loaded box (MJAPI + runner + SQL Server co-hosted) the
+    // fire-and-forget write commonly commits just after the window closes (verified in the v5.49.0
+    // build: the rows landed, the poll simply closed first). State the bound and name the knob.
+    Assert(false, `${entity} ${id} not found within ${budgetMs}ms bounded poll — the fire-and-forget write may still be in flight on a loaded box; raise MJ_IT_FETCH_POLL_MS (and consider AGENT_LIVE_SETTLE_MS for the pre-poll settle)`);
+    throw new Error('unreachable');
+}
+/**
+ * Verifies an `MJ: AI Prompt Runs` row finalized correctly: terminal Status, **CompletedAt set** (the
+ * "stuck at Running" guard the save queue prevents), and on success a non-empty Result + recorded timing.
+ */
+export async function verifyPromptRun(promptRunID, user) {
+    const row = await fetchById('MJ: AI Prompt Runs', promptRunID, user);
+    Assert(TERMINAL.has(String(row.Status)), `Prompt run ${promptRunID}: non-terminal Status '${row.Status}' (stuck at Running?)`);
+    Assert(row.CompletedAt != null, `Prompt run ${promptRunID}: CompletedAt is null while Status='${row.Status}' (finalize save lost)`);
+    if (row.Success === true) {
+        Assert(row.Result != null && String(row.Result).length > 0, `Prompt run ${promptRunID}: succeeded but Result is empty`);
+        Assert(Number(row.ExecutionTimeMS) > 0, `Prompt run ${promptRunID}: succeeded but ExecutionTimeMS not recorded`);
+    }
+    return row;
+}
+/** Verifies an `MJ: Action Execution Logs` row finalized: **EndedAt set** + a ResultCode recorded. */
+export async function verifyActionLog(logID, user) {
+    const row = await fetchById('MJ: Action Execution Logs', logID, user);
+    Assert(row.EndedAt != null, `Action log ${logID}: EndedAt is null (stuck 'Running' — the action-log finalize bug class)`);
+    Assert(row.ResultCode != null && String(row.ResultCode).length > 0, `Action log ${logID}: no ResultCode recorded`);
+    return row;
+}
+/**
+ * Deep-verifies an agent run end to end: the `MJ: AI Agent Runs` header, every `MJ: AI Agent Run Steps`
+ * row (each terminal + CompletedAt set — never stuck at Running), and the records each step points at via
+ * TargetLogID — Prompt steps → AI Prompt Runs, Actions/Tool steps → Action Execution Logs, Sub-Agent steps
+ * → child AI Agent Runs (recursively). `expectSuccess` asserts the run reached 'Completed'.
+ */
+export async function verifyAgentRun(agentRunID, user, expectSuccess = true, opts = {}) {
+    const run = await fetchById('MJ: AI Agent Runs', agentRunID, user);
+    const status = String(run.Status);
+    // The actual "stuck at Running" guard: a finalized run is anything except still-Running.
+    Assert(status !== 'Running', `Agent run ${agentRunID}: still 'Running' (never finalized — the stuck-at-Running bug)`);
+    // CompletedAt is required only for the truly-done states; AwaitingFeedback/Paused legitimately suspend without it.
+    if (TERMINAL.has(status)) {
+        Assert(run.CompletedAt != null, `Agent run ${agentRunID}: CompletedAt is null while Status='${status}' (finalize save lost)`);
+    }
+    if (expectSuccess) {
+        Assert(RAN_OK.has(status), `Agent run ${agentRunID}: expected Completed/AwaitingFeedback/Paused, got '${status}' (${run.ErrorMessage ?? ''})`);
+    }
+    const stepsResult = await new RunView().RunView({
+        EntityName: 'MJ: AI Agent Run Steps',
+        ExtraFilter: `AgentRunID='${agentRunID}'`,
+        OrderBy: 'StepNumber',
+        ResultType: 'simple',
+        BypassCache: true,
+    }, user);
+    Assert(stepsResult.Success, `RunView agent run steps failed: ${stepsResult.ErrorMessage}`);
+    const steps = stepsResult.Results;
+    let promptRunsVerified = 0;
+    let actionLogsVerified = 0;
+    let subAgentRunsVerified = 0;
+    for (const step of steps) {
+        const label = `${step.StepType}/${step.StepName ?? ''}`;
+        // The save-queue guarantee: every step must have finalized, never stuck at Running.
+        Assert(TERMINAL.has(String(step.Status)), `Agent run ${agentRunID} step '${label}': non-terminal Status '${step.Status}' (stuck at Running)`);
+        Assert(step.CompletedAt != null, `Agent run ${agentRunID} step '${label}': CompletedAt is null while Status='${step.Status}' (the exact stuck-at-Running bug)`);
+        const target = step.TargetLogID ? String(step.TargetLogID) : null;
+        if (!target) {
+            continue;
+        }
+        if (step.StepType === 'Prompt') {
+            await verifyPromptRun(target, user);
+            promptRunsVerified++;
+        }
+        else if (step.StepType === 'Actions' || step.StepType === 'Tool') {
+            // Action Execution Logs are written by the fire-and-forget queue and can land
+            // arbitrarily late relative to a run handle returning (esp. server-in-process).
+            // Callers that only care about run/step terminality pass skipActionLogs.
+            if (opts.skipActionLogs) {
+                continue;
+            }
+            await verifyActionLog(target, user);
+            actionLogsVerified++;
+        }
+        else if (step.StepType === 'Sub-Agent') {
+            await verifyAgentRun(target, user, false); // child success is the child's own concern
+            subAgentRunsVerified++;
+        }
+    }
+    return { run, stepCount: steps.length, promptRunsVerified, actionLogsVerified, subAgentRunsVerified };
+}
+//# sourceMappingURL=ai-verify.js.map

package/dist/ai-verify.js.map

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

package/dist/bootstrap-client.d.ts

@@ -0,0 +1,11 @@
+import '@memberjunction/core-entities';
+import { type IntegrationClientContext } from './bootstrap-shared.js';
+/**
+ * Client (GraphQL) bootstrap — installs the instrumented cache as FIRST caller, then
+ * configures `GraphQLDataProvider` against a separately-running MJAPI (reachable via
+ * MJ_API_KEY + the resolved URL). Idempotent within a process. Browser-faithful: the
+ * process registers only CLIENT entity subclasses (via the `@memberjunction/core-entities`
+ * import above), never the server ones.
+ */
+export declare function bootstrapIntegrationClient(): Promise<IntegrationClientContext>;
+//# sourceMappingURL=bootstrap-client.d.ts.map

package/dist/bootstrap-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-client.d.ts","sourceRoot":"","sources":["../src/bootstrap-client.ts"],"names":[],"mappings":"AAmBA,OAAO,+BAA+B,CAAC;AAGvC,OAAO,EAOH,KAAK,wBAAwB,EAChC,MAAM,oBAAoB,CAAC;AAE5B;;;;;;GAMG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,wBAAwB,CAAC,CA2CpF"}

package/dist/bootstrap-client.js

@@ -0,0 +1,68 @@
+/**
+ * bootstrap-client.ts — the CLIENT (GraphQL) integration bootstrap.
+ *
+ * This module is server-FREE by construction: it imports only client-safe packages —
+ * exactly what a real browser client (e.g. MJExplorer) loads: `@memberjunction/core`,
+ * `@memberjunction/graphql-dataprovider`, and `@memberjunction/core-entities` (the CLIENT
+ * generated entity subclasses). It must NEVER import `@memberjunction/sqlserver-dataprovider`
+ * or `@memberjunction/server-bootstrap-lite` (those register server-only `*EntityServer`
+ * subclasses whose constructors throw on a client provider — a real browser has none of them).
+ *
+ * A client dispatcher should import `bootstrapIntegrationClient` from HERE (the package's
+ * `./client` subpath export), NOT from the package barrel — the barrel evaluates every
+ * bundle's check file, which transitively pulls in server packages.
+ */
+import { LocalCacheManager, InMemoryLocalStorageProvider } from '@memberjunction/core';
+import { setupGraphQLClient, GraphQLProviderConfigData } from '@memberjunction/graphql-dataprovider';
+// Side-effect import: registers the CLIENT generated entity subclasses on the ClassFactory,
+// exactly as a browser client does. This is the client-faithful analog to the server's
+// `@memberjunction/server-bootstrap-lite` — NOT that package.
+import '@memberjunction/core-entities';
+import { InstrumentedLocalStorageProvider } from './instrumented-cache.js';
+import { LoadEnv, LoadClientConfig } from './config.js';
+import { assertOwnsProcess, getActiveIntegrationStorage, preflightMJAPI, getActiveIntegrationClientBootstrap, _setActiveStorage, _setCurrentClientBootstrap } from './bootstrap-shared.js';
+/**
+ * Client (GraphQL) bootstrap — installs the instrumented cache as FIRST caller, then
+ * configures `GraphQLDataProvider` against a separately-running MJAPI (reachable via
+ * MJ_API_KEY + the resolved URL). Idempotent within a process. Browser-faithful: the
+ * process registers only CLIENT entity subclasses (via the `@memberjunction/core-entities`
+ * import above), never the server ones.
+ */
+export async function bootstrapIntegrationClient() {
+    const existing = getActiveIntegrationClientBootstrap();
+    if (existing) {
+        return existing;
+    }
+    LoadEnv();
+    // Under `mj test` the CLI installs the instrumented cache as this process's FIRST caller
+    // (installInstrumentedCacheFirst, before its own provider spins up). That pre-claimed,
+    // INSTRUMENTED cache satisfies the ownership invariant — every cache read/write is already
+    // counted — so reuse it rather than refusing. Only a cache initialized by someone ELSE
+    // (e.g. co-hosted inside a live MJAPI) is grounds for refusal.
+    const preInstalled = getActiveIntegrationStorage();
+    if (!preInstalled) {
+        assertOwnsProcess();
+    }
+    const client = LoadClientConfig();
+    // Preflight BEFORE mutating cache/provider state — a dead MJAPI fails fast and clearly.
+    await preflightMJAPI(client.Url, client.MJAPIKey);
+    let storage;
+    if (preInstalled) {
+        storage = preInstalled;
+    }
+    else {
+        storage = new InstrumentedLocalStorageProvider(new InMemoryLocalStorageProvider());
+        await LocalCacheManager.Instance.Initialize(storage, { verboseLogging: false });
+        _setActiveStorage(storage);
+    }
+    const config = new GraphQLProviderConfigData('', // JWT token — unused; the system API key authenticates us
+    client.Url, client.WsUrl, // wsurl — required by the RO-3 wire-progress subscription (RemoteOperationProgress)
+    async () => '', // refreshTokenFunction — stub; API key auth never refreshes
+    '__mj', undefined, undefined, client.MJAPIKey // mjAPIKey → sent as x-mj-api-key on every request
+    );
+    await setupGraphQLClient(config);
+    const ctx = { Storage: storage, Client: client };
+    _setCurrentClientBootstrap(ctx);
+    return ctx;
+}
+//# sourceMappingURL=bootstrap-client.js.map

package/dist/bootstrap-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-client.js","sourceRoot":"","sources":["../src/bootstrap-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,iBAAiB,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AACrG,4FAA4F;AAC5F,uFAAuF;AACvF,8DAA8D;AAC9D,OAAO,+BAA+B,CAAC;AACvC,OAAO,EAAE,gCAAgC,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,EACH,iBAAiB,EACjB,2BAA2B,EAC3B,cAAc,EACd,mCAAmC,EACnC,iBAAiB,EACjB,0BAA0B,EAE7B,MAAM,oBAAoB,CAAC;AAE5B;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B;IAC5C,MAAM,QAAQ,GAAG,mCAAmC,EAAE,CAAC;IACvD,IAAI,QAAQ,EAAE,CAAC;QACX,OAAO,QAAQ,CAAC;IACpB,CAAC;IACD,OAAO,EAAE,CAAC;IACV,yFAAyF;IACzF,uFAAuF;IACvF,2FAA2F;IAC3F,uFAAuF;IACvF,+DAA+D;IAC/D,MAAM,YAAY,GAAG,2BAA2B,EAAE,CAAC;IACnD,IAAI,CAAC,YAAY,EAAE,CAAC;QAChB,iBAAiB,EAAE,CAAC;IACxB,CAAC;IACD,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC;IAClC,wFAAwF;IACxF,MAAM,cAAc,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAElD,IAAI,OAAyC,CAAC;IAC9C,IAAI,YAAY,EAAE,CAAC;QACf,OAAO,GAAG,YAAY,CAAC;IAC3B,CAAC;SAAM,CAAC;QACJ,OAAO,GAAG,IAAI,gCAAgC,CAAC,IAAI,4BAA4B,EAAE,CAAC,CAAC;QACnF,MAAM,iBAAiB,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;QAChF,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,yBAAyB,CACxC,EAAE,EAAkB,0DAA0D;IAC9E,MAAM,CAAC,GAAG,EACV,MAAM,CAAC,KAAK,EAAQ,oFAAoF;IACxG,KAAK,IAAI,EAAE,CAAC,EAAE,EAAM,4DAA4D;IAChF,MAAM,EACN,SAAS,EACT,SAAS,EACT,MAAM,CAAC,QAAQ,CAAK,mDAAmD;KAC1E,CAAC;IACF,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAEjC,MAAM,GAAG,GAA6B,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC3E,0BAA0B,CAAC,GAAG,CAAC,CAAC;IAChC,OAAO,GAAG,CAAC;AACf,CAAC"}

package/dist/bootstrap-shared.d.ts

@@ -0,0 +1,94 @@
+/**
+ * bootstrap-shared.ts — the server-FREE core shared by both integration bootstrap paths.
+ *
+ * This module deliberately imports ONLY client-safe packages (`@memberjunction/core`,
+ * local config/cache). It must NOT import `@memberjunction/sqlserver-dataprovider`,
+ * `@memberjunction/server-bootstrap-lite`, or any other server package — so that the
+ * CLIENT bootstrap (`bootstrap-client.ts`) can be imported by a client dispatcher WITHOUT
+ * dragging server-only entity subclasses into the process. A real browser client never
+ * loads those; loading them here would make a "client" test a server/client hybrid whose
+ * ClassFactory resolves server-only `*EntityServer` subclasses (which throw on the client).
+ *
+ * The process-global handoff state lives here (one integration run owns its process,
+ * CANONICAL D) so BOTH the server bootstrap and the client bootstrap — and the driver's
+ * `getActiveIntegrationStorage()` reader — observe the same install.
+ */
+import type * as sql from 'mssql';
+import type { UserInfo, IMetadataProvider } from '@memberjunction/core';
+import { InstrumentedLocalStorageProvider } from './instrumented-cache.js';
+import type { DbConfig, ClientConfig } from './config.js';
+/** Everything a server-side check/driver needs about the owned process. */
+export interface IntegrationBootstrapContext {
+    /**
+     * The mssql connection pool — present on SQL Server, undefined on PostgreSQL.
+     * Checks that issue raw `sql.Request(pool)` queries are SQL-Server-only; use
+     * ClosePool() to release the underlying connection on either backend.
+     */
+    Pool?: sql.ConnectionPool;
+    User: UserInfo;
+    /** The instrumented cache wrapper installed as LocalCacheManager's storage provider. */
+    Storage: InstrumentedLocalStorageProvider;
+    /** The run-scoped provider (the SQLServerDataProvider / PostgreSQLDataProvider this bootstrap set up). */
+    Provider: IMetadataProvider;
+    Db: DbConfig;
+    /** Releases the underlying DB connection platform-agnostically (mssql pool.close() / pg pool.end()). */
+    ClosePool(): Promise<void>;
+}
+/** Result of the client (GraphQL) bootstrap. */
+export interface IntegrationClientContext {
+    Storage: InstrumentedLocalStorageProvider;
+    Client: ClientConfig;
+}
+export interface BootstrapServerOptions {
+    /** Optional context-user override (else Owner-type, else Users[0]). Mirrors MJ_TEST_USER_EMAIL. */
+    ContextUserEmail?: string;
+    /** Verbose cache logging (default false). */
+    VerboseCacheLogging?: boolean;
+}
+/** @internal Setters used by the server/client bootstrap modules to publish process state. */
+export declare function _setActiveStorage(s: InstrumentedLocalStorageProvider): void;
+export declare function _setCurrentServerBootstrap(c: IntegrationBootstrapContext): void;
+export declare function _setCurrentClientBootstrap(c: IntegrationClientContext): void;
+/**
+ * The instrumented storage installed in this process (by any path), or null if none.
+ * The IntegrationTestDriver reads this to get the cache counters without re-bootstrapping.
+ */
+export declare function getActiveIntegrationStorage(): InstrumentedLocalStorageProvider | null;
+/**
+ * True when a server-transport integration run cannot own this process: no instrumented
+ * cache was installed first AND the cache is already initialized by another component
+ * (e.g. a serving MJAPI whose StartupManager claimed it). This is exactly the condition
+ * under which `bootstrapIntegrationServer()` would throw `assertOwnsProcess` — exposed so
+ * the driver can fail fast with a dashboard-friendly message instead of a bootstrap stack.
+ */
+export declare function serverProcessAlreadyClaimed(): boolean;
+/** The full server bootstrap context (with owned Pool), or null if not server-bootstrapped. */
+export declare function getActiveIntegrationBootstrap(): IntegrationBootstrapContext | null;
+/** The client (GraphQL) bootstrap context, or null if not client-bootstrapped in this process. */
+export declare function getActiveIntegrationClientBootstrap(): IntegrationClientContext | null;
+/**
+ * Fail fast with a clear message when MJAPI isn't reachable, before any cache or
+ * provider state is mutated. Used by both the driver (via bootstrapIntegrationClient)
+ * and the tsx scripts so they preflight identically.
+ */
+export declare function preflightMJAPI(url: string, apiKey: string): Promise<void>;
+/**
+ * Refuse to run an owning bootstrap when the cache is already initialized by some
+ * other component. SetStorageProvider is a destructive global mutation with no
+ * restore, so we never wedge instrumentation into a live host — we fail loudly.
+ */
+export declare function assertOwnsProcess(): void;
+/**
+ * Install the instrumented cache as the first caller WITHOUT owning the connection.
+ * For the testing-CLI path: call this BEFORE initializeMJProvider() so the CLI's
+ * own provider setup finds the cache already claimed (its StartupManager Initialize
+ * no-ops) and every cache read/write flows through the instrumented wrapper.
+ *
+ * Returns the instrumented storage, or null when the cache was ALREADY initialized
+ * by something else (can't instrument retroactively — the caller decides whether to
+ * proceed uninstrumented or abort).
+ */
+export declare function installInstrumentedCacheFirst(opts?: {
+    VerboseCacheLogging?: boolean;
+}): Promise<InstrumentedLocalStorageProvider | null>;
+//# sourceMappingURL=bootstrap-shared.d.ts.map

package/dist/bootstrap-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-shared.d.ts","sourceRoot":"","sources":["../src/bootstrap-shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,KAAK,GAAG,MAAM,OAAO,CAAC;AAElC,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAAE,gCAAgC,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEvD,2EAA2E;AAC3E,MAAM,WAAW,2BAA2B;IACxC;;;;OAIG;IACH,IAAI,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,wFAAwF;IACxF,OAAO,EAAE,gCAAgC,CAAC;IAC1C,0GAA0G;IAC1G,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,EAAE,EAAE,QAAQ,CAAC;IACb,wGAAwG;IACxG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,gDAAgD;AAChD,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,gCAAgC,CAAC;IAC1C,MAAM,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACnC,mGAAmG;IACnG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACjC;AAOD,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,gCAAgC,GAAG,IAAI,CAAuB;AACnG,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,2BAA2B,GAAG,IAAI,CAAgC;AAChH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,wBAAwB,GAAG,IAAI,CAAgC;AAE7G;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,gCAAgC,GAAG,IAAI,CAErF;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,IAAI,OAAO,CAErD;AAED,+FAA+F;AAC/F,wBAAgB,6BAA6B,IAAI,2BAA2B,GAAG,IAAI,CAElF;AAED,kGAAkG;AAClG,wBAAgB,mCAAmC,IAAI,wBAAwB,GAAG,IAAI,CAErF;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB/E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CASxC;AAED;;;;;;;;;GASG;AACH,wBAAsB,6BAA6B,CAAC,IAAI,GAAE;IAAE,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC,CAWlJ"}

package/dist/bootstrap-shared.js

@@ -0,0 +1,94 @@
+import { LocalCacheManager, InMemoryLocalStorageProvider } from '@memberjunction/core';
+import { InstrumentedLocalStorageProvider } from './instrumented-cache.js';
+// Process-global handoff state — one integration run owns its process (CANONICAL D).
+let activeStorage = null;
+let currentServerBootstrap = null;
+let currentClientBootstrap = null;
+/** @internal Setters used by the server/client bootstrap modules to publish process state. */
+export function _setActiveStorage(s) { activeStorage = s; }
+export function _setCurrentServerBootstrap(c) { currentServerBootstrap = c; }
+export function _setCurrentClientBootstrap(c) { currentClientBootstrap = c; }
+/**
+ * The instrumented storage installed in this process (by any path), or null if none.
+ * The IntegrationTestDriver reads this to get the cache counters without re-bootstrapping.
+ */
+export function getActiveIntegrationStorage() {
+    return activeStorage;
+}
+/**
+ * True when a server-transport integration run cannot own this process: no instrumented
+ * cache was installed first AND the cache is already initialized by another component
+ * (e.g. a serving MJAPI whose StartupManager claimed it). This is exactly the condition
+ * under which `bootstrapIntegrationServer()` would throw `assertOwnsProcess` — exposed so
+ * the driver can fail fast with a dashboard-friendly message instead of a bootstrap stack.
+ */
+export function serverProcessAlreadyClaimed() {
+    return !activeStorage && LocalCacheManager.Instance.IsInitialized;
+}
+/** The full server bootstrap context (with owned Pool), or null if not server-bootstrapped. */
+export function getActiveIntegrationBootstrap() {
+    return currentServerBootstrap;
+}
+/** The client (GraphQL) bootstrap context, or null if not client-bootstrapped in this process. */
+export function getActiveIntegrationClientBootstrap() {
+    return currentClientBootstrap;
+}
+/**
+ * Fail fast with a clear message when MJAPI isn't reachable, before any cache or
+ * provider state is mutated. Used by both the driver (via bootstrapIntegrationClient)
+ * and the tsx scripts so they preflight identically.
+ */
+export async function preflightMJAPI(url, apiKey) {
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'x-mj-api-key': apiKey },
+            body: JSON.stringify({ query: '{ __typename }' }),
+            signal: AbortSignal.timeout(5000)
+        });
+    }
+    catch (error) {
+        throw new Error(`MJAPI is not reachable at ${url} (${error instanceof Error ? error.message : String(error)}). ` +
+            `Start it first: cd packages/MJAPI && npm run start`);
+    }
+    if (!response.ok) {
+        throw new Error(`MJAPI at ${url} answered HTTP ${response.status} — check MJ_API_KEY and server logs.`);
+    }
+}
+/**
+ * Refuse to run an owning bootstrap when the cache is already initialized by some
+ * other component. SetStorageProvider is a destructive global mutation with no
+ * restore, so we never wedge instrumentation into a live host — we fail loudly.
+ */
+export function assertOwnsProcess() {
+    if (LocalCacheManager.Instance.IsInitialized) {
+        throw new Error('Integration bootstrap must own its process — LocalCacheManager is already initialized by another component. ' +
+            'When running via `mj test run`/`mj test suite`, set MJ_INTEGRATION_TEST=1 so the CLI installs the instrumented ' +
+            'cache as the first caller (before its own provider setup). Otherwise run in a dedicated process and never ' +
+            'co-host the integration test inside a serving MJAPI.');
+    }
+}
+/**
+ * Install the instrumented cache as the first caller WITHOUT owning the connection.
+ * For the testing-CLI path: call this BEFORE initializeMJProvider() so the CLI's
+ * own provider setup finds the cache already claimed (its StartupManager Initialize
+ * no-ops) and every cache read/write flows through the instrumented wrapper.
+ *
+ * Returns the instrumented storage, or null when the cache was ALREADY initialized
+ * by something else (can't instrument retroactively — the caller decides whether to
+ * proceed uninstrumented or abort).
+ */
+export async function installInstrumentedCacheFirst(opts = {}) {
+    if (activeStorage) {
+        return activeStorage;
+    }
+    if (LocalCacheManager.Instance.IsInitialized) {
+        return null;
+    }
+    const storage = new InstrumentedLocalStorageProvider(new InMemoryLocalStorageProvider());
+    await LocalCacheManager.Instance.Initialize(storage, { verboseLogging: opts.VerboseCacheLogging ?? false });
+    activeStorage = storage;
+    return storage;
+}
+//# sourceMappingURL=bootstrap-shared.js.map

package/dist/bootstrap-shared.js.map

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

package/dist/bootstrap.d.ts

@@ -0,0 +1,14 @@
+import { type IntegrationBootstrapContext, type BootstrapServerOptions } from './bootstrap-shared.js';
+import '@memberjunction/server-bootstrap-lite';
+export * from './bootstrap-shared.js';
+/**
+ * Own the process: install the instrumented cache as FIRST caller, then set up the
+ * data provider for the configured backend (SQL Server by default, PostgreSQL when
+ * DB_PLATFORM=postgresql) and resolve the context user. Idempotent within a process.
+ * THROWS if the cache is already initialized by a different component (see assertOwnsProcess).
+ *
+ * The instrumented-cache-first ordering is identical on both backends — the cache
+ * singleton is platform-agnostic. Only the provider setup differs, behind db.Platform.
+ */
+export declare function bootstrapIntegrationServer(opts?: BootstrapServerOptions): Promise<IntegrationBootstrapContext>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAyBA,OAAO,EAKH,KAAK,2BAA2B,EAChC,KAAK,sBAAsB,EAC9B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,uCAAuC,CAAC;AAG/C,cAAc,oBAAoB,CAAC;AAkCnC;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,CAAC,IAAI,GAAE,sBAA2B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAoBxH"}

package/dist/bootstrap.js

@@ -0,0 +1,133 @@
+/**
+ * bootstrap.ts — the SERVER (in-process) integration bootstrap.
+ *
+ * This module owns the SERVER transport: it connects directly to the database
+ * (SQL Server / PostgreSQL) and imports `@memberjunction/server-bootstrap-lite` to
+ * register the server generated entity subclasses. It is therefore server-laden by
+ * design — a CLIENT dispatcher must NOT import it (import `bootstrapIntegrationClient`
+ * from `./bootstrap-client` / the package's `./client` subpath instead, which loads
+ * only client packages).
+ *
+ * The load-bearing invariant (D1): the InstrumentedLocalStorageProvider MUST be
+ * installed as the FIRST caller of `LocalCacheManager.Instance.Initialize(...)` —
+ * before any provider setup (`setupSQLServerClient`) — or instrumentation is a silent
+ * no-op (`Initialize` is first-caller-wins). The process-global handoff state and the
+ * shared client-safe helpers (preflightMJAPI, assertOwnsProcess, installInstrumented-
+ * CacheFirst, the getActive* accessors, the interfaces) live in `./bootstrap-shared`
+ * so both this module and the client bootstrap publish/read the same install.
+ */
+import sql from 'mssql';
+import { LocalCacheManager, InMemoryLocalStorageProvider, Metadata, SetProvider } from '@memberjunction/core';
+import { setupSQLServerClient, SQLServerProviderConfigData, UserCache } from '@memberjunction/sqlserver-dataprovider';
+import { InstrumentedLocalStorageProvider } from './instrumented-cache.js';
+import { LoadEnv, LoadDbConfig } from './config.js';
+import { assertOwnsProcess, getActiveIntegrationBootstrap, _setActiveStorage, _setCurrentServerBootstrap } from './bootstrap-shared.js';
+// Side-effect import: registers the SERVER generated entity subclasses on the ClassFactory
+// so entity_object results materialize as real (server) BaseEntity instances.
+import '@memberjunction/server-bootstrap-lite';
+// Re-export the shared surface so existing barrel consumers keep working unchanged.
+export * from './bootstrap-shared.js';
+/** Resolve the context user: MJ_TEST_USER_EMAIL override → Owner-type → first user. */
+function resolveContextUser(email) {
+    const wanted = email?.toLowerCase();
+    const users = UserCache.Instance.Users;
+    const user = (wanted ? users.find(u => u.Email?.toLowerCase() === wanted) : undefined)
+        ?? users.find(u => u?.Type?.trim().toLowerCase() === 'owner')
+        ?? users[0];
+    if (!user) {
+        throw new Error('No context user found in UserCache. Set MJ_TEST_USER_EMAIL or ensure the Users table is populated.');
+    }
+    return user;
+}
+/**
+ * Resolve the context user on the PostgreSQL path. UserCache (mssql-only Refresh) is
+ * not populated on PG, so this surfaces the missing PG-aware user bootstrap as a clear,
+ * actionable error (the Phase-0 prerequisite) instead of fabricating a user.
+ */
+function resolvePostgresContextUser(email) {
+    const users = UserCache.Instance.Users ?? [];
+    if (users.length === 0) {
+        throw new Error('PostgreSQL integration bootstrap: no context user is available. UserCache.Refresh is ' +
+            'mssql-only, so PG needs a PG-aware user-cache bootstrap before the integration suites can ' +
+            'run against it (tracked Phase-0 prerequisite — plan §10 Step 6). The provider was configured ' +
+            'successfully; only user resolution is blocked.');
+    }
+    return resolveContextUser(email);
+}
+/**
+ * Own the process: install the instrumented cache as FIRST caller, then set up the
+ * data provider for the configured backend (SQL Server by default, PostgreSQL when
+ * DB_PLATFORM=postgresql) and resolve the context user. Idempotent within a process.
+ * THROWS if the cache is already initialized by a different component (see assertOwnsProcess).
+ *
+ * The instrumented-cache-first ordering is identical on both backends — the cache
+ * singleton is platform-agnostic. Only the provider setup differs, behind db.Platform.
+ */
+export async function bootstrapIntegrationServer(opts = {}) {
+    const existing = getActiveIntegrationBootstrap();
+    if (existing) {
+        return existing;
+    }
+    LoadEnv();
+    // Fail fast on mis-host BEFORE reading config — never wedge instrumentation into a live cache.
+    assertOwnsProcess();
+    const db = await LoadDbConfig();
+    // FIRST-CALLER cache init — MUST precede any provider setup (load-bearing on both backends).
+    const storage = new InstrumentedLocalStorageProvider(new InMemoryLocalStorageProvider());
+    await LocalCacheManager.Instance.Initialize(storage, { verboseLogging: opts.VerboseCacheLogging ?? false });
+    _setActiveStorage(storage);
+    const ctx = db.Platform === 'postgresql'
+        ? await setupPostgreSQLProvider(db, storage, opts)
+        : await setupSqlServerProvider(db, storage, opts);
+    _setCurrentServerBootstrap(ctx);
+    return ctx;
+}
+/** SQL Server provider setup — the locally-proven path (unchanged behavior). */
+async function setupSqlServerProvider(db, storage, opts) {
+    // Dedicated mssql pool (encrypt:false, trustServerCertificate:true — harness parity).
+    const pool = await new sql.ConnectionPool({
+        server: db.Host,
+        port: db.Port,
+        user: db.User,
+        password: db.Password,
+        database: db.Database,
+        options: { encrypt: false, trustServerCertificate: true }
+    }).connect();
+    await setupSQLServerClient(new SQLServerProviderConfigData(pool, db.Schema));
+    await UserCache.Instance.Refresh(pool);
+    const user = resolveContextUser(opts.ContextUserEmail);
+    return {
+        Pool: pool, User: user, Storage: storage, Provider: Metadata.Provider, Db: db, // global-provider-ok: this dedicated-process bootstrap just installed the one global provider (setupSQLServerClient) — it IS the single provider for this run (D1)
+        ClosePool: async () => { await pool.close(); }
+    };
+}
+/**
+ * PostgreSQL provider setup — runs the SAME downstream check code against a PG backend
+ * (the PG parity lane, D5.5). PG is an OPTIONAL backend: the provider (and its `pg`
+ * dependency) is dynamically imported so it stays out of the default dependency graph
+ * for SQL-Server-only consumers (CLAUDE.md rule #8 category 2; declared in optionalDependencies).
+ *
+ * NOTE (Phase-0 prerequisite, see plan §10 Step 6): there is no PG-aware user-cache
+ * bootstrap yet — `UserCache.Refresh` is mssql-only (raw `sql.Request`), and a fresh
+ * provider has no users loaded to seed a RunView-based load. This helper sets up the
+ * real provider, then resolves the context user from whatever is already cached; if
+ * nothing is, it throws a clear, actionable error rather than fabricating a user. The
+ * PG parity CI lane is therefore non-blocking until that framework gap is closed.
+ */
+async function setupPostgreSQLProvider(db, storage, opts) {
+    const { PostgreSQLDataProvider, PostgreSQLProviderConfigData } = await import('@memberjunction/postgresql-dataprovider');
+    const provider = new PostgreSQLDataProvider();
+    const pgConfig = new PostgreSQLProviderConfigData({ Host: db.Host, Port: db.Port, Database: db.Database, User: db.User, Password: db.Password }, db.Schema, 1 // checkRefreshIntervalSeconds > 0 → load metadata on Config
+    );
+    await provider.Config(pgConfig);
+    SetProvider(provider);
+    const user = resolvePostgresContextUser(opts.ContextUserEmail);
+    return {
+        Pool: undefined, User: user, Storage: storage, Provider: Metadata.Provider, Db: db, // global-provider-ok: this dedicated-process bootstrap just installed the one global provider (SetProvider above) — it IS the single provider for this run (D1)
+        ClosePool: async () => {
+            const pgPool = provider.DatabaseConnection;
+            await pgPool?.end?.();
+        }
+    };
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/bootstrap.js.map

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