v0.1.0 readiness — pre-plugin design notes

ステータス: 草案。規範的ではありません。ADR-2（拡張API）およびROADMAPのv0.1.0行が高レベルで記述するv0.1.0長期作業をキャプチャし、今後の実装者が何が再利用可能か、何を安定化する必要があるか、そして最初のパブリックプラグイン契約をリリースする前に何を発明しなければならないかを確認できるよう、各項目を今日のv0.0.7ワーキングツリーに照らして位置づけます。

このドキュメントは作業上のスケッチです。拘束力のある契約はADR-2、ADR-4（推論エンジン）、docs/internal-spec/inference-engine.md、およびdocs/internal-spec/internal-type-api.mdに引き続き存在します。このドラフトがそれらのいずれかと矛盾する場合、仕様 / ADRが拘束力を持ち、このドラフトは古くなっています。

v0.1.0がコミットするもの

ROADMAP.mdはv0.1.0を2つのクロスカットなインフラストラクチャサーフェスのために予約しています。

解析済みRBS環境、スコープインデックス、カタログデータの永続的なオンディスクキャッシュ——ウォームなrigor check実行を高速化するため。
プラグインAPI（ADR-2） ——プラグイン作者が結び付けるケイパビリティロール / ファクト貢献 / ミューテーションサマリーサーフェス。

現行のv0.0.xスライスは、プラグインAPIを設計する際の基板です。v0.0.7の「プリプラグインカバレッジプッシュ」は、v0.1.0プラグインが初日に躓くような最大の型言語および組み込みカバレッジのギャップを埋めました。

プラグインAPI観点での現在の解析器サーフェス

ADR-2はプラグインが受け取るパブリックオブジェクトを記述しています。今日のv0.0.7エンジンはそれらすべての内部カウンタパートを持っていますが、gem APIの意味でどれも「パブリック」と宣言されていません。以下の表はADR-2の語彙を現在のRigorモジュールにマッピングしています。

ADR-2サーフェス	v0.0.7実装	プラグイン準備ギャップ
`Scope`（不変、エッジ認識）	`Rigor::Scope`（39のパブリックメソッド、インスタンスごとに不変、`StatementEvaluator`と`ExpressionTyper`を通じてスレッド化）。	サーフェスは内部的に安定しているがパブリックとして注釈されていない。パブリック名前空間宣言 + ドリフトテスト（`RbsLoader`形状契約に類似）が公開前に必要。
型システム値オブジェクト	`Rigor::Type::*`キャリア + `Rigor::Type::Combinator`。仕様は`internal-type-api.md`。	すでにパブリック型オブジェクトサーフェスとして文書化済み。コンビネータ追加（例: v0.0.7の`key_of`、`value_of`、`int_mask`、`indexed_access`）は同じファクトリー契約を通じて流れます。型を読むプラグインはそのまま使用可能。
リフレクションレイヤー	混在: `Rigor::Environment`（クラスレジストリ + RBSローダー）、`Rigor::Inference::ScopeIndexer`（発見されたクラス / メソッド / インスタンス変数）、`Rigor::Builtins::*_CATALOG`（クラスごとのメソッドカタログ）。	統一されたファサードのない3つのリフレクションデータソース。v0.1.0では、これらを安定したクラスごと / メソッドごとのクエリサーフェスに結合する`Rigor::Reflection`（または類似）ファサードが必要です。
三値確信度	`Rigor::Trinary` + `Rigor::Type::AcceptsResult`。`Type::*#accepts`により広く使用されています。	パブリック対応済み。`yes` / `maybe` / `no`セマンティクスはすでにADR-2のポリシー（`maybe`は肯定的証明として絞り込みを行わない）と一致しています。
フロー効果バンドル	`Rigor::RbsExtended::*Effect`構造体（述語 / アサート / パラメータ / 戻り値） + `Rigor::Analysis::FactStore::Fact`。	効果構造体はRBS側のもの;統一されたプラグイン側バンドル（`return_type`、`truthy_facts`、`falsey_facts`、`post_return_facts`、`mutations`、`invalidations`、`exceptional`、`role_conformance`、`provenance`）はまだ構築されていない。ADR-2 §「フロー貢献バンドル」が仕様; v0.1.0で実装します。
診断由来	`Rigor::Analysis::Diagnostic`（パス / 行 / 列 / メッセージ / 重大度 / ルール）。	ルールごとの識別子は存在する;ソースファミリープレフィックス（`plugin.<id>.<name>`等）はまだサポートされていない。Diagnostic構造体に1つの由来フィールドが追加されます。
キャッシュディスクリプタ	実行時には存在しない;すべての`rigor check`がRBSを再解析し、再ロードし、スコープインデックスを再計算し、カタログを再ロードします。	スキーマは`20260505-cache-slice-taxonomy.md`で固定（スロットごとのエントリー形状、コンポジションルール、キャッシュキー導出、粒度ガイダンス）。永続化レイヤー（ストレージバックエンド、ロック、退避）はv0.1.0でリリースします。
プラグインマニフェスト / 設定	なし。	新しいサーフェス。ADR-2 §「プラグインの信頼とI/Oポリシー」からの信頼済みgemトラストモデル——Gemfileリストのgem + 設定スキーマから開始。
拡張テスト	RSpec + 統合FixtureHarness（`spec/integration/fixtures/*.rb`）。	フィクスチャハーネスはプラグインテストに再利用可能; v0.1.0リリースではプラグイン作者が同じ形状を得られるよう公開された`Rigor::Testing::PluginHarness`をリリースすべきです。
ケイパビリティロール	なし。ADR-2は独断的なコアカタログ（`_Closable`、`_Rewindable`など）を予約しています; v0.0.xエンジンは`docs/type-specification/structural-interfaces-and-object-shapes.md`下に構造的インターフェースインフラを持っていますが、具体的なロールカタログはまだありません。	適度な事前作業が必要——ロールは本質的に適合メタデータを持つ名前付き構造的インターフェースです。

