Make the promotion-gate authoritative/passive handoff boundary explicit across the exact gate/state/snapshot files.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,8 +2,8 @@ MODEL: GPT-5.4-codex
 REASONING: high
 
 COMMAND:
-Execute exactly docs/pr/BUILD_PR_PROMOTION_GATE_55_CONTRACT_AND_PUBLIC_READERS.md.
+Execute exactly docs/pr/BUILD_PR_PROMOTION_GATE_56_AUTHORITATIVE_PASSIVE_HANDOFF_BOUNDARY.md.
 Modify only the exact target files listed in the PR doc.
 Do not expand scope.
 Package the delta zip to:
-<project folder>/tmp/BUILD_PR_PROMOTION_GATE_55_CONTRACT_AND_PUBLIC_READERS_delta.zip
+<project folder>/tmp/BUILD_PR_PROMOTION_GATE_56_AUTHORITATIVE_PASSIVE_HANDOFF_BOUNDARY_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-Establish an explicit shared public-reader contract for the promotion gate and reduce local gate-specific state read assumptions.
+Make the promotion-gate authoritative/passive handoff boundary explicit across the exact gate/state/snapshot files.

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-After commit, inspect the promotion-gate delta and build the next exact slice only if authoritative/passive handoff files are explicit.
+After commit, inspect the delta and build the next exact promotion-gate slice only if observability/abort files are explicit.

docs/dev/reports/change_summary.txt

@@ -1,3 +1,3 @@
-- narrow promotion-gate BUILD focused on contract and public-reader boundary only
-- exact target files limited to createPromotionGate + shared state reader + promotion snapshot
+- narrow promotion-gate BUILD focused on authoritative/passive handoff boundary only
+- exact target files limited to promotion gate + world game state system + promotion snapshot
 - explicitly excludes replay/timeline/sample/game/debug widening

docs/dev/reports/file_tree.txt

@@ -1,10 +1,10 @@
-docs/pr/BUILD_PR_PROMOTION_GATE_55_CONTRACT_AND_PUBLIC_READERS.md
+docs/pr/BUILD_PR_PROMOTION_GATE_56_AUTHORITATIVE_PASSIVE_HANDOFF_BOUNDARY.md
 docs/dev/codex_commands.md
 docs/dev/commit_comment.txt
 docs/dev/next_command.txt
 docs/dev/reports/file_tree.txt
 docs/dev/reports/change_summary.txt
 docs/dev/reports/validation_checklist.txt
 src/advanced/promotion/createPromotionGate.js
-src/shared/state/getState.js
+src/advanced/state/createWorldGameStateSystem.js
 src/shared/state/createPromotionStateSnapshot.js

docs/pr/BUILD_PR_PROMOTION_GATE_56_AUTHORITATIVE_PASSIVE_HANDOFF_BOUNDARY.md

@@ -0,0 +1,56 @@
+# BUILD PR — Promotion Gate Authoritative/Passive Handoff Boundary
+
+## Purpose
+Make the authoritative/passive handoff boundary explicit for the promotion-gate lane without widening into replay, timeline, sample, or repo-structure work.
+
+## Exact Target Files
+- `src/advanced/promotion/createPromotionGate.js`
+- `src/advanced/state/createWorldGameStateSystem.js`
+- `src/shared/state/createPromotionStateSnapshot.js`
+
+## Why These Files
+This PR stays inside the existing promotion-gate and authoritative-state lane:
+- `createPromotionGate.js` is the promotion-gate owner
+- `createWorldGameStateSystem.js` is the authoritative world-state system entry
+- `createPromotionStateSnapshot.js` is the shared promotion snapshot contract already used in the lane
+
+This PR must not widen beyond these exact files.
+
+## Required Code Changes
+1. In `src/advanced/promotion/createPromotionGate.js`
+   - make the handoff boundary between passive and authoritative modes explicit
+   - ensure the gate names or uses a single handoff decision path
+   - preserve current runtime semantics except where needed to remove ambiguous handoff behavior
+
+2. In `src/advanced/state/createWorldGameStateSystem.js`
+   - align the world game state system with the explicit handoff path
+   - make the minimum authoritative/passive transition boundary readable from the gate-facing integration
+   - do not broaden this into general state cleanup
+
+3. In `src/shared/state/createPromotionStateSnapshot.js`
+   - update the shared promotion snapshot shape only if required to support the explicit handoff boundary
+   - keep this limited to handoff compatibility, not general snapshot redesign
+
+## Hard Constraints
+- exact files only
+- do not modify replay files
+- do not modify timeline files
+- do not modify selectors beyond what the exact files already require
+- do not modify sample files
+- do not modify game files
+- do not widen into debug UI work
+- do not perform repo-wide state cleanup
+- do not change unrelated state semantics
+
+## Validation Steps
+- confirm only the exact target files changed
+- confirm the promotion gate has a single explicit handoff path
+- confirm authoritative vs passive behavior boundary is explicit in the touched code
+- confirm imports/exports resolve
+- confirm no unrelated refactor or formatting-only churn was introduced
+
+## Acceptance Criteria
+- authoritative/passive handoff boundary is explicit
+- gate-to-state-system handoff path is singular and readable
+- promotion snapshot contract remains coherent with the handoff boundary
+- no replay/timeline/sample/game/debug scope expansion occurred

