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

2026-09-03 09:40:48 +00:00
parent ae7d55ef47
commit a3e2bf90ae
46 changed files with 3011 additions and 219 deletions
@@ -269,7 +269,14 @@ export const createAuctionBidder = async (options: {
                };
            }
            const processingNow = world.getGameNow(new Date());
-            const { bidAt, bidTick } = resolveAuctionBidTiming(world, processingNow, command.acceptedGameTick);
+            const convertedProcessingTick = Reflect.get(command, 'processingGameTick');
+            const { bidAt, bidTick } = resolveAuctionBidTiming(
+                world,
+                processingNow,
+                typeof convertedProcessingTick === 'number' && Number.isSafeInteger(convertedProcessingTick)
+                    ? convertedProcessingTick
+                    : command.acceptedGameTick
+            );
            if (hasAuctionClosePassed(auction, bidAt, bidTick)) {
                return {
                    type: 'auctionBid',
@@ -20,6 +20,8 @@ export * from './turn/engineStateManager.js';
 export * from './turn/inMemoryStateStore.js';
 export * from './turn/inMemoryTurnProcessor.js';
 export * from './turn/databaseHooks.js';
+export * from './turn/clockReconciliation.js';
+export * from './turn/clockProjectionOutbox.js';
 export * from './turn/joinCreateGeneralService.js';
 export * from './turn/npcPossessionService.js';
 export * from './turn/selectPoolService.js';
@@ -108,6 +108,13 @@ export class DatabaseTurnDaemonCommandQueue implements TurnDaemonControlQueue, T
    private async claimPending(limit = 100): Promise<TurnDaemonCommand[]> {
        await this.recoverExpiredLeases();
        return this.db.$transaction(async (transaction) => {
+            const world = await transaction.worldState.findFirst({
+                orderBy: { id: 'asc' },
+                select: { clockPhase: true, clockRevision: true, deadlineGeneration: true, clockTick: true },
+            });
+            const gameplayAllowed =
+                !world || world.clockPhase === 'RUNNING' || world.clockPhase === 'MANUAL';
+            const currentRevision = world?.clockRevision ?? null;
            const rows = await transaction.$queryRaw<
                Array<{
                    sequence: bigint;
@@ -115,6 +122,9 @@ export class DatabaseTurnDaemonCommandQueue implements TurnDaemonControlQueue, T
                    eventType: string;
                    payload: unknown;
                    createdAt: Date;
+                    acceptedGameTick: bigint | null;
+                    acceptedClockRevision: bigint | null;
+                    acceptedDeadlineGeneration: bigint | null;
                }>
            >(GamePrisma.sql`
                SELECT
@@ -122,10 +132,14 @@ export class DatabaseTurnDaemonCommandQueue implements TurnDaemonControlQueue, T
                    "request_id" AS "requestId",
                    "event_type" AS "eventType",
                    "payload",
-                    "created_at" AS "createdAt"
+                    "created_at" AS "createdAt",
+                    "accepted_game_tick" AS "acceptedGameTick",
+                    "accepted_clock_revision" AS "acceptedClockRevision",
+                    "accepted_deadline_generation" AS "acceptedDeadlineGeneration"
                FROM "input_event"
                WHERE "target" = 'ENGINE'::"InputEventTarget"
                  AND "status" = 'PENDING'::"InputEventStatus"
+                  AND (${gameplayAllowed} OR "event_type" = 'getStatus')
                ORDER BY "sequence" ASC
                FOR UPDATE SKIP LOCKED
                LIMIT ${limit}
@@ -133,23 +147,53 @@ export class DatabaseTurnDaemonCommandQueue implements TurnDaemonControlQueue, T
            if (rows.length === 0) {
                return [];
            }
-            await transaction.inputEvent.updateMany({
-                where: {
-                    sequence: { in: rows.map((row) => row.sequence) },
-                    target: 'ENGINE',
-                    status: 'PENDING',
-                },
-                data: {
-                    status: 'PROCESSING',
-                    processingAt: new Date(),
-                    lockedBy: this.workerId,
-                    leaseUntil: new Date(Date.now() + this.leaseDurationMs),
-                    attempts: { increment: 1 },
-                },
-            });
+            const appliedSuspensions = currentRevision
+                ? await transaction.clockSuspension.findMany({
+                      where: { status: 'APPLIED', targetRevision: { lte: currentRevision } },
+                      orderBy: { sourceRevision: 'asc' },
+                      select: { sourceRevision: true, targetRevision: true, shiftTicks: true },
+                  })
+                : [];
+            const convertTick = (row: (typeof rows)[number]): bigint | null | undefined => {
+                if (row.eventType === 'getStatus') return row.acceptedGameTick;
+                if (row.acceptedGameTick === null || row.acceptedClockRevision === null || currentRevision === null) {
+                    return row.acceptedGameTick ?? world?.clockTick ?? null;
+                }
+                if (row.acceptedClockRevision > currentRevision) return undefined;
+                let revision = row.acceptedClockRevision;
+                let tick = row.acceptedGameTick;
+                while (revision < currentRevision) {
+                    const step = appliedSuspensions.find((entry) => entry.sourceRevision === revision);
+                    if (!step || step.shiftTicks === null || step.targetRevision !== revision + 1n) return undefined;
+                    tick += step.shiftTicks;
+                    revision = step.targetRevision;
+                }
+                return tick;
+            };
+            const processableRows = rows
+                .map((row) => ({ row, processingGameTick: convertTick(row) }))
+                .filter(
+                    (entry): entry is { row: (typeof rows)[number]; processingGameTick: bigint | null } =>
+                        entry.processingGameTick !== undefined
+                );
+            for (const { row, processingGameTick } of processableRows) {
+                await transaction.inputEvent.update({
+                    where: { sequence: row.sequence },
+                    data: {
+                        status: 'PROCESSING',
+                        processingAt: new Date(),
+                        processingGameTick,
+                        processingClockRevision: currentRevision,
+                        processingDeadlineGeneration: world?.deadlineGeneration ?? null,
+                        lockedBy: this.workerId,
+                        leaseUntil: new Date(Date.now() + this.leaseDurationMs),
+                        attempts: { increment: 1 },
+                    },
+                });
+            }

            const commands: TurnDaemonCommand[] = [];
-            for (const row of rows) {
+            for (const { row, processingGameTick } of processableRows) {
                const command = normalizeTurnDaemonCommand({
                    requestId: row.requestId,
                    sentAt: row.createdAt.toISOString(),
@@ -168,6 +212,27 @@ export class DatabaseTurnDaemonCommandQueue implements TurnDaemonControlQueue, T
                    });
                    continue;
                }
+                if (
+                    processingGameTick !== null &&
+                    row.acceptedGameTick !== null &&
+                    processingGameTick !== row.acceptedGameTick
+                ) {
+                    const value = Number(processingGameTick);
+                    if (!Number.isSafeInteger(value)) {
+                        await transaction.inputEvent.update({
+                            where: { sequence: row.sequence },
+                            data: {
+                                status: 'FAILED',
+                                error: 'Converted processing game tick is outside the safe integer range.',
+                                completedAt: new Date(),
+                                lockedBy: null,
+                                leaseUntil: null,
+                            },
+                        });
+                        continue;
+                    }
+                    Reflect.set(command, 'processingGameTick', value);
+                }
                commands.push(command);
            }
            return commands;
@@ -0,0 +1,343 @@
+import { createHash } from 'node:crypto';
+
+import { GameClock, parseGameClockPhase } from '@sammo-ts/common';
+import {
+    CLOCK_OPERATION_PERSISTENCE_LOCK,
+    GamePrisma,
+    acquireGameSchemaAdvisoryXactLock,
+    type GamePrismaClient,
+} from '@sammo-ts/infra';
+
+interface ClockProjectionRedis {
+    get(key: string): Promise<string | null>;
+    eval(script: string, options: { keys: string[]; arguments: string[] }): Promise<unknown>;
+}
+
+interface ClaimedOutboxRow {
+    id: bigint;
+}
+
+interface DbWallRow {
+    wallNow: Date;
+}
+
+interface ProjectionPayload {
+    version: 1;
+    profileName: string;
+    suspensionId: string;
+    sourceRevision: number;
+    targetRevision: number;
+    deadlineGeneration: number;
+    shiftTicks: number;
+    projectionDeltaMilliseconds: number;
+    clockBaseTime: string;
+    ticksPerSecond: number;
+}
+
+interface TournamentProjectionState {
+    stage?: number;
+    nextAt?: string;
+    nextTick?: number;
+    bettingCloseAt?: string;
+    bettingCloseTick?: number;
+    clockRevision?: number;
+    deadlineGeneration?: number;
+    [key: string]: unknown;
+}
+
+const APPLY_CLOCK_PROJECTION_SCRIPT = `
+local active = redis.call('GET', KEYS[1])
+if active == ARGV[2] then
+  if redis.call('GET', KEYS[5]) == ARGV[4] and redis.call('GET', KEYS[2]) == ARGV[3] then
+    return 2
+  end
+  return -3
+end
+if active and active ~= ARGV[1] then
+  return -1
+end
+if ARGV[5] ~= '__NONE__' and redis.call('GET', KEYS[4]) ~= ARGV[5] then
+  return -2
+end
+redis.call('DEL', KEYS[3])
+local count = tonumber(ARGV[7])
+local offset = 8
+for index = 1, count do
+  redis.call('ZADD', KEYS[3], ARGV[offset], ARGV[offset + 1])
+  offset = offset + 2
+end
+if ARGV[5] ~= '__NONE__' then
+  redis.call('SET', KEYS[4], ARGV[6])
+end
+redis.call('SET', KEYS[1], ARGV[2])
+redis.call('SET', KEYS[2], ARGV[3])
+redis.call('SET', KEYS[5], ARGV[4])
+redis.call('SET', KEYS[6], 'RUNNING')
+return 1
+`;
+
+const safeInteger = (value: unknown, label: string): number => {
+    const result = typeof value === 'bigint' ? Number(value) : value;
+    if (typeof result !== 'number' || !Number.isSafeInteger(result)) {
+        throw new Error(`${label} must be a safe integer.`);
+    }
+    return result;
+};
+
+const canonicalize = (value: unknown): unknown => {
+    if (typeof value === 'bigint') return value.toString();
+    if (Array.isArray(value)) return value.map(canonicalize);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(
+            Object.entries(value as Record<string, unknown>)
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(([key, item]) => [key, canonicalize(item)])
+        );
+    }
+    return value;
+};
+
+const stableJson = (value: unknown): string => JSON.stringify(canonicalize(value));
+
+const checksum = (value: unknown): string => createHash('sha256').update(stableJson(value)).digest('hex');
+
+const readDbWall = async (db: GamePrisma.TransactionClient): Promise<Date> => {
+    const rows = await db.$queryRaw<DbWallRow[]>(GamePrisma.sql`
+        SELECT (CURRENT_TIMESTAMP AT TIME ZONE 'UTC')::timestamp(3) AS "wallNow"
+    `);
+    if (!rows[0]?.wallNow) throw new Error('Failed to read PostgreSQL wall time for the projection outbox.');
+    return rows[0].wallNow;
+};
+
+const parsePayload = (value: GamePrisma.JsonValue): ProjectionPayload => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Clock projection outbox payload must be an object.');
+    }
+    const payload = value as Record<string, unknown>;
+    if (payload.version !== 1 || typeof payload.profileName !== 'string' || typeof payload.suspensionId !== 'string') {
+        throw new Error('Clock projection outbox payload identity is invalid.');
+    }
+    if (typeof payload.clockBaseTime !== 'string') {
+        throw new Error('Clock projection outbox is missing its projection base.');
+    }
+    return {
+        version: 1,
+        profileName: payload.profileName,
+        suspensionId: payload.suspensionId,
+        sourceRevision: safeInteger(payload.sourceRevision, 'sourceRevision'),
+        targetRevision: safeInteger(payload.targetRevision, 'targetRevision'),
+        deadlineGeneration: safeInteger(payload.deadlineGeneration, 'deadlineGeneration'),
+        shiftTicks: safeInteger(payload.shiftTicks, 'shiftTicks'),
+        projectionDeltaMilliseconds: safeInteger(
+            payload.projectionDeltaMilliseconds,
+            'projectionDeltaMilliseconds'
+        ),
+        clockBaseTime: payload.clockBaseTime,
+        ticksPerSecond: safeInteger(payload.ticksPerSecond, 'ticksPerSecond'),
+    };
+};
+
+const claimNext = async (db: GamePrismaClient, workerId: string) =>
+    db.$transaction(async (transaction) => {
+        const rows = await transaction.$queryRaw<ClaimedOutboxRow[]>(GamePrisma.sql`
+            SELECT id
+            FROM clock_projection_outbox
+            WHERE available_at <= (CURRENT_TIMESTAMP AT TIME ZONE 'UTC')
+              AND (
+                status IN ('PENDING', 'FAILED')
+                OR (status = 'APPLYING' AND locked_at < (CURRENT_TIMESTAMP AT TIME ZONE 'UTC') - INTERVAL '30 seconds')
+              )
+            ORDER BY id
+            LIMIT 1
+            FOR UPDATE SKIP LOCKED
+        `);
+        const id = rows[0]?.id;
+        if (id === undefined) return null;
+        const lockedAt = await readDbWall(transaction);
+        return transaction.clockProjectionOutbox.update({
+            where: { id },
+            data: {
+                status: 'APPLYING',
+                attempts: { increment: 1 },
+                lockedAt,
+                lockedBy: workerId,
+                lastError: null,
+            },
+        });
+    });
+
+const projectTournamentState = (
+    raw: string | null,
+    payload: ProjectionPayload,
+    clock: GameClock
+): { expected: string; next: string } | null => {
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as TournamentProjectionState;
+    const active = typeof parsed.stage === 'number' && parsed.stage > 0;
+    if (active && parsed.nextAt && !Number.isSafeInteger(parsed.nextTick)) {
+        throw new Error('Active tournament nextAt lacks the authoritative nextTick dual-write.');
+    }
+    if (active && parsed.bettingCloseAt && !Number.isSafeInteger(parsed.bettingCloseTick)) {
+        throw new Error('Active tournament bettingCloseAt lacks the authoritative bettingCloseTick dual-write.');
+    }
+    const next: TournamentProjectionState = {
+        ...parsed,
+        clockRevision: payload.targetRevision,
+        deadlineGeneration: payload.deadlineGeneration,
+    };
+    if (Number.isSafeInteger(parsed.nextTick)) {
+        next.nextTick = parsed.nextTick! + payload.shiftTicks;
+        next.nextAt = clock.tickToDate(next.nextTick).toISOString();
+    }
+    if (Number.isSafeInteger(parsed.bettingCloseTick)) {
+        next.bettingCloseTick = parsed.bettingCloseTick! + payload.shiftTicks;
+        next.bettingCloseAt = clock.tickToDate(next.bettingCloseTick).toISOString();
+    }
+    return { expected: raw, next: JSON.stringify(next) };
+};
+
+const recordFailure = async (db: GamePrismaClient, outboxId: bigint, error: unknown): Promise<void> => {
+    const message = error instanceof Error ? error.message : String(error);
+    await db.$executeRaw(GamePrisma.sql`
+        UPDATE clock_projection_outbox
+        SET status = 'FAILED',
+            locked_at = NULL,
+            locked_by = NULL,
+            last_error = ${message.slice(0, 4_000)},
+            available_at = (CURRENT_TIMESTAMP AT TIME ZONE 'UTC') + INTERVAL '1 second'
+        WHERE id = ${outboxId} AND status = 'APPLYING'
+    `);
+};
+
+export const applyNextClockProjection = async (options: {
+    db: GamePrismaClient;
+    redis: ClockProjectionRedis;
+    workerId: string;
+}): Promise<'IDLE' | 'APPLIED' | 'RECOVERED'> => {
+    if (!options.workerId.trim()) throw new Error('Clock projection worker ID is required.');
+    const outbox = await claimNext(options.db, options.workerId);
+    if (!outbox) return 'IDLE';
+    try {
+        const payload = parsePayload(outbox.payload);
+        if (checksum(outbox.payload) !== outbox.checksum) {
+            throw new Error('Clock projection outbox checksum verification failed.');
+        }
+        if (outbox.targetRevision !== BigInt(payload.targetRevision)) {
+            throw new Error('Clock projection payload revision differs from its outbox row.');
+        }
+        const world = await options.db.worldState.findUniqueOrThrow({ where: { id: outbox.worldStateId } });
+        if (
+            parseGameClockPhase(world.clockPhase) !== 'RECONCILING' ||
+            world.clockRevision !== outbox.targetRevision ||
+            world.deadlineGeneration !== BigInt(payload.deadlineGeneration) ||
+            !world.clockBaseTime
+        ) {
+            throw new Error('Clock projection DB phase/revision/generation fence failed.');
+        }
+        const clock = new GameClock({
+            baseTime: new Date(payload.clockBaseTime),
+            tick: safeInteger(world.clockTick, 'world clock tick'),
+            mode: world.clockMode === 'manual' ? 'manual' : 'realtime',
+            wallAnchor: world.clockWallAnchor ?? new Date(),
+            turnSeconds: world.tickSeconds,
+            phase: 'RECONCILING',
+            revision: payload.targetRevision,
+        });
+        if (clock.ticksPerSecond !== payload.ticksPerSecond) {
+            throw new Error('Clock projection rate differs from the durable outbox payload.');
+        }
+        const auctions = await options.db.auction.findMany({
+            where: { status: { in: ['OPEN', 'FINALIZING'] } },
+            orderBy: { id: 'asc' },
+            select: { id: true, closeTick: true },
+        });
+        const timers = auctions.map((auction) => {
+            if (auction.closeTick === null) {
+                throw new Error(`Active auction ${auction.id} lacks closeTick during projection rebuild.`);
+            }
+            return { score: safeInteger(auction.closeTick, `auction ${auction.id} closeTick`), id: String(auction.id) };
+        });
+        const prefix = `sammo:${payload.profileName}`;
+        const tournamentKey = `${prefix}:tournament:state`;
+        const tournament = projectTournamentState(await options.redis.get(tournamentKey), payload, clock);
+        const result = await options.redis.eval(APPLY_CLOCK_PROJECTION_SCRIPT, {
+            keys: [
+                `${prefix}:clock:active-revision`,
+                `${prefix}:clock:deadline-generation`,
+                `${prefix}:auction:timer`,
+                tournamentKey,
+                `${prefix}:clock:projection-checksum`,
+                `${prefix}:clock:phase`,
+            ],
+            arguments: [
+                String(payload.sourceRevision),
+                String(payload.targetRevision),
+                String(payload.deadlineGeneration),
+                outbox.checksum,
+                tournament?.expected ?? '__NONE__',
+                tournament?.next ?? '__NONE__',
+                String(timers.length),
+                ...timers.flatMap(({ score, id }) => [String(score), id]),
+            ],
+        });
+        const applied = Number(result);
+        if (applied === -1) throw new Error('Redis active clock revision does not match the outbox source revision.');
+        if (applied === -2) throw new Error('Redis tournament state changed while rebuilding its projection.');
+        if (applied === -3) throw new Error('Redis target revision exists without the expected projection checksum.');
+        if (applied !== 1 && applied !== 2) throw new Error(`Unexpected Redis clock projection result: ${String(result)}`);
+
+        await options.db.$transaction(async (transaction) => {
+            await acquireGameSchemaAdvisoryXactLock(transaction, CLOCK_OPERATION_PERSISTENCE_LOCK);
+            await transaction.$queryRaw<ClaimedOutboxRow[]>(GamePrisma.sql`
+                SELECT id FROM world_state WHERE id = ${outbox.worldStateId} FOR UPDATE
+            `);
+            const finalized = await transaction.worldState.updateMany({
+                where: {
+                    id: outbox.worldStateId,
+                    clockPhase: 'RECONCILING',
+                    clockRevision: outbox.targetRevision,
+                    deadlineGeneration: BigInt(payload.deadlineGeneration),
+                },
+                data: { clockPhase: 'RUNNING' },
+            });
+            if (finalized.count !== 1) {
+                throw new Error('Clock projection final RUNNING transition fence failed.');
+            }
+            const appliedAt = await readDbWall(transaction);
+            await transaction.clockProjectionOutbox.update({
+                where: { id: outbox.id },
+                data: { status: 'APPLIED', appliedAt, lockedAt: null, lockedBy: null, lastError: null },
+            });
+            if (outbox.suspensionId) {
+                await transaction.clockSuspension.update({
+                    where: { id: outbox.suspensionId },
+                    data: { status: 'APPLIED' },
+                });
+            }
+        });
+        return applied === 2 ? 'RECOVERED' : 'APPLIED';
+    } catch (error) {
+        await recordFailure(options.db, outbox.id, error);
+        throw error;
+    }
+};
+
+export const loadClockReconciliationReadiness = async (db: GamePrismaClient) => {
+    const world = await db.worldState.findFirst({
+        orderBy: { id: 'asc' },
+        select: { clockPhase: true, clockRevision: true, deadlineGeneration: true },
+    });
+    const incompleteOutboxCount = await db.clockProjectionOutbox.count({ where: { status: { not: 'APPLIED' } } });
+    if (!world) {
+        return { ready: false, phase: null, revision: null, deadlineGeneration: null, incompleteOutboxCount };
+    }
+    const phase = parseGameClockPhase(world.clockPhase);
+    return {
+        ready: phase !== 'RECONCILING' && incompleteOutboxCount === 0,
+        gameplayEnabled: phase === 'RUNNING' || phase === 'MANUAL',
+        phase,
+        revision: safeInteger(world.clockRevision, 'clock revision'),
+        deadlineGeneration: safeInteger(world.deadlineGeneration, 'deadline generation'),
+        incompleteOutboxCount,
+    };
+};
@@ -0,0 +1,763 @@
+import { createHash } from 'node:crypto';
+
+import {
+    GAME_TICKS_PER_TURN,
+    MAX_SAFE_GAME_TICK,
+    GameClock,
+    buildClockAlignmentPlan,
+    parseClockAlignmentPolicy,
+    parseGameClockPhase,
+    type ClockAlignmentPolicy,
+} from '@sammo-ts/common';
+import {
+    CLOCK_OPERATION_PERSISTENCE_LOCK,
+    GENERAL_ACCESS_PERSISTENCE_LOCK,
+    GamePrisma,
+    acquireGameSchemaAdvisoryXactLock,
+    type GamePrismaClient,
+} from '@sammo-ts/infra';
+
+export type ClockSuspensionSource = 'MAINTENANCE' | 'OPEN_DELAY' | 'UNIFICATION_WAIT' | 'RECOVERY';
+
+export type ClockOperationAuthority =
+    | { kind: 'DAEMON'; profileName: string; ownerId: string; fencingEpoch: bigint }
+    | { kind: 'OFFLINE'; profileName: string; reason: string };
+
+export interface ClockSuspensionResult {
+    suspensionId: string;
+    phase: 'SUSPENDED';
+    sourceRevision: number;
+    targetRevision: number;
+    cutTick: number;
+    cutWallAt: Date;
+}
+
+export interface ClockReconciliationResult {
+    suspensionId: string;
+    phase: 'RECONCILING';
+    sourceRevision: number;
+    targetRevision: number;
+    deadlineGeneration: number;
+    gapTicks: number;
+    catchUpTicks: number;
+    shiftTicks: number;
+    alignedTick: number;
+    resumeWallAt: Date;
+}
+
+interface DbWallRow {
+    wallNow: Date;
+}
+
+interface LeaseFenceRow {
+    ownerId: string;
+    fencingEpoch: bigint;
+    valid: boolean;
+}
+
+interface IdRow {
+    id: number;
+}
+
+interface TextIdRow {
+    id: string;
+}
+
+interface ParticipantSnapshot {
+    key: string;
+    policy: 'SHIFT' | 'KEEP' | 'REBUILD';
+    checksum: string;
+    count: number;
+}
+
+const asJson = (value: unknown): GamePrisma.InputJsonValue => value as GamePrisma.InputJsonValue;
+
+const safeNumber = (value: bigint, label: string): number => {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result)) {
+        throw new Error(`${label} is outside the JavaScript safe integer range: ${value}`);
+    }
+    return result;
+};
+
+const canonicalize = (value: unknown): unknown => {
+    if (typeof value === 'bigint') return value.toString();
+    if (Array.isArray(value)) return value.map(canonicalize);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(
+            Object.entries(value as Record<string, unknown>)
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(([key, item]) => [key, canonicalize(item)])
+        );
+    }
+    return value;
+};
+
+const stableJson = (value: unknown): string => JSON.stringify(canonicalize(value));
+
+const checksum = (value: unknown): string => createHash('sha256').update(stableJson(value)).digest('hex');
+
+const aggregateChecksum = (participants: readonly ParticipantSnapshot[]): string =>
+    checksum(participants.map(({ key, policy, checksum: value, count }) => ({ key, policy, checksum: value, count })));
+
+const readDbWall = async (db: GamePrisma.TransactionClient): Promise<Date> => {
+    const rows = await db.$queryRaw<DbWallRow[]>(GamePrisma.sql`
+        SELECT (CURRENT_TIMESTAMP AT TIME ZONE 'UTC')::timestamp(3) AS "wallNow"
+    `);
+    const wallNow = rows[0]?.wallNow;
+    if (!wallNow || Number.isNaN(wallNow.getTime())) {
+        throw new Error('Failed to read the PostgreSQL wall clock.');
+    }
+    return wallNow;
+};
+
+const verifyAuthority = async (
+    db: GamePrisma.TransactionClient,
+    authority: ClockOperationAuthority
+): Promise<void> => {
+    const rows = await db.$queryRaw<LeaseFenceRow[]>(GamePrisma.sql`
+        SELECT owner_id AS "ownerId",
+               fencing_epoch AS "fencingEpoch",
+               lease_until > (CURRENT_TIMESTAMP AT TIME ZONE 'UTC') AS valid
+        FROM turn_daemon_lease
+        WHERE profile = ${authority.profileName}
+        FOR UPDATE
+    `);
+    const lease = rows[0];
+    if (authority.kind === 'OFFLINE') {
+        if (!authority.reason.trim()) {
+            throw new Error('Offline clock operations require an audit reason.');
+        }
+        if (lease?.valid) {
+            throw new Error(`Clock operation requires the ${authority.profileName} daemon lease to be offline.`);
+        }
+        return;
+    }
+    if (
+        !lease?.valid ||
+        lease.ownerId !== authority.ownerId ||
+        lease.fencingEpoch !== authority.fencingEpoch
+    ) {
+        throw new Error(`Stale turn-daemon fencing authority for profile ${authority.profileName}.`);
+    }
+};
+
+const lockWorld = async (db: GamePrisma.TransactionClient): Promise<number> => {
+    const rows = await db.$queryRaw<IdRow[]>(GamePrisma.sql`
+        SELECT id FROM world_state ORDER BY id LIMIT 2 FOR UPDATE
+    `);
+    if (rows.length !== 1) {
+        throw new Error(`Clock reconciliation requires exactly one world_state row; found ${rows.length}.`);
+    }
+    return rows[0]!.id;
+};
+
+const lockParticipants = async (db: GamePrisma.TransactionClient, cutTick: bigint): Promise<void> => {
+    await db.$queryRaw<IdRow[]>(GamePrisma.sql`SELECT id FROM general ORDER BY id FOR UPDATE`);
+    await db.$queryRaw<IdRow[]>(GamePrisma.sql`
+        SELECT id FROM auction
+        WHERE status IN ('OPEN'::auction_status, 'FINALIZING'::auction_status)
+        ORDER BY id FOR UPDATE
+    `);
+    await db.$queryRaw<IdRow[]>(GamePrisma.sql`
+        SELECT id FROM message
+        WHERE valid_until_tick IS NOT NULL AND valid_until_tick >= ${cutTick}
+        ORDER BY id FOR UPDATE
+    `);
+    await db.$queryRaw<IdRow[]>(GamePrisma.sql`
+        SELECT id FROM vote_poll WHERE closed_at IS NULL ORDER BY id FOR UPDATE
+    `);
+    await db.$queryRaw<IdRow[]>(GamePrisma.sql`
+        SELECT id FROM select_pool WHERE general_id IS NULL ORDER BY id FOR UPDATE
+    `);
+    await db.$queryRaw<TextIdRow[]>(GamePrisma.sql`
+        SELECT owner_user_id AS id FROM select_npc_token ORDER BY owner_user_id FOR UPDATE
+    `);
+};
+
+const readParticipantSnapshots = async (
+    db: GamePrisma.TransactionClient,
+    worldStateId: number,
+    cutTick: bigint
+): Promise<ParticipantSnapshot[]> => {
+    const [world, generals, auctions, messages, votes, pool, npcTokens, commands] = await Promise.all([
+        db.worldState.findUniqueOrThrow({
+            where: { id: worldStateId },
+            select: {
+                clockTick: true,
+                clockRevision: true,
+                deadlineGeneration: true,
+                lastTurnTick: true,
+                meta: true,
+            },
+        }),
+        db.general.findMany({
+            orderBy: { id: 'asc' },
+            select: { id: true, turnTick: true, recentWarTick: true },
+        }),
+        db.auction.findMany({
+            where: { status: { in: ['OPEN', 'FINALIZING'] } },
+            orderBy: { id: 'asc' },
+            select: { id: true, status: true, openTick: true, closeTick: true },
+        }),
+        db.message.findMany({
+            where: { validUntilTick: { not: null, gte: cutTick } },
+            orderBy: { id: 'asc' },
+            select: { id: true, timeTick: true, validUntilTick: true },
+        }),
+        db.votePoll.findMany({
+            where: { closedAt: null },
+            orderBy: { id: 'asc' },
+            select: { id: true, startTick: true, endTick: true },
+        }),
+        db.selectPoolEntry.findMany({
+            where: { generalId: null },
+            orderBy: { id: 'asc' },
+            select: { id: true, reservedUntilTick: true },
+        }),
+        db.npcSelectionToken.findMany({
+            orderBy: { ownerUserId: 'asc' },
+            select: { ownerUserId: true, validUntilTick: true, pickMoreFromTick: true },
+        }),
+        db.inputEvent.findMany({
+            where: { status: { in: ['PENDING', 'PROCESSING'] } },
+            orderBy: { sequence: 'asc' },
+            select: { sequence: true, acceptedGameTick: true, acceptedClockRevision: true },
+        }),
+    ]);
+    const snapshot = (key: string, policy: ParticipantSnapshot['policy'], rows: unknown[]): ParticipantSnapshot => ({
+        key,
+        policy,
+        checksum: checksum(rows),
+        count: rows.length,
+    });
+    const meta = world.meta && typeof world.meta === 'object' && !Array.isArray(world.meta) ? world.meta : {};
+    return [
+        snapshot('world-clock', 'REBUILD', [
+            {
+                clockTick: world.clockTick,
+                clockRevision: world.clockRevision,
+                deadlineGeneration: world.deadlineGeneration,
+            },
+        ]),
+        snapshot('turn-cursor', 'SHIFT', [{ lastTurnTick: world.lastTurnTick }]),
+        snapshot(
+            'general-next-turn',
+            'SHIFT',
+            generals.map(({ id, turnTick }) => ({ id, turnTick }))
+        ),
+        snapshot(
+            'general-recent-war-occurrence',
+            'KEEP',
+            generals.map(({ id, recentWarTick }) => ({ id, recentWarTick }))
+        ),
+        snapshot(
+            'auction-open-occurrence',
+            'KEEP',
+            auctions.map(({ id, openTick }) => ({ id, openTick }))
+        ),
+        snapshot(
+            'auction-deadline',
+            'SHIFT',
+            auctions.map(({ id, status, closeTick }) => ({ id, status, closeTick }))
+        ),
+        snapshot(
+            'auction-finalizing-recovery',
+            'REBUILD',
+            auctions.map(({ id, status }) => ({ id, status }))
+        ),
+        snapshot(
+            'message-occurrence',
+            'KEEP',
+            messages.map(({ id, timeTick }) => ({ id, timeTick }))
+        ),
+        snapshot(
+            'message-expiry',
+            'SHIFT',
+            messages.map(({ id, validUntilTick }) => ({ id, validUntilTick }))
+        ),
+        snapshot(
+            'vote-start-occurrence',
+            'KEEP',
+            votes.map(({ id, startTick }) => ({ id, startTick }))
+        ),
+        snapshot(
+            'vote-end-deadline',
+            'SHIFT',
+            votes.map(({ id, endTick }) => ({ id, endTick }))
+        ),
+        snapshot('select-pool-reservation', 'SHIFT', pool),
+        snapshot('npc-selection-window', 'SHIFT', npcTokens),
+        snapshot('accepted-command-coordinate', 'KEEP', commands),
+        snapshot('movable-json-rule-anchors', 'SHIFT', [
+            {
+                lastTurnTime: Reflect.get(meta, 'lastTurnTime'),
+                turntime: Reflect.get(meta, 'turntime'),
+                starttime: Reflect.get(meta, 'starttime'),
+                tnmt_time: Reflect.get(meta, 'tnmt_time'),
+            },
+        ]),
+    ];
+};
+
+const persistInitialParticipants = async (
+    db: GamePrisma.TransactionClient,
+    suspensionId: string,
+    participants: readonly ParticipantSnapshot[]
+): Promise<void> => {
+    for (const participant of participants) {
+        await db.clockReconciliationParticipant.create({
+            data: {
+                suspensionId,
+                participantKey: participant.key,
+                policy: participant.policy,
+                beforeChecksum: participant.checksum,
+                afterChecksum: participant.checksum,
+                affectedCount: 0,
+            },
+        });
+    }
+};
+
+const shiftMetaDate = (value: unknown, deltaMilliseconds: number): unknown => {
+    if (typeof value !== 'string' || !value.trim()) return value;
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) return value;
+    return new Date(parsed.getTime() + deltaMilliseconds).toISOString();
+};
+
+const shiftedMeta = (value: GamePrisma.JsonValue, deltaMilliseconds: number): GamePrisma.InputJsonValue => {
+    const meta = value && typeof value === 'object' && !Array.isArray(value) ? { ...value } : {};
+    for (const key of ['lastTurnTime', 'turntime', 'starttime', 'tnmt_time'] as const) {
+        if (Object.hasOwn(meta, key)) {
+            Reflect.set(meta, key, shiftMetaDate(Reflect.get(meta, key), deltaMilliseconds));
+        }
+    }
+    return asJson(meta);
+};
+
+const assertShiftFits = (participants: readonly ParticipantSnapshot[], shiftTicks: number): void => {
+    if (!Number.isSafeInteger(shiftTicks) || shiftTicks < 0) {
+        throw new Error(`Invalid reconciliation shift: ${shiftTicks}`);
+    }
+    // Checksums retain stringified values for audit; actual row ranges are
+    // checked by PostgreSQL BIGINT and the world aligned tick is checked by the
+    // shared GameClock plan. The sentinel expiry is deliberately never shifted.
+    if (participants.some((participant) => !participant.checksum)) {
+        throw new Error('Participant snapshot is incomplete.');
+    }
+};
+
+const assertScheduleRanges = async (db: GamePrisma.TransactionClient, shiftTicks: number): Promise<void> => {
+    const shift = BigInt(shiftTicks);
+    const maximum = BigInt(MAX_SAFE_GAME_TICK) - shift;
+    const [general, auction, message, vote, pool, npcValid, npcMore] = await Promise.all([
+        db.general.aggregate({ _max: { turnTick: true }, where: { turnTick: { not: null } } }),
+        db.auction.aggregate({
+            _max: { closeTick: true },
+            where: { status: { in: ['OPEN', 'FINALIZING'] }, closeTick: { not: null } },
+        }),
+        db.message.aggregate({
+            _max: { validUntilTick: true },
+            where: { validUntilTick: { not: null, lt: BigInt(MAX_SAFE_GAME_TICK) } },
+        }),
+        db.votePoll.aggregate({ _max: { endTick: true }, where: { closedAt: null, endTick: { not: null } } }),
+        db.selectPoolEntry.aggregate({
+            _max: { reservedUntilTick: true },
+            where: { generalId: null, reservedUntilTick: { not: null } },
+        }),
+        db.npcSelectionToken.aggregate({ _max: { validUntilTick: true }, where: { validUntilTick: { not: null } } }),
+        db.npcSelectionToken.aggregate({
+            _max: { pickMoreFromTick: true },
+            where: { pickMoreFromTick: { not: null } },
+        }),
+    ]);
+    const values: Array<[string, bigint | null]> = [
+        ['general.turn_tick', general._max.turnTick],
+        ['auction.close_tick', auction._max.closeTick],
+        ['message.valid_until_tick', message._max.validUntilTick],
+        ['vote_poll.end_tick', vote._max.endTick],
+        ['select_pool.reserved_until_tick', pool._max.reservedUntilTick],
+        ['select_npc_token.valid_until_tick', npcValid._max.validUntilTick],
+        ['select_npc_token.pick_more_from_tick', npcMore._max.pickMoreFromTick],
+    ];
+    for (const [label, value] of values) {
+        if (value !== null && value > maximum) {
+            throw new Error(`${label} would exceed the safe game tick range after reconciliation.`);
+        }
+    }
+};
+
+const applyParticipantShift = async (
+    db: GamePrisma.TransactionClient,
+    worldStateId: number,
+    cutTick: bigint,
+    alignedTick: bigint,
+    targetRevision: bigint,
+    targetGeneration: bigint,
+    shiftTicks: bigint,
+    projectionDeltaMilliseconds: number,
+    resumeWallAt: Date
+): Promise<Map<string, number>> => {
+    const affected = new Map<string, number>();
+    const world = await db.worldState.findUniqueOrThrow({ where: { id: worldStateId }, select: { meta: true } });
+    const cursor = await db.worldState.updateMany({
+        where: { id: worldStateId, lastTurnTick: { not: null } },
+        data: { lastTurnTick: { increment: shiftTicks } },
+    });
+    affected.set('turn-cursor', cursor.count);
+    affected.set(
+        'general-next-turn',
+        await db.$executeRaw(GamePrisma.sql`
+            UPDATE general
+            SET turn_tick = turn_tick + ${shiftTicks},
+                turn_time = turn_time + ${projectionDeltaMilliseconds} * INTERVAL '1 millisecond'
+            WHERE turn_tick IS NOT NULL
+        `)
+    );
+    affected.set(
+        'auction-deadline',
+        await db.$executeRaw(GamePrisma.sql`
+            UPDATE auction
+            SET close_tick = close_tick + ${shiftTicks},
+                close_at = close_at + ${projectionDeltaMilliseconds} * INTERVAL '1 millisecond'
+            WHERE status IN ('OPEN'::auction_status, 'FINALIZING'::auction_status)
+              AND close_tick IS NOT NULL
+        `)
+    );
+    affected.set(
+        'message-expiry',
+        await db.$executeRaw(GamePrisma.sql`
+            UPDATE message
+            SET valid_until_tick = valid_until_tick + ${shiftTicks},
+                valid_until = valid_until + ${projectionDeltaMilliseconds} * INTERVAL '1 millisecond'
+            WHERE valid_until_tick IS NOT NULL
+              AND valid_until_tick >= ${cutTick}
+              AND valid_until_tick < ${BigInt(MAX_SAFE_GAME_TICK)}
+        `)
+    );
+    affected.set(
+        'vote-end-deadline',
+        await db.$executeRaw(GamePrisma.sql`
+            UPDATE vote_poll
+            SET end_tick = end_tick + ${shiftTicks},
+                end_at = end_at + ${projectionDeltaMilliseconds} * INTERVAL '1 millisecond'
+            WHERE closed_at IS NULL AND end_tick IS NOT NULL
+        `)
+    );
+    affected.set(
+        'select-pool-reservation',
+        await db.$executeRaw(GamePrisma.sql`
+            UPDATE select_pool
+            SET reserved_until_tick = reserved_until_tick + ${shiftTicks},
+                reserved_until = reserved_until + ${projectionDeltaMilliseconds} * INTERVAL '1 millisecond'
+            WHERE general_id IS NULL AND reserved_until_tick IS NOT NULL
+        `)
+    );
+    affected.set(
+        'npc-selection-window',
+        await db.$executeRaw(GamePrisma.sql`
+            UPDATE select_npc_token
+            SET valid_until_tick = CASE
+                    WHEN valid_until_tick IS NULL THEN NULL ELSE valid_until_tick + ${shiftTicks} END,
+                valid_until = CASE
+                    WHEN valid_until_tick IS NULL THEN valid_until
+                    ELSE valid_until + ${projectionDeltaMilliseconds} * INTERVAL '1 millisecond' END,
+                pick_more_from_tick = CASE
+                    WHEN pick_more_from_tick IS NULL THEN NULL ELSE pick_more_from_tick + ${shiftTicks} END,
+                pick_more_from = CASE
+                    WHEN pick_more_from_tick IS NULL THEN pick_more_from
+                    ELSE pick_more_from + ${projectionDeltaMilliseconds} * INTERVAL '1 millisecond' END
+            WHERE valid_until_tick IS NOT NULL OR pick_more_from_tick IS NOT NULL
+        `)
+    );
+    await db.worldState.update({
+        where: { id: worldStateId },
+        data: {
+            clockTick: alignedTick,
+            clockWallAnchor: resumeWallAt,
+            clockPhase: 'RECONCILING',
+            clockRevision: targetRevision,
+            deadlineGeneration: targetGeneration,
+            meta: shiftedMeta(world.meta, projectionDeltaMilliseconds),
+        },
+    });
+    affected.set('world-clock', 1);
+    affected.set('movable-json-rule-anchors', 1);
+    affected.set('auction-finalizing-recovery', 0);
+    return affected;
+};
+
+export const startClockSuspension = async (options: {
+    db: GamePrismaClient;
+    suspensionId: string;
+    source: ClockSuspensionSource;
+    authority: ClockOperationAuthority;
+    policy?: ClockAlignmentPolicy;
+    catchUpTicks?: number;
+}): Promise<ClockSuspensionResult> => {
+    if (!options.suspensionId.trim() || options.suspensionId.length > 64) {
+        throw new Error('Clock suspension ID must contain 1-64 characters.');
+    }
+    const policy = options.policy ?? 'EXACT';
+    const catchUpTicks = options.catchUpTicks ?? 0;
+    if (!Number.isSafeInteger(catchUpTicks) || catchUpTicks < 0) {
+        throw new Error('Clock suspension catch-up ticks must be a non-negative safe integer.');
+    }
+    return options.db.$transaction(
+        async (db) => {
+            await verifyAuthority(db, options.authority);
+            await acquireGameSchemaAdvisoryXactLock(db, CLOCK_OPERATION_PERSISTENCE_LOCK);
+            await acquireGameSchemaAdvisoryXactLock(db, GENERAL_ACCESS_PERSISTENCE_LOCK);
+            const worldStateId = await lockWorld(db);
+            const existing = await db.clockSuspension.findUnique({ where: { id: options.suspensionId } });
+            if (existing) {
+                if (existing.worldStateId !== worldStateId || existing.source !== options.source || existing.policy !== policy) {
+                    throw new Error(`Clock suspension ID ${options.suspensionId} is already bound to another operation.`);
+                }
+                if (existing.status !== 'SUSPENDED') {
+                    throw new Error(`Clock suspension ${options.suspensionId} already advanced to ${existing.status}.`);
+                }
+                return {
+                    suspensionId: existing.id,
+                    phase: 'SUSPENDED' as const,
+                    sourceRevision: safeNumber(existing.sourceRevision, 'source revision'),
+                    targetRevision: safeNumber(existing.targetRevision, 'target revision'),
+                    cutTick: safeNumber(existing.cutTick, 'cut tick'),
+                    cutWallAt: existing.cutWallAt,
+                };
+            }
+            const world = await db.worldState.findUniqueOrThrow({ where: { id: worldStateId } });
+            const phase = parseGameClockPhase(world.clockPhase);
+            if (phase !== 'RUNNING') {
+                throw new Error(`Clock suspension can start only from RUNNING; current phase is ${phase}.`);
+            }
+            if (!world.clockBaseTime || world.clockTick === null || !world.clockWallAnchor) {
+                throw new Error('Clock suspension requires a fully initialized logical game clock.');
+            }
+            const cutWallAt = await readDbWall(db);
+            const storedTick = safeNumber(world.clockTick, 'world clock tick');
+            const sourceRevision = safeNumber(world.clockRevision, 'world clock revision');
+            const clock = new GameClock({
+                baseTime: world.clockBaseTime,
+                tick: storedTick,
+                mode: world.clockMode === 'manual' ? 'manual' : 'realtime',
+                wallAnchor: world.clockWallAnchor,
+                turnSeconds: world.tickSeconds,
+                phase,
+                revision: sourceRevision,
+            });
+            const cutTick = clock.nowTick(cutWallAt);
+            await lockParticipants(db, BigInt(cutTick));
+            await db.worldState.update({
+                where: { id: worldStateId },
+                data: { clockPhase: 'SUSPENDED', clockTick: BigInt(cutTick), clockWallAnchor: cutWallAt },
+            });
+            const participants = await readParticipantSnapshots(db, worldStateId, BigInt(cutTick));
+            await db.clockSuspension.create({
+                data: {
+                    id: options.suspensionId,
+                    worldStateId,
+                    source: options.source,
+                    policy,
+                    status: 'SUSPENDED',
+                    sourceRevision: BigInt(sourceRevision),
+                    targetRevision: BigInt(sourceRevision + 1),
+                    cutTick: BigInt(cutTick),
+                    cutWallAt,
+                    rateTicksPerSecond: GAME_TICKS_PER_TURN / world.tickSeconds,
+                    catchUpTicks: BigInt(catchUpTicks),
+                    participantChecksumBefore: aggregateChecksum(participants),
+                    detail: asJson({ authority: options.authority.kind, profileName: options.authority.profileName }),
+                },
+            });
+            await persistInitialParticipants(db, options.suspensionId, participants);
+            return {
+                suspensionId: options.suspensionId,
+                phase: 'SUSPENDED',
+                sourceRevision,
+                targetRevision: sourceRevision + 1,
+                cutTick,
+                cutWallAt,
+            };
+        },
+        { isolationLevel: 'Serializable', maxWait: 10_000, timeout: 30_000 }
+    );
+};
+
+export const reconcileClockSuspension = async (options: {
+    db: GamePrismaClient;
+    suspensionId: string;
+    authority: ClockOperationAuthority;
+    /** Deterministic fixture seam; production must always use PostgreSQL CURRENT_TIMESTAMP. */
+    testResumeWallAt?: Date;
+}): Promise<ClockReconciliationResult> =>
+    options.db.$transaction(
+        async (db) => {
+            await verifyAuthority(db, options.authority);
+            await acquireGameSchemaAdvisoryXactLock(db, CLOCK_OPERATION_PERSISTENCE_LOCK);
+            await acquireGameSchemaAdvisoryXactLock(db, GENERAL_ACCESS_PERSISTENCE_LOCK);
+            const worldStateId = await lockWorld(db);
+            const suspension = await db.clockSuspension.findUniqueOrThrow({ where: { id: options.suspensionId } });
+            if (suspension.worldStateId !== worldStateId) {
+                throw new Error('Clock suspension belongs to another world state.');
+            }
+            if (suspension.status === 'RECONCILING' || suspension.status === 'APPLIED') {
+                if (
+                    suspension.gapTicks === null ||
+                    suspension.shiftTicks === null ||
+                    suspension.alignedTick === null ||
+                    !suspension.resumeWallAt
+                ) {
+                    throw new Error('Persisted clock reconciliation result is incomplete.');
+                }
+                const world = await db.worldState.findUniqueOrThrow({ where: { id: worldStateId } });
+                return {
+                    suspensionId: suspension.id,
+                    phase: 'RECONCILING' as const,
+                    sourceRevision: safeNumber(suspension.sourceRevision, 'source revision'),
+                    targetRevision: safeNumber(suspension.targetRevision, 'target revision'),
+                    deadlineGeneration: safeNumber(world.deadlineGeneration, 'deadline generation'),
+                    gapTicks: safeNumber(suspension.gapTicks, 'gap ticks'),
+                    catchUpTicks: safeNumber(suspension.catchUpTicks, 'catch-up ticks'),
+                    shiftTicks: safeNumber(suspension.shiftTicks, 'shift ticks'),
+                    alignedTick: safeNumber(suspension.alignedTick, 'aligned tick'),
+                    resumeWallAt: suspension.resumeWallAt,
+                };
+            }
+            if (suspension.status !== 'SUSPENDED') {
+                throw new Error(`Clock suspension cannot reconcile from status ${suspension.status}.`);
+            }
+            const world = await db.worldState.findUniqueOrThrow({ where: { id: worldStateId } });
+            const phase = parseGameClockPhase(world.clockPhase);
+            if (phase !== 'SUSPENDED' || world.clockRevision !== suspension.sourceRevision) {
+                throw new Error('Clock reconciliation phase or source revision fence failed.');
+            }
+            const worldMeta =
+                world.meta && typeof world.meta === 'object' && !Array.isArray(world.meta)
+                    ? (world.meta as Record<string, unknown>)
+                    : {};
+            const united = Number(worldMeta.isunited ?? worldMeta.isUnited ?? 0);
+            if (suspension.source === 'UNIFICATION_WAIT' || united >= 2) {
+                throw new Error(
+                    'Unification wait requires the atomic alignment-and-invader workflow; generic resume is forbidden.'
+                );
+            }
+            const cutTick = safeNumber(suspension.cutTick, 'cut tick');
+            await lockParticipants(db, suspension.cutTick);
+            if (options.testResumeWallAt && process.env.NODE_ENV !== 'test') {
+                throw new Error('A clock reconciliation wall override is allowed only in tests.');
+            }
+            const resumeWallAt = options.testResumeWallAt
+                ? new Date(options.testResumeWallAt.getTime())
+                : await readDbWall(db);
+            const plan = buildClockAlignmentPlan({
+                policy: parseClockAlignmentPolicy(suspension.policy),
+                sourceRevision: safeNumber(suspension.sourceRevision, 'source revision'),
+                cutTick,
+                cutWall: suspension.cutWallAt,
+                resumeWall: resumeWallAt,
+                ticksPerSecond: suspension.rateTicksPerSecond,
+                catchUpTicks: safeNumber(suspension.catchUpTicks, 'catch-up ticks'),
+            });
+            const before = await readParticipantSnapshots(db, worldStateId, suspension.cutTick);
+            assertShiftFits(before, plan.shiftTicks);
+            await assertScheduleRanges(db, plan.shiftTicks);
+            const projectionDeltaMilliseconds = Math.trunc(
+                (plan.shiftTicks * 1_000) / suspension.rateTicksPerSecond
+            );
+            if (!Number.isSafeInteger(projectionDeltaMilliseconds)) {
+                throw new Error('Clock reconciliation projection delta is outside the safe integer range.');
+            }
+            const targetGeneration = world.deadlineGeneration + 1n;
+            const affected = await applyParticipantShift(
+                db,
+                worldStateId,
+                suspension.cutTick,
+                BigInt(plan.alignedTick),
+                BigInt(plan.targetRevision),
+                targetGeneration,
+                BigInt(plan.shiftTicks),
+                projectionDeltaMilliseconds,
+                resumeWallAt
+            );
+            const after = await readParticipantSnapshots(db, worldStateId, suspension.cutTick);
+            const afterByKey = new Map(after.map((participant) => [participant.key, participant]));
+            for (const participant of before) {
+                const next = afterByKey.get(participant.key);
+                if (!next) throw new Error(`Missing post-reconciliation participant: ${participant.key}`);
+                if (participant.policy === 'KEEP' && participant.checksum !== next.checksum) {
+                    throw new Error(`KEEP participant changed during reconciliation: ${participant.key}`);
+                }
+                await db.clockReconciliationParticipant.upsert({
+                    where: {
+                        suspensionId_participantKey: {
+                            suspensionId: suspension.id,
+                            participantKey: participant.key,
+                        },
+                    },
+                    create: {
+                        suspensionId: suspension.id,
+                        participantKey: participant.key,
+                        policy: participant.policy,
+                        beforeChecksum: participant.checksum,
+                        afterChecksum: next.checksum,
+                        affectedCount: affected.get(participant.key) ?? 0,
+                    },
+                    update: {
+                        policy: participant.policy,
+                        beforeChecksum: participant.checksum,
+                        afterChecksum: next.checksum,
+                        affectedCount: affected.get(participant.key) ?? 0,
+                    },
+                });
+            }
+            const outboxPayload = {
+                version: 1,
+                profileName: options.authority.profileName,
+                suspensionId: suspension.id,
+                sourceRevision: plan.sourceRevision,
+                targetRevision: plan.targetRevision,
+                deadlineGeneration: safeNumber(targetGeneration, 'deadline generation'),
+                shiftTicks: plan.shiftTicks,
+                projectionDeltaMilliseconds,
+                clockBaseTime: world.clockBaseTime!.toISOString(),
+                ticksPerSecond: suspension.rateTicksPerSecond,
+            };
+            await db.clockProjectionOutbox.create({
+                data: {
+                    worldStateId,
+                    suspensionId: suspension.id,
+                    targetRevision: BigInt(plan.targetRevision),
+                    status: 'PENDING',
+                    payload: asJson(outboxPayload),
+                    checksum: checksum(outboxPayload),
+                },
+            });
+            await db.clockSuspension.update({
+                where: { id: suspension.id },
+                data: {
+                    status: 'RECONCILING',
+                    resumeWallAt,
+                    gapTicks: BigInt(plan.gapTicks),
+                    shiftTicks: BigInt(plan.shiftTicks),
+                    alignedTick: BigInt(plan.alignedTick),
+                    participantChecksumBefore: aggregateChecksum(before),
+                    participantChecksumAfter: aggregateChecksum(after),
+                },
+            });
+            return {
+                suspensionId: suspension.id,
+                phase: 'RECONCILING',
+                sourceRevision: plan.sourceRevision,
+                targetRevision: plan.targetRevision,
+                deadlineGeneration: safeNumber(targetGeneration, 'deadline generation'),
+                gapTicks: plan.gapTicks,
+                catchUpTicks: plan.catchUpTicks,
+                shiftTicks: plan.shiftTicks,
+                alignedTick: plan.alignedTick,
+                resumeWallAt,
+            };
+        },
+        { isolationLevel: 'Serializable', maxWait: 10_000, timeout: 30_000 }
+    );
@@ -1218,6 +1218,34 @@ export const createDatabaseTurnHooks = async (
                        `found ${durableClock.clock_phase}@${durableClock.clock_revision}/${durableClock.deadline_generation}.`
                );
            }
+            if (commandCompletion) {
+                const commandFence = await prisma.$queryRaw<
+                    Array<{
+                        status: string;
+                        processing_clock_revision: bigint | null;
+                        processing_deadline_generation: bigint | null;
+                    }>
+                >(GamePrisma.sql`
+                    SELECT status,
+                           processing_clock_revision,
+                           processing_deadline_generation
+                    FROM input_event
+                    WHERE request_id = ${commandCompletion.requestId}
+                      AND target = 'ENGINE'::"InputEventTarget"
+                    FOR UPDATE
+                `);
+                const event = commandFence[0];
+                if (
+                    !event ||
+                    event.status !== 'PROCESSING' ||
+                    event.processing_clock_revision !== expectedRevision ||
+                    event.processing_deadline_generation !== expectedGeneration
+                ) {
+                    throw new Error(
+                        `Input event processing clock fence changed before commit: ${commandCompletion.requestId}.`
+                    );
+                }
+            }
            let neutralAuctionsToCreate = pendingNeutralAuctions;
            if (pendingNeutralAuctions.length > 0) {
                const latestRegistrationKey =
@@ -1,4 +1,4 @@
-import type { GamePrisma, GamePrismaClient } from '@sammo-ts/infra';
+import { readInputEventClockCoordinate, type GamePrisma, type GamePrismaClient } from '@sammo-ts/infra';
 import { randomUUID } from 'node:crypto';

 import {
@@ -137,13 +137,20 @@ const ensureEngineCommand = async (
        deltaMinutes,
    };
    try {
-        await db.inputEvent.create({
-            data: {
-                requestId,
-                target: 'ENGINE',
-                eventType: command.type,
-                payload: asJson(command),
-            },
+        await db.$transaction(async (transaction) => {
+            const coordinate = await readInputEventClockCoordinate(transaction);
+            await transaction.inputEvent.create({
+                data: {
+                    requestId,
+                    target: 'ENGINE',
+                    eventType: command.type,
+                    payload: asJson(command),
+                    acceptedGameTick: coordinate.gameTick,
+                    acceptedClockRevision: coordinate.clockRevision,
+                    acceptedDeadlineGeneration: coordinate.deadlineGeneration,
+                    createdAt: coordinate.wallAt,
+                },
+            });
        });
    } catch (error) {
        if (!isUniqueConflict(error)) {
@@ -10,7 +10,7 @@ import {
    type TurnDaemonCommand,
    type TurnDaemonCommandResult,
 } from '@sammo-ts/common';
-import type { GamePrisma, GamePrismaClient } from '@sammo-ts/infra';
+import { readInputEventClockCoordinate, type GamePrisma, type GamePrismaClient } from '@sammo-ts/infra';

 import type { GatewayAdminActionRecord, GatewayAdminActionResult } from './gatewayAdminActions.js';

@@ -97,13 +97,20 @@ const ensureEngineCommand = async (
        settings,
    };
    try {
-        await db.inputEvent.create({
-            data: {
-                requestId,
-                target: 'ENGINE',
-                eventType: command.type,
-                payload: asJson(command),
-            },
+        await db.$transaction(async (transaction) => {
+            const coordinate = await readInputEventClockCoordinate(transaction);
+            await transaction.inputEvent.create({
+                data: {
+                    requestId,
+                    target: 'ENGINE',
+                    eventType: command.type,
+                    payload: asJson(command),
+                    acceptedGameTick: coordinate.gameTick,
+                    acceptedClockRevision: coordinate.clockRevision,
+                    acceptedDeadlineGeneration: coordinate.deadlineGeneration,
+                    createdAt: coordinate.wallAt,
+                },
+            });
        });
    } catch (error) {
        if (!isUniqueConflict(error)) throw error;
@@ -439,15 +439,20 @@ export const reserveSelectionPool = async (options: {
    userId: string;
    now?: Date;
    acceptedGameTick?: number;
+    processingGameTick?: number;
    seedOwnerIdentity?: string | number;
 }): Promise<SelectPoolReservationDto> => {
    const { db, world, worldState, userId } = options;
    requirePoolWorld(worldState);
    const now = options.now ?? new Date();
    const acceptedGameTick = options.acceptedGameTick ?? resolveAcceptedGameTick(world, now);
+    const processingGameTick = options.processingGameTick ?? acceptedGameTick;
    if (!Number.isSafeInteger(acceptedGameTick)) {
        fail('INTERNAL_SERVER_ERROR', '장수 선택 예약 tick이 안전한 정수 범위를 벗어났습니다.');
    }
+    if (!Number.isSafeInteger(processingGameTick)) {
+        fail('INTERNAL_SERVER_ERROR', '장수 선택 처리 tick이 안전한 정수 범위를 벗어났습니다.');
+    }
    await lockSelectionUser(db, userId);
    await lockSelectionMutationTables(db);
    const general = await db.general.findFirst({
@@ -461,7 +466,7 @@ export const reserveSelectionPool = async (options: {

    let currentRows = await synchronizeSelectionPoolWorld(db, world);
    const existing = currentRows.filter(
-        (row) => row.ownerUserId === userId && row.generalId === null && isReservationActive(row, now, acceptedGameTick)
+        (row) => row.ownerUserId === userId && row.generalId === null && isReservationActive(row, now, processingGameTick)
    );
    if (existing.length > 0) {
        return toReservationDto(existing, Boolean(general), worldState, world);
@@ -471,7 +476,7 @@ export const reserveSelectionPool = async (options: {
        where: {
            generalId: null,
            OR: [
-                { reservedUntilTick: { lt: BigInt(acceptedGameTick) } },
+                { reservedUntilTick: { lt: BigInt(processingGameTick) } },
                { reservedUntilTick: null, reservedUntil: { lt: now } },
            ],
        },
@@ -483,7 +488,7 @@ export const reserveSelectionPool = async (options: {
    });
    currentRows = await synchronizeSelectionPoolWorld(db, world);
    const availableIds = new Set(
-        world.listGeneralPoolCandidates(now, acceptedGameTick)?.map((candidate) => candidate.poolEntryId) ?? []
+        world.listGeneralPoolCandidates(now, processingGameTick)?.map((candidate) => candidate.poolEntryId) ?? []
    );
    const available = currentRows.filter(
        (row) =>
@@ -507,7 +512,7 @@ export const reserveSelectionPool = async (options: {
        (row) =>
            [row, calculateSelectionCandidateWeight(poolName, parseCandidate(row), true)] as [SelectPoolRow, number]
    );
-    const reservedUntilTick = acceptedGameTick + RESERVATION_TURN_MULTIPLIER * GAME_TICKS_PER_TURN;
+    const reservedUntilTick = processingGameTick + RESERVATION_TURN_MULTIPLIER * GAME_TICKS_PER_TURN;
    if (!Number.isSafeInteger(reservedUntilTick)) {
        fail('INTERNAL_SERVER_ERROR', '장수 선택 예약 tick이 안전한 정수 범위를 벗어났습니다.');
    }
@@ -14,8 +14,12 @@ 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;
@@ -76,6 +80,9 @@ export const createTournamentAutoStartHandler = (options: {
        sourceRevisionKey: `sammo:${options.profileName}:tournament:source-revision`,
        sourceRevisionChannel: `sammo:${options.profileName}:tournament:source-changed`,
        realtimeEventChannel: buildGameEventChannel(options.profileName),
+        activeClockRevisionKey: `sammo:${options.profileName}:clock:active-revision`,
+        deadlineGenerationKey: `sammo:${options.profileName}:clock:deadline-generation`,
+        clockPhaseKey: `sammo:${options.profileName}:clock:phase`,
    };
    return {
        onMonthChanged: async (context) => {
@@ -118,6 +125,8 @@ export const createTournamentAutoStartHandler = (options: {
                previousState && Number.isFinite(previousState.termSeconds) && previousState.termSeconds > 0
                    ? previousState.termSeconds
                    : resolveTermSeconds(state.tickSeconds);
+            const nextAt = new Date(now.getTime() + termSeconds * 60_000);
+            const clockState = world.getGameClockState();
            const nextState: TournamentState = {
                stage: 1,
                phase: 0,
@@ -129,7 +138,10 @@ export const createTournamentAutoStartHandler = (options: {
                // Ref startTournament() passes calcTournamentTerm()'s seconds
                // value to DateInterval's minute field. Preserve that historical
                // initial enrollment delay; later tournament phases use seconds.
-                nextAt: new Date(now.getTime() + termSeconds * 60_000).toISOString(),
+                nextAt: nextAt.toISOString(),
+                nextTick: world.dateToGameTick(nextAt),
+                clockRevision: clockState.revision,
+                deadlineGeneration: clockState.deadlineGeneration,
                bettingId:
                    typeof previousState?.bettingId === 'number' && Number.isFinite(previousState.bettingId)
                        ? previousState.bettingId + 1
@@ -142,12 +154,26 @@ export const createTournamentAutoStartHandler = (options: {
                lastError: undefined,
                lastErrorAt: undefined,
            };
-            await writeTournamentProjection(redis, keys, [
-                { key: keys.participantsKey, value: [] },
-                { key: keys.matchesKey, value: [] },
-                { key: keys.bettingKey, value: [] },
-                { key: keys.stateKey, value: nextState },
-            ]);
+            await writeTournamentProjection(
+                redis,
+                keys,
+                [
+                    { key: keys.participantsKey, value: [] },
+                    { key: keys.matchesKey, value: [] },
+                    { key: keys.bettingKey, value: [] },
+                    { key: keys.stateKey, value: nextState },
+                ],
+                clockState.phase === 'RUNNING'
+                    ? {
+                          activeRevisionKey: keys.activeClockRevisionKey,
+                          deadlineGenerationKey: keys.deadlineGenerationKey,
+                          phaseKey: keys.clockPhaseKey,
+                          revision: clockState.revision,
+                          deadlineGeneration: clockState.deadlineGeneration,
+                          phase: 'RUNNING',
+                      }
+                    : undefined
+            );

            const [typeText, generalTypeText] = TOURNAMENT_TEXT[type] ?? TOURNAMENT_TEXT[0];
            const emperor = world
@@ -274,6 +274,10 @@ const resolveSelectionCommandAcceptedAt = async (
    command: Extract<TurnDaemonCommand, { type: 'selectPoolReserve' | 'selectPoolCreate' | 'selectPoolReselect' }>
 ): Promise<Date> => {
    const operationalAcceptedAt = await resolveCommandAcceptedAt(db, command);
+    const processingGameTick = Reflect.get(command, 'processingGameTick');
+    if (typeof processingGameTick === 'number' && Number.isSafeInteger(processingGameTick)) {
+        return world.gameTickToDate(processingGameTick);
+    }
    if (command.acceptedGameTick !== undefined) {
        return world.gameTickToDate(command.acceptedGameTick);
    }
@@ -407,9 +411,13 @@ async function handleNpcPossessGeneral(
        throw new Error('NPC possession world state is missing.');
    }
    const operationalAcceptedAt = await resolveCommandAcceptedAt(db, command);
-    const acceptedAt = command.acceptedGameAt
-        ? new Date(command.acceptedGameAt)
-        : ctx.world.getGameNow(operationalAcceptedAt);
+    const processingGameTick = Reflect.get(command, 'processingGameTick');
+    const acceptedAt =
+        typeof processingGameTick === 'number' && Number.isSafeInteger(processingGameTick)
+            ? ctx.world.gameTickToDate(processingGameTick)
+            : command.acceptedGameAt
+              ? new Date(command.acceptedGameAt)
+              : ctx.world.getGameNow(operationalAcceptedAt);
    try {
        return {
            type: 'npcPossessGeneral',
@@ -451,8 +459,11 @@ async function handleSelectPoolCreate(
        throw new Error('Selection-pool world state is missing.');
    }
    const operationalAcceptedAt = await resolveCommandAcceptedAt(db, command);
+    const processingGameTick = Reflect.get(command, 'processingGameTick');
    const acceptedAt =
-        command.acceptedGameTick !== undefined
+        typeof processingGameTick === 'number' && Number.isSafeInteger(processingGameTick)
+            ? ctx.world.gameTickToDate(processingGameTick)
+            : command.acceptedGameTick !== undefined
            ? ctx.world.gameTickToDate(command.acceptedGameTick)
            : command.acceptedGameAt !== undefined
              ? new Date(command.acceptedGameAt)
@@ -515,6 +526,9 @@ async function handleSelectPoolReserve(
                seedOwnerIdentity: command.seedOwnerIdentity,
                now: acceptedAt,
                ...(command.acceptedGameTick === undefined ? {} : { acceptedGameTick: command.acceptedGameTick }),
+                ...(typeof Reflect.get(command, 'processingGameTick') === 'number'
+                    ? { processingGameTick: Reflect.get(command, 'processingGameTick') as number }
+                    : {}),
            }),
        };
    } catch (error) {
@@ -2770,9 +2784,15 @@ const validateVoteSelectionInTransaction = async (
    if (!poll) return '설문조사가 없습니다.';

    const processingNow = ctx.world.getGameNow(new Date());
-    const acceptedGameTick = command.acceptedGameTick ?? ctx.world.dateToGameTick(processingNow);
+    const convertedProcessingTick = Reflect.get(command, 'processingGameTick');
+    const acceptedGameTick =
+        typeof convertedProcessingTick === 'number' && Number.isSafeInteger(convertedProcessingTick)
+            ? convertedProcessingTick
+            : (command.acceptedGameTick ?? ctx.world.dateToGameTick(processingNow));
    const acceptedGameAt =
-        command.acceptedGameTick === undefined ? processingNow : ctx.world.gameTickToDate(command.acceptedGameTick);
+        command.acceptedGameTick === undefined && convertedProcessingTick === undefined
+            ? processingNow
+            : ctx.world.gameTickToDate(acceptedGameTick);
    if (hasVotePollDeadlinePassed(poll, acceptedGameAt, acceptedGameTick)) {
        return '설문조사가 종료되었습니다.';
    }