Day 052 — unsafe fnの契約を「# Safety」として明文化し、precondition と safety invariant を区別する

📚 背景知識（読んでから問題へ）

Day 051では「生ポインタのデリファレンス」を扱い、unsafe { *p.add(i) }の直前に// SAFETY:コメントを書きました。あのコメントは「この呼び出し箇所で、なぜ安全と言えるか」を呼び出し側自身が証明するものでした。

今日はもう一段階上の話をします。unsafe fnという関数そのものを自分で定義するとき、その関数を使うすべての呼び出し元に対して「これを満たさなければ未定義動作(undefined behavior、以下UB)になる」という契約を宣言する必要があります。これがRust API Guidelinesが定める# Safetyセクションです。

📋 コピー/// # Safety
///
/// 呼び出し元は `i < v.len()` を保証しなければならない。
unsafe fn get_unchecked(v: &[i32], i: usize) -> i32 { /* ... */ }

重要なのは、この2つのコメントは書く人も読む人も役割が違うという点です。

unsafe fnを呼び出すコード自体はunsafe {}ブロックで囲む必要がありますが、それだけではコンパイラは何もチェックしません。unsafe fnの呼び出しが許可される5つのunsafe操作の1つである以上、コンパイラが要求するのは「囲んだ」という構文的な事実だけです。呼び出し元が本当に# Safetyに書かれた前提条件（例: i < v.len()）を満たしているかどうかは、人間が# Safetyセクションを読んで、自分の目で確認する以外に検証手段がありません。これが今日のテーマである「安全性不変条件の証明」です。

さらにRustのnomicon（公式のunsafe解説書）では、条件を2種類に分けています。

• precondition（事前条件）: その関数を呼ぶ瞬間だけ満たせばよい条件。例: get_unchecked(v, i)を呼ぶ瞬間にi < v.len()であること
• safety invariant（安全性不変条件）: ある型の値が存在している間ずっと満たし続けなければならない条件。例: NonNull<T>は「一度作られたら二度とnullにならない」ことを型の性質として保証し続ける

📝 問題

以下の4つに答えてください。

1. 概念: // SAFETY:コメント（Day051、呼び出し箇所に書く）と# Safetyセクション（今日、unsafe fnの宣言に書く）は何が違うか。「誰が」「何に対して」書くものかという観点で1〜2文で説明してください。
2. 実装: unsafe fn get_unchecked_i32(v: &[i32], i: usize) -> i32を実装してください。境界チェックを一切行わず、生ポインタ演算だけでi番目の要素を取り出します。関数には# Safetyセクションを持つdocコメントを書き、呼び出し元が満たすべき前提条件を明記してください。さらに、このunsafe fnを内部で呼び出す安全な公開API fn get_i32(v: &[i32], i: usize) -> Option<i32>を実装してください（範囲チェックをしてから呼び出す）。cargo testで、範囲内・範囲外・空スライス・境界値（i == v.len() - 1）の4パターンを検証してください。
3. デバッグ・コードレビュー: 次のコードはコンパイルが通ります。しかし重大な問題を抱えています。何が問題か、なぜコンパイラがこれを検出できないのかを説明してください。

   📋 コピーfn risky_last(v: &[i32]) -> i32 {
       // v.len() 番目 = 末尾の「1つ次」を読もうとしている（オフバイワン）
       unsafe { get_unchecked_i32(v, v.len()) }
   }

4. 安全性不変条件の分類: 次の2つの条件は、それぞれ「precondition（事前条件）」と「safety invariant（安全性不変条件）」のどちらに分類されるか、理由とともに答えてください。
   • (a) get_unchecked_i32(v, i)を呼ぶときのi < v.len()
   • (b) String::from_utf8_unchecked(bytes)で構築した後のStringが、その後ずっとUTF-8として妥当なバイト列であり続けること

🔍 ヒント（段階的開示）

📋 コピー/// # Safety
///
/// 呼び出し元は以下を保証しなければならない:
/// - `i < v.len()` (ここに理由も書く)
///
/// 満たされない場合の動作: (何が起きるか書く)
unsafe fn get_unchecked_i32(v: &[i32], i: usize) -> i32 {
    unsafe { /* Day051と同じ形のポインタ演算 */ }
}

fn get_i32(v: &[i32], i: usize) -> Option {
    if i < v.len() {
        // SAFETY: 直前のif文で確認済み
        Some(unsafe { get_unchecked_i32(v, i) })
    } else {
        None
    }
}

