@memberjunction/server 6.1.4 → 6.2.0-edge.1

package/src/generic/CacheInvalidationResolver.ts

@@ -119,7 +119,7 @@ export interface CacheInvalidationFilterContext {
  * roles, so this stays cheap enough to run per subscriber per event. It is not free: it runs for
  * every connected socket on every save, so keep it free of I/O.
  */
-export function cacheInvalidationFilter(data: {
+export function CacheInvalidationFilter(data: {
     payload: CacheInvalidationPayload;
     context: CacheInvalidationFilterContext | undefined;
 }): boolean {
@@ -151,13 +151,21 @@ export function cacheInvalidationFilter(data: {
     return entity.GetUserPermisions(user).CanRead;
 }
 
+/** @deprecated Use {@link CacheInvalidationFilter}. */
+export function cacheInvalidationFilter(data: {
+    payload: CacheInvalidationPayload;
+    context: CacheInvalidationFilterContext | undefined;
+}): boolean {
+  return CacheInvalidationFilter(data);
+}
+
 @Resolver()
 export class CacheInvalidationResolver {
     /**
      * Subscription that broadcasts cache invalidation events to connected clients, so cross-server
      * cache invalidation reaches browsers.
      *
-     * Delivery is filtered only by ENTITY-level read permission (see {@link cacheInvalidationFilter}).
+     * Delivery is filtered only by ENTITY-level read permission (see {@link CacheInvalidationFilter}).
      * Every session that may read an entity at all still receives every event for it, from every
      * other session and tenant.
      *
@@ -184,9 +192,9 @@ export class CacheInvalidationResolver {
     @Subscription(() => CacheInvalidationNotification, {
         topics: CACHE_INVALIDATION_TOPIC,
         filter: (data: { payload: CacheInvalidationPayload; context: CacheInvalidationFilterContext | undefined }) =>
-            cacheInvalidationFilter(data),
+            CacheInvalidationFilter(data),
     })
-    cacheInvalidation(
+    cacheInvalidation(  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
         @Root() payload: CacheInvalidationPayload
     ): CacheInvalidationNotification {
         return {

package/src/generic/FireAndForgetHeartbeat.ts

@@ -1,6 +1,6 @@
 import { PubSubEngine } from 'type-graphql';
 import { LogError } from '@memberjunction/core';
-import { publishStatusUpdate } from './PushStatusResolver.js';
+import { PublishStatusUpdate } from './PushStatusResolver.js';
 
 /** Default cadence for fire-and-forget liveness pulses (5 minutes). */
 export const DEFAULT_PULSE_INTERVAL_MS = 5 * 60 * 1000;
@@ -15,38 +15,38 @@ export const HEARTBEAT_MESSAGE_TYPE = 'Heartbeat';
  */
 export interface PulseStatus {
     /** Primary key of the persisted run record (AIAgentRun, TestRun, TestSuiteRun). */
-    runId?: string;
+    runId?: string;  // case-violation-ok-legacy-back-compat: optional, and the old name is also read off a value the checker cannot type; renaming it stays assignable and silently yields undefined
     /** Current run status, e.g. 'Running'. */
-    status?: string;
+    status?: string;  // case-violation-ok-legacy-back-compat: optional, and the old name is also read off a value the checker cannot type; renaming it stays assignable and silently yields undefined
     /** Optional human-readable current step for UI display. */
-    currentStep?: string;
+    currentStep?: string;  // case-violation-ok-legacy-back-compat: optional, and the old name is also read off a value the checker cannot type; renaming it stays assignable and silently yields undefined
 }
 
 /** Handle returned by {@link startLivenessPulse}; call `stop()` when the work settles. */
 export interface LivenessPulseHandle {
-    stop(): void;
+    Stop(): void;
 }
 
 export interface LivenessPulseOptions {
     /** PubSub engine used to publish on the shared push-status topic. */
-    pubSub: PubSubEngine;
+    pubSub: PubSubEngine;  // case-violation-ok-legacy-back-compat: renaming it broke a use the checker could not see from the declaration — the compile proved it
     /** Session the client is subscribed on (used by the subscription filter). */
-    sessionId: string;
+    sessionId: string;  // case-violation-ok-legacy-back-compat: the old name is also read off a value typed `any`, where a rename would compile and silently return undefined
     /**
      * Authenticated user the operation belongs to (B49). Stamped on every pulse so the
      * subscription filter binds delivery to identity, not just the client-chosen sessionId.
      */
-    ownerUserId: string;
+    ownerUserId: string;  // case-violation-ok-legacy-back-compat: renaming it broke a use the checker could not see from the declaration — the compile proved it
     /** Resolver label echoed in the message envelope (e.g. 'RunAIAgentResolver'). */
-    resolver: string;
+    resolver: string;  // case-violation-ok-legacy-back-compat: the old name is also read off a value typed `any`, where a rename would compile and silently return undefined
     /** Pulse cadence in ms. Defaults to {@link DEFAULT_PULSE_INTERVAL_MS}. */
-    intervalMs?: number;
+    intervalMs?: number;  // case-violation-ok-legacy-back-compat: renaming it broke a use the checker could not see from the declaration — the compile proved it
     /**
      * Optional cheap status reader invoked on each tick. Should read from an
      * in-memory ref, not the database. Errors are swallowed so a transient read
      * never kills the pulse loop.
      */
-    readStatus?: () => PulseStatus | undefined;
+    readStatus?: () => PulseStatus | undefined;  // case-violation-ok-legacy-back-compat: renaming it broke a use the checker could not see from the declaration — the compile proved it
 }
 
 /**
@@ -60,7 +60,7 @@ export interface LivenessPulseOptions {
  * (`{ message: JSON.stringify({ resolver, type, status, data }), sessionId }`),
  * so the client receives it through the same subscription with no special parsing.
  */
-export function startLivenessPulse(options: LivenessPulseOptions): LivenessPulseHandle {
+export function StartLivenessPulse(options: LivenessPulseOptions): LivenessPulseHandle {
     const { pubSub, sessionId, ownerUserId, resolver, readStatus } = options;
     const intervalMs = options.intervalMs ?? DEFAULT_PULSE_INTERVAL_MS;
 
@@ -73,7 +73,7 @@ export function startLivenessPulse(options: LivenessPulseOptions): LivenessPulse
             LogError(`[LivenessPulse:${resolver}] readStatus failed: ${(e as Error).message}`);
         }
 
-        publishStatusUpdate(pubSub, {
+        PublishStatusUpdate(pubSub, {
             sessionId,
             ownerUserId,
             message: JSON.stringify({
@@ -86,6 +86,11 @@ export function startLivenessPulse(options: LivenessPulseOptions): LivenessPulse
     }, intervalMs);
 
     return {
-        stop: () => clearInterval(timer),
+        Stop: () => clearInterval(timer),
     };
 }
+
+/** @deprecated Use {@link StartLivenessPulse}. */
+export function startLivenessPulse(options: LivenessPulseOptions): LivenessPulseHandle {
+    return StartLivenessPulse(options);
+}

package/src/generic/PushStatusResolver.ts

@@ -7,13 +7,13 @@ export const PUSH_STATUS_UPDATES_TOPIC = 'PUSH_STATUS_UPDATES';
 @ObjectType()
 export class PushStatusNotification {
   @Field(() => String, { nullable: true })
-  message?: string;
+  message?: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field((_type) => Date)
-  date!: Date;
+  date!: Date;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field((_type) => ID)
-  sessionId!: string;
+  sessionId!: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 }
 
 /**
@@ -55,7 +55,7 @@ export interface StatusUpdateParams {
  * payload shape and the required-identity guarantee live in exactly one place. Adding a field to
  * the push is a one-line change here; a new publisher physically cannot omit `ownerUserId`.
  */
-export function publishStatusUpdate(pubSub: PubSubEngine, params: StatusUpdateParams): void {
+export function PublishStatusUpdate(pubSub: PubSubEngine, params: StatusUpdateParams): void {
   const payload: PushStatusNotificationPayload = {
     sessionId: params.sessionId,
     ownerUserId: params.ownerUserId,
@@ -64,6 +64,11 @@ export function publishStatusUpdate(pubSub: PubSubEngine, params: StatusUpdatePa
   pubSub.publish(PUSH_STATUS_UPDATES_TOPIC, payload);
 }
 
+/** @deprecated Use {@link PublishStatusUpdate}. */
+export function publishStatusUpdate(pubSub: PubSubEngine, params: StatusUpdateParams): void {
+  return PublishStatusUpdate(pubSub, params);
+}
+
 /** Minimal shape of the subscription's connection context needed by the filter. */
 export interface StatusUpdatesFilterContext {
   userPayload?: UserPayload;
@@ -82,7 +87,7 @@ export interface StatusUpdatesFilterContext {
  * `sessionId` is no longer sufficient. Fails CLOSED — a missing owner or connection identity never
  * matches.
  */
-export function statusUpdatesFilter(data: {
+export function StatusUpdatesFilter(data: {
   payload: PushStatusNotificationPayload;
   args: PushStatusNotificationArgs;
   context: StatusUpdatesFilterContext | undefined;
@@ -98,14 +103,23 @@ export function statusUpdatesFilter(data: {
   return UUIDsEqual(payload.ownerUserId, connectionUserId);
 }
 
+/** @deprecated Use {@link StatusUpdatesFilter}. */
+export function statusUpdatesFilter(data: {
+  payload: PushStatusNotificationPayload;
+  args: PushStatusNotificationArgs;
+  context: StatusUpdatesFilterContext | undefined;
+}): boolean {
+  return StatusUpdatesFilter(data);
+}
+
 @Resolver()
 export class PushStatusResolver {
   @Subscription(() => PushStatusNotification, {
     topics: PUSH_STATUS_UPDATES_TOPIC,
     filter: (data: ResolverFilterData<PushStatusNotificationPayload, PushStatusNotificationArgs, StatusUpdatesFilterContext>) =>
-      statusUpdatesFilter(data),
+      StatusUpdatesFilter(data),
   })
-  statusUpdates(
+  statusUpdates(  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
     @Root() { message }: PushStatusNotificationPayload,
     @Arg('sessionId', () => String) sessionId: string
   ): PushStatusNotification {

package/src/generic/ResolverBase.ts

@@ -10,6 +10,7 @@ import {
   EntitySaveOptions,
   IMetadataProvider,
   IRunViewProvider,
+  KeyValuePair,
   LogDebug,
   LogError,
   LogStatus,
@@ -39,7 +40,7 @@ import { MJEvent, MJEventType, MJGlobal, ENCRYPTED_SENTINEL, EscapeSQLString, Is
 import { SQLParser } from '@memberjunction/sql-parser';
 import { PostgreSQLDialect, SQLServerDialect, type SQLParserDialect } from '@memberjunction/sql-dialect';
 import { EncryptionEngine } from '@memberjunction/encryption';
-import { PUSH_STATUS_UPDATES_TOPIC, publishStatusUpdate } from './PushStatusResolver.js';
+import { PUSH_STATUS_UPDATES_TOPIC, PublishStatusUpdate } from './PushStatusResolver.js';
 import { CACHE_INVALIDATION_TOPIC, MayBroadcastRecordData } from './CacheInvalidationResolver.js';
 import { PubSubManager } from './PubSubManager.js';
 import { FieldMapper } from '@memberjunction/graphql-dataprovider';
@@ -50,7 +51,7 @@ export class ResolverBase {
   private static _cloudeventsHeaders = process.env.CLOUDEVENTS_HTTP_HEADERS ? JSON.parse(process.env.CLOUDEVENTS_HTTP_HEADERS) : {};
 
   private static _eventSubscriptionKey: string = '___MJServer___ResolverBase___EventSubscriptions';
-  private get EventSubscriptions(): Map<string, Subscription> {
+  private get eventSubscriptions(): Map<string, Subscription> {
     // here we use the global object store instead of a static member becuase in some cases based on import code paths/bundling/etc, the static member
     // could actually be duplicated and we'd end up with multiple instances of the same map, which would be bad.
     const g = MJGlobal.Instance.GetGlobalObjectStore();
@@ -1479,7 +1480,7 @@ export class ResolverBase {
    * `publishStatusUpdate()` function directly with an explicit `ownerUserId`.
    */
   protected PublishStatusUpdate(pubSub: PubSubEngine, sessionId: string, message: string | undefined, userPayload: UserPayload): void {
-    publishStatusUpdate(pubSub, {
+    PublishStatusUpdate(pubSub, {
       sessionId,
       ownerUserId: userPayload?.userRecord?.ID ?? '',
       message,
@@ -1492,7 +1493,7 @@ export class ResolverBase {
     // cause issues with multiple messages for the same event.
     const uniqueKey = entityObject.EntityInfo.Name;
 
-    if (!this.EventSubscriptions.has(uniqueKey)) {
+    if (!this.eventSubscriptions.has(uniqueKey)) {
       // listen for events from the entityObject in case it is a long running task and we can push messages back to the client via pubSub
       LogDebug(`ResolverBase.ListenForEntityMessages: About to call MJGlobal.Instance.GetEventListener() to get the event listener subscription for ${uniqueKey}`);
       const theSub = MJGlobal.Instance.GetEventListener(false).subscribe(async (event: MJEvent) => {
@@ -1525,10 +1526,66 @@ export class ResolverBase {
           }
         }
       });
-      this.EventSubscriptions.set(uniqueKey, theSub);
+      this.eventSubscriptions.set(uniqueKey, theSub);
     }
   }
 
+  /**
+   * IS-A PROMOTION over the wire: an EXISTING parent record gaining a subtype — an Animal that is
+   * now also a Dog. It arrives as the CHILD's create mutation carrying the existing parent's
+   * primary key, because in IS-A the shared key is the relationship and the child has no key of
+   * its own to mint. `NewRecord()` has just reset the whole chain to "new", so left alone the
+   * parent would save as a CREATE: a second copy of a row that already exists (a unique-constraint
+   * violation at best, a silently duplicated parent at worst).
+   *
+   * When a child create carries a complete primary key, bind the new child to the existing parent
+   * row with `AttachToParent` (#3825): it loads the parent chain, so the parent saves as an UPDATE
+   * and only the child is INSERTed. A key that matches no row leaves the fresh chain exactly as
+   * `NewRecord()` built it — the ordinary whole-chain create. A non-IS-A entity, or a create with
+   * no key, never gets past the guards.
+   *
+   * @returns true when the child was attached to an existing parent row.
+   */
+  protected async attachToExistingParentIfPromotion(entityObject: BaseEntity, input: Record<string, unknown>): Promise<boolean> {
+    if (!entityObject.EntityInfo.IsChildType) {
+      return false;
+    }
+    const key = this.primaryKeyFromInput(entityObject.EntityInfo, input);
+    if (!key) {
+      return false;
+    }
+    const attached = await entityObject.AttachToParent(key);
+    if (!attached) {
+      // No parent row under that key: this is a whole-chain create on the CALLER's key (the
+      // client mints the shared key at the root and sends it, so honoring it keeps the client's
+      // in-memory chain and the stored rows on one key). AttachToParent restored the fresh chain,
+      // but the root's ReadOnly key slot is no longer writable — a later SetMany would silently
+      // keep the server-minted value — so re-seed the chain with the supplied key explicitly.
+      entityObject.NewRecord(key);
+    }
+    return attached;
+  }
+
+  /**
+   * The entity's primary key as supplied on a mutation input, or null when any part of it is
+   * missing. Composite keys are all-or-nothing: a half-specified key identifies nothing. An empty
+   * string counts as missing, the same as null — it is never a valid key value, and a GUID or
+   * string key that is "" identifies no row, so the create proceeds as a whole-chain create rather
+   * than failing the lookup. A malformed non-empty key (e.g. a non-GUID for a uniqueidentifier)
+   * is NOT swallowed: the load throws and the mutation fails loudly.
+   */
+  protected primaryKeyFromInput(entityInfo: EntityInfo, input: Record<string, unknown>): CompositeKey | null {
+    const pairs: KeyValuePair[] = [];
+    for (const pk of entityInfo.PrimaryKeys) {
+      const value = input[pk.Name] ?? input[pk.CodeName];
+      if (value === null || value === undefined || value === '') {
+        return null;
+      }
+      pairs.push(new KeyValuePair(pk.Name, value));
+    }
+    return pairs.length > 0 ? CompositeKey.FromKeyValuePairs(pairs) : null;
+  }
+
   protected async CreateRecord(entityName: string, input: any, provider: DatabaseProviderBase, userPayload: UserPayload, pubSub: PubSubEngine) {
     // Check API key scope authorization for entity create operations
     await this.CheckAPIKeyScopeAuthorization('entity:create', entityName, userPayload);
@@ -1546,6 +1603,10 @@ export class ResolverBase {
       for (const key of Object.keys(input)) {
         if (key !== 'RestoreContext___') fieldsForSet[key] = input[key];
       }
+      // IS-A promotion: bind the new child to its EXISTING parent row BEFORE the field
+      // assignments, so values the client sent for parent fields land on the loaded parent
+      // (as an update) instead of being wiped by the load.
+      await this.attachToExistingParentIfPromotion(entityObject, fieldsForSet);
       entityObject.SetMany(fieldsForSet);
 
       // Reconstruct the client-side restore context, if any, on this server

package/src/generic/RunViewResolver.ts

@@ -45,13 +45,13 @@ export class AggregateExpressionInput {
   @Field(() => String, {
     description: 'SQL expression for the aggregate (e.g., "SUM(OrderTotal)", "COUNT(*)", "AVG(Price)")'
   })
-  expression: string;
+  expression: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => String, {
     nullable: true,
     description: 'Optional alias for the result (used in error messages and debugging)'
   })
-  alias?: string;
+  alias?: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 }
 
 /**
@@ -60,22 +60,22 @@ export class AggregateExpressionInput {
 @ObjectType()
 export class AggregateResultOutput {
   @Field(() => String, { description: 'The expression that was calculated' })
-  expression: string;
+  expression: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => String, { description: 'The alias (or expression if no alias provided)' })
-  alias: string;
+  alias: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => String, {
     nullable: true,
     description: 'The calculated value as a JSON string (preserves type information)'
   })
-  value?: string;
+  value?: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => String, {
     nullable: true,
     description: 'Error message if calculation failed'
   })
-  error?: string;
+  error?: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 }
 
 //****************************************************************************
@@ -573,22 +573,22 @@ export class RunViewGenericInput {
 @InputType()
 export class RunViewCacheStatusInput {
   @Field(() => String, { description: 'The maximum __mj_UpdatedAt value from cached results' })
-  maxUpdatedAt: string;
+  maxUpdatedAt: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => Int, { description: 'The number of rows in cached results' })
-  rowCount: number;
+  rowCount: number;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 }
 
 @InputType()
 export class RunViewWithCacheCheckInput {
   @Field(() => RunDynamicViewInput, { description: 'The RunView parameters' })
-  params: RunDynamicViewInput;
+  params: RunDynamicViewInput;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => RunViewCacheStatusInput, {
     nullable: true,
     description: 'Optional cache status - if provided, server will check if cache is current'
   })
-  cacheStatus?: RunViewCacheStatusInput;
+  cacheStatus?: RunViewCacheStatusInput;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 }
 
 @ObjectType()
@@ -596,21 +596,21 @@ export class DifferentialDataOutput {
   @Field(() => [RunViewGenericResultRow], {
     description: 'Records that have been created or updated since the client\'s maxUpdatedAt'
   })
-  updatedRows: RunViewGenericResultRow[];
+  updatedRows: RunViewGenericResultRow[];  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => [String], {
     description: 'Primary key values (as concatenated strings) of records that have been deleted'
   })
-  deletedRecordIDs: string[];
+  deletedRecordIDs: string[];  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 }
 
 @ObjectType()
 export class RunViewWithCacheCheckResultOutput {
   @Field(() => Int, { description: 'The index of this view in the batch request' })
-  viewIndex: number;
+  viewIndex: number;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => String, { description: "'current', 'differential', 'stale', or 'error'" })
-  status: string;
+  status: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => [RunViewGenericResultRow], {
     nullable: true,
@@ -622,34 +622,34 @@ export class RunViewWithCacheCheckResultOutput {
     nullable: true,
     description: 'Differential update data - only populated when status is differential'
   })
-  differentialData?: DifferentialDataOutput;
+  differentialData?: DifferentialDataOutput;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => String, { nullable: true, description: 'Max __mj_UpdatedAt from results when stale or differential' })
-  maxUpdatedAt?: string;
+  maxUpdatedAt?: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => Int, { nullable: true, description: 'Row count of results when stale or differential (total after applying delta)' })
-  rowCount?: number;
+  rowCount?: number;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => String, { nullable: true, description: 'Error message if status is error' })
-  errorMessage?: string;
+  errorMessage?: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => [AggregateResultOutput], {
     nullable: true,
     description: 'Aggregate results when status is stale and aggregates were requested (B40 — previously never marshalled, so CacheLocal callers got no aggregates at all)'
   })
-  aggregateResults?: AggregateResultOutput[];
+  aggregateResults?: AggregateResultOutput[];  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 }
 
 @ObjectType()
 export class RunViewsWithCacheCheckOutput {
   @Field(() => Boolean, { description: 'Whether the overall operation succeeded' })
-  success: boolean;
+  success: boolean;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => [RunViewWithCacheCheckResultOutput], { description: 'Results for each view in the batch' })
-  results: RunViewWithCacheCheckResultOutput[];
+  results: RunViewWithCacheCheckResultOutput[];  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
   @Field(() => String, { nullable: true, description: 'Overall error message if success is false' })
-  errorMessage?: string;
+  errorMessage?: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 }
 
 //****************************************************************************

package/src/generic/__tests__/FireAndForgetHeartbeat.test.ts

@@ -2,7 +2,7 @@ import 'reflect-metadata';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { PubSubEngine } from 'type-graphql';
 import {
-    startLivenessPulse,
+    StartLivenessPulse,
     DEFAULT_PULSE_INTERVAL_MS,
     HEARTBEAT_MESSAGE_TYPE,
 } from '../FireAndForgetHeartbeat';
@@ -31,14 +31,14 @@ describe('startLivenessPulse', () => {
 
     it('does not publish before the first interval elapses', () => {
         const pubSub = makePubSub();
-        startLivenessPulse({ pubSub, sessionId: 's1', resolver: 'TestResolver' });
+        StartLivenessPulse({ pubSub, sessionId: 's1', resolver: 'TestResolver' });
         vi.advanceTimersByTime(DEFAULT_PULSE_INTERVAL_MS - 1);
         expect(pubSub.publish).not.toHaveBeenCalled();
     });
 
     it('publishes a heartbeat on the push-status topic each interval', () => {
         const pubSub = makePubSub();
-        startLivenessPulse({ pubSub, sessionId: 's1', resolver: 'TestResolver', intervalMs: 1000 });
+        StartLivenessPulse({ pubSub, sessionId: 's1', resolver: 'TestResolver', intervalMs: 1000 });
 
         vi.advanceTimersByTime(3000);
 
@@ -52,7 +52,7 @@ describe('startLivenessPulse', () => {
 
     it('includes the enriched status snapshot from readStatus', () => {
         const pubSub = makePubSub();
-        startLivenessPulse({
+        StartLivenessPulse({
             pubSub,
             sessionId: 's1',
             resolver: 'RunAIAgentResolver',
@@ -68,7 +68,7 @@ describe('startLivenessPulse', () => {
 
     it('publishes an empty data object when readStatus throws (loop survives)', () => {
         const pubSub = makePubSub();
-        startLivenessPulse({
+        StartLivenessPulse({
             pubSub,
             sessionId: 's1',
             resolver: 'RunAIAgentResolver',
@@ -87,12 +87,12 @@ describe('startLivenessPulse', () => {
 
     it('stops publishing after stop() is called', () => {
         const pubSub = makePubSub();
-        const handle = startLivenessPulse({ pubSub, sessionId: 's1', resolver: 'TestResolver', intervalMs: 1000 });
+        const handle = StartLivenessPulse({ pubSub, sessionId: 's1', resolver: 'TestResolver', intervalMs: 1000 });
 
         vi.advanceTimersByTime(2000);
         expect(pubSub.publish).toHaveBeenCalledTimes(2);
 
-        handle.stop();
+        handle.Stop();
         vi.advanceTimersByTime(5000);
         expect(pubSub.publish).toHaveBeenCalledTimes(2);
     });

package/src/index.ts

@@ -32,7 +32,7 @@ import { RealtimeProxyServer } from './realtimeProxy/RealtimeProxyServer.js';
 import buildApolloServer from './apolloServer/index.js';
 import { configInfo, configFilePath, dbDatabase, dbHost, dbPort, dbUsername, graphqlPort, graphqlRootPath, mj_core_schema, websiteRunFromPackage, RESTApiOptions } from './config.js';
 import { default as jwt } from 'jsonwebtoken';
-import { contextFunction, createUnifiedAuthMiddleware, getUserPayload } from './context.js';
+import { contextFunction, CreateUnifiedAuthMiddleware, getUserPayload } from './context.js';
 import { UserPayload } from './types.js';
 import { requireSystemUserDirective, publicDirective } from './directives/index.js';
 import { variablesLoggingMiddleware } from './logging/variablesLoggingMiddleware.js';
@@ -67,6 +67,8 @@ import { RegisterRSUProgressBridge } from './integration/RSUProgressBridge.js';
 import { ClientToolRequestManager, AgentRunWatchdog } from '@memberjunction/ai-agents';
 import { SessionJanitor } from './agentSessions/index.js';
 import { StartTaskGraphDispatcher } from './services/StartTaskGraphDispatcher.js';
+import { GetAttachmentService } from '@memberjunction/aiengine';
+import { MJStorageBlobStore } from './services/MJStorageBlobStore.js';
 import { CACHE_INVALIDATION_TOPIC, MayBroadcastRecordData, ConfigureRecordDataBroadcast } from './generic/CacheInvalidationResolver.js';
 import { ConnectorFactory, IntegrationEngine, IntegrationSyncOptions } from '@memberjunction/integration-engine';
 import { CronExpressionHelper } from '@memberjunction/scheduling-engine';
@@ -80,6 +82,7 @@ import {
 import { ServerExtensionLoader, ServerExtensionConfig, mergeServerExtensionConfigs, prepareServerExtensionConfigs, describeServerExtensionMount, InstallMediaUpgradeDispatcher, IsGraphQLWsPath } from '@memberjunction/server-extensions-core';
 import { coreReservedServerExtensionRoots } from './serverExtensionReservedRoots.js';
 import { MetadataCacheRefreshIntervalSeconds } from './providerConfigUnits.js';
+import { CreateMetadataRefreshSignalHandler, METADATA_REFRESH_SIGNAL } from './metadataRefreshSignal.js';
 
 const cacheRefreshInterval = configInfo.databaseSettings.metadataCacheRefreshInterval;
 
@@ -97,10 +100,15 @@ export { MetadataCacheRefreshIntervalSeconds } from './providerConfigUnits.js';
  * CodeGenLib). This wrapper keeps the public `getDbType()` symbol that
  * MJServer consumers (and the broader stack) already import.
  */
-export function getDbType(): DatabasePlatform {
+export function GetDbType(): DatabasePlatform {
     return resolveDbPlatformFromEnv() ?? 'sqlserver';
 }
 
+/** @deprecated Use {@link GetDbType}. */
+export function getDbType(): DatabasePlatform {
+  return GetDbType();
+}
+
 export { MaxLength } from 'class-validator';
 export * from 'type-graphql';
 // Named re-export so Open App generated resolvers get a live ESM binding for
@@ -261,7 +269,10 @@ const localPath = (p: string) => {
   return resolvedPath;
 };
 
-export const createApp = (): Application => express();
+export const CreateApp = (): Application => express();
+
+/** @deprecated Use {@link CreateApp}. */
+export const createApp = CreateApp;
 
 /**
  * Resolves the MJServer package version for the startup summary header.
@@ -281,7 +292,18 @@ function resolveServerVersion(): string | undefined {
   }
 }
 
-export const serve = async (resolverPaths: Array<string>, app: Application = createApp(), options?: MJServerOptions): Promise<void> => {
+// Bind MJStorage as the conversation-attachment blob store. The attachment service itself no longer
+// imports `@memberjunction/storage` — that dependency made it unusable from any browser or React
+// Native client, which is why the same attachment rules had been reimplemented three times.
+//
+// This runs at module load, not inside `serve()`, so that merely importing MJServer is enough: any
+// entry point that reaches the attachment service — a resolver under test, a script, a worker that
+// never calls `serve()` — finds storage already bound rather than degrading to "storage is not
+// available on this host". The store is stateless and configures `FileStorageEngine` on use, so
+// there is no ordering hazard in binding this early.
+GetAttachmentService().BlobStore = new MJStorageBlobStore();
+
+export const Serve = async (resolverPaths: Array<string>, app: Application = CreateApp(), options?: MJServerOptions): Promise<void> => {
   const t0 = performance.now();
   // Level-gated startup logger. Resolves verbosity from telemetry.level (single
   // operator knob). At `standard` (default), per-phase timings are collapsed into
@@ -307,8 +329,8 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
     console.log({ combinedResolverPaths, paths, cwd: process.cwd() });
   }
 
-  const setupComplete$ = new ReplaySubject(1);
-  const dbType = getDbType();
+const setupComplete$ = new ReplaySubject(1);
+  const dbType = GetDbType();
   const dataSources: DataSourceInfo[] = [];
 
   if (dbType === 'postgresql') {
@@ -1377,7 +1399,7 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
   startupLog.LogIf('verbose', `[Auth] Public provider catalog registered at ${AUTH_CATALOG_MOUNT_PATH}/providers`);
 
   // ─── Unified auth middleware (replaces both REST authMiddleware and contextFunction auth) ─────
-  app.use(createUnifiedAuthMiddleware(dataSources));
+  app.use(CreateUnifiedAuthMiddleware(dataSources));
 
   // ─── Post-auth middleware from BaseServerMiddleware plugins ─────
   // Middleware here has access to the authenticated user via req.userPayload.
@@ -1666,6 +1688,8 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
 
   process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
   process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+  // Operator control: `kill -HUP <pid>` hard-reloads metadata from the DB — see metadataRefreshSignal.ts
+  process.on(METADATA_REFRESH_SIGNAL, CreateMetadataRefreshSignalHandler(() => Metadata.Provider.Refresh())); // global-provider-ok: operator-triggered refresh of the global cache that per-request providers adopt from
 
   // Handle unhandled promise rejections to prevent server crashes
   process.on('unhandledRejection', (reason, promise) => {
@@ -1676,6 +1700,9 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
   });
 };
 
+/** @deprecated Use {@link Serve}. */
+export const serve = Serve;
+
 /**
  * Age at which an unprocessed `MJ: RSU Pending Works` row is reported as stranded.
  * A row older than this survived at least one full restart cycle without being completed.

package/src/integration/CustomColumnPromoter.ts

@@ -133,7 +133,7 @@ interface WorkItem {
 }
 
 /** Registers the post-sync custom-column promotion hook on the IntegrationEngine singleton. */
-export function registerIntegrationCustomColumnPromoter(): void {
+export function RegisterIntegrationCustomColumnPromoter(): void {
     IntegrationEngine.Instance.SetPostSyncSchemaPromotionCallback(async (ctx) => {
         const user = ctx.ContextUser as UserInfo;
         const provider = ctx.Provider as IMetadataProvider | undefined;
@@ -164,6 +164,11 @@ export function registerIntegrationCustomColumnPromoter(): void {
     LogStatusEx({ message: '[CustomColumnPromoter] Registered post-sync custom-column promotion hook (auto-promote opt-in, default OFF).', verboseOnly: true });
 }
 
+/** @deprecated Use {@link RegisterIntegrationCustomColumnPromoter}. */
+export function registerIntegrationCustomColumnPromoter(): void {
+    return RegisterIntegrationCustomColumnPromoter();
+}
+
 /** Reads the per-connection `autoPromoteCustomColumns` flag (default false = capture-only, on-demand promotion). */
 async function readAutoPromoteFlag(companyIntegrationID: string, user: UserInfo, provider?: IMetadataProvider): Promise<boolean> {
     try {