feat: 게임 시계 reconciliation 권위 기반 추가

app/game-api/src/context.ts

@@ -65,7 +65,15 @@ export type WorldStateMeta = z.infer<typeof zWorldStateMeta>;
 
 type PrismaWorldStateRow = GamePrisma.WorldStateGetPayload<Record<string, never>>;
 type PrismaGeneralRow = GamePrisma.GeneralGetPayload<Record<string, never>>;
-type WorldClockFields = 'clockBaseTime' | 'clockTick' | 'clockMode' | 'clockWallAnchor' | 'lastTurnTick';
+type WorldClockFields =
+    | 'clockBaseTime'
+    | 'clockTick'
+    | 'clockMode'
+    | 'clockWallAnchor'
+    | 'lastTurnTick'
+    | 'clockPhase'
+    | 'clockRevision'
+    | 'deadlineGeneration';
 type GeneralClockFields = 'turnTick' | 'recentWarTick';
 
 // Transitional API fixtures may still model the pre-clock row. Runtime Prisma

app/game-api/src/services/gameClock.ts

@@ -1,4 +1,10 @@
-import { GameClock, type GameClockMode } from '@sammo-ts/common';
+import {
+    GameClock,
+    inferClockPhase,
+    parseGameClockPhase,
+    type GameClockMode,
+    type GameClockPhase,
+} from '@sammo-ts/common';
 
 import type { DatabaseClient } from '../context.js';
 
@@ -7,6 +13,9 @@ export interface CurrentGameTime {
     wallNow: Date;
     tick: number | null;
     mode: GameClockMode | null;
+    phase?: GameClockPhase | null;
+    revision?: number | null;
+    deadlineGeneration?: number | null;
     running: boolean;
     startsAt: Date | null;
     dateToTick(date: Date): number | null;
@@ -19,6 +28,9 @@ export const loadCurrentGameTime = async (db: DatabaseClient, wallNow = new Date
             wallNow,
             tick: null,
             mode: null,
+            phase: null,
+            revision: null,
+            deadlineGeneration: null,
             running: true,
             startsAt: null,
             dateToTick: () => null,
@@ -32,6 +44,9 @@ export const loadCurrentGameTime = async (db: DatabaseClient, wallNow = new Date
             clockMode: true,
             clockWallAnchor: true,
             tickSeconds: true,
+            clockPhase: true,
+            clockRevision: true,
+            deadlineGeneration: true,
         },
     });
     if (!state?.clockBaseTime || state.clockTick === null || !state.clockWallAnchor) {
@@ -40,32 +55,53 @@ export const loadCurrentGameTime = async (db: DatabaseClient, wallNow = new Date
             wallNow,
             tick: null,
             mode: null,
+            phase: null,
+            revision: null,
+            deadlineGeneration: null,
             running: true,
             startsAt: null,
             dateToTick: () => null,
         };
     }
     const mode: GameClockMode = state.clockMode === 'manual' ? 'manual' : 'realtime';
+    // During the dual-read migration an older profile (or a rolling-deploy
+    // fixture) can lack clock_phase. Preserve the existing future-anchor
+    // PREOPEN contract until every profile has the authoritative column.
+    const phase = state.clockPhase
+        ? parseGameClockPhase(state.clockPhase)
+        : mode === 'realtime' && wallNow.getTime() < state.clockWallAnchor.getTime()
+          ? 'PREOPEN'
+          : inferClockPhase(mode);
     const storedTick = Number(state.clockTick);
     if (!Number.isSafeInteger(storedTick)) {
         throw new Error(`world_state.clock_tick is outside the JavaScript safe integer range: ${state.clockTick}`);
     }
+    const revision = Number(state.clockRevision ?? 1n);
+    const deadlineGeneration = Number(state.deadlineGeneration ?? 1n);
+    if (!Number.isSafeInteger(revision) || !Number.isSafeInteger(deadlineGeneration)) {
+        throw new Error('world_state clock revision or deadline generation is outside the safe integer range.');
+    }
     const clock = new GameClock({
         baseTime: state.clockBaseTime,
         tick: storedTick,
         mode,
         wallAnchor: state.clockWallAnchor,
         turnSeconds: state.tickSeconds,
+        phase,
+        revision,
     });
     const tick = clock.nowTick(wallNow);
-    const running = mode === 'realtime' && wallNow.getTime() >= state.clockWallAnchor.getTime();
+    const running = phase === 'RUNNING' && mode === 'realtime';
     return {
         now: clock.tickToDate(tick),
         wallNow,
         tick,
         mode,
+        phase,
+        revision,
+        deadlineGeneration,
         running,
-        startsAt: mode === 'realtime' && !running ? state.clockWallAnchor : null,
+        startsAt: phase === 'PREOPEN' ? state.clockWallAnchor : null,
         dateToTick: (date) => clock.dateToTick(date),
     };
 };

app/game-api/test/gameClock.test.ts

@@ -3,7 +3,10 @@ import { describe, expect, it, vi } from 'vitest';
 import type { DatabaseClient } from '../src/context.js';
 import { loadCurrentGameTime } from '../src/services/gameClock.js';
 
-const buildDatabase = (mode: 'realtime' | 'manual' = 'realtime'): DatabaseClient =>
+const buildDatabase = (
+    mode: 'realtime' | 'manual' = 'realtime',
+    phase: 'PREOPEN' | 'RUNNING' | 'MANUAL' = mode === 'manual' ? 'MANUAL' : 'PREOPEN'
+): DatabaseClient =>
     ({
         worldState: {
             findFirst: vi.fn(async () => ({
@@ -12,6 +15,9 @@ const buildDatabase = (mode: 'realtime' | 'manual' = 'realtime'): DatabaseClient
                 clockMode: mode,
                 clockWallAnchor: new Date('2026-08-21T11:00:00.000Z'),
                 tickSeconds: 600,
+                clockPhase: phase,
+                clockRevision: 1n,
+                deadlineGeneration: 1n,
             })),
         },
     }) as unknown as DatabaseClient;
@@ -26,11 +32,15 @@ describe('current game time projection', () => {
             wallNow: new Date('2026-08-21T10:30:00.000Z'),
             tick: -108_000_000,
             mode: 'realtime',
+            phase: 'PREOPEN',
             running: false,
             startsAt: new Date('2026-08-21T11:00:00.000Z'),
         });
 
-        const opened = await loadCurrentGameTime(db, new Date('2026-08-21T11:00:05.000Z'));
+        const opened = await loadCurrentGameTime(
+            buildDatabase('realtime', 'RUNNING'),
+            new Date('2026-08-21T11:00:05.000Z')
+        );
         expect(opened).toMatchObject({
             now: new Date('2026-08-21T11:00:05.000Z'),
             tick: 300_000,