Add cross-parameter stage validation.

Author: rasmi

functions/package.json

@@ -11,7 +11,7 @@
     "deploy": "firebase deploy --only functions",
     "logs": "firebase functions:log",
     "test": "npm run test:unit && npm run test:firestore",
-    "test:firestore": "firebase -c ../firebase-test.json emulators:exec --only firestore,functions --project=demo-deliberate-lab \"npx jest --runInBand $npm_package_config_firestore_tests\"",
+    "test:firestore": "GOOGLE_CLOUD_PROJECT=demo-deliberate-lab firebase -c ../firebase-test.json emulators:exec --only firestore,functions --project=demo-deliberate-lab \"npx jest --runInBand $npm_package_config_firestore_tests\"",
     "test:unit": "npx jest --testPathIgnorePatterns=$npm_package_config_firestore_tests",
     "typecheck": "tsc --noEmit",
     "migrate:require-full-time": "npx tsx src/migrations/migrate-require-full-time.ts",

functions/src/dl_api/experiments.dl_api.integration.test.ts

@@ -15,6 +15,7 @@ import {
   ProlificConfig,
   Visibility,
   createExperimentConfig,
+  createPrivateChatStage,
 } from '@deliberation-lab/utils';
 import {
   TestContext,
@@ -895,4 +896,25 @@ describe('API Experiment Creation Integration Tests', () => {
       }
     });
   });
+
+  // ==========================================================================
+  // Stage Validation Tests
+  // ==========================================================================
+
+  describe('Stage validation', () => {
+    it('should reject experiment creation with invalid stage config (minTurns > maxTurns)', async () => {
+      const invalidStage = createPrivateChatStage({
+        name: 'Invalid chat',
+        minNumberOfTurns: 10,
+        maxNumberOfTurns: 3,
+      });
+
+      const response = await apiRequest('POST', '/v1/experiments', {
+        name: 'Invalid experiment',
+        stages: JSON.parse(JSON.stringify([invalidStage])),
+      });
+
+      expect(response.ok).toBe(false);
+    });
+  });
 });

functions/src/experiment.utils.ts

@@ -22,6 +22,7 @@ import {getExperimentDownload} from './data';
 import {generateVariablesForScope} from './variables.utils';
 import {AuthGuard} from './utils/auth-guard';
 import {createCohortFromDefinition} from './cohort.utils';
+import {validateStages} from './utils/validation';
 
 /**
  * Create cohorts from cohort definitions and update the definitions with generated IDs.
@@ -80,6 +81,12 @@ export async function writeExperimentFromTemplate(
 ): Promise<string> {
   const {collectionName = 'experiments'} = options;
 
+  // Validate stage configs (schema + cross-field business rules)
+  const stageValidation = validateStages(template.stageConfigs);
+  if (!stageValidation.valid) {
+    throw new Error(`Invalid stage configuration: ${stageValidation.error}`);
+  }
+
   // Set up experiment config with stageIds
   const experimentConfig = createExperimentConfig(
     template.stageConfigs,
@@ -298,7 +305,11 @@ export interface UpdateExperimentOptions {
  */
 export interface UpdateExperimentResult {
   success: boolean;
-  error?: 'not-found' | 'not-owner' | 'cohort-definitions-locked';
+  error?:
+    | 'not-found'
+    | 'not-owner'
+    | 'cohort-definitions-locked'
+    | 'invalid-stages';
 }
 
 /**
@@ -322,6 +333,12 @@ export async function updateExperimentFromTemplate(
 ): Promise<UpdateExperimentResult> {
   const {collectionName = 'experiments'} = options;
 
+  // Validate stage configs (schema + cross-field business rules)
+  const stageValidation = validateStages(template.stageConfigs);
+  if (!stageValidation.valid) {
+    return {success: false, error: 'invalid-stages'};
+  }
+
   // Set up experiment config with stageIds
   const experimentConfig = createExperimentConfig(
     template.stageConfigs,

functions/src/utils/validation.ts

@@ -1,6 +1,7 @@
 /** Pretty printing and analysis utils for typebox validation */
 
 import {
+  BaseStageConfig,
   CONFIG_DATA,
   CohortParticipantConfig,
   CohortParticipantConfigSchema,
@@ -111,12 +112,17 @@ export const checkUnionErrorOnPath = (
     : Value.Errors(validator, value);
 };
 
+/** Schema-only map extracted from CONFIG_DATA for union error resolution. */
+const CONFIG_DATA_SCHEMAS: Record<Index, TSchema> = Object.fromEntries(
+  Object.entries(CONFIG_DATA).map(([key, entry]) => [key, entry.schema]),
+);
+
 // Variants
 export const checkConfigDataUnionOnPath = (
   data: unknown,
   path: string,
   references?: TSchema[],
-) => checkUnionErrorOnPath(data, path, CONFIG_DATA, references);
+) => checkUnionErrorOnPath(data, path, CONFIG_DATA_SCHEMAS, references);
 
 // ************************************************************************* //
 // STAGE VALIDATION                                                          //
