instanceof ベースの絞り込みで Result の型引数が失われる（PHPStan の制限）

[valbeat]

概要

Result<int, RuntimeException> を instanceof Ok / instanceof Err で絞り込むと、PHPStan は型引数を失った Ok / Err（型引数なし）に絞り込み、unwrap() / unwrapErr() が mixed になる。

isOk() / isErr()（@phpstan-assert-if-true Ok<T> $this）経由なら Ok<int> / Err<RuntimeException> が保たれる。

再現

/** @param Result<int, RuntimeException> $result */
function f(Result $result): void
{
    if ($result instanceof Ok) {
        // actual: Valbeat\Result\Ok（型引数なし）、unwrap() は mixed
    }
    if ($result->isOk()) {
        // actual: Valbeat\Result\Ok<int>、unwrap() は int
    }
}

Ok<T> implements Result<T, never>・@template-covariant・@phpstan-sealed は宣言済みであり、Result<int, E> のサブタイプである Ok は論理的に Ok<int> しかあり得ないため、Ok<int> への絞り込みは健全。PHPStan が instanceof で逆方向のテンプレート解決をしないことが原因（PHPStan 2.2.2 で実測）。

対応状況

• 型テストで現状をピン留め（test: add assertType coverage for untested type inference cases #80 の testInstanceofOkNarrowing / testMatchArmNarrowing）— PHPStan 側が改善されたらテストが落ちて検知できる
• README / PHPDoc に注記し isOk() / isErr() を推奨（docs: document instanceof narrowing limitation, recommend isOk()/isErr() #82）
• PHPStan 本体への issue 報告（最小再現つき）
• PHPStan 側で修正されたら、ピン留めしたテストの期待値を Ok<int> / int に更新し、README / PHPDoc の注記を削除

アップストリーム関連 issue

• Narrowing down template types doesn't work as expected phpstan/phpstan#10553 — Narrowing down template types doesn't work as expected（open / feature-request）。最も近い既存報告
• Generic type is not inferred at all when instanceof is used. phpstan/phpstan#13204 — Generic type is not inferred at all when instanceof is used（closed / 2026-03 修正済み）。テンプレート境界からの推論の話で、本ケース（既知の型引数の実装クラスへの射影）は未解決

[valbeat]

この制限への対応は出尽くしたため、本 issue をクローズします。

クローズ理由

• ドキュメント済み: instanceof のジェネリクス喪失と回避策（isOk()/isErr()、match() メソッド）を README に明記（docs: document instanceof narrowing limitation, recommend isOk()/isErr() #82, docs: document the exhaustiveness vs. generics trade-off in match constructs #85）
• テストでピン留め済み: tests/Types/result.php に既知挙動を固定（testInstanceofOkNarrowing ほか）。PHPStan 側がいつか修正したら assertType の不一致で検知できる＝トラッキングの役割はテストが担う
• エラー側も網羅性を検証・文書化: enum / @phpstan-sealed なエラー型での exhaustiveness をテスト＋README化（test+docs: error-side exhaustiveness for enum and sealed error types #86）
• 回避策が実用上十分: 値を扱う分岐は isOk()/isErr() か match() メソッドで型引数を保持でき、instanceof は網羅性チェック専用として割り切れる

PHPStan 本体への報告について

未報告のままだが、業界的に皆メソッドベース絞り込みを使うため需要が低く、優先度は低いと判断。報告したくなった場合の最小再現と issue ドラフトはローカル（/tmp/repro_min.php, /tmp/ISSUE_DRAFT.md）で検証済み。必要になれば #13204 のフォローアップとして起票できる。