シーケンシング: 何が何をブロックするか

インフラストラクチャサーフェスには自然な順序があります。各行はその下の行の前提条件です。

リフレクションファサード。ソース宣言 / RBS / カタログが1つの安定したファサードを通じてアクセスできるようになるまで、プラグインリフレクション貢献を確定的にマージすることはできません。今日のScopeIndexer + Environment + Builtins::*_CATALOGトライアドには、統一された読み取り側APIが必要です。推定: 中程度。新しい解析ロジックなし——既存データに対する純粋なファサード。
キャッシュスライススキーマ。プラグイン貢献が永続化される前にキャッシュが不可欠です。プラグインファクト（動的メンバー、動的戻り値、ロール適合）は入力が変わった際に無効化されなければならないからです。型付きスロットスキーマ（files、gems、plugins、configs）が最初に入り、永続化（ファイルベースストア + 整合性チェック）が続きます。推定: 大規模。難しいのは、プラグイン貢献とコンポーズするキャッシュカーディナリティを爆発させないスライス境界を設計することです。
フロー貢献バンドル。ADR-2のバンドル構造体はプラグインが返すパブリック形状です。内部効果構造体（PredicateEffect等）はバンドルのスーパーセット形状と調和させてから、ディスパッチパス（MethodDispatcher + Narrowing）が組み込みルールがすでに使用している同じマージルールを通じてバンドルを消費します。推定: 中程度。ほとんどの内部実装はすでに存在——マージとディスパッチのサイトはすでに複数のソースを受け入れています。
プラグインマニフェスト + 登録。プラグインgemが実装するプロトコルを宣言し; Rigorはgemをロードしてサービスをインスタンス化します。推定: 小規模（信頼済みgemモデルが維持されれば）——本質的にGemfile検査とサービスコンテナのコンストラクタインジェクション。
狭い拡張プロトコル。動的戻り値型、型仕様、動的リフレクションは3つの最高レバレッジプロトコルです。各々にインターフェースモジュール、登録サイト、既存のティアチェーンへのディスパッチフックが必要です。プロトコルごとに推定: 中程度ですが各々は独立しているため順次着地可能。
診断由来プレフィックス。Rigor::Analysis::Diagnosticにソースファミリーフィールドを追加し、フォーマッタを更新します。推定: 小規模。
プラグインテストハーネス。既存のFixtureHarness周りの公開ラッパーとルールテストヘルパー。推定: 小規模。

キャッシュとフロー貢献バンドルが最も重い項目です。それ以外はほぼ、これら2つが揃えば機械的な組み立てです。

v0.0.7の作業で解決された未解決の問題（および依然として未解決の問題）

ADR-2の「未解決の問題」セクションには9つの項目があります。v0.0.7のプッシュによりいくつかが絞り込まれました。

