Record と棋譜データモデル

Record は 1 局の棋譜全体を表現するデータ構造である。 初期局面、初期局面コメント、対局メタデータ、本手順および変化手順を保持する有向木、ならびに対局結果から構成される。

全体構造と主要型

Record を構成する主要な型と責務は以下の通りである。

手順ツリーと RecordNodeId

Record の内部では、本手順とすべての変化手順が単一のアリーナ配列上の木構造として管理される。 Record::root_id()（raw == 0）は常に初期局面を表す root ノードであり、各 RecordNode は親ノード ID（parent()）と子ノード ID のスライス（children()）を持つ。

あるノードに複数の子ノードが存在する場合、children[0]（main_child(node_id)）がその枝の主手順（本手順または変化の主ライン）を表し、children[1..]（variation_children(node_id)）が同手数への別分岐（変化手順）を表す。 Record::main_moves()（Python では Record.moves）は root ノードから常に children[0] を辿って得られる本手順の指し手列を返す。

ツリー全体の走査や各ノードへのアクセスには、以下のメソッドを使用する。

• Record::root_id() / Record::root()：ルートノード ID（0）およびルート RecordNode への参照を返す。
• Record::node(node_id) / Record::try_node(node_id)：指定 ID の RecordNode を取得する（外部由来の ID には Result を返す try_node を使用する）。
• Record::children(node_id) / Record::variation_children(node_id)：全子ノード ID、または children[1..] の分岐子ノード ID スライスを返す。
• RecordNode::mv() / RecordNode::special()：ノードが指し手であれば Some(&MoveEntry)、終局特殊手であれば Some(&SpecialMoveEntry) を返す。
• RecordNode::annotation()：ノードに付随する RecordAnnotation（comment()、time_ms()、engine_info()）を参照する。
• Record::main_line_ids()：本手順上のすべての指し手ノード ID を先頭から順に返す。

終局表現と GameResult

Record は対局の終局状態を「終局特殊手エントリ（SpecialMoveEntry）」と「対局結果（GameResult）」の 2 層で管理する。

• 終局特殊手（SpecialMoveEntry）：本手順や分岐手順の末尾に配置される葉ノードであり、投了（SpecialMove::Resign）や時間切れ（SpecialMove::Timeout）などの具体的な終局事由と、対応する GameResult および原文表現（raw）を保持する。本手順の終局特殊手は Record::main_terminal()（ノード ID は Record::main_terminal_node()）で取得できる。
• 対局結果（GameResult）：本手順の main_terminal が持つ勝敗結果を返す集計値であり、Record::result()（Python では Record.result）で取得できる。main_terminal が None の場合は GameResult::Invalid となる。

フォーマット別の終局行欠落時の挙動

棋譜ファイルに終局行や要約行が存在しない場合の挙動は、フォーマットの仕様によって異なる。

KIF、KI2、CSA、JKF の各エクスポータは、main_terminal が None の Record であってもエラーにせず、終局行を省略して手順のみを書き出すことができる。

評価値（EngineInfo.eval）の視点規則

RecordAnnotation 内の EngineInfo.eval は、原則として その手を指す直前の手番側（side-to-move before the move）から見た評価値（単位：cp、Eval(i16)） として保持される。 先手番の指し手では先手有利が正の値となり、後手番の指し手では後手有利が正の値となる。

外部フォーマットとの入出力時における評価値の扱いは以下の通りである。

パース時とエクスポート時の共通規則

各テキストフォーマットのパーサとエクスポータは以下の規則に従ってデータをマッピングする。

• 初期局面コメント：初手の指し手より前に出現する KIF/KI2 の * コメント行および CSA の '* コメント行は、Record::initial_comment()（root ノードの comment）に格納される。
• 指し手コメント：各指し手の直後に続くコメント行は、その指し手ノードの RecordAnnotation::comment()（複数行は \n で連結）に格納される。
• 消費時間：KIF の (<elapsed>/<total>)、CSA の T<seconds>（V3.0 のミリ秒小数表記 T6.123 を含む）、JKF の "time.now" オブジェクトは、対応する指し手または終局特殊手ノードの time_ms（ミリ秒単位の u32）として格納される。KIF や JKF のエクスポート時には、各ノードの time_ms を手番ごとに累積して累計消費時間を自動計算する。
• 分岐手順の表現：KIF と KI2 は 変化：N手 セクションで分岐を入出力し、JKF は指し手オブジェクトの "forks" 配列で分岐を入出力する。CSA 形式はフォーマット仕様上、分岐手順の構文を持たないため本手順のみを扱う。

Rust コアの編集および走査 API

Rust クレート（rsshogi::records feature 有効時）では、棋譜ツリーの編集と局面復元のための専用 API を提供する。

• RecordEditor：RecordEditor::new(initial_position) または RecordEditor::from_record(record) で生成し、go_to、go_back、go_forward、branch_to、append_move、append_move_with_annotation、append_special、merge_record などを用いて現在位置の合法性を検証しながら棋譜ツリーを編集できる。
• traversal::traverse_with_position(&record, visitor)：深さ優先探索（DFS）で全ノードを走査し、指し手ノードでは指し手適用後の Position、終局特殊手ノードでは終局直前の Position をコールバックへ渡す。
• traversal::position_at(&record, node_id)：任意の RecordNodeId 時点における Position を初期局面から再生して復元する。
• export_*_bytes / export_*_bytes_with_options：ExportOptions::new(TextEncoding::ShiftJis) や .with_csa_version(CsaVersion::V3_0) を指定してバイト列を生成する。返り値の EncodedText::has_unmappable_chars() により、Shift_JIS へ変換できなかった文字の有無を検査できる。

関連項目

• フォーマット仕様一覧
• Record API（Python）
• sbinpack フォーマット仕様