《移动游戏产品的架构·客户端与移动运行时》4.2 状态保存与恢复：快照与操作日志

// file: src/runtime/resume.ts
// tier: L2
// verify: node --test test/runtime/resume.test.ts

import { fail, ok, type Result } from "../core/result.ts";

export interface SessionProfile { readonly name: string; readonly secondsMin: number; readonly secondsMax: number; readonly actionsPerMinute: number; }

export const MATCH3_SESSION: SessionProfile = { name: "潮汐消消", secondsMin: 90, secondsMax: 90, actionsPerMinute: 24 };
export const ARK_SESSION: SessionProfile = { name: "潮汐方舟", secondsMin: 480, secondsMax: 720, actionsPerMinute: 30 };

export interface RestorePolicy { readonly baseRestoreMs: number; readonly perOperationMs: number; readonly snapshotRestoreMs: number; readonly checkpointEveryMs: number; }

export const DEFAULT_RESTORE_POLICY: RestorePolicy = {
  baseRestoreMs: 40,
  perOperationMs: 2,
  snapshotRestoreMs: 120,
  checkpointEveryMs: 20_000,
};

export type RestoreStrategy = "operation-log" | "snapshot-plus-log";

export interface RestorePlan { readonly strategy: RestoreStrategy; readonly replayMs: number; readonly checkpointMs: number; readonly reason: string; }

export interface OperationCount { readonly min: number; readonly max: number; }

export function operationCount(profile: SessionProfile): OperationCount {
  const perSecond = profile.actionsPerMinute / 60;
  return {
    min: Math.ceil(profile.secondsMin * perSecond),
    max: Math.ceil(profile.secondsMax * perSecond),
  };
}

export function chooseRestorePlan(
  profile: SessionProfile,
  policy: RestorePolicy = DEFAULT_RESTORE_POLICY,
): RestorePlan {
  const counts = operationCount(profile);
  const fullLogMs = policy.baseRestoreMs + counts.max * policy.perOperationMs;

  if (fullLogMs <= policy.snapshotRestoreMs) {
    return {
      strategy: "operation-log",
      replayMs: fullLogMs,
      checkpointMs: 0,
      reason: `全量回放 ${counts.max} 次操作用 ${fullLogMs}ms，不超过快照恢复 ${policy.snapshotRestoreMs}ms`,
    };
  }

  const tailOps = Math.ceil((policy.checkpointEveryMs / 1_000) * (profile.actionsPerMinute / 60));
  const tailMs = policy.baseRestoreMs + tailOps * policy.perOperationMs;
  return {
    strategy: "snapshot-plus-log",
    replayMs: Math.max(policy.snapshotRestoreMs, tailMs),
    checkpointMs: policy.checkpointEveryMs,
    reason: `全量回放 ${counts.max} 次操作用 ${fullLogMs}ms，超过快照恢复 ${policy.snapshotRestoreMs}ms，改为快照加尾日志`,
  };
}

export type OperationKind = "score" | "move" | "combo";

export interface OperationRecord { readonly seq: number; readonly opId: string; readonly kind: OperationKind; readonly amount: number; }

export interface ScoreState { readonly score: number; readonly moves: number; readonly applied: ReadonlySet<string>; }

export const EMPTY_SCORE: ScoreState = { score: 0, moves: 0, applied: new Set<string>() };

export interface ApplyOutcome {
  readonly state: ScoreState;
  readonly applied: boolean;
}

export function applyOperation(state: ScoreState, op: OperationRecord): ApplyOutcome {
  if (state.applied.has(op.opId)) {
    return { state, applied: false };
  }
  if (!Number.isInteger(op.amount) || op.amount < 0) {
    throw new RangeError(`operation amount must be a non-negative integer: ${op.amount}`);
  }

  const applied = new Set(state.applied);
  applied.add(op.opId);

  switch (op.kind) {
    case "score":
      return { state: { score: state.score + op.amount, moves: state.moves, applied }, applied: true };
    case "move":
      return { state: { score: state.score, moves: state.moves + 1, applied }, applied: true };
    case "combo":
      return { state: { score: state.score + op.amount, moves: state.moves + 1, applied }, applied: true };
    default:
      throw new Error(`unknown operation kind: ${String(op.kind)}`);
  }
}

export interface ReplayResult { readonly state: ScoreState; readonly applied: number; readonly skipped: number; }

export function replayOperations(state: ScoreState, ops: readonly OperationRecord[]): ReplayResult {
  const ordered = [...ops].sort((a, b) => a.seq - b.seq || a.opId.localeCompare(b.opId));
  let current = state;
  let applied = 0;
  let skipped = 0;

  for (const op of ordered) {
    const outcome = applyOperation(current, op);
    current = outcome.state;
    if (outcome.applied) {
      applied += 1;
    } else {
      skipped += 1;
    }
  }

  return { state: current, applied, skipped };
}

