第13章：タイムマシンと古い箱

5歳児にもわかるゲームから始めよう

この章の 1 つの真実: History は現在のプレイ セッション内の時間を処理します。 Migration は、古いボックスのバージョン間の時間を処理します。

おもちゃの車、卓上の写真 3 枚、段ボール箱 3 つを用意します。まず、子供に車を A から B まで押してもらい、次に B から C まで押してもらいます。写真に各ステップが記録されるので、「戻る」を 1 回押すと、車を C から B まで戻すことができます。つまり、現在のセッション内の Undo です。次に、ボックスに v1、v2、v3 というラベルを付けます。v1 ボックスには「赤い車」のみが表示され、v2 ではその位置も記録され、v3 では色が構造化ペイント ラベルに置き換えられます。 3 年後に v1 ボックスを見つけた場合、その欠落しているフィールドを今日のゲーム ルールに直接渡してはなりません。まずそれを調べてから、ボックスを一度に 1 つのバージョンずつ交換します。

続行する前に答えを予想してください。子供が A から B まで継続的にドラッグし、その手が 87 点を通過した場合、Undo で車を 1 ピクセル戻す必要がありますか、それとも A までずっと移動する必要がありますか? 1 つのジェスチャは 1 つの Transaction であるため、A に戻る必要があります。ここで、「カーソルが車の上に浮かんでいる」写真を撮影し、後で箱を再度開くときにそれを復元することが意味があるかどうかを予測します。そうではありません。それは机の上のほんの一瞬の状態にすぎませんでした。

このゲームには 2 つのタイムラインがあります。写真スタックは、ページを開いてからのアクションの履歴に属します。バージョン番号はデータ形式の履歴に属します。 Undo は Migration を置き換えることはできません。また、Migration は元に戻すことができる一連のユーザー アクションを作成すべきではありません。

おもちゃを Canvas の概念に置き換える

類推はここで終わります。本物の Patch は写真ではありません。安定した ID、参照、同時実行性、および障害を処理する必要があります。本物の IndexedDB Transaction はビジネス Undo Transaction でもありません。どちらも「すべてが成功するか、すべてが失敗するか」を必要とするだけです。スナップショットは復元が簡単ですが、サイズが大きくなります。 Operation Log は増分同期が簡単ですが、再生、圧縮、およびバージョン管理されたプロトコルが必要です。このアナロジーでボックスを逆方向に交換できるという事実は、すべての本番 Migration がダウンする可能性があることを意味するわけではありません。データの分割、削除、または暗号化は元に戻せない可能性があります。

まず誤った思い込みを捨てる

• 「すべての pointermove で history.push を呼び出すのが最も忠実なアプローチです。」 メモリとコラボレーション トラフィックが爆発的に増加する中、1 つのユーザー意図は数十の Undo ステップになります。 Preview は高頻度で変化します。リリース時にのみコミットします。
• 「JSON.stringify(engineState) を保存するだけで十分です。」 エンジン状態には、Camera、Hover、DOM の参照とキャッシュが混在します。 Durable Document、Local Session、および Ephemeral Presence は、有効期間と権限が異なります。
• 「TypeScript 型は、JSON に検証が必要ないことを意味します。」 型はコンパイル後に消えます。 IndexedDB、サーバー、クリップボード、および古いクライアントから到着する値はすべて信頼できません。
• 「Migration は、読み取ったばかりのオブジェクトを変更できます。」 途中で例外が発生すると、半分新しく、半分古いオブジェクトが残ります。各ステップは純粋な関数である必要があります。入力を保存し、出力を再度検証します。
• 「不明なレコードは常に削除します。」 古いクライアントは、新しいクライアントによって書き込まれたレコードをサイレントに消費する可能性があります。元のバイトを保持したままそれらを隔離するか、書き込み可能モードで文書を開くことを拒否します。
• 「Autosave が成功したということは、Asset が成功したことを意味します。」 第 12 章のバイナリ アセットには、Document レコードから独立したライフサイクルがあります。参照には ready/pending/missing プロトコルが必要です。
• 「Undo は古い Snapshot を復元するだけです。」 マルチプレイヤー作業では、リモートでの変更も消去されます。 Local Undo はローカル Transaction を反転し、現在の正本となる状態に対して再検証しなければなりません。

