feat: fence periodic turn daemon execution

app/game-engine/src/turn/databaseHooks.ts

@@ -29,6 +29,7 @@ import type { InMemoryReservedTurnStore } from './reservedTurnStore.js';
 import { buildDiplomacyMeta } from '@sammo-ts/logic';
 import { ensureItemInventory, withSerializedItemInventory } from '@sammo-ts/logic/items/index.js';
 import { persistGeneralLifecycleEvents } from './generalTurnLifecyclePersistence.js';
+import type { DatabaseTurnDaemonLease } from '../lifecycle/databaseTurnDaemonLease.js';
 
 export interface DatabaseTurnHooks {
     hooks: TurnDaemonHooks;
@@ -313,7 +314,10 @@ const buildLogCreateData = (
 export const createDatabaseTurnHooks = async (
     databaseUrl: string,
     world: InMemoryTurnWorld,
-    options?: { reservedTurns?: InMemoryReservedTurnStore }
+    options?: {
+        reservedTurns?: InMemoryReservedTurnStore;
+        turnDaemonLease?: DatabaseTurnDaemonLease;
+    }
 ): Promise<DatabaseTurnHooks> => {
     // 턴 처리 결과를 DB에 반영하는 훅을 만든다.
     const connector = createGamePostgresConnector({ url: databaseUrl });
@@ -354,6 +358,10 @@ export const createDatabaseTurnHooks = async (
             meta: asJson(state.meta),
         };
         const persist = async (prisma: GamePrisma.TransactionClient): Promise<void> => {
+            // Lock and validate the fencing row in the same transaction as every
+            // world mutation. A stale daemon can finish calculating, but it can
+            // never commit after another owner has advanced the epoch.
+            await options?.turnDaemonLease?.assertActive(prisma);
             await prisma.worldState.update({
                 where: { id: state.id },
                 data: worldStateUpdate,

app/game-engine/src/turn/turnDaemon.ts

@@ -34,6 +34,10 @@ import { createTournamentRewardFinalizer } from '../tournament/finalizer.js';
 import { createTournamentAutoStartHandler } from './tournamentAutoStart.js';
 import { createYearbookHandler } from './yearbookHandler.js';
 import { createMonthlyEventHandler, type MonthlyEventActionHandler } from './monthlyEventHandler.js';
+import {
+    DatabaseTurnDaemonLease,
+    TurnDaemonLeaseUnavailableError,
+} from '../lifecycle/databaseTurnDaemonLease.js';
 
 export interface TurnDaemonRuntimeOptions {
     profile: string;
@@ -55,6 +59,9 @@ export interface TurnDaemonRuntimeOptions {
     adminActionIntervalMs?: number;
     redisUrl?: string;
     commandStreamStartId?: string;
+    leaseDurationMs?: number;
+    leaseOwnerId?: string;
+    enableLeaseHeartbeat?: boolean;
 }
 
 export interface TurnDaemonRuntime {
@@ -90,6 +97,19 @@ const resolveRedisConfig = (redisUrl?: string, env: NodeJS.ProcessEnv = process.
 
 export const createTurnDaemonRuntime = async (options: TurnDaemonRuntimeOptions): Promise<TurnDaemonRuntime> => {
     // DB에서 월드를 읽고 턴 데몬을 구동할 런타임을 만든다.
+    const databaseFlushEnabled = options.enableDatabaseFlush ?? true;
+    const turnDaemonLease = databaseFlushEnabled
+        ? await DatabaseTurnDaemonLease.connect(options.databaseUrl, {
+              profile: options.profileName ?? options.profile,
+              ownerId: options.leaseOwnerId,
+              leaseDurationMs: options.leaseDurationMs,
+              heartbeat: options.enableLeaseHeartbeat,
+          })
+        : null;
+    if (turnDaemonLease && !(await turnDaemonLease.acquire())) {
+        await turnDaemonLease.close();
+        throw new TurnDaemonLeaseUnavailableError(options.profileName ?? options.profile);
+    }
     const { state, snapshot } = await loadTurnWorldFromDatabase({
         databaseUrl: options.databaseUrl,
         mapOptions: options.mapOptions,
@@ -286,9 +306,10 @@ export const createTurnDaemonRuntime = async (options: TurnDaemonRuntimeOptions)
     if (gatewayGate) {
         pauseGate = gatewayGate.shouldPause;
     }
-    if (options.enableDatabaseFlush ?? true) {
+    if (databaseFlushEnabled) {
         const dbHooks = await createDatabaseTurnHooks(options.databaseUrl, world, {
             reservedTurns: reservedTurnStoreHandle?.store,
+            turnDaemonLease: turnDaemonLease ?? undefined,
         });
         auctionBidder = await createAuctionBidder({
             databaseUrl: options.databaseUrl,
@@ -325,6 +346,7 @@ export const createTurnDaemonRuntime = async (options: TurnDaemonRuntimeOptions)
             }
             await gatewayGate?.close();
             await adminActionConsumer?.stop();
+            await turnDaemonLease?.close();
         };
     } else if (reservedTurnStoreHandle) {
         hooks = {
@@ -426,7 +448,7 @@ export const createTurnDaemonRuntime = async (options: TurnDaemonRuntimeOptions)
             stateStore,
             processor,
             hooks,
-            pauseGate,
+            pauseGate: async () => turnDaemonLease?.isLost() || ((await pauseGate?.()) ?? false),
             commandHandler,
             commandResponder: options.controlQueue ? undefined : (databaseCommandQueue ?? undefined),
         },