export interface ResumeToken { readonly sessionId: string; readonly baseSeq: number; readonly ops: readonly OperationRecord[]; }

export type MergeConflictReason = "session-mismatch" | "payload-mismatch" | "seq-collision";

export interface MergeConflict {
  readonly opId: string;
  readonly reason: MergeConflictReason;
}

export interface MergeOutcome {
  readonly token: ResumeToken;
  readonly duplicates: number;
}

export function mergeResumeTokens(
  a: ResumeToken,
  b: ResumeToken,
): Result<MergeOutcome, readonly MergeConflict[]> {
  if (a.sessionId !== b.sessionId) {
    return fail([{ opId: "", reason: "session-mismatch" }], `${a.sessionId} != ${b.sessionId}`);
  }

  const byId = new Map<string, OperationRecord>();
  const bySeq = new Map<number, string>();
  const conflicts: MergeConflict[] = [];
  let duplicates = 0;

  for (const op of [...a.ops, ...b.ops]) {
    const existing = byId.get(op.opId);
    if (existing) {
      if (existing.seq !== op.seq || existing.kind !== op.kind || existing.amount !== op.amount) {
        conflicts.push({ opId: op.opId, reason: "payload-mismatch" });
      } else {
        duplicates += 1;
      }
      continue;
    }

    const seqOwner = bySeq.get(op.seq);
    if (seqOwner !== undefined && seqOwner !== op.opId) {
      conflicts.push({ opId: op.opId, reason: "seq-collision" });
      continue;
    }

    byId.set(op.opId, op);
    bySeq.set(op.seq, op.opId);
  }

  if (conflicts.length > 0) {
    return fail(conflicts, `${conflicts.length} conflict(s)`);
  }

  const ops = [...byId.values()].sort((x, y) => x.seq - y.seq || x.opId.localeCompare(y.opId));
  return ok({
    token: { sessionId: a.sessionId, baseSeq: Math.min(a.baseSeq, b.baseSeq), ops },
    duplicates,
  });
}

export interface Snapshot { readonly version: 1; readonly score: number; readonly moves: number; readonly applied: readonly string[]; readonly watermarkSeq: number; }

export function takeSnapshot(state: ScoreState, watermarkSeq: number): Snapshot {
  return {
    version: 1,
    score: state.score,
    moves: state.moves,
    applied: [...state.applied].sort(),
    watermarkSeq,
  };
}

export function restoreSnapshot(snapshot: Snapshot, tail: readonly OperationRecord[]): ReplayResult {
  if (snapshot.version !== 1) {
    throw new RangeError(`unsupported snapshot version: ${String(snapshot.version)}`);
  }
  const base: ScoreState = {
    score: snapshot.score,
    moves: snapshot.moves,
    applied: new Set(snapshot.applied),
  };
  return replayOperations(base, tail.filter((op) => op.seq > snapshot.watermarkSeq));
}

export class ResumeJournal {
  #sessionId: string;
  #baseSeq: number;
  #nextSeq: number;
  #ops: OperationRecord[] = [];
  #state: ScoreState = EMPTY_SCORE;

  constructor(sessionId: string, baseSeq = 0) {
    this.#sessionId = sessionId;
    this.#baseSeq = baseSeq;
    this.#nextSeq = baseSeq;
  }

  get state(): ScoreState {
    return this.#state;
  }

  get size(): number {
    return this.#ops.length;
  }

  append(kind: OperationKind, amount: number, opId?: string): OperationRecord {
    const seq = this.#nextSeq;
    const record: OperationRecord = { seq, opId: opId ?? `${this.#sessionId}:${seq}`, kind, amount };
    const outcome = applyOperation(this.#state, record);
    if (!outcome.applied) {
      throw new Error(`duplicate operation id: ${record.opId}`);
    }
    this.#state = outcome.state;
    this.#ops.push(record);
    this.#nextSeq = seq + 1;
    return record;
  }

  token(): ResumeToken {
    return { sessionId: this.#sessionId, baseSeq: this.#baseSeq, ops: [...this.#ops] };
  }

  restore(other: ResumeToken): Result<ReplayResult, readonly MergeConflict[]> {
    const merged = mergeResumeTokens(this.token(), other);
    if (!merged.ok) {
      return fail(merged.error, merged.reason);
    }

    const replay = replayOperations(EMPTY_SCORE, merged.value.token.ops);
    this.#ops = [...merged.value.token.ops];
    this.#state = replay.state;
    this.#baseSeq = merged.value.token.baseSeq;
    const last = this.#ops[this.#ops.length - 1];
    this.#nextSeq = last ? last.seq + 1 : this.#baseSeq;
    return ok(replay);
  }
}