src/advanced/promotion/createPromotionGate.js

@@ -39,6 +39,15 @@ function sanitizeRequiredCriteria(requiredCriteria) {
   return out;
 }
 
+function createHandoffDecision({ promoted, promotedNow }) {
+  return {
+    decisionPath: 'PROMOTION_GATE_HANDOFF',
+    fromMode: promotedNow ? 'passive' : (promoted ? 'authoritative' : 'passive'),
+    toMode: promoted ? 'authoritative' : 'passive',
+    shouldHandoff: Boolean(promotedNow)
+  };
+}
+
 function createPromotionGate(options = {}) {
   const now = typeof options.now === 'function' ? options.now : () => Date.now();
   const requiredCriteria = sanitizeRequiredCriteria(options.requiredCriteria);
@@ -127,6 +136,7 @@ function createPromotionGate(options = {}) {
     const readiness = promoted
       ? 'authoritative'
       : (allCriteriaMet ? 'stabilizing' : 'passive');
+    const handoff = createHandoffDecision({ promoted, promotedNow });
     const evaluation = {
       transitionName: String(transitionName || ''),
       frame: frame !== undefined && frame !== null ? Number(frame) : null,
@@ -144,6 +154,7 @@ function createPromotionGate(options = {}) {
         unmet: unmetCriteria,
         allMet: allCriteriaMet
       },
+      handoff,
       reason: lastReason,
       metrics: getMetrics()
     };

src/advanced/state/createWorldGameStateSystem.js

@@ -106,6 +106,15 @@ function normalizeCriteriaMap(criteria, requiredCriteria) {
   return normalized;
 }
 
+function createPromotionHandoffDecision({ promoted, promotedNow }) {
+  return {
+    decisionPath: 'PROMOTION_GATE_HANDOFF',
+    fromMode: promotedNow ? 'passive' : (promoted ? 'authoritative' : 'passive'),
+    toMode: promoted ? 'authoritative' : 'passive',
+    shouldHandoff: Boolean(promotedNow)
+  };
+}
+
 function createInlinePromotionGate({
   now,
   requiredCriteria,
@@ -185,6 +194,7 @@ function createInlinePromotionGate({
     }
 
     const readiness = promoted ? 'authoritative' : (allCriteriaMet ? 'stabilizing' : 'passive');
+    const handoff = createPromotionHandoffDecision({ promoted, promotedNow });
     const evaluation = {
       transitionName: String(transitionName || ''),
       frame: frame !== undefined && frame !== null ? Number(frame) : null,
@@ -202,6 +212,7 @@ function createInlinePromotionGate({
         unmet,
         allMet: allCriteriaMet
       },
+      handoff,
       reason: lastReason,
       metrics: getMetrics()
     };
@@ -227,6 +238,10 @@ function createInlinePromotionGate({
         stabilityWindowFrames: windowFrames,
         lastReason,
         lastEvaluation,
+        handoff: createPromotionHandoffDecision({
+          promoted,
+          promotedNow: false
+        }),
         cloneLastEvaluation: (value) => (value ? cloneDeep(value) : null)
       });
     }
@@ -323,7 +338,13 @@ function createWorldGameStateSystem(options = {}) {
       frame: resolveFrameFromMeta(meta, payload)
     });
 
-    if (evaluation.promotedNow) {
+    const handoff = isPlainObject(evaluation?.handoff)
+      ? evaluation.handoff
+      : createPromotionHandoffDecision({
+          promoted: Boolean(evaluation?.promoted),
+          promotedNow: Boolean(evaluation?.promotedNow)
+        });
+    if (handoff.shouldHandoff) {
       activeMode = 'authoritative';
     }
 

src/shared/state/createPromotionStateSnapshot.js

@@ -2,15 +2,21 @@ function defaultCloneLastEvaluation(value) {
   return value ? { ...value } : null;
 }
 
+function cloneHandoff(value) {
+  if (!value || typeof value !== 'object') return null;
+  return { ...value };
+}
+
 export function createPromotionStateSnapshot({
   promoted,
   stableFrames,
   stabilityWindowFrames,
   lastReason,
   lastEvaluation,
+  handoff,
   cloneLastEvaluation
 }) {
-  return {
+  const snapshot = {
     promoted,
     stableFrames,
     stabilityWindowFrames,
@@ -19,4 +25,8 @@ export function createPromotionStateSnapshot({
       ? cloneLastEvaluation
       : defaultCloneLastEvaluation)(lastEvaluation)
   };
+  if (handoff !== undefined) {
+    snapshot.handoff = cloneHandoff(handoff);
+  }
+  return snapshot;
 }