feat: 플레이 감사 월별 수집과 원자적 배치 저장 연결

2026-09-16 02:37:38 +00:00
parent 4de3175279
commit 35155e6b59
14 changed files with 594 additions and 12 deletions
@@ -0,0 +1,83 @@
+import { asRecord } from '@sammo-ts/common';
+import type { InMemoryTurnWorld, TurnCalendarHandler } from '../turn/inMemoryWorld.js';
+import { buildAuditSnapshot, type AuditSettlement } from './snapshot.js';
+
+interface MonthlyFlows {
+    year: number;
+    month: number;
+    complete: boolean;
+    entries: Record<string, AuditSettlement>;
+}
+
+const readFlows = (world: InMemoryTurnWorld): MonthlyFlows => {
+    const state = world.getState();
+    const raw = asRecord(state.meta.playAuditFlows);
+    const entries: Record<string, AuditSettlement> = {};
+    const matches = raw.year === state.currentYear && raw.month === state.currentMonth;
+    if (matches) {
+        for (const [key, value] of Object.entries(asRecord(raw.entries))) {
+            const row = asRecord(value);
+            if (
+                typeof row.nationId === 'number' &&
+                (row.resource === 'gold' || row.resource === 'rice') &&
+                typeof row.income === 'number' &&
+                Number.isFinite(row.income) &&
+                typeof row.paid === 'number' &&
+                Number.isFinite(row.paid)
+            ) {
+                entries[key] = { nationId: row.nationId, resource: row.resource, income: row.income, paid: row.paid };
+            }
+        }
+    }
+    return { year: state.currentYear, month: state.currentMonth, complete: matches && raw.complete === true, entries };
+};
+
+export const recordAuditSettlement = (world: InMemoryTurnWorld, settlement: AuditSettlement): void => {
+    if (typeof world.getState().meta.serverId !== 'string') return;
+    const flows = readFlows(world);
+    const key = `${settlement.nationId}:${settlement.resource}`;
+    const previous = flows.entries[key];
+    flows.entries[key] = {
+        ...settlement,
+        income: (previous?.income ?? 0) + settlement.income,
+        paid: (previous?.paid ?? 0) + settlement.paid,
+    };
+    // 월내 flush/reload에도 누적값을 잃지 않도록 작은 국가별 합계만 world meta에 보존한다.
+    world.updateWorldMeta({ playAuditFlows: flows });
+};
+
+export const queueAuditMonth = (world: InMemoryTurnWorld, kind: 'MONTH_END' | 'FINAL' = 'MONTH_END'): void => {
+    const state = world.getState();
+    const serverId = state.meta.serverId;
+    // identity 없는 레거시 fixture/설치에서 profile명으로 가짜 기수를 만들지 않는다.
+    if (typeof serverId !== 'string' || !serverId.trim()) return;
+    const flows = readFlows(world);
+    const snapshot = buildAuditSnapshot({
+        nations: world.listNations(),
+        cities: world.listCities(),
+        generals: world.listGenerals(),
+        settlements: Object.values(flows.entries),
+        settlementsComplete: flows.complete,
+    });
+    world.queueAuditMonth({
+        ...snapshot,
+        serverId,
+        year: state.currentYear,
+        month: state.currentMonth,
+        tick: state.lastTurnTick ?? null,
+        kind,
+        settlementsComplete: flows.complete,
+    });
+};
+
+export const createPlayAuditHandler = (getWorld: () => InMemoryTurnWorld | null): TurnCalendarHandler => ({
+    beforeMonthChanged: (context) => {
+        const world = getWorld();
+        if (!world) return;
+        queueAuditMonth(world);
+        // 다음 달의 정산보다 먼저 활성화한다. 도입 당월은 complete=false로 남긴다.
+        world.updateWorldMeta({
+            playAuditFlows: { year: context.currentYear, month: context.currentMonth, complete: true, entries: {} },
+        });
+    },
+});
@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto';
+import type { GamePrisma, InputJsonValue } from '@sammo-ts/infra';
+import type { AuditCitySnapshot, AuditGeneralSnapshot, AuditNationSnapshot } from './snapshot.js';
+
+export interface PendingAuditMonth {
+    serverId: string;
+    year: number;
+    month: number;
+    kind: 'MONTH_END' | 'FINAL';
+    tick: number | null;
+    settlementsComplete: boolean;
+    nations: AuditNationSnapshot[];
+    cities: AuditCitySnapshot[];
+    generals: AuditGeneralSnapshot[];
+}
+
+// JSON parameter 한 번에 전체 기수나 world를 전송하지 않는다.
+const BATCH_SIZE = 200;
+const asJson = (value: AuditNationSnapshot | AuditCitySnapshot | AuditGeneralSnapshot): InputJsonValue =>
+    JSON.parse(JSON.stringify(value)) as InputJsonValue;
+
+export const persistAuditMonth = async (
+    tx: GamePrisma.TransactionClient,
+    snapshot: PendingAuditMonth
+): Promise<void> => {
+    if (
+        !snapshot.serverId.trim() ||
+        !Number.isInteger(snapshot.year) ||
+        !Number.isInteger(snapshot.month) ||
+        snapshot.month < 1 ||
+        snapshot.month > 12
+    ) {
+        throw new Error('Invalid play audit month identity');
+    }
+    const id = JSON.stringify([snapshot.serverId, snapshot.year, snapshot.month, snapshot.kind]);
+    const hash = createHash('sha256').update(JSON.stringify(snapshot)).digest('hex');
+    const saved = await tx.playAuditMonth.upsert({
+        where: { id },
+        create: {
+            id,
+            serverId: snapshot.serverId,
+            year: snapshot.year,
+            month: snapshot.month,
+            kind: snapshot.kind,
+            tick: snapshot.tick,
+            settlementsComplete: snapshot.settlementsComplete,
+            hash,
+        },
+        update: {},
+        select: { hash: true },
+    });
+    if (saved.hash !== hash) throw new Error('Play audit month replay payload conflict');
+    for (let offset = 0; offset < snapshot.nations.length; offset += BATCH_SIZE) {
+        await tx.playAuditNation.createMany({
+            skipDuplicates: true,
+            data: snapshot.nations
+                .slice(offset, offset + BATCH_SIZE)
+                .map((nation) => ({ sampleId: id, nationId: nation.id, data: asJson(nation) })),
+        });
+    }
+    for (let offset = 0; offset < snapshot.cities.length; offset += BATCH_SIZE) {
+        await tx.playAuditCity.createMany({
+            skipDuplicates: true,
+            data: snapshot.cities
+                .slice(offset, offset + BATCH_SIZE)
+                .map((city) => ({ sampleId: id, cityId: city.id, nationId: city.nationId, data: asJson(city) })),
+        });
+    }
+    for (let offset = 0; offset < snapshot.generals.length; offset += BATCH_SIZE) {
+        await tx.playAuditGeneral.createMany({
+            skipDuplicates: true,
+            data: snapshot.generals.slice(offset, offset + BATCH_SIZE).map((general) => ({
+                sampleId: id,
+                generalId: general.id,
+                nationId: general.nationId,
+                cityId: general.cityId,
+                npcState: general.npcState,
+                data: asJson(general),
+            })),
+        });
+    }
+};
@@ -1,3 +1,4 @@
+import { persistAuditMonth } from '../playAudit/persistence.js';
 import { persistGeneralAccessScores, persistGeneralUpdates } from './generalBatchPersistence.js';
 import { areSeasonRecordsFinalized } from './seasonRecords.js';
 import {
@@ -1138,6 +1139,7 @@ export const createDatabaseTurnHooks = async (
            pendingNationBettingOpens,
            pendingNationBettingFinishes,
            pendingYearbookSnapshots,
+            pendingAuditMonths,
            pendingUnificationFinalizations,
        } = changes;
        const reservedTurnChanges = options?.reservedTurns?.peekDirtyState();
@@ -1867,6 +1869,9 @@ export const createDatabaseTurnHooks = async (
                    data: pendingLogRows,
                });
            }
