Level 11.1: Event whitelist guard

- Enforced allowed event types
- No API changes

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,21 +2,22 @@ MODEL: GPT-5.3-codex
 REASONING: high
 
 COMMAND:
-Implement BUILD_PR_LEVEL_11_1_PASSIVE_MODE_GUARD.
+Implement BUILD_PR_LEVEL_11_1_EVENT_WHITELIST_GUARD.
 
 Modify ONLY:
 src/advanced/state/transitions.js
 
 Change:
-- Add guard to prevent authoritativeApply execution when in passive mode
+- Before emitting eventType, validate it exists in WORLD_GAME_STATE_EVENT_TYPES
+- Reject if not present
 
 Do NOT:
 - change APIs
 - refactor unrelated logic
 
 Validation:
-- Passive mode does not mutate state
+- Unknown event types rejected
 - Existing tests pass
 
 Output:
-<project folder>/tmp/BUILD_PR_LEVEL_11_1_PASSIVE_MODE_GUARD.zip
+<project folder>/tmp/BUILD_PR_LEVEL_11_1_EVENT_WHITELIST_GUARD.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1,4 +1,4 @@
-Level 11.1: Passive mode guard
+Level 11.1: Event whitelist guard
 
-- Prevented authoritative mutations in passive mode
+- Enforced allowed event types
 - No API changes

docs/dev/reports/change_summary.txt

@@ -1 +1 @@
-Added passive mode guard to prevent state mutation during non-authoritative execution.
+Added guard to ensure only whitelisted event types are emitted from transitions.

docs/dev/reports/validation_checklist.txt

@@ -1,5 +1,4 @@
 [ ] transitions.js modified only
-[ ] Passive mode does not mutate
-[ ] Authoritative mode unchanged
+[ ] Unknown event types rejected
 [ ] No API changes
 [ ] Tests pass

docs/pr/BUILD_PR_LEVEL_11_1_EVENT_WHITELIST_GUARD.md

@@ -0,0 +1,18 @@
+# BUILD PR — Level 11.1 Event Whitelist Guard
+
+## Purpose
+Ensure only approved event types are emitted from transitions.
+
+## Scope
+- Validation guard only
+- No API changes
+
+## File
+- src/advanced/state/transitions.js
+
+## Change
+- Enforce eventType must exist in WORLD_GAME_STATE_EVENT_TYPES
+
+## Validation
+- Unknown event types rejected
+- Existing tests pass

src/advanced/state/transitions.js

@@ -9,13 +9,52 @@ import { WORLD_GAME_STATE_EVENT_TYPES } from './constants.js';
 import { isPlainObject } from '../../shared/utils/objectUtils.js';
 import { toFiniteNumber } from '../../shared/math/numberNormalization.js';
 
+const ALLOWED_TRANSITION_EVENT_TYPES = new Set(Object.values(WORLD_GAME_STATE_EVENT_TYPES));
+
 function isPassiveModeContext(context) {
   if (!isPlainObject(context)) return false;
   if (context.passiveMode === true) return true;
   if (typeof context.mode === 'string' && context.mode.trim().toLowerCase() === 'passive') return true;
   return false;
 }
 
+function validateTransitionEventType(eventType, transitionName) {
+  const normalizedEventType = String(eventType || '').trim();
+  if (!ALLOWED_TRANSITION_EVENT_TYPES.has(normalizedEventType)) {
+    return {
+      ok: false,
+      reason: `${String(transitionName || 'transition')} has unapproved eventType.`
+    };
+  }
+  return { ok: true };
+}
+
+function createWhitelistedTransition({
+  transitionName,
+  validate,
+  eventType,
+  authoritativeApply
+}) {
+  const baseValidate = typeof validate === 'function'
+    ? validate
+    : () => ({ ok: false, reason: `${String(transitionName || 'transition')} missing validate handler.` });
+
+  const definition = {
+    eventType: String(eventType || ''),
+    validate(payload, context) {
+      const eventTypeValidation = validateTransitionEventType(definition.eventType, transitionName);
+      if (!eventTypeValidation.ok) return eventTypeValidation;
+      return baseValidate(payload, context);
+    }
+  };
+
+  if (typeof authoritativeApply === 'function') {
+    definition.authoritativeApply = authoritativeApply;
+  }
+
+  return definition;
+}
+
 function recalcObjectiveSummary(objectivesById) {
   const objectiveIds = Object.keys(objectivesById);
   let completed = 0;
@@ -191,36 +230,43 @@ function validateResolveRunOutcome(payload) {
 
 function createTransitionRegistry() {
   return {
-    transitionGameMode: {
+    transitionGameMode: createWhitelistedTransition({
+      transitionName: 'transitionGameMode',
       validate: validateTransitionGameMode,
       eventType: WORLD_GAME_STATE_EVENT_TYPES.GAME_MODE_CHANGED
-    },
-    transitionPhase: {
+    }),
+    transitionPhase: createWhitelistedTransition({
+      transitionName: 'transitionPhase',
       validate: validateTransitionPhase,
       eventType: WORLD_GAME_STATE_EVENT_TYPES.GAME_PHASE_CHANGED
-    },
-    advanceWave: {
+    }),
+    advanceWave: createWhitelistedTransition({
+      transitionName: 'advanceWave',
       validate: validateAdvanceWave,
       eventType: WORLD_GAME_STATE_EVENT_TYPES.TRANSITION_APPLIED
-    },
-    applyScoreDelta: {
+    }),
+    applyScoreDelta: createWhitelistedTransition({
+      transitionName: 'applyScoreDelta',
       validate: validateApplyScoreDelta,
       eventType: WORLD_GAME_STATE_EVENT_TYPES.TRANSITION_APPLIED,
       authoritativeApply: applyAuthoritativeScoreDelta
-    },
-    updateObjectiveProgress: {
+    }),
+    updateObjectiveProgress: createWhitelistedTransition({
+      transitionName: 'updateObjectiveProgress',
       validate: validateUpdateObjectiveProgress,
       eventType: WORLD_GAME_STATE_EVENT_TYPES.OBJECTIVE_SNAPSHOT_UPDATED,
       authoritativeApply: applyAuthoritativeObjectiveProgress
-    },
-    setWorldFlag: {
+    }),
+    setWorldFlag: createWhitelistedTransition({
+      transitionName: 'setWorldFlag',
       validate: validateSetWorldFlag,
       eventType: WORLD_GAME_STATE_EVENT_TYPES.TRANSITION_APPLIED
-    },
-    resolveRunOutcome: {
+    }),
+    resolveRunOutcome: createWhitelistedTransition({
+      transitionName: 'resolveRunOutcome',
       validate: validateResolveRunOutcome,
       eventType: WORLD_GAME_STATE_EVENT_TYPES.TRANSITION_APPLIED
-    }
+    })
   };
 }