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

2026-09-03 09:40:48 +00:00
parent ae7d55ef47
commit a3e2bf90ae
46 changed files with 3011 additions and 219 deletions
@@ -8,6 +8,9 @@ export interface TournamentKeys {
    sourceRevisionKey: string;
    sourceRevisionChannel: string;
    realtimeEventChannel: string;
+    activeClockRevisionKey: string;
+    deadlineGenerationKey: string;
+    clockPhaseKey: string;
 }

 export const buildTournamentKeys = (profileName: string): TournamentKeys => ({
@@ -18,4 +21,7 @@ export const buildTournamentKeys = (profileName: string): TournamentKeys => ({
    sourceRevisionKey: `sammo:${profileName}:tournament:source-revision`,
    sourceRevisionChannel: `sammo:${profileName}:tournament:source-changed`,
    realtimeEventChannel: buildGameEventChannel(profileName),
+    activeClockRevisionKey: `sammo:${profileName}:clock:active-revision`,
+    deadlineGenerationKey: `sammo:${profileName}:clock:deadline-generation`,
+    clockPhaseKey: `sammo:${profileName}:clock:phase`,
 });
@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { parseTournamentSourceRevision, writeTournamentProjection } from '@sammo-ts/common';
+import { parseTournamentSourceRevision, writeTournamentProjection, type TournamentClockFence } from '@sammo-ts/common';
 import { z } from 'zod';

 import type { TournamentKeys } from './keys.js';
@@ -37,8 +37,12 @@ const zTournamentState = z
        openMonth: z.number().int(),
        termSeconds: z.number(),
        nextAt: z.string(),
+        nextTick: z.number().int().safe().optional(),
+        clockRevision: z.number().int().positive().safe().optional(),
+        deadlineGeneration: z.number().int().positive().safe().optional(),
        bettingId: z.number().int().optional(),
        bettingCloseAt: z.string().optional(),
+        bettingCloseTick: z.number().int().safe().optional(),
        winnerId: z.number().int().optional(),
        bettingSettled: z.boolean().optional(),
        rewardSettled: z.boolean().optional(),
@@ -131,12 +135,62 @@ const parseProjection = <T>(raw: string | null, key: string, schema: z.ZodType<T
    return parsed.data;
 };

+export interface TournamentClockContext {
+    phase: 'RUNNING';
+    revision: number;
+    deadlineGeneration: number;
+    dateToTick(date: Date): number | null;
+}
+
+const parseDeadlineTick = (value: string, context: TournamentClockContext, field: string): number => {
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new Error(`Tournament ${field} is not a valid instant.`);
+    }
+    const tick = context.dateToTick(date);
+    if (tick === null || !Number.isSafeInteger(tick)) {
+        throw new Error(`Tournament ${field} cannot be represented in the active game clock.`);
+    }
+    return tick;
+};
+
+export const stampTournamentClock = (state: TournamentState, context: TournamentClockContext): TournamentState => ({
+    ...state,
+    nextTick: parseDeadlineTick(state.nextAt, context, 'nextAt'),
+    clockRevision: context.revision,
+    deadlineGeneration: context.deadlineGeneration,
+    ...(state.bettingCloseAt
+        ? { bettingCloseTick: parseDeadlineTick(state.bettingCloseAt, context, 'bettingCloseAt') }
+        : { bettingCloseTick: undefined }),
+});
+
+const toClockFence = (keys: TournamentKeys, context: TournamentClockContext): TournamentClockFence => ({
+    activeRevisionKey: keys.activeClockRevisionKey,
+    deadlineGenerationKey: keys.deadlineGenerationKey,
+    phaseKey: keys.clockPhaseKey,
+    revision: context.revision,
+    deadlineGeneration: context.deadlineGeneration,
+    phase: context.phase,
+});
+
 export class TournamentStore {
+    private clockContext: TournamentClockContext | null = null;
+
    constructor(
        private readonly redis: RedisClientLike,
        private readonly keys: TournamentKeys
    ) {}

+    async withClockContext<T>(context: TournamentClockContext, operation: () => Promise<T>): Promise<T> {
+        const previous = this.clockContext;
+        this.clockContext = context;
+        try {
+            return await operation();
+        } finally {
+            this.clockContext = previous;
+        }
+    }
+
    async withMutationLock<T>(operation: () => Promise<T>, timeoutMs = 2_000): Promise<T> {
        if (!this.redis.del) {
            return operation();
@@ -174,11 +228,15 @@ export class TournamentStore {
    }

    private async writeWithSourceRevision(key: string, value: unknown): Promise<string> {
-        return writeTournamentProjection(this.redis, this.keys, [{ key, value }]);
+        const fence = this.clockContext ? toClockFence(this.keys, this.clockContext) : undefined;
+        return writeTournamentProjection(this.redis, this.keys, [{ key, value }], fence);
    }

    async setState(state: TournamentState): Promise<string> {
-        return this.writeWithSourceRevision(this.keys.stateKey, state);
+        return this.writeWithSourceRevision(
+            this.keys.stateKey,
+            this.clockContext ? stampTournamentClock(state, this.clockContext) : state
+        );
    }

    async getParticipants(): Promise<TournamentParticipantEntry[]> {
@@ -9,8 +9,12 @@ export interface TournamentState {
    openMonth: number;
    termSeconds: number;
    nextAt: string;
+    nextTick?: number;
+    clockRevision?: number;
+    deadlineGeneration?: number;
    bettingId?: number;
    bettingCloseAt?: string;
+    bettingCloseTick?: number;
    winnerId?: number;
    bettingSettled?: boolean;
    rewardSettled?: boolean;
@@ -13,9 +13,10 @@ import { DatabaseTurnDaemonTransport } from '../daemon/databaseTransport.js';
 import { createBestEffortResourceCloser } from '../services/bestEffortResourceCloser.js';
 import { loadCurrentGameTime } from '../services/gameClock.js';
 import { createPollingWorkerControl, waitForWorkerPoll } from '../services/pollingWorkerLifecycle.js';
+import { ensureActiveRedisClockFence } from '../services/redisClockFence.js';
 import type { TurnDaemonTransport } from '../daemon/transport.js';
 import { buildTournamentKeys } from './keys.js';
-import { TournamentStore } from './store.js';
+import { TournamentStore, stampTournamentClock, type TournamentClockContext } from './store.js';
 import type { TournamentMatchEntry, TournamentState } from './types.js';
 import {
    applyGroupMatch,
@@ -595,41 +596,63 @@ export const processTournamentTick = async (options: {
    prisma: GamePrismaClient;
    daemonTransport: TurnDaemonTransport;
    now?: () => number;
+    clockContext?: TournamentClockContext;
 }): Promise<TournamentState | null> => {
    const { store, prisma, daemonTransport } = options;
    const now = options.now ?? Date.now;
    let processedState: TournamentState | null = null;

-    await store.withMutationLock(async () => {
-        const state = await store.getState();
-        if (!state || (!state.auto && !needsSettlement(state))) {
-            return;
-        }
-        const nextAt = new Date(state.nextAt).getTime();
-        if (state.auto && Number.isFinite(nextAt) && nextAt > now()) {
-            return;
-        }
+    const processWithLock = async (): Promise<void> =>
+        store.withMutationLock(async () => {
+            const state = await store.getState();
+            if (!state || (!state.auto && !needsSettlement(state))) {
+                return;
+            }
+            if (
+                options.clockContext &&
+                (state.clockRevision !== options.clockContext.revision ||
+                    state.deadlineGeneration !== options.clockContext.deadlineGeneration)
+            ) {
+                throw new Error('Tournament state does not match the active clock revision.');
+            }
+            const nextAt = new Date(state.nextAt).getTime();
+            const notDue = options.clockContext
+                ? !Number.isSafeInteger(state.nextTick) ||
+                  state.nextTick! > options.clockContext.dateToTick(new Date(now()))!
+                : Number.isFinite(nextAt) && nextAt > now();
+            if (state.auto && notDue) {
+                if (options.clockContext && !Number.isSafeInteger(state.nextTick)) {
+                    throw new Error('Active tournament nextAt lacks the authoritative nextTick dual-write.');
+                }
+                return;
+            }

-        if (needsSettlement(state)) {
-            processedState = (await settleTournamentOutcome({ store, daemonTransport, state })) ?? state;
-            return;
-        }
+            if (needsSettlement(state)) {
+                processedState = (await settleTournamentOutcome({ store, daemonTransport, state })) ?? state;
+                return;
+            }

-        const worldState = await prisma.worldState.findFirst();
-        const baseSeed = (worldState?.meta as Record<string, unknown> | null)?.hiddenSeed ?? 'tournament';
-        let nextState = state;
-        if (isBattleStage(state.stage)) {
-            nextState = await applyBattle(store, state, String(baseSeed), daemonTransport);
-        } else if (isPreBattleStage(state.stage)) {
-            nextState = await applyPreBattleStage(store, prisma, state, String(baseSeed), daemonTransport, now);
-        }
-        processedState =
-            (await settleTournamentOutcome({
-                store,
-                daemonTransport,
-                state: nextState,
-            })) ?? nextState;
-    });
+            const worldState = await prisma.worldState.findFirst();
+            const baseSeed = (worldState?.meta as Record<string, unknown> | null)?.hiddenSeed ?? 'tournament';
+            let nextState = state;
+            if (isBattleStage(state.stage)) {
+                nextState = await applyBattle(store, state, String(baseSeed), daemonTransport);
+            } else if (isPreBattleStage(state.stage)) {
+                nextState = await applyPreBattleStage(store, prisma, state, String(baseSeed), daemonTransport, now);
+            }
+            processedState =
+                (await settleTournamentOutcome({
+                    store,
+                    daemonTransport,
+                    state: nextState,
+                })) ?? nextState;
+        });
+
+    if (options.clockContext) {
+        await store.withClockContext(options.clockContext, processWithLock);
+    } else {
+        await processWithLock();
+    }

    return processedState;
 };
@@ -656,16 +679,60 @@ export const runTournamentWorker = async (options: TournamentWorkerOptions = {})

    try {
        while (!control.signal.aborted) {
-            const state = await store.getState();
+            let state = await store.getState();
            if (!state || (!state.auto && !needsSettlement(state))) {
                await waitForWorkerPoll(control.signal, config.tournamentPollMs);
                continue;
            }

+            const gameTime = await loadCurrentGameTime(postgres.prisma);
+            if (gameTime.phase && gameTime.phase !== 'RUNNING') {
+                await waitForWorkerPoll(control.signal, config.tournamentPollMs);
+                continue;
+            }
+            const clockFence = gameTime.phase
+                ? await ensureActiveRedisClockFence(redis.client, config.profileName, gameTime)
+                : null;
+            if (gameTime.phase && !clockFence) {
+                await waitForWorkerPoll(control.signal, config.tournamentPollMs);
+                continue;
+            }
+            const clockContext: TournamentClockContext | undefined = clockFence
+                ? {
+                      phase: 'RUNNING',
+                      revision: clockFence.revision,
+                      deadlineGeneration: clockFence.generation,
+                      dateToTick: gameTime.dateToTick,
+                  }
+                : undefined;
+            if (
+                clockContext &&
+                (!Number.isSafeInteger(state.nextTick) ||
+                    state.clockRevision === undefined ||
+                    state.deadlineGeneration === undefined)
+            ) {
+                state = stampTournamentClock(state, clockContext);
+                await store.withClockContext(clockContext, () => store.setState(state!));
+            }
+            if (
+                clockContext &&
+                (state.clockRevision !== clockContext.revision ||
+                    state.deadlineGeneration !== clockContext.deadlineGeneration)
+            ) {
+                await waitForWorkerPoll(control.signal, config.tournamentPollMs);
+                continue;
+            }
+
            const nextAt = new Date(state.nextAt).getTime();
-            const gameNow = (await loadCurrentGameTime(postgres.prisma)).now.getTime();
-            if (state.auto && Number.isFinite(nextAt) && nextAt > gameNow) {
-                await waitForWorkerPoll(control.signal, Math.min(config.tournamentPollMs, nextAt - gameNow));
+            const gameNow = gameTime.now.getTime();
+            const notDue = clockContext
+                ? state.nextTick! > gameTime.tick!
+                : Number.isFinite(nextAt) && nextAt > gameNow;
+            if (state.auto && notDue) {
+                await waitForWorkerPoll(
+                    control.signal,
+                    Math.min(config.tournamentPollMs, Math.max(1, nextAt - gameNow))
+                );
                continue;
            }

@@ -675,6 +742,7 @@ export const runTournamentWorker = async (options: TournamentWorkerOptions = {})
                    prisma: postgres.prisma,
                    daemonTransport,
                    now: () => gameNow,
+                    clockContext,
                });
            } catch (error) {
                const message = error instanceof Error ? error.message : 'Unknown error';
@@ -700,7 +768,11 @@ export const runTournamentWorker = async (options: TournamentWorkerOptions = {})
                    lastError: message,
                    lastErrorAt: failedAt,
                };
-                await store.setState(nextState);
+                if (clockContext) {
+                    await store.withClockContext(clockContext, () => store.setState(nextState));
+                } else {
+                    await store.setState(nextState);
+                }
            }

            await waitForWorkerPoll(control.signal, config.tournamentPollMs);