+            for (const snapshot of pendingAuditMonths) {
+                await persistAuditMonth(prisma, snapshot);
+            }
            for (const snapshot of pendingYearbookSnapshots) {
                await persistYearbookSnapshot(prisma, snapshot);
            }
@@ -1,3 +1,4 @@
+import type { PendingAuditMonth } from '../playAudit/persistence.js';
 import type {
    City,
    LogEntryDraft,
@@ -199,6 +200,7 @@ export interface TurnWorldChanges {
    pendingNationBettingOpens: PendingNationBettingOpen[];
    pendingNationBettingFinishes: PendingNationBettingFinish[];
    pendingYearbookSnapshots: PendingYearbookSnapshot[];
+    pendingAuditMonths: PendingAuditMonth[];
    pendingUnificationFinalizations: PendingUnificationFinalization[];
 }

@@ -239,6 +241,7 @@ export interface InMemoryTurnWorldStateSnapshot {
    pendingNationBettingOpens: PendingNationBettingOpen[];
    pendingNationBettingFinishes: PendingNationBettingFinish[];
    pendingYearbookSnapshots: PendingYearbookSnapshot[];
+    pendingAuditMonths: PendingAuditMonth[];
    pendingUnificationFinalizations: PendingUnificationFinalization[];
    pendingRealtimeBacklogShiftTicks: number;
 }
@@ -543,6 +546,7 @@ export class InMemoryTurnWorld {
    private readonly pendingNationBettingOpens: PendingNationBettingOpen[] = [];
    private readonly pendingNationBettingFinishes: PendingNationBettingFinish[] = [];
    private readonly pendingYearbookSnapshots: PendingYearbookSnapshot[] = [];
+    private readonly pendingAuditMonths: PendingAuditMonth[] = [];
    private readonly pendingUnificationFinalizations: PendingUnificationFinalization[] = [];
    private pendingRealtimeBacklogShiftTicks = 0;
    private readonly scenarioConfig: ScenarioConfig;
@@ -1091,6 +1095,7 @@ export class InMemoryTurnWorld {
            pendingNationBettingOpens: this.pendingNationBettingOpens,
            pendingNationBettingFinishes: this.pendingNationBettingFinishes,
            pendingYearbookSnapshots: this.pendingYearbookSnapshots,
+            pendingAuditMonths: this.pendingAuditMonths,
            pendingUnificationFinalizations: this.pendingUnificationFinalizations,
            pendingRealtimeBacklogShiftTicks: this.pendingRealtimeBacklogShiftTicks,
        } satisfies InMemoryTurnWorldStateSnapshot);
@@ -1137,6 +1142,7 @@ export class InMemoryTurnWorld {
        this.replaceArray(this.pendingNationBettingOpens, restored.pendingNationBettingOpens);
        this.replaceArray(this.pendingNationBettingFinishes, restored.pendingNationBettingFinishes);
        this.replaceArray(this.pendingYearbookSnapshots, restored.pendingYearbookSnapshots);
+        this.replaceArray(this.pendingAuditMonths, restored.pendingAuditMonths);
        this.replaceArray(this.pendingUnificationFinalizations, restored.pendingUnificationFinalizations);
        this.pendingRealtimeBacklogShiftTicks = restored.pendingRealtimeBacklogShiftTicks ?? 0;
    }
@@ -1352,6 +1358,10 @@ export class InMemoryTurnWorld {
        });
    }