最初のプラグインマニフェストフォーマット / 設定スキーマ言語。未解決。おそらくの回答: data/builtins/ruby_core/*.ymlの先例に合わせたYAMLマニフェスト + Ruby DSLハイブリッド。
ルール用の合成 / 仮想ASTノード。未解決。今日のStatementEvaluatorは生のPrism::Nodeで動作します;仮想ノードレイヤーの導入は実際のアーキテクチャ決定です。
推論型アサーション用のフィクスチャマーカーのスペリング。v0.0.xはすでにフィクスチャファイルでassert_type("...", expr)呼び出しを使用しています（spec/integration/fixtures/*_catalog.rb）。この構文はPrismを通じてラウンドトリップし、Ruby有効のまま残ります;プラグインテストの公開スペリングにもすべきです。
ケイパビリティロール適合ペイロード（フル / 部分的 / 除外 / maybe）。未解決。形状が固まる前に実例が必要——おそらく具体的なStream / Closableロールの提案によって駆動されます。
競合するプラグイン貢献に対する診断識別子分類体系。未解決。v0.0.xはDiagnosticにrule:プレフィックスを使用しています; source-family.plugin-id.rule-idへの拡張は小さな構造体変更です。
リフレクションキャッシュキースキーマ。未解決。キャッシュスライス設計（上記項目2）に依存します。
パブリック拡張名前空間の互換性範囲。未解決。最初のプロトコルが公開されるまで回答できません; ADR-2の作業上の回答（gemバージョン依存関係 + 適合テストスイート）は維持されます。
後で有効化された場合の幅広い式 / 演算子フック。ADR-2作業上の回答に従い引き続き延期。v0.0.7の「狭いティア」パターン（MethodDispatcher::ConstantFolding / BlockFolding / ShapeDispatch / KernelDispatch）は、幅広いディスパッチなしに狭いフックがほとんどの実際のユースケースをカバーすることを示しています。
名目的のみに対する構造的インターフェース / オブジェクト形状による動的戻り値マッチング。未解決。構造的インターフェースインフラは存在しています（structural-interfaces-and-object-shapes.md）が、ディスパッチャーではまだ使用されていません。v0.1.0はおそらく名目のみで開始し、構造的マッチングをフォローアップとして追加します。

ADR-2のリリースを必要とせずに着地できるpre-v0.1.0作業

いくつかの項目はプラグインAPIとは独立して着地でき、v0.1.0を実質的に短縮できます。

Rigor::Scope、Rigor::Type、Rigor::EnvironmentのパブリックAPI宣言——名前空間ポリシー + ドリフトテスト。新しいコードなし、契約宣言のみ。
リフレクションファサードのスキャフォールディング——class_definition_for(name)、method_definitions_for(class_name, method_name)、constants_for(class_name)などを公開する薄いRigor::Reflectionモジュール。既存のソースから読み取り;安定した形状を公開。
キャッシュスライス分類体系——20260505-cache-slice-taxonomy.mdで着地済み。スロットごとのエントリー形状、比較器セマンティクス、コンポジションルール、キャッシュキー導出、粒度ガイダンス、スキーマバージョニングポリシーを固定します。コードなし; v0.1.0でリリースされる永続化レイヤーの前提条件となる契約。
フロー効果バンドル構造体——ADR-2の8スロットを持つRigor::FlowContribution構造体として定義します。内部のPredicateEffect等の構造体はRbsExtendedとNarrowingの境界でバンドルに変換されます;組み込みルールもバンドルを生成します。プラグインも同様。
診断由来フィールド——Diagnosticをsource_family（デフォルト:builtin）で拡張します。フォーマッタをオプションでルールIDにプレフィックスを含めるよう更新します。

これらはv0.0.xドットリリースとしてリリースできます; ADR-2が最終化される必要はありません。

pre-v0.1.0作業が不要なもの

Rigor::Type::*キャリアは十分です。v0.0.7の追加（key_of、value_of、int_mask、indexed_access）がスペックテーブルをカバーしました。
カタログティア（MethodDispatcher::ConstantFolding + BlockFolding + ShapeDispatch + KernelDispatch）は良好な状態です。各ティアは小さく、よく定義されたサーフェスエリアを持っています;プラグインは新しい精度ティアや汎用ディスパッチャーフックを追加することで同じティアチェーンパターンを通じて登録できます。
RBS::Extendedディレクティブ（return:、param:、assert*、predicate-if-*）はユーザー側の作成サーフェスをカバーしています。残りのconforms-toディレクティブはそれ自体がopen v0.1.0の問題である構造的適合チェッカーに依存する唯一の仕様リストのディレクティブです。
Rigor::Inference::ScopeIndexerはすでに明確な契約を持っています: 一度書き込まれ、推論中にクエリされる読み取り専用宣言テーブル。再構造化は不要です。
Rigor::TrinaryとType::AcceptsResultは正規の確信度サーフェスです。プラグインはそれらを直接消費します。

推奨される次のスライス（将来の実装者向け）

ステータス更新（v0.0.7バッチ6、2026-05-05）: リフレクションファサードのスキャフォールディングが着地しました。Rigor::Reflectionは統一された読み取り側ファサードとして公開されました（仕様はdocs/internal-spec/reflection.md、RBSはsig/rigor/reflection.rbs、仕様はspec/rigor/reflection_spec.rb）。パブリックAPIがカバーするもの:

class_known? / class_ordering / nominal_for_name / singleton_for_name、
constant_type_for（インソースとRBS側定数の結合;衝突時はインソースが勝つ）、
instance_method_definition / singleton_method_definition、
discovered_class? / discovered_method?。

ファサードは読み取り専用かつアディティブです: ScopeまたはRbsLoaderから直接読み取る既存のコールサイトは変更されずに動作し続け、自分のペースでファサードに移行できます。

ステータス更新（v0.0.7バッチ7、2026-05-05）: コンシューマー移行も着地しました。5つのエンジン内部コーラーがscope.environment.rbs_loaderの代わりにファサードを通じて読み取るようになりました: Analysis::CheckRules（4つのルール実装コールサイト + definition_available? / lookup_methodヘルパー）、Inference::Narrowing#resolve_rbs_extended_method、Inference::StatementEvaluator#resolve_call_method、Inference::MethodDispatcher#user_class_fallback_receiver、Inference::MethodParameterBinder#lookup_rbs_method、Inference::MethodDispatcher::RbsDispatchのlookup_method / build_type_varsヘルパー。RbsDispatch#try_dispatch / #block_param_typesに2つの生のenvironment.rbs_loader存在チェックが残っています——これらは「ローダーは存在するか？」を確認するものであり、ファサードラッパーはコールサイトを簡略化することなくノイズを追加するだけです。

ファサードはrbs_class_known?、instance_definition / singleton_definition、class_type_param_names、および一度限りのScope構築コストなしに移行をサポートするenvironment: kwargsの代替を獲得しました。

ステータス更新（v0.0.7バッチ8、2026-05-05）: キャッシュスライス分類体系設計ドキュメントが着地しました。20260505-cache-slice-taxonomy.mdに。スロットごとのエントリー形状（:digest / :mtime / :exists比較器を持つFileEntry、GemEntry、PluginEntry、ConfigEntry）、プロデューサー間のコンポジションルール（スロットごとのキーによる和集合、ファイルの競合ではより厳格な比較器が勝つ、競合はスライスを無効化）、正規キャッシュキー導出、プロデューサーファミリー（リフレクション / 推論 / カタログ / プラグイン）ごとの粒度ガイダンス、スキーマバージョニングポリシーを固定します。

ステータス更新（v0.0.8プランニング、2026-05-05）: キャッシュ永続化バックエンドの選択が固定されました。ADR-6が作業上の決定を記録しています: カスタム正規フォーマットを通じて書き込まれるバイナリエントリーのシャードディレクトリ、新しいgem依存関係ゼロ、書き込みアトミシティのためのファイルごとのflock、最初の実装では退避なし。永続化レイヤーはv0.0.8リリースのテーマとしてリリースされます; ROADMAP.mdのv0.0.8行を参照してください。

キャッシュレイヤー後のpre-v0.1.0次スライス: Rigor::FlowContributionバンドル構造体——ADR-2 §「フロー貢献バンドル」が指定する8スロット形状。内部効果構造体（PredicateEffect等）は境界でバンドルに変換されます;組み込みルールとプラグインの両方がバンドルを生成します。これはキャッシュ後の次のサブストレート作業です;スコープが許せばv0.0.8のコンパニオンとして着地できますが、v0.0.9まで残っても構いません。

設計ドキュメント自体のステータス

このドキュメントはv0.1.0に向けたv0.0.7ワーキングツリーの準備状況のスナップショットです。以下の場合に更新されます。

v0.0.xドットリリースが「ADR-2のリリースを必要としないpre-v0.1.0作業」リストの項目を閉じた時。
ADR-2の「未解決の問題」が具体的なスキーマに解決された時。
リフレクションファサードが着地し、基礎となるリフレクションサーフェスエリアが変わった時。

v0.1.0がリリースされた後、このドキュメントはパブリックプラグインAPIドキュメントに取って代わられ、歴史的記録としてdocs/design/に残ります。