@memberjunction/server 6.2.0-edge.0 → 6.2.0-edge.2

package/src/generic/PushStatusResolver.ts

@@ -1,5 +1,5 @@
 import { Arg, Field, ID, ObjectType, PubSubEngine, Resolver, ResolverFilterData, Root, Subscription } from 'type-graphql';
-import { UUIDsEqual } from '@memberjunction/global';
+import { MJGlobal, UUIDsEqual } from '@memberjunction/global';
 import { UserPayload } from '../types.js';
 
 export const PUSH_STATUS_UPDATES_TOPIC = 'PUSH_STATUS_UPDATES';
@@ -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
 }
 
 /**
@@ -32,6 +32,89 @@ export interface PushStatusNotificationPayload {
   sessionId: string;
   /** Authenticated user the update belongs to. Server-side filter key; never sent to the client. */
   ownerUserId: string;
+  /**
+   * `MJGlobal.ProcessUUID` of the instance that first published this update. Used only for
+   * cross-instance echo suppression: an instance that receives its own message back from the
+   * message bus must drop it, or every push is delivered twice.
+   */
+  SourceServerId?: string;
+}
+
+/** Receives every locally-published status update, for fan-out to other server instances. */
+export type PushStatusPublishHook = (payload: PushStatusNotificationPayload) => void;
+
+let _publishHook: PushStatusPublishHook | undefined;
+
+/**
+ * Register (or clear, with no arg) the cross-instance fan-out hook.
+ *
+ * Inversion of control, deliberately: this module must not know that Redis exists. The server
+ * registers the hook at startup only when a message bus is configured, so a single-instance
+ * deployment behaves exactly as before.
+ */
+export function SetPushStatusPublishHook(hook?: PushStatusPublishHook): void {
+  _publishHook = hook;
+}
+
+/**
+ * Validate an update received from the cross-instance message bus.
+ *
+ * The bus carries messages from other processes, so every field is type-checked before the update
+ * is republished onto the local topic, where {@link StatusUpdatesFilter} compares `ownerUserId`
+ * with the connection's user.
+ *
+ * @param raw The JSON text taken off the bus.
+ * @param localServerId This process's `MJGlobal.ProcessUUID`, used to drop our own echo.
+ * @returns The update to republish, or `null` to drop it.
+ */
+export function ParseReplicatedStatusUpdate(raw: string, localServerId: string): PushStatusNotificationPayload | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== 'object' || parsed === null) {
+    return null;
+  }
+
+  const { sessionId, ownerUserId, message, SourceServerId } = parsed as Record<string, unknown>;
+  const source = typeof SourceServerId === 'string' ? SourceServerId : undefined;
+  const body = typeof message === 'string' ? message : undefined;
+  if ((SourceServerId != null && source === undefined) || (message != null && body === undefined)) {
+    return null; // a present field of the wrong type
+  }
+  if (source === localServerId) {
+    return null; // our own message, echoed back
+  }
+  if (typeof sessionId !== 'string' || !sessionId || typeof ownerUserId !== 'string' || !ownerUserId) {
+    return null; // fail closed: an update with no valid identity can never be routed safely
+  }
+
+  return { sessionId, ownerUserId, message: body, SourceServerId: source };
+}
+
+/**
+ * Whether an update is worth sending to other server instances.
+ *
+ * Streaming content is excluded. It arrives at hundreds of messages per second and each one carries
+ * a full serialized agent run, so replicating it would cost far more bandwidth than the delivery it
+ * buys — and a token delta is worthless to a client that has already missed the ones before it.
+ * Progress and completion are low-rate and each is individually meaningful, which is exactly the
+ * kind of message that must survive landing on the wrong replica.
+ */
+export function ShouldReplicateStatusUpdate(message?: string): boolean {
+  if (!message) {
+    return false;
+  }
+  try {
+    const parsed: unknown = JSON.parse(message);
+    const type = (parsed as { type?: unknown })?.type;
+    return type !== 'StreamingContent';
+  } catch {
+    // A plain-string message (not the resolvers' JSON envelope) is rare and low-rate. Replicate it.
+    return true;
+  }
 }
 
 interface PushStatusNotificationArgs {
@@ -55,13 +138,31 @@ 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,
     message: params.message,
+    SourceServerId: MJGlobal.Instance.ProcessUUID,
   };
   pubSub.publish(PUSH_STATUS_UPDATES_TOPIC, payload);