@@ -187,6 +193,19 @@ export function validateStages(stages: unknown[]): ValidationResult {
           errorMessages.push(`  - ${error.path}: ${error.message}`);
         }
       }
+    } else {
+      // Schema passed — run cross-field business rule validation
+      const stageObj = stage as BaseStageConfig;
+      const entry = CONFIG_DATA[stageObj.kind as string];
+      if (entry?.validate) {
+        const result = entry.validate(stageObj);
+        if (!result.valid) {
+          const stageName = stageObj?.name || 'unnamed';
+          errorMessages.push(
+            `Stage ${i} (name: "${stageName}", kind: "${stageObj.kind}"): ${result.error}`,
+          );
+        }
+      }
     }
   }
 

utils/src/export-schemas.ts

@@ -54,8 +54,8 @@ function collectSchemasWithId(
 }
 
 // Verify all stage configs have $id for proper naming in $defs
-for (const [key, schema] of Object.entries(CONFIG_DATA)) {
-  if (!(schema as Record<string, unknown>).$id) {
+for (const [key, entry] of Object.entries(CONFIG_DATA)) {
+  if (!(entry.schema as Record<string, unknown>).$id) {
     throw new Error(
       `Stage config "${key}" is missing $id. Add $id to its TypeBox definition.`,
     );

utils/src/index.ts

@@ -73,6 +73,7 @@ export * from './stages/stage.handler';
 export * from './stages/stage.manager';
 export * from './stages/stage.prompts';
 export * from './stages/stage.validation';
+export * from './stages/stage.schemas';
 
 export * from './stages/chat_stage';
 export * from './stages/chat_stage.manager';

utils/src/stages/chat_stage.validation.ts

@@ -1,9 +1,13 @@
 import {Type, type Static} from '@sinclair/typebox';
 import {UnifiedTimestampSchema} from '../shared.validation';
-import {StageKind} from './stage';
+import {BaseStageConfig, StageKind} from './stage';
 import {ChatDiscussionType} from './chat_stage';
-import {BaseStageConfigSchema} from './stage.schemas';
+import {
+  BaseStageConfigSchema,
+  type StageValidationResult,
+} from './stage.schemas';
 import {UserType} from '../participant';
+import {ChatStageConfig} from './chat_stage';
 
 /** Shorthand for strict TypeBox object validation */
 const strict = {additionalProperties: false} as const;
@@ -70,6 +74,23 @@ export const ChatStageConfigData = Type.Composite(
   {$id: 'ChatStageConfig', ...strict},
 );
 
+/** Validate cross-field business rules for chat time configs. */
+export function validateChatStageConfig(
+  stage: BaseStageConfig,
+): StageValidationResult {
+  const {timeMinimumInMinutes: min, timeLimitInMinutes: max} =
+    stage as ChatStageConfig;
+
+  if (min != null && max != null && min > max) {
+    return {
+      valid: false,
+      error: `timeMinimumInMinutes (${min}) cannot exceed timeLimitInMinutes (${max})`,
+    };
+  }
+
+  return {valid: true};
+}
+
 // ************************************************************************* //
 // updateChatMessage endpoint                                                //
 // ************************************************************************* //

utils/src/stages/private_chat_stage.validation.ts

@@ -1,7 +1,12 @@
 import {Type, type Static} from '@sinclair/typebox';
 import {UnifiedTimestampSchema} from '../shared.validation';
-import {StageKind} from './stage';
-import {BaseStageConfigSchema} from './stage.schemas';
+import {BaseStageConfig, StageKind} from './stage';
+import {
+  BaseStageConfigSchema,
+  type StageValidationResult,
+} from './stage.schemas';
+import {validateChatStageConfig} from './chat_stage.validation';
+import {PrivateChatStageConfig} from './private_chat_stage';
 
 /** Shorthand for strict TypeBox object validation */
 const strict = {additionalProperties: false} as const;
@@ -37,3 +42,24 @@ export const PrivateChatStageConfigData = Type.Composite(
   ],
   {$id: 'PrivateChatStageConfig', ...strict},
 );
+
+/** Validate cross-field business rules for private chat stage configs. */
+export function validatePrivateChatStageConfig(
+  stage: BaseStageConfig,
+): StageValidationResult {
+  // Check time constraints (shared with group chat)
+  const timeResult = validateChatStageConfig(stage);
+  if (!timeResult.valid) return timeResult;
+
+  const {minNumberOfTurns: minTurns, maxNumberOfTurns: maxTurns} =
+    stage as PrivateChatStageConfig;
+
+  if (minTurns != null && maxTurns != null && minTurns > maxTurns) {
+    return {
+      valid: false,
+      error: `minNumberOfTurns (${minTurns}) cannot exceed maxNumberOfTurns (${maxTurns})`,
+    };
+  }
+
+  return {valid: true};
+}

utils/src/stages/stage.schemas.ts

@@ -6,6 +6,11 @@ import {StageKind} from './stage';
  * These are defined in a separate file to ensure they're bundled before Type.Ref() calls.
  */
 
+/** Result type for cross-field stage config validators. */
+export type StageValidationResult =
+  | {valid: true}
+  | {valid: false; error: string};
+
 /** StageTextConfig input validation. */
 export const StageTextConfigSchema = Type.Object(
   {

utils/src/stages/stage.validation.ts

@@ -1,17 +1,24 @@
-import {Type} from '@sinclair/typebox';
-import {StageKind} from './stage';
+import {Type, type TSchema} from '@sinclair/typebox';
+import {BaseStageConfig, StageKind} from './stage';
+import {type StageValidationResult} from './stage.schemas';
 import {
   AssetAllocationStageConfigData,
   MultiAssetAllocationStageConfigData,
 } from './asset_allocation_stage.validation';
-import {ChatStageConfigData} from './chat_stage.validation';
+import {
+  ChatStageConfigData,
+  validateChatStageConfig,
+} from './chat_stage.validation';
 import {ChipStageConfigData} from './chip_stage.validation';
 import {ComprehensionStageConfigData} from './comprehension_stage.validation';
 import {FlipCardStageConfigData} from './flipcard_stage.validation';
 import {RankingStageConfigData} from './ranking_stage.validation';
 import {InfoStageConfigData} from './info_stage.validation';
 import {PayoutStageConfigData} from './payout_stage.validation';
-import {PrivateChatStageConfigData} from './private_chat_stage.validation';
+import {
+  PrivateChatStageConfigData,
+  validatePrivateChatStageConfig,
+} from './private_chat_stage.validation';
 import {ProfileStageConfigData} from './profile_stage.validation';
 import {RevealStageConfigData} from './reveal_stage.validation';
 import {RoleStageConfigData} from './role_stage.validation';
@@ -35,28 +42,39 @@ export const StageKindData = Type.Enum(StageKind, {$id: 'StageKind'});
 // writeExperiment, updateStageConfig endpoints                              //
 // ************************************************************************* //
 
-/** Map of stage kinds to their validators */
-export const CONFIG_DATA = {
-  assetAllocation: AssetAllocationStageConfigData,
-  multiAssetAllocation: MultiAssetAllocationStageConfigData,
-  chat: ChatStageConfigData,
-  chip: ChipStageConfigData,
-  comprehension: ComprehensionStageConfigData,
-  flipcard: FlipCardStageConfigData,
-  info: InfoStageConfigData,
-  payout: PayoutStageConfigData,
-  privateChat: PrivateChatStageConfigData,
-  profile: ProfileStageConfigData,
-  ranking: RankingStageConfigData,
-  reveal: RevealStageConfigData,
-  role: RoleStageConfigData,
-  salesperson: SalespersonStageConfigData,
-  stockinfo: StockInfoStageConfigData,
-  surveyPerParticipant: SurveyPerParticipantStageConfigData,
-  survey: SurveyStageConfigData,
-  tos: TOSStageConfigData,
-  transfer: TransferStageConfigData,
+/** Stage config entry with schema and optional cross-field validator. */
+export interface StageConfigEntry {
+  schema: TSchema;
+  validate?: (stage: BaseStageConfig) => StageValidationResult;
+}
+
+/** Map of stage kinds to their schema and optional validator */
+export const CONFIG_DATA: Record<string, StageConfigEntry> = {
+  assetAllocation: {schema: AssetAllocationStageConfigData},
+  multiAssetAllocation: {schema: MultiAssetAllocationStageConfigData},
+  chat: {schema: ChatStageConfigData, validate: validateChatStageConfig},
+  chip: {schema: ChipStageConfigData},
+  comprehension: {schema: ComprehensionStageConfigData},
+  flipcard: {schema: FlipCardStageConfigData},
+  info: {schema: InfoStageConfigData},
+  payout: {schema: PayoutStageConfigData},
+  privateChat: {
+    schema: PrivateChatStageConfigData,
+    validate: validatePrivateChatStageConfig,
+  },
+  profile: {schema: ProfileStageConfigData},
+  ranking: {schema: RankingStageConfigData},
+  reveal: {schema: RevealStageConfigData},
+  role: {schema: RoleStageConfigData},
+  salesperson: {schema: SalespersonStageConfigData},
+  stockinfo: {schema: StockInfoStageConfigData},
+  surveyPerParticipant: {schema: SurveyPerParticipantStageConfigData},
+  survey: {schema: SurveyStageConfigData},
+  tos: {schema: TOSStageConfigData},
+  transfer: {schema: TransferStageConfigData},
 };
 
 /** StageConfig input validation (union of all stage types) */
-export const StageConfigData = Type.Union(Object.values(CONFIG_DATA));
+export const StageConfigData = Type.Union(
+  Object.values(CONFIG_DATA).map((entry) => entry.schema),
+);