✅ 模範解答

📋 コピー// safety_contract.rs
// cargo run または cargo test でそのまま実行できます。
// Cargo.toml に追加のクレート依存は不要です（標準ライブラリのみ）。

/// スライス `v` の `i` 番目の要素を、境界チェックなしで取得する。
///
/// # Safety
///
/// 呼び出し元は次を保証しなければならない:
/// - `i < v.len()` であること。
///
/// この条件が満たされない場合、`v` が確保している領域の外側のメモリを
/// 読み出すことになり、動作は未定義（undefined behavior）である。
/// 具体的には、たまたま隣接するメモリの値が返る・プロセスがクラッシュする・
/// 最適化によって全く別の結果になる、のいずれもあり得る。
unsafe fn get_unchecked_i32(v: &[i32], i: usize) -> i32 {
    // SAFETY: この関数自身の `# Safety` 契約により、呼び出し元が
    // `i < v.len()` を保証している前提でのみこの関数は呼ばれる。
    // その前提のもとでは `v.as_ptr().add(i)` は `v` の確保済み領域内の
    // 有効な `i32` を指しており、`v` がこの呼び出しの間生存しているため
    // ダングリングでもない。
    unsafe { *v.as_ptr().add(i) }
}

/// `get_unchecked_i32` を範囲チェック付きでラップした安全な公開API。
/// `unsafe` の契約を内部に隠蔽し、外部からは決してUBを起こせない形で公開する。
fn get_i32(v: &[i32], i: usize) -> Option {
    if i < v.len() {
        // SAFETY: 直前の `if i < v.len()` により、`get_unchecked_i32` の
        // `# Safety` に書かれた前提条件（i < v.len()）を満たしていることを
        // この時点で確認済み。
        Some(unsafe { get_unchecked_i32(v, i) })
    } else {
        None
    }
}

fn main() {
    let data = vec![10, 20, 30, 40, 50];
    println!("get_i32(&data, 2) = {:?}", get_i32(&data, 2));
    println!("get_i32(&data, 99) = {:?}", get_i32(&data, 99));
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn in_range_index_returns_correct_value() {
        let data = vec![10, 20, 30, 40, 50];
        assert_eq!(get_i32(&data, 2), Some(30));
    }

    #[test]
    fn out_of_range_index_returns_none() {
        let data = vec![10, 20, 30];
        assert_eq!(get_i32(&data, 3), None);
        assert_eq!(get_i32(&data, 100), None);
    }

    #[test]
    fn empty_slice_returns_none() {
        let data: Vec = vec![];
        assert_eq!(get_i32(&data, 0), None);
    }

    #[test]
    fn boundary_last_valid_index_returns_value() {
        let data = vec![10, 20, 30];
        // 最後の有効なインデックスは len() - 1 == 2
        assert_eq!(get_i32(&data, 2), Some(30));
        // len() そのものは範囲外
        assert_eq!(get_i32(&data, 3), None);
    }
}

(1) の回答

// SAFETY:はある1つの呼び出し箇所で「私はこの場で前提条件を満たしていることを確認した」と呼び出し元が書く証明であるのに対し、# Safetyはunsafe fnの宣言そのものに、その関数を呼ぶすべての将来の呼び出し元が満たすべき契約を関数の作者が書く仕様である。前者は「証明」、後者は「契約の公開」という役割の違いがある。

(3) の回答

get_unchecked_i32(v, v.len())はi == v.len()であり、# Safetyが要求するi < v.len()を満たしていません（オフバイワンエラー）。しかしコンパイラはこれを検出できません。なぜならunsafe fnの呼び出しが許可されるかどうかをコンパイラがチェックするのは「unsafe {}ブロックで囲まれているか」という構文的な事実だけであり、# Safetyに書かれたi < v.len()という意味的な契約を検証する能力はコンパイラには無いからです（そもそも# Safetyはただのdocコメント＝Markdownテキストであり、コンパイラはコメントの中身を実行時条件として解釈しません）。この関数はcargo buildもcargo test（呼ばなければ）も通り、実行すればvの直後のメモリをi32として読み出す未定義動作になります。デバッグビルドでは偶然それらしい値が返ることもありますが、それは「動いたから正しい」を意味しません。

(4) の回答