+    queueAuditMonth(snapshot: PendingAuditMonth): void {
+        this.pendingAuditMonths.push(structuredClone(snapshot));
+    }
+
    queueYearbookSnapshot(snapshot: PendingYearbookSnapshot): void {
        this.pendingYearbookSnapshots.push(structuredClone(snapshot));
    }
@@ -2194,6 +2204,7 @@ export class InMemoryTurnWorld {
            turnTime: new Date(entry.turnTime.getTime()),
        }));
        const pendingYearbookSnapshots = structuredClone(this.pendingYearbookSnapshots);
+        const pendingAuditMonths = structuredClone(this.pendingAuditMonths);
        const pendingUnificationFinalizations = structuredClone(this.pendingUnificationFinalizations);
        const accessScoreResetGeneralIds = Array.from(this.accessScoreResetGeneralIds).sort(
            (left, right) => left - right
@@ -2226,6 +2237,7 @@ export class InMemoryTurnWorld {
            pendingNationBettingOpens,
            pendingNationBettingFinishes,
            pendingYearbookSnapshots,
+            pendingAuditMonths,
            pendingUnificationFinalizations,
        };
    }
@@ -2264,6 +2276,7 @@ export class InMemoryTurnWorld {
        this.pendingNationBettingOpens.splice(0, changes.pendingNationBettingOpens.length);
        this.pendingNationBettingFinishes.splice(0, changes.pendingNationBettingFinishes.length);
        this.pendingYearbookSnapshots.splice(0, changes.pendingYearbookSnapshots.length);
+        this.pendingAuditMonths.splice(0, changes.pendingAuditMonths.length);
        this.pendingUnificationFinalizations.splice(0, changes.pendingUnificationFinalizations.length);
    }