本番環境に必要な知識

前提条件

第 5 章では、安定した ID と Document/Page/Shape/Asset/Binding レコードについて説明します。第 9 章では、Preview と Commit の間の Transaction Boundary を定義します。第 12 章では、Asset 状態と安全なインポートについて説明します。 History は検証されたコマンドのみを受け入れ、Renderer ピクセルを読み取りません。永続化境界は現在の DocumentV3 のみを受け入れます。すべての外部 Payload は最初に unknown → validate envelope → migrate → validate current を通過します。

体系的な知識

Command はユーザーがやりたいことを表し、Operation は最小の実行レベルの変更を表し、Patch は前後の値を保持し、Snapshot は完全な状態を保持します。作成、移動、サイズ変更、および削除は、それぞれ apply および invert を実装します。 Batch は、最初にすべての子コマンドを検証してから、リビジョンを 1 回増分します。 Transaction は、Pointer Down でベースラインをキャプチャし、移動中に Preview のみを更新し、Pointer Up でコミットします。 Coalescing は、同じ transactionId を共有する継続的な更新を組み合わせます。新しいローカル Command が成功すると、Redo スタックがクリアされます。

Undo Scope は明示的である必要があります: 1 ページまたは Document 全体、Page スイッチを通過するかどうか、アクションとともに Selection が復元されるかどうか。 Canvas Lab は「グローバル Document History; Page スイッチは History に入りません。Undo の後、Session は影響を受けるページに移動し、影響を受ける ID を選択します。」を選択します。 Hover、Cursor、カメラ アニメーション、位置合わせガイド、およびコミットされていないテキストは Transient State です。 Selection History は安定した ID ヒントのみを保存し、削除後にフィルタリングし、Session を Document Patch に混合することはありません。

Autosave はデバウンスを使用して、近くで発生するコミットを吸収しますが、ページが非表示になるか閉じる前のフラッシュはベスト エフォートにすぎません。 beforeunload は信頼できるデータベースではありません。 Crash Recovery は 2 つの IndexedDB スロットを使用します。committed ポインターは常に前の完全なエンベロープを参照します。 staging が完全に書き込まれて検証された後、新しいリビジョンを書き込んで、同じ readwrite トランザクション内でポインターを切り替える必要があります。トランザクションが中止されるか、プロセスがクラッシュした場合は、古いポインタの読み取りを続けます。最初に唯一の古いコピーを上書きしないでください。 2 つのタブを同時に保存する場合は、リビジョン条件付き書き込みまたはシングルライター プロトコルも必要です。 IndexedDB のトランザクション アトミック性は、ビジネス レベルの更新の喪失を自動的に防ぐわけではありません。次に、Server Persistence は {documentId, revision, schemaVersion, checksum} で条件付き書き込みを実行します。競合が黙って Last-Write-Wins になってはいけません。

Schema には、レコード識別子、必須フィールド、数値範囲、参照ルール、および schemaVersion が含まれます。 Validation は、構造とセマンティクスの両方 (一意の ID、非循環の親、既存のページ、および有効な Asset 参照) をチェックします。 Up Migration は、v1→v2 または v2→v3 など、1 つのバージョンのみを横断します。各ステップは決定的である必要があり、宣言されたソース バージョンのみを受け入れ、入力を保存し、出力を検証する必要があります。ここでは Idempotence を正確に使用してください。2 番目の入力は v1 ではないため、v1ToV2(v1) 自体は 2 回適用できる関数ではありません。冪等である必要があるのはリカバリ エントリ ポイントです。現在のバージョンは loadDocument を再度通過しても変更されず、クラッシュ後に元のコミットされたペイロードから再実行しても同じ結果が得られます。 Down Migration はデフォルトの約束ではありません。リリースをロールバックする必要がある場合は、どの新しいレコードを表現できないかを特定し、ダウングレード書き込みを拒否します。読み取り専用で開き、不明なレコードの隔離、元の Payload のバックアップを使用して Forward Compatibility を処理します。決して理解したふりをしないでください。