+
+  // Fan out to other instances. Only reached by updates originating HERE: a message arriving from
+  // the bus is republished straight onto the local topic and never comes back through this
+  // function, so there is no loop to break beyond the SourceServerId check on the receiving side.
+  if (_publishHook && ShouldReplicateStatusUpdate(params.message)) {
+    try {
+      _publishHook(payload);
+    } catch {
+      // Fan-out is an optimization over the durable tail query. A message bus that is down must
+      // never break local delivery, which is the path that works for the common case.
+    }
+  }
+}
+
+/** @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. */
@@ -82,7 +183,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 +199,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

@@ -4,6 +4,7 @@ import {
   BaseEntityEvent,
   CompositeKey,
   DatabaseProviderBase,
+  EntityFieldInfo,
   EntityFieldTSType,
   EntityInfo,
   EntityPermissionType,
@@ -40,8 +41,8 @@ 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 { CACHE_INVALIDATION_TOPIC } from './CacheInvalidationResolver.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';
 import { Subscription } from 'rxjs';
@@ -51,7 +52,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();
@@ -1450,16 +1451,24 @@ export class ResolverBase {
    * Publishes a CACHE_INVALIDATION event to connected browser clients after a successful
    * entity save or delete. Includes the originSessionId so the originating browser can
    * skip redundant re-fetches (it already handled the event locally).
+   *
+   * The row itself rides along ONLY for entities opted in via
+   * `cacheSettings.recordDataBroadcastEntities` — this event reaches every connected client
+   * unfiltered, so the row would otherwise be readable by sessions that could not read the record.
    */
   protected PublishCacheInvalidation(entityObject: BaseEntity, action: 'save' | 'delete', userPayload: UserPayload): void {
+    const entityName = entityObject.EntityInfo.Name;
     PubSubManager.Instance.Publish(CACHE_INVALIDATION_TOPIC, {
-      entityName: entityObject.EntityInfo.Name,
+      entityName,
       primaryKeyValues: JSON.stringify(entityObject.PrimaryKey.KeyValuePairs),
       action,
       sourceServerId: MJGlobal.Instance.ProcessUUID,
       timestamp: new Date(),
       originSessionId: userPayload?.sessionId || null,
-      recordData: action === 'save' ? JSON.stringify(entityObject.GetAll()) : undefined,
+      recordData:
+        action === 'save' && MayBroadcastRecordData(entityName)
+          ? JSON.stringify(entityObject.GetAll())
+          : undefined,
     });
   }
 
@@ -1472,7 +1481,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,
@@ -1485,7 +1494,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) => {
@@ -1518,7 +1527,7 @@ export class ResolverBase {
           }
         }
       });
-      this.EventSubscriptions.set(uniqueKey, theSub);
+      this.eventSubscriptions.set(uniqueKey, theSub);
     }
   }
 
