《移动游戏产品的架构·客户端与移动运行时》10.2 云存档冲突与合并

// file: src/save/merge.ts
// tier: L1
// verify: node --test test/save/merge.test.ts

import type { SavePayload, SaveValue } from "./store.ts";

export type MergeRule = "lww" | "max" | "union" | "sum" | "server-authoritative";
export interface FieldRule {
  readonly rule: MergeRule; readonly prompt?: boolean; readonly additive?: boolean;
}
export interface MergePolicy {
  readonly id: string; readonly defaultRule: FieldRule;
  readonly fields: Readonly<Record<string, FieldRule>>;
  readonly serverFields: readonly string[];
}
export type VectorComparison = "equal" | "local-before" | "local-after" | "concurrent";
export interface FieldStamp {
  readonly vector: Readonly<Record<string, number>>;
  readonly atMs: number; readonly deviceId: string;
}
export interface SaveSnapshot {
  readonly fields: SavePayload;
  readonly stamps: Readonly<Record<string, FieldStamp>>;
  readonly savedAtMs: number; readonly revision: number;
  readonly serverRevision: number; readonly deviceId: string;
}
export interface FieldConflict {
  readonly field: string; readonly localValue: SaveValue; readonly remoteValue: SaveValue;
  readonly winner: "local" | "remote"; readonly rule: MergeRule;
  readonly prompt: boolean; readonly reason: string;
}
export interface MergeResult {
  readonly policyId: string; readonly fields: SavePayload;
  readonly stamps: Readonly<Record<string, FieldStamp>>;
  readonly conflicts: readonly FieldConflict[]; readonly promptRequired: boolean;
  readonly revision: number; readonly serverRevision: number;
}

function same(left: SaveValue, right: SaveValue): boolean {
  return JSON.stringify(left) === JSON.stringify(right);
}

export function compareVectors(
  local: Readonly<Record<string, number>>,
  remote: Readonly<Record<string, number>>,
): VectorComparison {
  const devices = new Set([...Object.keys(local), ...Object.keys(remote)]);
  let localAhead = false;
  let remoteAhead = false;
  for (const device of devices) {
    const left = local[device] ?? 0;
    const right = remote[device] ?? 0;
    if (left > right) localAhead = true;
    if (right > left) remoteAhead = true;
  }
  if (localAhead && remoteAhead) return "concurrent";
  return localAhead ? "local-after" : remoteAhead ? "local-before" : "equal";
}

function maxVector(
  left: Readonly<Record<string, number>>,
  right: Readonly<Record<string, number>>,
): Readonly<Record<string, number>> {
  const merged: Record<string, number> = { ...left };
  for (const [device, counter] of Object.entries(right)) {
    merged[device] = Math.max(merged[device] ?? 0, counter);
  }
  return merged;
}

function pickLater(
  local: FieldStamp, remote: FieldStamp, localValue: SaveValue, remoteValue: SaveValue,
): "local" | "remote" {
  if (local.atMs !== remote.atMs) return local.atMs > remote.atMs ? "local" : "remote";
  if (local.deviceId !== remote.deviceId) {
    return local.deviceId.localeCompare(remote.deviceId) >= 0 ? "local" : "remote";
  }
  return JSON.stringify(localValue).localeCompare(JSON.stringify(remoteValue)) >= 0
    ? "local"
    : "remote";
}

function resolveValue(
  local: SaveValue,
  remote: SaveValue,
  localStamp: FieldStamp,
  remoteStamp: FieldStamp,
  localServerRevision: number,
  remoteServerRevision: number,
  rule: FieldRule,
): { winner: "local" | "remote"; value: SaveValue; reason: string } {
  const winner = pickLater(localStamp, remoteStamp, local, remote);
  if (rule.rule === "lww") {
    return { winner, value: winner === "local" ? local : remote, reason: "lww" };
  }
  if (rule.rule === "max" && typeof local === "number" && typeof remote === "number") {
    return local >= remote
      ? { winner: "local", value: local, reason: `max ${local}>=${remote}` }
      : { winner: "remote", value: remote, reason: `max ${remote}>${local}` };
  }
  if (rule.rule === "union" && Array.isArray(local) && Array.isArray(remote)) {
    const merged = [...new Set([...local, ...remote])].sort();
    return { winner: "local", value: merged, reason: `union ${merged.length} entries` };
  }
  if (rule.rule === "sum" && rule.additive === true
    && typeof local === "number" && typeof remote === "number"
    && localServerRevision === remoteServerRevision) {
    return { winner: "local", value: local + remote, reason: `sum on serverRevision ${localServerRevision}` };
  }
  if (rule.rule === "server-authoritative") {
    if (localServerRevision !== remoteServerRevision) {
      return localServerRevision > remoteServerRevision
        ? { winner: "local", value: local, reason: `serverRevision ${localServerRevision}` }
        : { winner: "remote", value: remote, reason: `serverRevision ${remoteServerRevision}` };
    }
    return { winner: "local", value: local, reason: "same serverRevision; hold local" };
  }
  return {
    winner,
    value: winner === "local" ? local : remote,
    reason: `rule ${rule.rule} not applicable; fell back to lww`,
  };
}