Document は、共有され、耐久性があり、移行可能な信頼できる情報源です。 Session は、1 つのデバイス上の 1 人のユーザーの Camera、現在の Page、Selection、および Tool です。個別にローカルに保存できます。 Presence は Cursor、ビューポート、TTL 付きのオンライン状態です。ブロードキャストすることはできますが、リカバリ スナップショットには決して入れないでください。 3 つすべてがレコードとして表される場合がありますが、scope、保存場所、アクセス許可、およびクリーンアップ ポリシーは異なるままでなければなりません。

根拠と互換性（確認日：2026-08-29）

IndexedDB は、ブラウザーにトランザクション オブジェクト ストレージを提供します。 MDN IndexedDB API で API と可用性の制約を確認してください。 Page ライフサイクルとバックグラウンド フリーズは、アンロード イベントだけに依存することはできません。 Chrome Page ライフサイクル を参照してください。 structuredClone() は多くの構造をコピーできますが、Schema Validation ではありません。 MDN 構造化クローンのドキュメント でサポートされているタイプを参照してください。サーバーは、アクセス許可、バージョン、セマンティクスを検証する必要があります。クライアント検証では、エラーが早期に報告されるだけです。それは信頼境界ではありません。

本章の実装ステップ

開始点: 第 12 章の Document は JSON として手動でのみエクスポートでき、進行中のレコードをドラッグで直接変更します。 終了ライン: 作成/移動/サイズ変更/削除は元に戻すことができます。連続ドラッグは 1 Undo です。 v1/v2 は v3 に安全に移行します。 Autosave はクラッシュから回復します。 Sessionは別途保管されます。

次のインターフェイスとファイルを追加します。

• src/engine/history/History.ts: Transaction, Batch, Coalescing, Undo/Redo;
• src/engine/persistence/schema.ts: バージョン管理されたエンベロープとランタイム検証。
• src/engine/persistence/migrations.ts: 純粋な v1→v2→v3 関数。
• src/engine/persistence/DocumentRepository.ts: 2 スロット Autosave および Crash Recovery。
• src/engine/session/SessionRepository.ts: Page/Camera/Selection のみを格納します。
• src/engine/persistence/__tests__/migrations.test.ts: 独立した Migration 証拠。

以下は実行可能な最小限のコアです。重要な移行ロジックが省略記号の背後に隠れることはありません。

type ShapeV1 = { id: string; type: 'rect'; x: number; y: number; color?: string };
type DocV1 = { schemaVersion: 1; shapes: ShapeV1[] };
type ShapeV2 = ShapeV1 & { w: number; h: number };
type DocV2 = { schemaVersion: 2; pageId: string; shapes: ShapeV2[] };
export type ShapeV3 = Omit<ShapeV2, 'color'> & { fill: { kind: 'solid'; color: string } };
export type DocV3 = {
  schemaVersion: 3;
  pages: Array<{ id: string; shapeIds: string[] }>;
  shapes: ShapeV3[];
};

const object = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null;
const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
const validId = (v: unknown): v is string => typeof v === 'string' && /^[a-z]+-[a-z0-9-]+$/.test(v);