@@ -1684,7 +1693,7 @@ export class ResolverBase {
             await this.TestAndSetClientOldValuesToDBValues(input, clientNewValues, entityObject, userInfo);
           } else {
             // no OldValues, so we can just set the new values from input
-            entityObject.SetMany(input);
+            entityObject.SetMany(clientNewValues);
           }
         } else {
           // Use a generic message to avoid leaking whether a record exists — distinguishing
@@ -1696,8 +1705,11 @@ export class ResolverBase {
       } else {
         // we get here if we are NOT tracking changes and we DO have OldValues, so we can load from them
         const oldValues = {};
-        // for each item in the oldValues array, add it to the oldValues object
-        input.OldValues___?.forEach((item) => (oldValues[item.Key] = item.Value));
+        // for each item in the oldValues array, add it to the oldValues object, typed like the field
+        input.OldValues___?.forEach((item) => {
+          const field = entityObject.EntityInfo.Fields.find((f) => f.CodeName === item.Key);
+          oldValues[item.Key] = field ? this.ClientOldValueToFieldValue(field, item.Value) : item.Value;
+        });
 
         // 1) load the old values, this will be the initial state of the object
         await entityObject.LoadFromData(oldValues);
@@ -1764,6 +1776,11 @@ export class ResolverBase {
    *
    * Ordered so the boolean flag is evaluated last: the extra load lands only on entities that have
    * the feature switched on, which is almost none of them.
+   *
+   * `MJ: Record Changes` always loads from the database: its server class allows an update only when
+   * Comments is the one dirty field, and "dirty" compared against client-supplied OldValues lets a
+   * caller pin forged audit columns as both old and new values. It doesn't track its own changes, so
+   * nothing else forces the load.
    */
   protected MustLoadTruthFromDatabase(
     entityInfo: EntityInfo,
@@ -1773,6 +1790,7 @@ export class ResolverBase {
   ): boolean {
     return (
       entityInfo.TrackRecordChanges ||
+      entityInfo.Name.trim().toLowerCase() === 'mj: record changes' ||
       !input.OldValues___ ||
       hasDeniedReadFields ||
       hasNarrowedAuditPayload ||
@@ -1909,6 +1927,41 @@ export class ResolverBase {
     return true;
   }
 
+  /**
+   * Converts one client-sent old value (always a string on the wire; dates as epoch milliseconds,
+   * the GraphQL Timestamp form) to the field's TypeScript type, so it compares equal to the stored
+   * value. Both the OldValues comparison and the load-from-OldValues path use it: without it a date
+   * old value becomes an Invalid Date and an unchanged date field reads as edited.
+   */
+  protected ClientOldValueToFieldValue(field: EntityFieldInfo | undefined, raw: unknown): string | number | boolean | Date | null {
+    let val: unknown = raw;
+    if ((val === null || val === undefined) && field && field.DefaultValue !== null && field.DefaultValue !== undefined && !field.AllowsNull)
+      val = field.DefaultValue; // set default value as the field was never set and it does NOT allow nulls
+    if (val === undefined) val = null;
+    // A null old value stays null, except a boolean, which the comparison has always read as false.
+    if (field?.TSType === EntityFieldTSType.Boolean && val === null) return false;
+    if (val === null) return null;
+    if (!field) {
+      // No field metadata to convert by: pass scalars through, stringify anything else.
+      return typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean' || val instanceof Date ? val : String(val);
+    }
+
+    const text = String(val);
+    switch (field.TSType) {
+      case EntityFieldTSType.Number: {
+        const integer = ['int', 'smallint', 'bigint', 'tinyint'].includes((field.Type as string).toLowerCase());
+        return integer ? parseInt(text) : parseFloat(text);
+      }
+      case EntityFieldTSType.Boolean:
+        return !(text === 'false' || text === '0' || parseInt(text) === 0);
+      case EntityFieldTSType.Date:
+        // Epoch milliseconds (the GraphQL Timestamp form) arrive as a numeric string.
+        return new Date(text.trim() !== '' && !isNaN(Number(text)) ? parseInt(text) : text);
+      default:
+        return text; // already a string
+    }
+  }
+
   /**
    * This routine compares the OldValues property in the input object to the values in the DB that we just loaded. If there are differences, we need to check to see if the client
    * is trying to update any of those fields (e.g. overlap). If there is overlap, we throw an error. If there is no overlap, we can proceed with the update even if the DB Values
@@ -1923,52 +1976,7 @@ export class ResolverBase {
     input.OldValues___.forEach((item) => {
       // we need to do a quick transform on the values to make sure they match the TS Type for the given field because item.Value will always be a string
       const field = entityObject.EntityInfo.Fields.find((f) => f.CodeName === item.Key);
-      let val = item.Value;
-      if ((val === null || val === undefined) && field.DefaultValue !== null && field.DefaultValue !== undefined && !field.AllowsNull)
-        val = field.DefaultValue; // set default value as the field was never set and it does NOT allow nulls
-
-      if (field) {
-        switch (field.TSType) {
-          case EntityFieldTSType.Number:
-            if (val == null && val == undefined) {
-              val = null;
-            }
-            else {
-              let typeLowered = (field.Type as string).toLowerCase();
-
-              switch (typeLowered) {
-                case 'int':
-                case 'smallint':
-                case 'bigint':
-                case 'tinyint':
-                  val = parseInt(val);
-                  break;
-                case 'money':
-                case 'smallmoney':
-                case 'decimal':
-                case 'numeric':
-                case 'float':
-                  val = parseFloat(val);
-                  break;
-                default:
-                  val = parseFloat(val);
-                  break;
-              }
-            }
-            break;
-          case EntityFieldTSType.Boolean:
-            val = val === null || val === undefined || val === 'false' || val === '0' || parseInt(val) === 0 ? false : true;
-            break;
-          case EntityFieldTSType.Date:
-            // first, if val is a string and it is actually a number (milliseconds since epoch), convert it to a number.
-            if (val !== null && val !== undefined && val.toString().trim() !== '' && !isNaN(val)) val = parseInt(val);
-
-            val = val !== null && val !== undefined ? new Date(val) : null;
-            break;
-          default:
-            break; // already a string
-        }
-      }
+      const val = this.ClientOldValueToFieldValue(field, item.Value);
       clientOldValues[item.Key] = val;
     });
 

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);
     });