export function mergeSnapshots(
  local: SaveSnapshot,
  remote: SaveSnapshot,
  policy: MergePolicy,
): MergeResult {
  const fields: Record<string, SaveValue> = {};
  const stamps: Record<string, FieldStamp> = {};
  const conflicts: FieldConflict[] = [];
  const names = new Set([
    ...Object.keys(local.fields), ...Object.keys(remote.fields),
    ...Object.keys(local.stamps), ...Object.keys(remote.stamps),
  ]);

  for (const field of [...names].sort()) {
    const localStamp = local.stamps[field];
    const remoteStamp = remote.stamps[field];
    if (localStamp === undefined && remoteStamp === undefined) continue;
    if (localStamp === undefined) {
      fields[field] = remote.fields[field];
      stamps[field] = remoteStamp as FieldStamp;
      continue;
    }
    if (remoteStamp === undefined) {
      fields[field] = local.fields[field];
      stamps[field] = localStamp;
      continue;
    }

    const localValue = local.fields[field];
    const remoteValue = remote.fields[field];
    const comparison = compareVectors(localStamp.vector, remoteStamp.vector);
    let winner: "local" | "remote";
    let mergedValue: SaveValue | null = null;
    let reason: string;
    if (comparison === "local-after") {
      winner = "local";
      reason = "local vector dominates";
    } else if (comparison === "local-before") {
      winner = "remote";
      reason = "remote vector dominates";
    } else {
      const rule = policy.fields[field] ?? policy.defaultRule;
      const resolved = resolveValue(localValue, remoteValue, localStamp, remoteStamp,
        local.serverRevision, remote.serverRevision, rule);
      winner = resolved.winner;
      mergedValue = resolved.value;
      reason = resolved.reason;
      if (!same(localValue, remoteValue)) {
        conflicts.push({
          field, localValue, remoteValue, winner,
          rule: rule.rule, prompt: rule.prompt === true, reason,
        });
      }
    }

    fields[field] = mergedValue ?? (winner === "local" ? localValue : remoteValue);
    stamps[field] = {
      vector: maxVector(localStamp.vector, remoteStamp.vector),
      atMs: Math.max(localStamp.atMs, remoteStamp.atMs),
      deviceId: winner === "local" ? localStamp.deviceId : remoteStamp.deviceId,
    };
  }

  return {
    policyId: policy.id, fields, stamps, conflicts,
    promptRequired: conflicts.some((conflict) => conflict.prompt),
    revision: Math.max(local.revision, remote.revision) + 1,
    serverRevision: Math.max(local.serverRevision, remote.serverRevision),
  };
}

export const MATCH3_MERGE_POLICY: MergePolicy = {
  id: "match3-weak-network",
  defaultRule: { rule: "lww", prompt: true },
  fields: {
    levelProgress: { rule: "max" },
    coins: { rule: "server-authoritative", prompt: true },
    homeLayout: { rule: "lww", prompt: true },
    achievements: { rule: "union" },
    settings: { rule: "lww" },
    adViews: { rule: "sum", additive: true, prompt: true },
  },
  serverFields: ["coins"],
};

export const ARK_MERGE_POLICY: MergePolicy = {
  id: "ark-strong-network",
  defaultRule: { rule: "server-authoritative" },
  fields: {
    accountLevel: { rule: "server-authoritative" },
    currencies: { rule: "server-authoritative" },
    deck: { rule: "server-authoritative" },
    seasonPoints: { rule: "server-authoritative" },
    settings: { rule: "lww" },
    battleHistory: { rule: "union" },
  },
  serverFields: ["accountLevel", "currencies", "deck", "seasonPoints"],
};