function assertV1(v: unknown): asserts v is DocV1 {
  if (!object(v) || v.schemaVersion !== 1 || !Array.isArray(v.shapes))
    throw new Error('INVALID_V1');
  for (const s of v.shapes)
    if (!object(s) || !validId(s.id) || s.type !== 'rect' || !finite(s.x) || !finite(s.y))
      throw new Error('INVALID_V1_SHAPE');
}
function assertV2(v: unknown): asserts v is DocV2 {
  if (!object(v) || v.schemaVersion !== 2 || !validId(v.pageId) || !Array.isArray(v.shapes))
    throw new Error('INVALID_V2');
  for (const s of v.shapes)
    if (
      !object(s) ||
      !validId(s.id) ||
      s.type !== 'rect' ||
      !finite(s.x) ||
      !finite(s.y) ||
      !finite(s.w) ||
      !finite(s.h)
    )
      throw new Error('INVALID_V2_SHAPE');
}
export function assertV3(v: unknown): asserts v is DocV3 {
  if (!object(v) || v.schemaVersion !== 3 || !Array.isArray(v.pages) || !Array.isArray(v.shapes))
    throw new Error('INVALID_V3');
  const ids = new Set<string>();
  for (const s of v.shapes) {
    if (
      !object(s) ||
      !validId(s.id) ||
      ids.has(s.id) ||
      s.type !== 'rect' ||
      !finite(s.x) ||
      !finite(s.y) ||
      !finite(s.w) ||
      !finite(s.h) ||
      !object(s.fill) ||
      s.fill.kind !== 'solid' ||
      typeof s.fill.color !== 'string'
    )
      throw new Error('INVALID_V3_SHAPE');
    ids.add(s.id);
  }
  const pageIds = new Set<string>(),
    placed = new Set<string>();
  for (const p of v.pages) {
    if (!object(p) || !validId(p.id) || pageIds.has(p.id) || !Array.isArray(p.shapeIds))
      throw new Error('INVALID_V3_PAGE');
    pageIds.add(p.id);
    for (const id of p.shapeIds) {
      if (typeof id !== 'string' || !ids.has(id) || placed.has(id))
        throw new Error('INVALID_V3_PAGE');
      placed.add(id);
    }
  }
  if (placed.size !== ids.size) throw new Error('INVALID_V3_ORPHAN_SHAPE');
}

export function v1ToV2(input: DocV1): DocV2 {
  return {
    schemaVersion: 2,
    pageId: 'page-main',
    shapes: input.shapes.map((s) => ({ ...s, w: 120, h: 80 })),
  };
}
export function v2ToV3(input: DocV2): DocV3 {
  const shapes = input.shapes.map(({ color = '#64748b', ...s }) => ({
    ...s,
    fill: { kind: 'solid' as const, color },
  }));
  return {
    schemaVersion: 3,
    pages: [{ id: input.pageId, shapeIds: shapes.map((s) => s.id) }],
    shapes,
  };
}
export function loadDocument(raw: unknown): DocV3 {
  if (!object(raw) || !Number.isInteger(raw.schemaVersion)) throw new Error('INVALID_ENVELOPE');
  let current: unknown = structuredClone(raw);
  if ((current as { schemaVersion: number }).schemaVersion === 1) {
    assertV1(current);
    current = v1ToV2(current);
  }
  if ((current as { schemaVersion: number }).schemaVersion === 2) {
    assertV2(current);
    current = v2ToV3(current);
  }
  assertV3(current);
  return current;
}

type Patch = { id: string; before: ShapeV3 | null; after: ShapeV3 | null };
type Step = { transactionId: string; patches: Patch[]; pageId: string; selectedIds: string[] };
export class History {
  private undoStack: Step[] = [];
  private redoStack: Step[] = [];
  commit(step: Step) {
    this.undoStack.push(structuredClone(step));
    this.redoStack.length = 0;
  }
  undo(applyAtomically: (patches: Patch[]) => void): Step | undefined {
    const step = this.undoStack.at(-1);
    if (!step) return;
    applyAtomically(step.patches.map((p) => ({ id: p.id, before: p.after, after: p.before })));
    this.undoStack.pop();
    this.redoStack.push(step);
    return step;
  }
  redo(applyAtomically: (patches: Patch[]) => void): Step | undefined {
    const step = this.redoStack.at(-1);
    if (!step) return;
    applyAtomically(step.patches);
    this.redoStack.pop();
    this.undoStack.push(step);
    return step;
  }
}