• (a) precondition（事前条件）。i < v.len()はget_unchecked_i32を呼ぶそのタイミングだけ満たせばよい条件で、呼び出しごとにiもvも変わりうる。関数呼び出しの前に確認し、呼び出しの後にはその条件自体は意味を持たない（次にまた呼ぶときは改めて確認が要る）。
• (b) safety invariant（安全性不変条件）。String::from_utf8_uncheckedの# Safetyが要求するのは構築時点でのUTF-8妥当性というpreconditionに見えるが、実際にはその結果生まれるStringという型そのものが「内部バイト列は常にUTF-8として妥当」という不変条件を持ち続けることを、Stringのあらゆるメソッド（push_str・chars()・as_str()等）が無条件に前提にしている。つまり一度構築した後も、そのStringが生きている間ずっとこの条件が破れてはならない。破ると、後から全く無関係に見える別の場所（例えばchars()でUTF-8をデコードする箇所）でUBが発生する。

🪜 Step-by-Step 解説

💡 設計思想・なぜこう書くのか

Rustの型システムと借用チェッカーは「証明可能な安全性」を自動化する仕組みですが、unsafe fnの契約はその自動化の限界を、意図的にドキュメントという形で人間に押し返す装置です。ここで重要なのは、Rustが「証明できないなら諦めてC言語のように無検証にする」のではなく、「証明できない部分の境界線を明示的な構文（unsafeキーワード）とドキュメント規約（# Safety）で区切り、そこだけ人間の責任にする」という設計を取っていることです。

これは「ゼロコスト抽象化」の思想とも一致します。もしget_unchecked_i32が常に境界チェックを行うなら実行時コストが発生しますが、# Safetyで契約を明文化した上でチェックを省略すれば、契約を守れる呼び出し元にとってはコストゼロになります。標準ライブラリのget_unchecked系メソッド（slice::get_unchecked等）が広く使われているのはまさにこの理由からで、ホットパス（既に別の場所で範囲チェック済みであることが分かっている箇所）でのみ意図的に使われます。

🛑 コンパイルエラーが出た場合

問題(3)のrisky_lastはコンパイルエラーを出しません。これは今日のテーマの核心です。参考までに、もしunsafe {}で囲むこと自体を忘れた場合は次のエラーになります（Day051と同種）。

🌐 他言語との比較

C言語やGoにも「関数を正しく使うための暗黙の前提」は当然存在しますが、それを構文レベルでunsafe扱いにする仕組みも、契約をdocコメントの決まった見出しとして強制する仕組みもありません。Rustは「危険性そのもの」をゼロにはできない代わりに、「危険性の所在」をunsafeキーワードと# Safety見出しという検索可能な形に固定した点が設計上の差です。

🏆 実務での使いどころ

• 標準ライブラリのget_unchecked系API: slice::get_unchecked・str::get_uncheckedなど、境界チェック済みであることが構造的に保証されているホットパスで、境界チェックのオーバーヘッドを避けるために使われる
• FFI関数のラッピング: Day111で扱うが、C言語の関数をunsafe extern "C"として受け入れた後、Rust側の安全なAPIでラップする際、C側の関数が要求する前提条件（ポインタがnullでない・呼び出し順序等）を# Safetyとして文書化するのが標準的なパターン
• パフォーマンスクリティカルなクレートのAPI設計: bytesクレートやndarrayクレートなど、内部でunsafeを使いつつ安全なAPIを公開する著名クレートは、内部のunsafe fnに対してほぼ例外なく# Safetyセクションを備えている（クレートのソースコードを見れば実例として確認できる）
• コードレビューの実務プロセス: unsafeコードを含むPull Requestでは、レビュアーが「# Safetyに書かれた契約と、実際の呼び出し箇所の// SAFETY:コメントが本当に対応しているか」を突き合わせて確認するのが標準的なレビュー観点になる

⚠️ よくある誤解・ミス

🚀 次のステップ

• 発展: 問題(3)のrisky_lastを実際にcargo miri runで実行し、Miriが「memory access out of bounds」のようなUB検出メッセージを出すことを確認する（本日はMiriの導入手順そのものは範囲外とし、Day051に続きここでも意図的に割愛する）
• 次回予告: Phase 3の次テーマFFI（C言語との相互運用）に進む。今日学んだ「# Safetyで契約を明文化し、安全なラッパーで隠蔽する」パターンが、C言語の関数を呼ぶ際にそのまま応用される

🎯 自己評価

自分の回答

気づき・メモ