feat: 시계 reconciliation 워커와 명령 경계 완성

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

@@ -0,0 +1,92 @@
+import { parseGameClockPhase } from '@sammo-ts/common';
+
+import type { DatabaseClient } from '../context.js';
+
+const safeInteger = (value: bigint, label: string): number => {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result)) throw new Error(`${label} is outside the safe integer range.`);
+    return result;
+};
+
+export const loadClockReadiness = async (db: DatabaseClient) => {
+    if (!db.clockProjectionOutbox) {
+        return {
+            reconciliationComplete: false,
+            gameplayEnabled: false,
+            phase: null,
+            revision: null,
+            deadlineGeneration: null,
+            incompleteOutboxCount: null,
+        };
+    }
+    const [world, incompleteOutboxCount] = await Promise.all([
+        db.worldState.findFirst({
+            orderBy: { id: 'asc' },
+            select: { clockPhase: true, clockRevision: true, deadlineGeneration: true },
+        }),
+        db.clockProjectionOutbox.count({ where: { status: { not: 'APPLIED' } } }),
+    ]);
+    if (!world) {
+        return {
+            reconciliationComplete: false,
+            gameplayEnabled: false,
+            phase: null,
+            revision: null,
+            deadlineGeneration: null,
+            incompleteOutboxCount,
+        };
+    }
+    const phase = parseGameClockPhase(world.clockPhase);
+    return {
+        reconciliationComplete: phase !== 'RECONCILING' && incompleteOutboxCount === 0,
+        gameplayEnabled: phase === 'RUNNING' || phase === 'MANUAL',
+        phase,
+        revision: safeInteger(world.clockRevision, 'clock revision'),
+        deadlineGeneration: safeInteger(world.deadlineGeneration, 'deadline generation'),
+        incompleteOutboxCount,
+    };
+};
+
+export const loadClockAdminStatus = async (db: DatabaseClient) => {
+    const readiness = await loadClockReadiness(db);
+    if (!db.clockSuspension) {
+        return { ...readiness, latestReconciliation: null };
+    }
+    const latest = await db.clockSuspension.findFirst({
+        orderBy: { createdAt: 'desc' },
+        include: {
+            participants: { orderBy: { participantKey: 'asc' } },
+            projectionOutbox: { orderBy: { id: 'asc' } },
+        },
+    });
+    if (!latest) return { ...readiness, latestReconciliation: null };
+    return {
+        ...readiness,
+        latestReconciliation: {
+            id: latest.id,
+            source: latest.source,
+            policy: latest.policy,
+            status: latest.status,
+            sourceRevision: safeInteger(latest.sourceRevision, 'source revision'),
+            targetRevision: safeInteger(latest.targetRevision, 'target revision'),
+            cutTick: safeInteger(latest.cutTick, 'cut tick'),
+            alignedTick: latest.alignedTick === null ? null : safeInteger(latest.alignedTick, 'aligned tick'),
+            participantChecksumBefore: latest.participantChecksumBefore,
+            participantChecksumAfter: latest.participantChecksumAfter,
+            participants: latest.participants.map((participant) => ({
+                key: participant.participantKey,
+                policy: participant.policy,
+                beforeChecksum: participant.beforeChecksum,
+                afterChecksum: participant.afterChecksum,
+                affectedCount: participant.affectedCount,
+            })),
+            outbox: latest.projectionOutbox.map((entry) => ({
+                id: entry.id.toString(),
+                targetRevision: safeInteger(entry.targetRevision, 'outbox target revision'),
+                status: entry.status,
+                attempts: entry.attempts,
+                lastError: entry.lastError,
+            })),
+        },
+    };
+};

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

@@ -0,0 +1,55 @@
+import type { CurrentGameTime } from './gameClock.js';
+
+interface ClockFenceRedis {
+    eval(script: string, options: { keys: string[]; arguments: string[] }): Promise<unknown>;
+}
+
+const BOOTSTRAP_CLOCK_FENCE_SCRIPT = `
+local revision = redis.call('GET', KEYS[1])
+local generation = redis.call('GET', KEYS[2])
+local phase = redis.call('GET', KEYS[3])
+if not revision and not generation and not phase then
+    redis.call('SET', KEYS[1], ARGV[1])
+    redis.call('SET', KEYS[2], ARGV[2])
+    redis.call('SET', KEYS[3], ARGV[3])
+    return 1
+end
+if revision == ARGV[1] and generation == ARGV[2] and phase == ARGV[3] then
+    return 2
+end
+return 0
+`;
+
+export interface ActiveRedisClockFence {
+    activeRevisionKey: string;
+    deadlineGenerationKey: string;
+    phaseKey: string;
+    revision: number;
+    generation: number;
+}
+
+export const ensureActiveRedisClockFence = async (
+    redis: ClockFenceRedis,
+    profileName: string,
+    gameTime: CurrentGameTime
+): Promise<ActiveRedisClockFence | null> => {
+    if (
+        gameTime.phase !== 'RUNNING' ||
+        !Number.isSafeInteger(gameTime.revision) ||
+        !Number.isSafeInteger(gameTime.deadlineGeneration)
+    ) {
+        return null;
+    }
+    const fence: ActiveRedisClockFence = {
+        activeRevisionKey: `sammo:${profileName}:clock:active-revision`,
+        deadlineGenerationKey: `sammo:${profileName}:clock:deadline-generation`,
+        phaseKey: `sammo:${profileName}:clock:phase`,
+        revision: gameTime.revision!,
+        generation: gameTime.deadlineGeneration!,
+    };
+    const result = await redis.eval(BOOTSTRAP_CLOCK_FENCE_SCRIPT, {
+        keys: [fence.activeRevisionKey, fence.deadlineGenerationKey, fence.phaseKey],
+        arguments: [String(fence.revision), String(fence.generation), 'RUNNING'],
+    });
+    return Number(result) === 1 || Number(result) === 2 ? fence : null;
+};