おもちゃの話に戻ります。87 個の中間位置は、単に子供の手がどこを通過したかを示しているだけです。 commit({ transactionId }) はリバーシブル写真を撮るものです。 loadDocument はボックス検査官です。 v1 を今日の Renderer に直接渡すことはありません。 applyAtomically は、単なる安心させる関数名ではありません。実装では、最初に Patch グループ全体を不可視のコピーに対して検証し、次に Document を 1 回置き換える必要があります。途中で変異してからスローする可能性がある場合、ステップを History スタックに保持しても、書きかけの Document を救出することはできません。

Migration と History は個別にテストする必要があります。

import { describe, expect, it } from 'vitest';
import { History } from '../../history/History';
import { loadDocument, v1ToV2, v2ToV3 } from '../migrations';

describe('バージョン付き永続化', () => {
  const v1 = {
    schemaVersion: 1 as const,
    shapes: [{ id: 'shape-a', type: 'rect' as const, x: 1, y: 2, color: '#f00' }],
  };
  it('v1 → v3 を決定的に移行し、再読み込みしても変化しない', () => {
    const once = loadDocument(v1);
    expect(loadDocument(once)).toEqual(once);
    expect(v2ToV3(v1ToV2(v1))).toEqual(once);
  });
  it('連続ドラッグを1つの可逆ステップとしてコミットする', () => {
    const history = new History();
    const applied: unknown[] = [];
    history.commit({
      transactionId: 'drag-1',
      pageId: 'page-main',
      selectedIds: ['shape-a'],
      patches: [
        {
          id: 'shape-a',
          before: loadDocument(v1).shapes[0],
          after: { ...loadDocument(v1).shapes[0], x: 90 },
        },
      ],
    });
    history.undo((p) => applied.push(p));
    expect(applied).toHaveLength(1);
    expect((applied[0] as Array<{ after: { x: number } }>)[0].after.x).toBe(1);
  });
  it('壊れた参照を Renderer に渡さず拒否する', () => {
    expect(() =>
      loadDocument({
        schemaVersion: 3,
        pages: [{ id: 'page-main', shapeIds: ['shape-missing'] }],
        shapes: [],
      }),
    ).toThrow('INVALID_V3_PAGE');
  });
});

npm exec vitest run src/engine/persistence src/engine/history を実行します。すべての Migration、リカバリ エントリ冪等性、破損分離、Command Inversion、および「スタックを移動せずに applyAtomically をスローする」テストに合格することが期待されます。ブラウザで npm exec playwright test tests/crash-recovery.spec.ts を実行します。ステージングの書き込み、リビジョンの書き込み、およびコミットされたポインターの切り替え中に、個別にリロードを強制します。リカバリでは、以前のコミットされた状態または完全な新しいコミットされた状態のみが得られる場合があり、Document の半分になることはありません。次に、2 つのタブを開き、同じベース リビジョンから保存します。一方は、他方を黙って上書きするのではなく、競合を受け取る必要があります。

意図的に壊してみる

根拠を示して合格する

• Migration には独立したテストがあります。入力は保持され、出力は検証され、ロードを繰り返すと同じ結果が返されます。
• Document と Session は異なるキー、スキーマ、およびリポジトリを使用します。 Presence には永続書き込みがありません。
• Hover、アライメントガイド、トランジェント Preview、および Cursor は、Undo または Autosave に入ることはありません。
• 古いクライアントは、Unknown Record をサイレントに削除して結果を書き戻すことはありません。
• 新しい Command が Redo をクリアします。 Batch が失敗した場合、リビジョンは増加しません。
• リカバリ UI は、単に「問題が発生しました」と言うのではなく、どのリビジョンが復元されたかを説明します。

5歳児に説明する

「Command」、「Transaction」、または「Migration」という言葉を使わずに、これを説明してください。車をテーブルの左側から右側にドラッグし続けた後、戻るボタンを一度押すと、車が最初の位置に戻るのはなぜですか? 3 年前のボックスを今日のゲームテーブルに直接放り投げてはいけないのはなぜでしょうか?なぜ今友達が手を振っている場所を永久の箱に封印すべきではないのでしょうか？