@@ -1,3 +1,4 @@
+import { recordAuditSettlement } from '../playAudit/collection.js';
 import { asNumber, asRecord } from '@sammo-ts/common';
 import {
    ActionLogger,
@@ -175,8 +176,10 @@ const processIncomeForNation = (
    const incomeText = Math.round(incomeValue).toLocaleString('en-US');
    const incomeLog =
        type === 'gold' ? `이번 수입은 금 <C>${incomeText}</>입니다.` : `이번 수입은 쌀 <C>${incomeText}</>입니다.`;
+    let paid = 0;
    for (const general of nationGenerals) {
        const pay = Math.round(getBill(general.dedication) * ratio);
+        paid += pay;
        if (
            process.env.SEED_PARITY_MONTHLY_RESOURCE_TRACE === '1' &&
            (process.env.AI_TRACE_GENERAL_IDS ?? '').split(',').includes(String(general.id))
@@ -203,6 +206,7 @@ const processIncomeForNation = (
        logger.pushGeneralActionLog(payLog, LogFormat.PLAIN);
        pushLogs(world, logger.flush());
    }
+    recordAuditSettlement(world, { nationId: nation.id, resource: type, income: incomeValue, paid });
 };

 export interface IncomeHandler extends TurnCalendarHandler {
@@ -1,3 +1,4 @@
+import { createPlayAuditHandler } from '../playAudit/collection.js';
 import { randomUUID } from 'node:crypto';
 import { createRuntimePauseGate } from './runtimePauseGate.js';

@@ -480,6 +481,7 @@ const createMonthlyCalendarRuntime = async (options: {
        options.monthlyEventHandler,
        options.hasEventAction('ProcessIncome') ? null : options.incomeHandler,
        createYearbookHandler({ profileName: options.profileName, getWorld: options.getWorld }).handler,
+        createPlayAuditHandler(options.getWorld),
        monthlyBoundaryPreHandler,
        createNationTurnMonthlyHandler({ getWorld: options.getWorld }),
        monthlyNationStatsHandler,
@@ -1,3 +1,4 @@
+import { queueAuditMonth } from '../playAudit/collection.js';
 import { resolveMessageTargetIcon } from '@sammo-ts/logic';
 import { createHash } from 'node:crypto';

@@ -177,6 +178,7 @@ export const createUnificationHandler = (options: {
            }

            queueYearbookSnapshot(world, options.profileName, context.currentYear, context.currentMonth);
+            queueAuditMonth(world, 'FINAL');
            world.queueUnificationFinalization({
                generationKey: `unification:${serverId}`,
                serverId,
@@ -1,3 +1,4 @@
+import { createPlayAuditHandler } from '../src/playAudit/collection.js';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import { LogCategory, LogScope, type TurnCommandEnv } from '@sammo-ts/logic';
 import { createGamePostgresConnector, type GamePrismaClient } from '@sammo-ts/infra';
@@ -35,6 +36,7 @@ integration('monthly pre-update persistence', () => {
        await db.nation.deleteMany({ where: { id: nationId } });
        await db.worldState.deleteMany({ where: { scenarioCode: 'monthly-boundary-pre-persistence' } });
        await db.yearbookHistory.deleteMany({ where: { profileName: { in: [yearbookProfile, yearbookServerId] } } });
+        await db.playAuditMonth.deleteMany({ where: { serverId: yearbookServerId } });
        await db.logEntry.deleteMany({ where: { text: { in: archivedLogTexts } } });
    });

@@ -46,6 +48,7 @@ integration('monthly pre-update persistence', () => {
        await db.nation.deleteMany({ where: { id: nationId } });
        await db.worldState.deleteMany({ where: { scenarioCode: 'monthly-boundary-pre-persistence' } });
        await db.yearbookHistory.deleteMany({ where: { profileName: { in: [yearbookProfile, yearbookServerId] } } });
+        await db.playAuditMonth.deleteMany({ where: { serverId: yearbookServerId } });
        await db.logEntry.deleteMany({ where: { text: { in: archivedLogTexts } } });
        await closeDb?.();
    });
@@ -184,7 +187,12 @@ integration('monthly pre-update persistence', () => {
        });
        world = new InMemoryTurnWorld(loaded.state, loaded.snapshot, {
            schedule: { entries: [{ startMinute: 0, tickMinutes: 10 }] },
-            calendarHandler: composeCalendarHandlers(yearbook.handler, boundary, nations),
+            calendarHandler: composeCalendarHandlers(
+                yearbook.handler,
+                createPlayAuditHandler(() => world),
+                boundary,
+                nations
+            ),
        });
        const hooks = await createDatabaseTurnHooks(databaseUrl!, world, { profileName: yearbookProfile });
        try {
@@ -227,6 +235,17 @@ integration('monthly pre-update persistence', () => {
                currentMonth: 1,
                meta: expect.objectContaining({ develcost: 40 }),
            });
+            const audit = await db.playAuditMonth.findFirstOrThrow({
+                where: { serverId: yearbookServerId },
+                include: { nations: true, generals: true, cities: true },
+            });
+            expect(audit).toMatchObject({ year: 200, month: 12, kind: 'MONTH_END', settlementsComplete: false });
+            expect(audit.nations.find((row) => row.nationId === nationId)?.data).toMatchObject({ appliedRate: 10 });
+            expect(audit.generals).toHaveLength(generalIds.length);
+            expect(audit.cities).toHaveLength(cityIds.length);
+            expect(world.peekDirtyState().pendingAuditMonths).toEqual([]);
+            const reloaded = await loadTurnWorldFromDatabase({ databaseUrl: databaseUrl! });
+            expect(reloaded!.state.meta.playAuditFlows).toMatchObject({ year: 201, month: 1, complete: true });
            const cityRows = await db.city.findMany({
                where: { id: { in: cityIds } },
                orderBy: { id: 'asc' },
@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'vitest';
+import type { City, Nation } from '@sammo-ts/logic';
+import { InMemoryTurnWorld } from '../src/turn/inMemoryWorld.js';
+import type { TurnGeneral, TurnWorldSnapshot, TurnWorldState } from '../src/turn/types.js';
+import { createPlayAuditHandler, queueAuditMonth, recordAuditSettlement } from '../src/playAudit/collection.js';
+const turnTime = new Date('0200-01-01T00:00:00.000Z');
+
+const buildGeneral = (id: number, nationId: number): TurnGeneral => ({
+    id,
+    name: `장수${id}`,
+    nationId,
+    cityId: nationId,
+    troopId: 0,
+    stats: { leadership: 80, strength: 70, intelligence: 60 },
+    experience: 1_000,
+    dedication: 900,
+    officerLevel: 1,
+    role: {
+        personality: null,
+        specialDomestic: null,
+        specialWar: null,
+        items: { horse: null, weapon: null, book: null, item: null },
+    },
+    injury: 0,
+    gold: 2_000,
+    rice: 2_000,
+    crew: 0,
+    crewTypeId: 0,
+    train: 0,
+    atmos: 0,
+    age: 30,
+    npcState: nationId === 0 ? 2 : 0,
+    triggerState: { flags: {}, counters: {}, modifiers: {}, meta: {} },
+    meta: { killturn: 24 },
+    turnTime,
+});
+
+const buildCity = (id: number, nationId: number): City => ({
+    id,
+    name: `도시${id}`,
+    nationId,
+    level: 1,
+    state: 0,
+    population: 10_000,
+    populationMax: 20_000,
+    agriculture: 1_000,
+    agricultureMax: 2_000,
+    commerce: 1_000,
+    commerceMax: 2_000,
+    security: 1_000,
+    securityMax: 2_000,
+    supplyState: 1,
+    frontState: 0,
+    defence: 1_000,
+    defenceMax: 2_000,
+    wall: 1_000,
+    wallMax: 2_000,
+    meta: {},
+});
+
+const buildNation = (id: number, power: number, meta: Nation['meta']): Nation => ({
+    id,
+    name: id === 0 ? '재야' : `국가${id}`,
+    color: '#777777',
+    capitalCityId: id === 0 ? null : id,
+    chiefGeneralId: null,
+    gold: 10_000,
+    rice: 20_000,
+    power,
+    level: id === 0 ? 0 : 1,
+    typeCode: 'che_중립',
+    meta,
+});
+
+const buildWorld = () => {
+    const state: TurnWorldState = {
+        id: 1,
+        currentYear: 200,
+        currentMonth: 1,
+        tickSeconds: 600,
+        lastTurnTime: turnTime,
+        meta: { serverId: 'yearbook-projection-test' },
+    };
+    const snapshot: TurnWorldSnapshot = {
+        scenarioConfig: {
+            stat: { total: 300, min: 10, max: 100, npcTotal: 150, npcMax: 50, npcMin: 10, chiefMin: 70 },
+            iconPath: '',
+            map: {},
+            const: {},
+            environment: { mapName: 'test', unitSet: 'test' },
+        },
+        scenarioMeta: {
+            title: '연감 테스트',
+            startYear: 200,
+            life: null,
+            fiction: 0,
+            history: [],
+            ignoreDefaultEvents: false,
+        },
+        map: { id: 'test', name: 'test', cities: [] },
+        nations: [
+            {
+                ...buildNation(0, 90, { gennum: 90, tech: 90 }),
+                name: '오염된 재야',
+                color: '#ffffff',
+                level: 9,
+            },
+            buildNation(1, 777, { gennum: 9, tech: 100 }),
+            buildNation(2, 0, { tech: 100 }),
+        ],
+        cities: [buildCity(0, 0), buildCity(1, 1), buildCity(2, 2)],
+        generals: [buildGeneral(1, 0), buildGeneral(2, 0), buildGeneral(3, 1), buildGeneral(4, 2), buildGeneral(5, 2)],
+        troops: [],
+        diplomacy: [],
+        events: [],
+        initialEvents: [],
+    };
+    const world = new InMemoryTurnWorld(state, snapshot, {
+        schedule: { entries: [{ startMinute: 0, tickMinutes: 10 }] },
+    });
+
+    return world;
+};
+describe('play audit collection durability state', () => {
+    it('restores pending snapshots and monthly flows on rollback and acknowledges only persisted rows', () => {
+        const world = buildWorld();
+        const before = world.captureState();
+        recordAuditSettlement(world, { nationId: 1, resource: 'gold', income: 943.5, paid: 123 });
+        queueAuditMonth(world);
+        expect(world.peekDirtyState().pendingAuditMonths).toHaveLength(1);
+        world.restoreState(before);
+        expect(world.peekDirtyState().pendingAuditMonths).toHaveLength(0);
+        expect(world.getState().meta.playAuditFlows).toBeUndefined();
+        queueAuditMonth(world);
+        const saved = world.peekDirtyState();
+        queueAuditMonth(world, 'FINAL');
+        world.acknowledgeDirtyState(saved);
+        expect(world.peekDirtyState().pendingAuditMonths.map((row) => row.kind)).toEqual(['FINAL']);
+    });
+    it('keeps partial adoption unknown then attributes income to the new month across reload state', async () => {
+        const world = buildWorld();
+        const handler = createPlayAuditHandler(() => world);
+        await handler.beforeMonthChanged!({
+            previousYear: 200,
+            previousMonth: 1,
+            currentYear: 200,
+            currentMonth: 2,
+            turnTime,
+        });
+        expect(world.peekDirtyState().pendingAuditMonths[0]!.settlementsComplete).toBe(false);
+        const next = world.captureState();
+        next.state.currentMonth = 2;
+        world.restoreState(next);
+        recordAuditSettlement(world, { nationId: 1, resource: 'gold', income: 943.5, paid: 123 });
+        const reloaded = buildWorld();
+        reloaded.restoreState(world.captureState());
+        queueAuditMonth(reloaded);
+        const feb = reloaded.peekDirtyState().pendingAuditMonths.at(-1)!;
+        expect(feb.month).toBe(2);
+        expect(feb.settlementsComplete).toBe(true);
+        expect(feb.nations.find((row) => row.id === 1)).toMatchObject({
+            incomeGold: 943.5,
+            paidGold: 123,
+            incomeRice: 0,
+        });
+    });
+    it('does not replace missing season identity with a profile or create a false snapshot', () => {
+        const world = buildWorld();
+        const state = world.captureState();
+        delete state.state.meta.serverId;
+        world.restoreState(state);
+        queueAuditMonth(world);
+        expect(world.peekDirtyState().pendingAuditMonths).toEqual([]);
+    });
+});
@@ -0,0 +1,74 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { createGamePostgresConnector, type GamePrismaClient } from '@sammo-ts/infra';
+import { persistAuditMonth, type PendingAuditMonth } from '../src/playAudit/persistence.js';
+import { buildAuditSnapshot } from '../src/playAudit/snapshot.js';
+
+const databaseUrl = process.env.INPUT_EVENT_DATABASE_URL;
+const integration = describe.skipIf(!databaseUrl);
+const serverId = 'play-audit-persistence-fixture-20260916';
+
+integration('play audit transactional month persistence', () => {
+    let db: GamePrismaClient;
+    let close: () => Promise<void>;
+    const snapshot: PendingAuditMonth = {
+        serverId,
+        year: 200,
+        month: 1,
+        tick: 10,
+        kind: 'MONTH_END',
+        settlementsComplete: true,
+        ...buildAuditSnapshot({
+            nations: [
+                {
+                    id: 1,
+                    name: '감사국',
+                    color: '#ffffff',
+                    capitalCityId: null,
+                    chiefGeneralId: null,
+                    gold: 100,
+                    rice: 200,
+                    power: 0,
+                    level: 1,
+                    typeCode: 'che_중립',
+                    meta: {},
+                },
+            ],
+            cities: [],
+            generals: [],
+            settlements: [],
+            settlementsComplete: true,
+        }),
+    };
+    beforeAll(async () => {
+        const connector = createGamePostgresConnector({ url: databaseUrl! });
+        await connector.connect();
+        db = connector.prisma;
+        close = () => connector.disconnect();
+    });
+    afterAll(async () => {
+        await db.playAuditMonth.deleteMany({ where: { serverId } });
+        await close();
+    });
+    it('rolls back all audit rows, reloads exact data, rejects conflicting replay and deduplicates retries', async () => {
+        await expect(
+            db.$transaction(async (tx) => {
+                await tx.nation.create({ data: { id: 999_916, name: 'rollback audit', color: '#ffffff' } });
+                await persistAuditMonth(tx, snapshot);
+                throw new Error('fixture rollback');
+            })
+        ).rejects.toThrow('fixture rollback');
+        expect(await db.playAuditMonth.count({ where: { serverId } })).toBe(0);
+        expect(await db.nation.findUnique({ where: { id: 999_916 } })).toBeNull();
+        await db.$transaction((tx) => persistAuditMonth(tx, snapshot));
+        await db.$transaction((tx) => persistAuditMonth(tx, snapshot));
+        const saved = await db.playAuditMonth.findFirstOrThrow({ where: { serverId }, include: { nations: true } });
+        expect(saved.nations.map((row) => row.data)).toEqual(snapshot.nations);
+        expect(await db.playAuditMonth.count({ where: { serverId } })).toBe(1);
+        await expect(db.$transaction((tx) => persistAuditMonth(tx, { ...snapshot, tick: 11 }))).rejects.toThrow(
+            'replay payload conflict'
+        );
+        expect((await db.playAuditMonth.findUniqueOrThrow({ where: { id: saved.id } })).tick).toBe(10);
+        await db.playAuditMonth.delete({ where: { id: saved.id } });
+        expect(await db.playAuditNation.count({ where: { sampleId: saved.id } })).toBe(0);
+    });
+});
@@ -116,6 +116,7 @@ describe('durable read-model change journal mapping', () => {
            pendingNationBettingOpens: [],
            pendingNationBettingFinishes: [],
            pendingYearbookSnapshots: [],
+            pendingAuditMonths: [],
            pendingUnificationFinalizations: [],
        } satisfies TurnWorldChanges;
        const readModelChanges = createEmptyRealtimeReadModelChanges();