Level 11.1: State contract finalization

- Enforced normalized state structure
- Prevented malformed state writes

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,22 +2,18 @@ MODEL: GPT-5.3-codex
 REASONING: high
 
 COMMAND:
-Implement BUILD_PR_LEVEL_11_1_AUTHORITATIVE_APPLY_GUARD.
+Implement BUILD_PR_LEVEL_11_1_STATE_CONTRACT_FINALIZATION.
 
 Modify ONLY:
 src/advanced/state/transitions.js
 
 Change:
-- Wrap authoritativeApply calls with:
-  if (context && context.authoritative === true)
-
-Do NOT:
-- change APIs
-- refactor unrelated logic
+- Enforce normalized structure for worldState mutations
+- Reject malformed payloads early
 
 Validation:
-- Passive mode does not invoke authoritativeApply
-- Existing tests pass
+- No undefined state fields
+- Tests pass
 
 Output:
-<project folder>/tmp/BUILD_PR_LEVEL_11_1_AUTHORITATIVE_APPLY_GUARD.zip
+<project folder>/tmp/BUILD_PR_LEVEL_11_1_STATE_CONTRACT_FINALIZATION.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1,4 +1,4 @@
-Level 11.1: Authoritative apply guard
+Level 11.1: State contract finalization
 
-- Restricted authoritativeApply execution
-- No API changes
+- Enforced normalized state structure
+- Prevented malformed state writes

docs/dev/reports/change_summary.txt

@@ -1 +1 @@
-Added guard to ensure authoritativeApply executes only in authoritative context.
+Finalized state contract boundaries and normalization enforcement.

docs/dev/reports/validation_checklist.txt

@@ -1,5 +1,4 @@
 [ ] transitions.js modified only
-[ ] authoritativeApply guarded
-[ ] Passive mode safe
-[ ] No API changes
+[ ] State normalized
+[ ] No undefined shapes
 [ ] Tests pass

docs/pr/BUILD_PR_LEVEL_11_1_STATE_CONTRACT_FINALIZATION.md

@@ -0,0 +1,19 @@
+# BUILD PR — Level 11.1 State Contract Finalization
+
+## Purpose
+Finalize state contract boundaries to ensure consistent shape and safe reads.
+
+## Scope
+- Validation + contract enforcement only
+- No API changes
+
+## File
+- src/advanced/state/transitions.js
+
+## Change
+- Ensure all state writes produce normalized structure
+- Reject malformed state payloads at boundary
+
+## Validation
+- No undefined state shapes
+- Existing tests pass

src/advanced/state/transitions.js

@@ -79,6 +79,37 @@ function recalcObjectiveSummary(objectivesById) {
   };
 }
 
+function ensureNormalizedWorldState(snapshot) {
+  if (!isPlainObject(snapshot.worldState)) {
+    snapshot.worldState = {};
+  }
+
+  const worldState = snapshot.worldState;
+
+  if (!isPlainObject(worldState.scores)) {
+    worldState.scores = {};
+  }
+  worldState.scores.total = toFiniteNumber(worldState.scores.total, 0);
+  worldState.scores.rewardPoints = toFiniteNumber(worldState.scores.rewardPoints, 0);
+  if (worldState.scores.rank === undefined) {
+    worldState.scores.rank = null;
+  }
+
+  if (!isPlainObject(worldState.objectives)) {
+    worldState.objectives = {};
+  }
+  if (!isPlainObject(worldState.objectives.byId)) {
+    worldState.objectives.byId = {};
+  }
+  worldState.objectives.summary = recalcObjectiveSummary(worldState.objectives.byId);
+
+  if (!isPlainObject(worldState.flags)) {
+    worldState.flags = {};
+  }
+
+  return worldState;
+}
+
 function validateTransitionGameMode(payload) {
   const nextMode = payload && payload.nextMode;
   if (typeof nextMode !== 'string' || !nextMode.trim()) {
@@ -114,25 +145,18 @@ function validateApplyScoreDelta(payload) {
   if (!Number.isFinite(normalizedDelta)) {
     return { ok: false, reason: 'applyScoreDelta requires finite numeric payload.delta.' };
   }
+  if (payload.rewardDelta !== undefined && !Number.isFinite(Number(payload.rewardDelta))) {
+    return { ok: false, reason: 'applyScoreDelta payload.rewardDelta must be finite numeric when provided.' };
+  }
   return { ok: true };
 }
 
 function applyAuthoritativeScoreDelta(snapshot, payload, context = {}) {
   if (isPassiveModeContext(context)) {
     return { changes: [] };
   }
-  if (!snapshot.worldState || !isPlainObject(snapshot.worldState)) {
-    snapshot.worldState = {};
-  }
-  if (!isPlainObject(snapshot.worldState.scores)) {
-    snapshot.worldState.scores = {
-      total: 0,
-      rewardPoints: 0,
-      rank: null
-    };
-  }
-
-  const scores = snapshot.worldState.scores;
+  const worldState = ensureNormalizedWorldState(snapshot);
+  const scores = worldState.scores;
   const currentTotal = toFiniteNumber(scores.total, 0);
   const currentRewardPoints = toFiniteNumber(scores.rewardPoints, 0);
   const delta = toFiniteNumber(payload.delta, 0);
@@ -177,17 +201,8 @@ function applyAuthoritativeObjectiveProgress(snapshot, payload, context = {}) {
   }
   const now = typeof context.now === 'function' ? context.now : () => Date.now();
   const objectiveId = String(payload.objectiveId || '').trim();
-  const objectives = snapshot.worldState && snapshot.worldState.objectives
-    ? snapshot.worldState.objectives
-    : { summary: { total: 0, completed: 0, active: 0 }, byId: {} };
-  if (!snapshot.worldState.objectives) {
-    snapshot.worldState.objectives = objectives;
-  }
-
-  if (!isPlainObject(objectives.byId)) objectives.byId = {};
-  if (!isPlainObject(objectives.summary)) {
-    objectives.summary = { total: 0, completed: 0, active: 0 };
-  }
+  const worldState = ensureNormalizedWorldState(snapshot);
+  const objectives = worldState.objectives;
 
   const existing = isPlainObject(objectives.byId[objectiveId]) ? objectives.byId[objectiveId] : {};
   objectives.byId[objectiveId] = {