inkcheck

ink ストーリーのための機械的 QA。 コンパイルチェック、制限付きの系統的な分岐探索、ランタイムエラーの再現パス、デッドコンテンツ検出 — ライターとチーム向けのスタンドアロン CLI として、オプションの CI および MCP 統合を備えています。

エージェントはここから始めてください → SKILL.md — これを呼び出すタイミング、実例、MUST/MUST NOT。ファミリー契約: FAMILY.md。

inkcheck は QA ツールであり、ライティングツールではありません。散文の一言も生成、書き換え、送信しません。あなたが書いたストーリーを機械的にチェックできるようにするために存在します: ink の公式コンパイラでコンパイルし、明示的な制限内で選択パスを探索し、プレイヤーが見つける前に失敗を再現します。

AI を使用しますか？

いいえ。inkcheck 自体は、ストーリーをテストするために AI、機械学習、LLM、生成モデルを使用しません。ソースでトレーニングしたり、散文の変更を推測したり、ストーリーテキストを書き換えたり、ストーリーコンテンツを AI サービスに送信したりしません。

人間、CI システム、オプションの AI コーディングエージェントがすべて同じ機械的 QA チェックを実行できるように設計されています。実際のチェックは決定論的なコードです: 公式の ink コンパイラ、ink ランタイム、制限付き分岐探索、構造化レポート。

Related MCP server: RenForge MCP

2 分で試す

Node.js 18 以降の場合:

npx -y inkcheck path/to/main.ink

自分のストーリーを試す前に失敗パスのレポートを見たいですか？ 2 分の合成デモ を実行してください。

製品の約束

Inkcheck は、ink ストーリーのための制限付き機械的 QA です。大きなストーリーですべてのパスが機能することを証明するものではありません。明示的な制限内で到達可能なストーリー状態を決定論的に探索し、見つけた問題の正確な再現パスを報告し、カバレッジが部分的であった場所と理由を示すため、作者は安価で繰り返し可能な回帰保険として使用できます。

Inkcheck は、大規模なインタラクティブストーリーにバグがないことを証明するものではありません。組み合わせ爆発は現実です: ループ、変数、ランダム性、ホストゲームコードは、どのツールも網羅的に訪問できるよりも多くの可能な状態を作り出すことができます。

約束はより狭く、より有用です: 機械的なストーリー QA を安価で、繰り返し可能で、実行可能にすること。Inkcheck は、明示的な制限内で実際の到達可能な選択状態を歩き、実行が部分的だったときに通知し、失敗を修正後に再実行できる再現パスに変えます。今日壊れたパスを見つけた場合、同じ設定のチェックが明日もそのパスを再度探すことができるはずです。

これはオープンソースの QA プロジェクトです。その境界が重要だからです。レポートが過大評価している、明らかなパターンを見逃している、より良いトラバーサル戦略が必要、または安全に共有できるストーリー形状で失敗する場合は、フィクスチャまたは問題を持ち込んでください。ロードマップは、部分的なカバレッジをより透明で価値あるものにすることであり、部分的なカバレッジが証明になるふりをすることではありません。

製品の方向性と自己スコア

Inkcheck の将来の価値は、再現可能なハイブリッドからもたらされる予定です: 広範なシード付きプローブ、系統的なローカル検査、制限付き多様性探索、およびゲート、ループ、アサーション、ストーリーレットの適格性のための Ink 対応スペシャリスト。スペシャリストは制限を維持し、ポートフォリオに新しい証拠を通じてより多くの作業を獲得する必要があります。なぜなら、それらも予算の罠になる可能性があるからです。

同じ取引がハードウェアにも適用されます。ローカル CLI とワンショット MCP ポートフォリオチェックは、決定論的な 1,024 状態のライブパイロットをデフォルトとし、小さく、深さに制限があり、作者のフロンティアで飽和したジョブをシーケンシャルに保ち、オープンな持続フロンティアに対してのみ制限付きワーカーをアクティブにします。すべてのパイロット状態は元のグローバル上限の下でカウントされます。決定を下すために検索が再開されることはありません。マッチした評価は正確な証拠を保持し、1 つの 5M 状態、深さ 100 の The Intercept 実行を 25.6% 改善しましたが、制約付きおよびホストされたジョブは明示的なシーケンシャル上限を保持します。並行性評価 を参照してください。

これらは個別のスコアであり、平均ではありません。高い信頼スコアは失われたランタイムエラーを相殺できません。詳細な製品およびエンジニアリングの真実スコアカードは、すべての 10/10 ターゲット、現在の証拠、エンジニアリング制約、および各エピックまたはリリースで使用される再評価プロトコルを定義しています。最初の完全なポリシー v2 プロモーション評価は、動的割り当てを実験的なままにし、混合証拠をローンチの主張に変えません。

Inkcheck 0.6 のスコープ

Inkcheck 0.6 は、普遍的に優れた動的検索ポリシーを主張することなく、いつでも QA 基盤を出荷します。確立された制限付きポートフォリオが検索のデフォルトのままです。ワークロード対応の並行性は、ライブパイロットが十分な持続作業を示した場合に結果を左シフトする可能性があります。耐久キャンペーンは、ソースにバインドされた結果ウィンドウを返却、再開、検査できます。人間とエージェントは、名前付きの時間/リソース姿勢を選択できます。そして、すべての自動決定は帰属可能なままです。ロングテールの拡張、ローテーション、停止は、3 ファミリープロモーションゲートが作者向けの価値を十分に広く確立しなかったため、シャドウのみのままです。

これは完了したリリース契約であり、より大きな研究問題が解決されたという主張ではありません。動的な最初のウィンドウサイズ設定、コンパクトな大規模チェックポイント、プロバイダー帰属コスト、より広範なエージェント評価、制限付きスペシャリストエクスプローラーは、個別に追跡されるロードマップ作業のままです。将来のリリースは、チェックされた証拠が同じ重要な保持、リプレイ、リソース、誠実さのゲートをクリアした場合にのみ、固定ポートフォリオを置き換える可能性があります。

Inkcheck 0.7: 重要なルール

Inkcheck 0.7 は、作者が宣言した不変条件を、ホストされたチェッカーだけでなく、ローカル設定、CI、MCP でも第一級にします。ライターは、Web フローで gold >= 0 などのオプションの数値ルールを 1 つ追加できます。実行前に平易な言語で表示され、生成された型付き設定で表示され、通常の制限付き QA 中にチェックされ、違反した場合は正確なリプレイ証人とともに報告されます。Web フローは宣言された Ink 変数を検出して選択を支援しますが、サーバーは権威のままです: 未知の変数、無効な型、サポートされていない文法は探索前に失敗します。一時的なルール設定はアップロードとともに削除されます。エージェントは型付きルール提案をドラフトできますが、黙って承認することはできません。バージョン 0.7.2 は、プライベート QA 証拠ピンも追加します: 承認されたランタイム、アサーション、または目標の証人は、別の検索なしで編集後に再チェックできますが、広範な検証には新しい制限付き実行が必要です。

別のアサーション指向スペシャリストは、オプトインで実験的なままです。事前登録された証拠ゲートを通過するまで、デフォルトの予算を受け取らず、スコアカードを変更せず、より良いカバレッジを主張しません。重要なルール契約 は両方の境界を定義しています。

エージェントキャンペーンポリシー

MCP エージェントは、エクスプローラーの重みを発明する代わりに、高レベルの quick、balanced、deep、overnight、または campaign モードで耐久キャンペーンを開始できます。balanced は新しいエージェントのデフォルトです。fixed は明示的なレガシーコントロールを保持します。制限付きオーバーライドは、状態/ウィンドウ/時間/メモリ/ディスク/期限の姿勢、希少/バランス/豊富なリソース、優先値 (broad_qa、runtime_assertions、outcomes、または approved_goals)、保護されたロングテール作業、および ceilings 対 knee の停止を変更できます。正確なベースウィンドウは、アサーション/ゴールなしで再開可能なままです。保護されたロングテール割り当ては、正確なベースチェックポイントを保持しながら、代替の検索シードとより深い境界を持つ決定論的なルート開始ポートフォリオ子を起動します。runtime_assertions キャンペーンは、add_assertions で検証済みのアサーションウィンドウを追加できます。approved_goals キャンペーンは、add_goal で検証済みの目標を追加できます。すべての子は明示的な許可を使用し、個別の証拠レポートを保存し、キャンペーンに新しい重要な、意図、作者のノット、またはターミナル証拠に対してのみクレジットを受け取ります。

最初の作者付きストーリーキャンペーン子評価は、The Intercept で 1 つの信頼できる古い変数レビューリードと 1 つの拒否されたアサーション仮説を見つけました。段階的な目標は外れ、両方の高予算子は 5M の前にメモリで停止し、500K の共有ベースは耐久チェックポイントの上限を超えました。これは有望なアサーション価値と明確な警告です: エージェント作成のルールは人間の検証が必要であり、スペシャリストはプローブから拡張への経済学が必要であり、大規模なキャンペーンが日常的になる前にコンパクトなチェックポイントが必要です。

マッチした独立ロングテール評価は、成長する共有フロンティアと保護されたルート開始ポートフォリオパーティションを比較しました。5M の Intercept キャンペーンでは、共有アームは合計 786,559 状態でメモリで停止しました。9 つの独立した子は、より低いピークヒープで 5M すべてを完了し、407 に対して 3,558 のキャンペーンに新しいターミナルバリアントをクレジットしました。彼らは新しい重要な問題、作者のノット、または目に見えるエンディングを見つけませんでした。これは、リソース効率の高い多様性と測定可能な収穫逓減の証拠であり、普遍的な QA 価値の主張ではありません。

その後の 3 ファミリー 0.6 プロモーションゲートは、動的な停止または拡張を促進しませんでした。Dog Ink Adventure と Heresy II はどちらも、500K ベースが再開可能なチェックポイントを生成する前にリソース上限に達したため、ロングテールポリシーは機能しませんでした。The Intercept では、独立したパーティションは 1.40 GiB のピークヒープで 4.66M 状態に達しましたが、成長するフロンティアは 787K 状態と 3.70 GiB で停止しました。ターミナルの再発見は 34% から 94% に上昇し、新しい重要な問題、作者のノット、または目に見える結果はありませんでした。Inkcheck はこれらの推奨事項をシャドウのみに保ち、動的な最初のウィンドウサイズ設定をより強力な次の製品要件として扱います。

すべての結果ウィンドウは、安定したポリシー ID、割り当て理由、測定された優先収量、スループット/リソース証拠、別のウィンドウの不確実性ラベル付き経験的範囲、拘束力のある制約、および完全な曲線または発見を検査するために使用されるレポート ID を返します。コンパクトな検査は、最新のウィンドウの目的、パーティション、限界収量も示します。膝には、優先収量のない 3 つの連続したウィンドウが必要であり、保護されたプローブを消費できません。これは、実際に実行された軌跡に対する制限付きの観察であり、ストーリーがカバーされている、または後の発見が存在しないという主張ではありません。キャンペーンポリシー契約 と MCP 結果ウィンドウガイド を参照してください。

独立した子実行の後、コンパクトな決定には、バージョン管理されたシャドウ専用のロングテール推奨も含まれます。同じファミリーを拡張するか、別のパーティションにローテーションするか、保護された下限の後に停止するかです。選択されたプリファレンスの下でキャンペーン新規価値を使用し、状態と秒ごとの最近の収量を報告し、希少/均衡/豊富な姿勢に対して段階的により多くのドライプローブを必要とし、コンパクトな選択値の再発見と、事実に基づくレポートローカルの発見ギャップを公開します。古い台帳はそれらのシグナルを利用不可とマークします。再発見は、以前のキャンペーンレポートとの同一性の重複であり、生の重複状態作業ではありません。ギャップの拡大は観察であり、プラトーの証明ではありません。liveEffect: false は、この証拠がまだ割り当てを変更できないことを意味します。

人間は、その制御方法を学ばずに同じ耐久性のあるポリシーを使用できます。inkcheck campaign story.ink はバランスの取れた意図を実行し、--mode quick、deep、または overnight は結果と時間の姿勢を選択します。作業の進行に応じて不変のソースバインド結果ウィンドウを返し、期限またはウィンドウ間のキャンセル時に最新の部分レポートを保持し、技術的な状態/時間/メモリ/ディスクの上限をエキスパートオーバーライドとして利用可能に保ちます。結果ウィンドウは、費やした作業、実行可能な収量、予測の不確実性、検索を続行できるかどうかを分離します。静かな発見間隔や観察された膝は、完全なカバレッジとして説明されることはありません。

クイックスタート

Node.js 18以降の場合:

npx -y inkcheck path/to/main.ink

グローバルインストールは不要です。初回実行時に、固定された公式の ink コンパイラをダウンロードし、その SHA-256 ハッシュを検証して、ストーリーをローカルで処理します。

プロジェクト設定

プロジェクトがすべての人間またはエージェントセッションで同じエントリポイントと境界付き CI 設定を使用する必要がある場合は、inkcheck.yml をコミットします:

schemaVersion: 1
entrypoint: story.ink
ci:
  maxDepth: 100
  maxStates: 1000000
  goalMaxStates: 250000
  seed: 1
  storySeed: 1
  search: portfolio
  concurrency: auto
  strict: true
assertions:
  - id: gold_nonnegative
    description: Gold never goes negative
    when: always
    condition:
      left: { variable: gold }
      operator: ">="
      right: { literal: 0 }
goals:
  - id: depleted_gold
    description: Seek paths where the player runs out of gold
    condition:
      left: { variable: gold }
      operator: "<="
      right: { literal: 0 }

inkcheck validate-config を実行して確認します。そのディレクトリから、inkcheck は設定されたエントリポイントとデフォルトを使用します。明示的な CLI フラグは引き続き優先されます。不明なキーは検証に失敗するため、サポートされていない外部動作や編集ポリシーフィールドが実装されているように見えることはありません。公開された契約は config schema v1 です。

アサーションは型付きデータであり、JavaScript や任意の Ink 式ではありません。オペランドは変数またはスカラーリテラルです。比較は ==、!=、<、<=、>、または >= を使用し、条件は all、any、not で構成できます。ルールは常に、終端状態で、または名前付きノットに入るときに実行されます。不明な変数/ノットと無効なクロスタイプ比較は、探索が状態予算を使い果たす前に失敗します。違反は常に CI を失敗させ、観察された値と正確なインデックス付きリプレイ証人を含みます。境界付きクリーン実行は「違反が観察されなかった」ことのみを意味します。徹底的な実行のみが、ルールを徹底的に検証済みとして報告します。

ゴールは同じ非実行可能な条件文法を使用しますが、CI を失敗させる代わりに探索をガイドします。一般的な探索は常に完全な maxStates 予算を受け取ります。設定で goalMaxStates を設定するか、CLI で --goal-states を使用して、明示的な決定論的ゴール近接スライスを追加します。デフォルトはゼロで、結合予算は 100,000,000 状態を超えることはできません。追加のスライスが要求されない場合でも、ゴールは通常の探索中に観察されます。到達したゴールには正確な選択インデックスが含まれます。ミスは、徹底的な探索が実際に到達不能を証明しない限り、not_reached_within_limits と言います。レポートはベースライン、ゴール、総予算を別々に公開するため、ステアリングが一般的な QA の発見を静かに置き換えることはできません。検索実験 の比較証拠を参照してください。

遅延複合依存関係の場合、condition を 2 つ以上の順序付けられた stages に置き換えます。各ステージは同じ型付き文法を使用します。Inkcheck は最初の未達成の累積マイルストーンを探すため、後のステージは、その状態が以前のすべてのステージも満たすパス上でのみ到達されます。未達の前提条件は、後のステージを blocked_by_stage のままにします。到達不能とは呼びません。この最初の段階的契約は、1 つの共有された追加ゴール予算を使用し、ランタイムチェックポイントをシリアル化する代わりに、ストーリールートから決定論的に再起動します。

1 つの .ink ファイルを含む新しいプロジェクトの場合、inkcheck init がこの設定を作成します。複数ファイルプロジェクトは、--entrypoint でルートを指定する必要があります。inkcheck agent-kit --format codex は、必要な場合に設定、固定された GitHub Actions の例、.inkcheck/ アーティファクト無視ルール、およびコンパクトなバージョン一致エージェント指示を追加します。両方のコマンドは冪等で、すべてのターゲットを事前チェックします。既存の作成済みファイルを上書きしたり部分的に変更したりする代わりに、操作全体を拒否します。npm アーティファクトには、標準の skills/inkcheck/SKILL.md、段階的な Ink/ワークフロー参照、および 10 の実行可能なゴールデン演習も含まれます。inkcheck capabilities --json はこれを features.bundledAgentSkill として宣伝し、インストールされたスキーマ契約の権威であり続けます。

--save-report は、バージョン管理されたレポートを .inkcheck/reports/ の下に原子的に保存し、その安定したコンテンツおよびエントリポイント由来の ID を返します。後のセッションで inkcheck artifacts list --json と inkcheck artifacts show <report-id> --json を使用できます。再オープンすると、保存された証拠が現在のエントリポイントに対して current、stale、または path_changed のいずれであるかが報告されます。レポートにはストーリーテキスト、変数、正確な証人が含まれる可能性があるため、エージェントキットはデフォルトでそれらを無視します。信頼、プライバシー、互換性の契約については、ローカルレポートアーティファクト を参照してください。

長いベース共有実行は、その正確なライブフロンティアをローカルに永続化することもできます。--search=shared --no-min-repro --save-checkpoint で開始し、後で inkcheck resume <checkpoint-id> --max-states N で続行します。N はより大きな総付与であり、追加の隠れた作業ではありません。inkcheck checkpoints list/show は、境界付きメタデータ、耐久性のある圧縮サイズ、ストレージエンコーディング、ソースの鮮度を報告します。新しいチェックポイントファイルはストリーミング gzip アーティファクトです。古いプレーンな schema-v1 JSON は読み取り可能なままです。チェックポイントはプライベートで、原子的で、ソース/設定にバインドされ、デフォルトで無視され、保持上限があります。作成されたテキストとランタイム状態を含む場合があります。ローカル再開可能チェックポイント を参照してください。共有パスは、決定論的な論理アカウンティングをライブヒープ/RSS 観察から分離する、境界付きのリソース/収量観測台帳も公開します。MCP エージェントは、耐久性のある start_search / inspect_search / continue_search / cancel_search 結果ウィンドウを通じて同じ正確な基盤を使用できます。また、add_goal を使用して、ストーリールートから開始し、その正確なベースフロンティアに触れない明示的な加算的指向プローブを追加できます。ポートフォリオ、共有変数、アサーション、指向フロンティア再開、ホスト型ジョブは、まだこのチェックポイント契約を使用していません。

ホスト型チェッカー

リポジトリには、ターミナルを使用したくないライター向けのセルフホスト型 Web インターフェースが含まれるようになりました。ホスト型モードは、承認された .ink ソースを一時的にアップロードし、Quick(早期の 250K 状態結果)と Balanced(より深い 1M 状態結果)の意図を提供し、短命のプライベートジョブを作成し、実際の作業、収量、不確実性シグナルをストリーミングし、完了、キャンセル、または失敗後に一時的なジョブディレクトリを削除します。完了したホスト型チェックは、ソースバインドされた結果ウィンドウ ID と安定した発見 ID を返します。レポートを公開したり、アプリケーションログにストーリーテキストを保持したりしません。オプションのファーストパーティ使用状況メトリクスは、毎日の集計数と、プライバシーを保護するおおよその毎日のユニークブラウザ推定値を保持します。IP、ユーザーエージェント、ブラウザトークン、訪問者プロファイルは保持されません。

ローカル CLI は、ストーリーのアップロードが発生しないため、プライバシーファーストのオプションのままです。脅威モデル、Docker デプロイ、運用制限、現在の月額 50 ドル未満の予算については、ホスト型チェッカーデプロイ を参照してください。

検出されるもの

• コンパイルエラーと警告 — 壊れたダイバート、未解決の変数、行き止まり。ファイルと行番号付き(inklecate、公式コンパイラ経由)

• 再現パス付きのランタイムエラー — ゼロ除算、不正な外部呼び出し、またはコンテンツ外をトリガーする正確な選択シーケンス。例: repro: [Enter in darkness → Descend to the cellar]

• 可能性のある非終了強制選択サイクル — 利用可能な唯一の選択が同じ著者可視変数で同じ制御状態に戻る場合の保守的なレビュー警告。オプションの出口、ランダム動作、ターン数、訪問数、EXTERNAL 呼び出しは意図的に除外されます

• 未訪問コンテンツ、トリアージ済み — 設定された制限内で探索されたパスが訪問しないノット。それぞれがインバウンドダイバートスキャンで分類されます:「ここに作成されたダイバートポイントなし — 孤立の可能性」対「インバウンドダイバートあり — この実行の制限を超えている可能性」

• 異なる終端状態 — それぞれに到達する選択トレイル付き。異なる最終変数は異なる結果として保持されます

代替案との比較

コンパイラはストーリーが有効であることを教えてくれます。クリックして進めることは、たまたまクリックしたパスが機能することを教えてくれます。Ink-Tester はランダムなプレイスルーを繰り返しサンプリングし、行レベルの頻度を報告します。inkcheck は代わりに選択状態を体系的に歩き、短い失敗パスを返します。重要な違いは再現性です。報告されたパスを修正した後、同じ設定の実行でそのパスを再度チェックできます。これらのアプローチは、特にランダム性やエンジン統合を含むストーリーでは補完的です。

例

$ inkcheck examples/manor.ink
✓ compiled — 92 words, 7 knots, 6 choices
✓ explored 18050 states within limits (depth 100, 10000000 states, seed 1) — exhaustive (every reachable state visited) — 5 distinct terminal state(s)
    terminal via [Enter in darkness → Search the study → Leave with your loot]: "You slip out the servant door, heavier by half a purse."
    ...
✗ 1 runtime error(s):
    obj is null or undefined (at cellar.3)
      repro: [Enter in darkness → Descend to the cellar] (found by dfs:last)
⚠ 1 knot(s) never visited on any explored path — unreached is not necessarily unreachable:
    treasure_vault (manor.ink line 35) — no authored divert points here — possible orphan

実行が途中で終了した場合、レポートは実際に制限した制限の名前を示します — 例: ⚠ coverage is partial, not a proof — paths were cut at 30 choices deep; raise --max-depth to follow longer trails。深さと状態予算は別々の軸です。The Intercept のローカル実行では、--max-depth を 30 から 100 に上げると、1,000,000 状態の予算で、深さ 30 で 10 倍の予算を使用した場合よりも多くの後半ストーリーコンテンツに到達しました。

終了コードは、コンパイルまたはランタイムエラーで非ゼロです。--strict を追加すると、警告、未訪問ノット、切り詰め、外部スタブでも失敗するため、部分的なカバレッジが静かに CI を通過することはありません。

ストーリーは、デフォルトの予算を超えるために長い必要はありません。Inkle が公開した The Intercept は、コミュニティでは比較的小さなソースファイルと見なされていますが、Inkcheck は 5,000,000 状態でも部分的なものとして報告します。分岐と永続変数は、表示されている選択数が示唆するよりもはるかに大きな到達可能状態グラフを作成します。枯渇は、ソースサイズから推測される期待ではなく、観察された証明です。有限値のストーリーは原理的には網羅可能かもしれませんが、列挙するのは非現実的かもしれません。ターン、ランダム、または無制限の変数状態は、セマンティックグラフを無制限にする可能性があります。境界付き実行は、状態、深さ、時間、メモリのいずれか最初に来たもので停止し、それを示します。ホスト型チェッカーは共有ジョブを 1,000,000 状態に制限します。より大きなジョブ(CLI の 100M 上限まで)はローカルに属します。サイズ設定のガイダンスについては、パフォーマンスとメモリ を参照してください。

1回の実行内で、inkcheckは状態予算を相補的な探索パスに分散して使い、1つの走査順序にすべてを賭けることはありません。現在のCLIポートフォリオは、最後選択優先・最初選択優先・内側から外側へのDFSスライスを探索し、決定的パスが繰り返しがちな初期選択プレフィックスを変化させるシード付きランダムサンプリングスライスを追加し、BFSのようにレベルごとに進みながら変数シグネチャ系統ごとに1状態を保持するフロンティア上限付き多様性ビームを追加し、さらに小さな幅優先スライスを確保して再現パスを短縮します。ランダムスライスは固定のデフォルトシードを使用し、ビームはシードをまったく必要としないため、実行はCIで再現可能なままです。報告されるすべての終端と実行時エラーは、それを見つけたパス（とシード）を明示します。これにより、同じ--max-states制限下でより多くの終端と到達可能な結び目が見つかることが多いですが、それでも境界付きQAにすぎません。切り詰められたレポートは有用な証拠であり、網羅的な証明ではありません。

--search=sharedは実験的な代替手段を選択します。深層・新規性優先・シード付きのビューが1つの重複排除済みフロンティアから描画し、各到達可能状態は最大1回だけ展開されます。これにより、複数の戦略が同じ状態を再発見する場合に、限られた予算をより効率的に使えます。JSONテレメトリは、保留中およびアクティブなチェックポイントJSON/変数、保持された証人祖先、重複排除および意味インデックス、フロンティア参照、発見事項を分離して報告し、解放された祖先と古いビューの圧縮も報告します。これらは決定的に計上されたペイロード/構造の推定値であり、正確なV8ヒープ使用量ではありません。これはまだデフォルトではありません。一部の初期選択構造では、ポートフォリオの独立したランダムおよびビームパスが依然として有利な場合があります。

長時間実行される共有ジョブを評価するライブラリ利用者は、exploreSharedResumable(...)を使用できます。予算が残っている場合、これは正確なライブ基本共有フロンティアを含むソースバインド・バージョン付きJSONチェックポイントを返します。後の呼び出しで総付与額を引き上げ（たとえば100kから1m）、最初の100kを再生することなく続行します。分割実行の等価性は、中断のない実行に対して回帰テストされています。これはエンジンの基盤であり、まだCLIの永続化機能ではありません。チェックポイントには作成者テキスト、変数、ランタイム状態、証人パスが含まれる場合があり、スキーマv1は意図的にアサーション、ゴール、変数/ゴール対応の共有モードを除外しています。共有チェックポイントスキーマv1を参照してください。

--search=shared-variableはより狭い実験で、共有フロンティアの選択の12.5%を、珍しい変数スナップショットまたは遷移を通じて到達した状態に与えます。このブーストは制限されており、深層・新規性・シード付きビューは引き続きアクティブです。これは機械駆動のストーリーレットグラフに役立ちますが、一様に優れているわけではありません。チェックイン済みの比較表には改善と後退の両方が含まれています。

適応型ポートフォリオは、汎用のデフォルトのままです。実験モードはその重みや動作を変更しません。inkcheckの探索戦略ポリシーは、将来のデフォルト変更の前に必要なベンチマーク幅と回帰ゲートを定義しています。

境界付き探索とランダムサンプリング

inkcheckは、非自明なストーリーのすべての可能な状態を訪問することを約束するものではありません。分岐、ループ、変数、ランダムな動作、ホストゲーム統合により、網羅的なカバレッジは物理的に非現実的になる可能性があります。ランダムサンプリングに対するその実用的な利点は再現性です。同じストーリーと制限が与えられた場合、inkcheckは選択グラフを体系的に歩き、失敗に対して正確な選択パスを返し、未訪問の結び目の手がかりを報告し、実行が部分的であったことを明示的に示します。

ランダムサンプリングは、特にランダム性や巨大な状態空間を持つストーリーにとって依然として有用です。これらのアプローチは相補的として扱ってください。ランダムプレイは驚くべきパスに偶然出会うことがありますが、inkcheckは宣言された予算内で決定的なCIフレンドリーな証拠を提供します。

深さ制限30でのThe Interceptのローカルテストでは、より高い予算でより多くの終端状態が見つかりましたが、それでも完全なカバレッジを証明しませんでした。タイミングは1台のローカル開発マシンからのものであり、普遍的なベンチマークではなくスケールの証拠として読むべきです：

これが意図された解釈です。各実行は実際の到達可能状態をテストし、実際の壊れたパスを表面化できますが、切り詰められたレポートは訪問されたものについての証拠であり、すべてが到達可能または正しいという証明ではありません。

パフォーマンスとメモリ

デフォルトの予算は10,000,000状態で、上限は100,000,000なので、大きな実行のコストを知っておく価値があります。実行を制約するリソースは2つあります：時間とメモリです。小さいまたは尽きるストーリーはどちらにも触れません。体系的パスが到達可能空間の完全性を証明した瞬間にポートフォリオは早期終了するため、inkcheck small.inkはデフォルトに関係なく、持っている数個の状態で終了します。以下の数値は、大規模で非網羅的なストーリーにのみ関係します。

時間は探索された状態にほぼ線形にスケールします。1台の開発マシンでは、The Interceptは100万状態あたり約200秒で実行されました（上の表を参照）。したがって、10M状態の実行は数十分、100Mの実行は数時間です。ローカルCLIにはウォールクロック制限がないため、CIまたは対話型使用では、デフォルトに頼るのではなく、実際に必要なカバレッジに--max-statesを固定してください。または、--progress（対話型ターミナルではデフォルトでオン）でデフォルトを実行して、監視して中断できるようにしてください。

メモリは異なる成長を持つ項の合計であり、上限が危険ではなく高い理由です：

そこから得られる2つの実用的な経験則：

• 状態だけでなくヒープを予算化する。 最悪ケースの見積もり（状態の重複排除なし）として、10Mの異なる状態あたり約2 GBのヒープを計画してください。ループのあるストーリーは重複排除が多く、はるかに少ないメモリを使用します。重複排除が少ないストーリーは最悪ケースに近くなります。したがって、10M状態の実行の最悪ケース（~2 GB）はNodeのデフォルトヒープ制限近くに位置します。ループの多いストーリーは十分に下回りますが、大きな低重複排除のものは、デフォルト予算でもメモリガードに達する前に停止する可能性があります。100M状態の実行は通常のデフォルトヒープを超え、--max-old-space-sizeを上げない限りガードで停止します。どちらの場合も、部分レポート付きでクリーンに停止します。ガードが高い上限を安全に指し示せる理由であり、実行が完了するという約束ではありません。

• メモリガードが実際の制限要因であり、上限ではありません。 実行はV8ヒープの85%（または--max-memory）でクリーンに停止し、クラッシュする代わりにtruncatedBy.memoryを持つ部分レポートを返します。したがって、--max-states 100000000を設定することは無謀ではありません。通常のマシンでは、上限ではなくガードが停止位置を決定します。さらに進めるには、Nodeにより多くのヒープを与えてください：NODE_OPTIONS=--max-old-space-size=8192 inkcheck big.ink --max-states 100000000。

• 安全制限は効率の決定ではありません。 状態・時間・メモリの上限は「このジョブはどこまで進めてよいか」に答えます。マシン全体を使うことが価値があるとか、見かけのプラトーが完了であると主張するものではありません。0.6研究パスは、時間経過に伴うポートフォリオ新規発見、スループット、回復ギャップ、ピークRSS、保持フロンティアバイトを測定し、将来のクイック/バランス/ディープポリシーが有用な結果ウィンドウを選択できるようにしつつ、ロングテールプローブを予約します。固定制限はCIと監査のために引き続き利用可能です。

ストーリーが大きすぎて完了できない場合の影響順のレバー：--max-old-space-sizeを上げる（より多くのヘッドルーム）、--no-min-reproを渡す（超線形BFSフロンティアを削除）、--max-statesを下げる（時間とメモリの両方を制限）、またはストーリーを分割して各部分を個別にチェックする。実験的共有モードでは、保留中チェックポイントキュー自体がより厳しい境界を必要とする場合に--max-frontier-memoryまたは--max-frontier-statesを設定し、レポートが有用な証拠が到着し続けていることを示す場合にのみそのエンベロープを引き上げてください。nextRunの判定は各実行後に制限する結合を明示するため、どのレバーが適用されるかがわかります。

測定されたリソース安全な深層実行評価は、作成者による5M上限ジョブでガードがどのように動作するかを記録しており、共有フロンティアの保留状態とシリアル化バイトの高水位標の証拠を含みます。

MCPサーバー

インクストーリーに取り組むAIエージェント向けのツール：

Claude Code に追加:

claude mcp add inkcheck -- npx -y inkcheck mcp

または任意の MCP クライアント設定に:

{
  "mcpServers": {
    "inkcheck": { "command": "npx", "args": ["-y", "inkcheck", "mcp"] }
  }
}

デフォルトの MCP プロファイルは5つのツールを公開する: inkcheck_capabilities、inspect_story、compile_story、start_search、inkcheck_workflow。これにより、新しいエージェントのブートストラップコンテキストを小さく保つ。capabilities はルーターの論理操作とリクエストフィールドを一覧表示する。すべての操作を個別の名前付きツールとして必要とするクライアントにのみ INKCHECK_MCP_PROFILE=full を設定する。

コンパクトなエージェントループは inkcheck_capabilities -> inspect_story -> compile_story -> start_search -> ファインディング/リプレイ/リグレッション操作を inkcheck_workflow 経由でルーティング -> 修正 -> コンパイルと検証。結果ウィンドウセッションは、永続的で境界付き、ページング可能、ソースに束縛されているため、デフォルトのエージェントパスである。論理的な start_campaign / continue_campaign 操作は、同じ厳密な共有フロンティアの周囲に集約ポリシーと測定された支出/来歴を追加する。通常の start_search / continue_search は明示的な累積付与制御を保持する。呼び出しは同期であるため、キャンセルは返された永続的な境界で信頼でき、ウィンドウ途中のプリエンプションではない。inspect_search はプライバシー最小限のままである。add_goal は、厳密な基本検索を弱めることなく、別途報告される指示付き予算を消費できる。replay_witness は、1つの現在のトランスクリプト、選択トレイル、変数状態を返す明示的な境界である。実行時障害、アサーション違反、承認済みゴールウィットネスの場合、編集前に pin_regression、編集後に check_regression を実行すると、別の検索実行なしで1つの厳密なプライベートウィットネスがリプレイされる。ピンは広範な再検証ではない。意味のある編集後は新しい境界付き検索を実行する。QA エビデンスピン、バンドルスキル、MCP 結果ウィンドウセッションを参照。

作者またはエージェントがストーリールールを提案する場合、inkcheck_workflow は最初に review_contract を実行できる。レビューは、型付きアサーションとゴールをコンパイル済みストーリーに対して検証し、既存のコントラクトをインベントリし、作者の承認を要求し、デフォルトで指示付き予算ゼロの広範な QA を推奨する。これは読み取り専用である: 設定を編集したり、検索予算を消費したり、ゴールプローブを黙って昇格させたりすることはできない。エージェント指示型 QA コントラクトを参照。

CLI

inkcheck capabilities [--json]
inkcheck inspect <story.ink> [--json]
inkcheck <story.ink> [--max-depth N] [--max-states N] [--seed N] [--story-seed N] [--search=portfolio|shared|shared-variable] [--concurrency auto|N] [--max-frontier-states N] [--max-frontier-memory MB] [--auto] [--profile] [--next] [--no-min-repro] [--strict] [--save-report] [--save-checkpoint] [--progress=auto|human|ndjson|off] [--human|--json|--json-stream|--markdown]
inkcheck artifacts list [--json]
inkcheck artifacts show <report-id> [--json]
inkcheck artifacts findings <report-id> [--limit N] [--cursor C] [--json]
inkcheck artifacts finding <report-id> <finding-id> [--json]
inkcheck artifacts replay <report-id> <finding-id> [--json]
inkcheck artifacts delete <report-id> [--apply] [--json]
inkcheck artifacts prune --keep N [--apply] [--json]
inkcheck checkpoints list [--json]
inkcheck checkpoints show <checkpoint-id> [--json]
inkcheck resume <checkpoint-id> --max-states N [--json]
inkcheck mcp    # start the MCP server on stdio

inkcheck capabilities --json を使用すると、エージェントは依存する前にスキーマバージョン、制限、検索モード、明示的にサポートされている機能または利用不可の機能を確認できる。inkcheck inspect story.ink --json は、コンパイルや探索なしで決定的なソースのみのディスカバリを実行する: プロジェクトローカルのインクルードを追跡し、ストーリーの形状、セマンティクス、外部参照、ノット/関数、変数宣言/読み取り/書き込み、事実上の代入サイトを持つ静的条件ゲートの境界付きマップを返す。永続的な MCP セッションは、明示的に選択されたサポート済みゲートの1つを、別の境界付き probe_gate ゴール実行に変換できる。そのルート開始プローブは、厳密な基本フロンティアを保持し、ウィットネスまたは境界付きミスを報告する。ゲート検査と代入サイトは前提条件のヒントであり、到達可能性の証明やデフォルトの検索割り当ての変更ではない。複合ゲート検査コントラクトとエージェントディスカバリコントラクトを参照。

ゲートプローブ評価プロトコルは、通常の共有検索を、早期選択コンビネーションロックとオプトインの5M The Intercept セルに対する同予算の明示的プローブと比較する。これは、さらなる前提条件ステアリングが価値があるかどうかのエビデンスであり、カバレッジやプロモーションの主張ではない。

JSON チェックはバージョン管理されたレポートスキーマを使用する。ファインディングには安定した ID と正規化された種類があり、終了および実行時エラーのウィットネスは人間が読める選択テキストとゼロベースの選択インデックスの両方を保持するため、重複ラベルも playtest_story を通じて正確にリプレイ可能である。エンベロープは Inkcheck バージョン、コンパイル済みストーリーフィンガープリント、有効な設定、バインディング制限、観察専用の shadowDecision を記録し、確立された compile、stats、explore、nextRun セクションを保持する。

--concurrency auto はローカルポートフォリオのデフォルトである。これは4レーンの上限を設定するものであり、無条件の4ワーカーではない: 1つの内側から外側への DFS パスは最大1,024状態で実行され、その後、ストーリーが尽きた場合、深さが束縛された場合、作者のノットがすでに飽和している場合、ハードウェアが1コアの場合、またはメモリがワーカーを安全に賄えない場合、バージョン管理された分類子はシーケンシャルのままである。開いた持続フロンティアは、そのライブパスを親に保持し、未タッチのパスは永続ワーカーで開始される。--concurrency 1 はハードなシーケンシャルオプトアウトである。明示的な値2〜16は、ワークロード分類なしで固定ワーカー上限を維持する。共有検索と加算ゴール実行は、互換性のない固定値が明示的に要求されない限り、自動的にシーケンシャルのままである。

レポートは concurrencyMode、解決された上限、アクティベーションポリシー/決定/理由、パイロット作業、有効ワーカー、集約ヒーププラン、重複評価(本番ポリシーではゼロ)を公開する。ワーカー障害は最新の完了したエビデンスを保持し、truncatedBy.worker を報告する。状態予算の停止を装うことは決してない。ホスト型デプロイメントは独自の明示的なジョブごとの上限を渡し、本番コンテナではデフォルトで1になり、実際の子キャンセルは一時アップロードをクリーンアップする。ピーク RSS は V8/ランタイムオーバーヘッドがヒープではないため高くなる可能性がある。分類子はワークロード形状を推定するものであり、カバレッジの完全性ではない。

MCP はデフォルトでコンパクトなマシン出力を使用する: 検査は16 KiB に制限され、コンパイル、統計、ワンショット探索、結果ウィンドウ応答は32 KiB に制限される。出力の省略は境界付き検索の切り捨てとは別に報告される。ストーリー全体を含むレポートは、明示的な詳細またはドリルダウン呼び出しでのみ利用可能である。

保存されたレポートは、完全なレポートを読み込まずに境界付きファインディングのドリルダウンをサポートする。artifacts findings はデフォルトで最大20件のプライバシー最小限のサマリーを返し(最大100件)、レポートに束縛されたカーソルを返す。サマリーはストーリーの散文、変数、選択テキスト、ウィットネスパスを省略する。artifacts finding は1つの完全な安定したファインディングを取得する。artifacts replay は保存されたエントリポイントを再コンパイルし、保存されたストーリーシードでそのファインディングのインデックス付き選択を追跡するが、アーティファクトの鮮度が current の場合のみ。古いまたは移動されたソースはフェイルクローズする。

レポートストレージはプライベートで境界付きである: 1つのレポートは最大256 MiB を使用でき、1つのプロジェクト内のすべてのレポートは最大1 GiB を使用できる。どちらかの上限を超える保存は、古いエビデンスを削除せずに失敗する。artifacts delete と artifacts prune --keep N はデフォルトでプレビューし、--apply でのみ変更する。prune は各エントリポイントの最新 N 件のレポートを保持し、1回の呼び出しで最大100件を削除する。この明示的なライフサイクルにより、別の実行が終了しただけで安定したレポート ID が消えることを防ぐ。

メンテナは、マニフェスト駆動のシャドウポリシー評価器を使用して、独立した予算実行間のシャドウ推奨を比較できる。別の検索プロモーションベンチマークは、チェックインされた20ファミリーのコーパスとピン留めされた同意安全な作者プロジェクト層にわたってマッチしたベースライン/候補マトリックスを実行し、リソース観測と最悪ファミリー/プロジェクト損失を報告し、勝者を宣言することはない。最初の作者プロジェクト評価は、セルが完了した場所でのパリティと、ポリシーv2の利点ではなく意味のあるプロジェクト形状のリソース制限を見出した。どちらのツールも、境界付きの大規模実行をオラクルと呼んだり、デフォルトポリシーを変更したりしない。

--max-depth は1〜1,000を受け入れ、--max-states は1〜100,000,000を受け入れ、デフォルト予算は10,000,000である。これらのハードな上限は、不正な自動化入力が誤って探索境界を無効にすることを防ぐ。デフォルトは意図的に野心的である。なぜなら、3つのことが大きな予算を無謀ではなく安全にするからである: 完全に探索可能なストーリーは、体系的なパスが網羅性を証明した瞬間に早期終了する(そのため小さなストーリーは依然として少数の状態で完了する)、メモリガードはメモリ不足クラッシュの前にクリーンに停止する、進行状況レポートにより長時間の実行を監視して中断できる。したがって、大規模で非網羅的なストーリーはその予算を使用する — CI で実行する前にパフォーマンスとメモリを参照し、境界付きランタイムがカバレッジの深さよりも重要である場合は、そこに小さな --max-states をピン留めする。

--max-states は実行の総予算であり、単一の DFS ウォークがすべての状態を消費するという約束ではない。デフォルトでは、CLI はその予算の大部分を選択ツリーの3つの補完的な DFS ビューとシード付きランダムサンプリングスライスに分割し、短い失敗および終了リプロパスのために小さな幅優先スライスを保持する。幅優先の短縮がより広範な検索よりも重要でない場合は、--no-min-repro を使用してそのリプロスライスを DFS ポートフォリオに費やす。

--seed(デフォルト1)は Inkcheck のランダムサンプリング検索スライスのみを制御する。--story-seed(デフォルト1)は RANDOM() とシャッフル動作のための Ink の初期ランタイム RNG 状態を独立して設定する。再現可能な CI と正確なウィットネスリプレイのために両方を固定する。--seed を変更して異なる選択ウォークをサンプリングするか、--story-seed を意図的に変更して別の有効なストーリーランダム性シーケンスを実行する。作者の SEED_RANDOM(...) コマンドは依然として有効で、初期ストーリーシードをオーバーライドできる。Inkcheck は両方のシードを記録し、リプレイ命令に storySeed を保持するが、1回の実行で可能なすべてのストーリーシードを列挙するわけではない。--json 出力の各ファインディングの foundBy フィールドは、それを発見したパスを指定する。例: dfs:last または random:seed=1。

--search=shared は実験的な共有状態マルチフロンティアエンジンを選択する。--search=portfolio は変更されていないデフォルトである。共有モードは固定シードに対して決定的なままであり、深さ、状態、メモリ、時間、進行状況、リプロ短縮制御を引き続き尊重する。

--save-checkpoint は通常の共有検索よりも意図的に狭い: --search=shared --no-min-repro と、同じコマンド内にアサーション、ゴール、--auto、--next、またはレポートアーティファクトがないことを要求する。ライブ作業が残っている場合、JSON 出力にはソースに束縛されたチェックポイント ID が含まれる。inkcheck resume <id> --max-states N は、ソースと検索バインディングが一致し、N がチェックポイントの以前の総付与を超えることを要求する。自動的に次世代を保存する。完了した検索とリソース停止した検索は、再開可能なチェックポイントを発明せずにレポートを返す。

--search=shared-variable は共有検索に小さな変数レアリティフロンティアを追加する。観測された珍しい変数値を優先し、機械的に変更する。AI を使用したり、ストーリーの意味を理解したり、どの値が望ましいかを推論したりしない。

--max-frontier-states と --max-frontier-memory は、保持される保留中チェックポイントに対するオプションの共有検索セーフティエンベロープです。どちらにもデフォルトはありません。Inkcheck は低い普遍的なフロンティア上限を課しません。明示的なエンベロープが制約として働く場合、実行は発見内容を保持し、truncatedBy.frontier を報告し、停止を状態予算の枯渇と誤ってラベル付けしません。同じ制御は ci.maxFrontierStates / ci.maxFrontierMb および MCP の explore_story 入力としても利用できます。

--max-memory <mb> は、実行全体がクリーンに停止するまでに使用できるヒープの上限を設定します。V8 ヒープのメモリ不足によるアボートは事後的に捕捉できないため、inkcheck は探索中にメモリを監視し、クラッシュする前に停止して、これまでに見つけたすべてを保持し、実行を失う代わりに部分レポートとともに truncatedBy.memory を報告します。明示的な上限は、最終結果の構築とフラッシュのために最大 25%（最大 1 GiB）を保持します。制限付きストリームは、完全なエンベロープと低い方の検索ウォーターマークの両方を報告します。デフォルトの上限は V8 ヒープ制限の 85% です（設定した NODE_OPTIONS=--max-old-space-size を尊重します）。そのため、控えめなハードウェアでの大規模な実行は、停止する代わりに優雅に劣化します。明示的な値を渡すと、上限を厳しくしたり緩めたりできます。メモリ停止時、nextRun の判定は investigate です（--max-old-space-size を上げる、--max-states を下げる、またはストーリーを分割する）— 決して broaden ではありません。予算を増やしても、より早く壁にぶつかるだけだからです。

--max-time <s> は、合計ウォールクロック時間の対応物です。期限はコンパイルとソーススキャンの前に始まり、実行は保持された発見をマージして結果をフラッシュするために、付与時間の 10%（最小 250 ミリ秒、最大 60 秒）を保持します。探索は状態予算まで実行する代わりに truncatedBy.time で停止します。ローカル CLI にはデフォルトの時間制限はありません。これは、実行時間を制限する必要があるが、これまでの発見は引き続き必要とする CI やその他のコンテキストを意図しています。メモリガードと同じ優雅な部分停止の考え方を時間に適用したものです。ホスト型 Web チェッカーは、ハードタイムアウトの直前にこれを自動的に設定するため、遅いストーリーは強制終了される代わりに部分レポートを返します。

--profile は、ストーリーの安価な静的シェイププロファイル（変数とその代入箇所、選択肢の密度、最長のダイバートパス）に加えて、inkcheck がそのシェイプに対して選択する深さ制限とパス重みを、探索を実行せずに出力します。--auto はそれらの提案を適用します。静的ダイバートパスがデフォルトを超える場合に --max-depth を引き上げ（決して下げることはなく、明示的なフラグが常に優先されます）、プロファイルのパス重みをポートフォリオに渡します。メインパスが 40 選択肢の深さのストーリーでは、デフォルト設定では何も見つかりませんが、--auto はエンディングに到達し、約 111 状態でストーリーの網羅性を証明します。

対話型ターミナルでは、デフォルトで簡潔なライブ進行行が表示されます。実際のフェーズ、設定されたワーク予算に対する探索済み状態、発見数、経過時間です。--progress=human は CI ログ用の読みやすいスナップショットを強制し、--progress=ndjson はエージェントやパーサー向けのバージョン付きイベントを書き出し、--progress=off は進行状況を無音にします。これらのパーセンテージはどれもストーリーのカバレッジを主張するものではありません。最終的な stdout レポートが引き続き権威を持ち、進行状況にストーリーの散文、選択肢、変数、ソーススニペットが含まれることはありません。

すべてのレポートには nextRun 判定も含まれます。これは、レポート自体から決定的に計算される小さな閉じた語彙（stop、deepen、broaden、reseed、investigate）で、具体的なフラグ、使用したフィールドを引用する根拠、証拠に裏付けられた期待される利得を伴います。--next はそれに基づいて動作します。チェック後、inkcheck は推奨されるエスカレーションを適用して再実行し、最大 3 回まで、stop/investigate 判定、フラグ上限、またはエスカレーションされた実行が新しい発見をしない場合（固定点）に停止します。実行ごとのトレイルは --json 出力の runs に格納され、ホップの説明は stderr に送られるため、機械出力はクリーンなままです。推奨事項は文書化されたハード上限を決して超えません。フラグ増加に証拠がない場合、判定は investigate に格下げされ、レビューに値するノットを指し示します。

GitHub Actions:

- uses: actions/setup-node@v4
  with: { node-version: 22 }
- name: Check the story and publish a readable summary
  shell: bash
  run: |
    set -o pipefail
    npx -y inkcheck story/main.ink --strict --markdown --max-states 500000 | tee -a "$GITHUB_STEP_SUMMARY"

この例では --max-states 500000 を固定しているため、ジョブの実行時間は予測可能です。デフォルトの予算は 10,000,000 で、大規模で網羅的でないストーリーは実際にそれを使い切ります（パフォーマンスとメモリ を参照）。最大カバレッジよりも制限されたウォールクロックが重要な場合は、CI で予算を固定してください。

--strict は、警告や未訪問のノットだけでなく、探索が切り詰められた場合や EXTERNAL 関数をスタブ化する必要があった場合にも失敗します。これにより、部分チェックが緑の「完了」バッジを付けることを防ぎます。

ライター向けのセットアップとレポートの解釈については、InkJam QA ガイド を参照してください。

誤解を招く結果を見つけましたか？ 公開 issue フォームを使用して、不正確または見逃した結果を報告 したり、ライセンスされた最小フィクスチャを提供 したり、オプトインの QA クリニックチェックをリクエスト したりできます。非公開、機密扱い、またはジャム制限付きのストーリー素材を公開 issue に添付しないでください。

人間、CI、エージェント向け

inkcheck は、ターミナルで人間、CI ジョブ、またはオプションの AI コーディングエージェントによって操作できます。ツール自体は依然として AI を使用しません。エージェントは CLI または MCP サーバーの単なる別の呼び出し元です。

• 機械可読インターフェース: リポジトリルートの tool.json は、CLI フラグ、MCP ツール、終了コード、--json / --json-stream 出力シェイプを 1 つのファイルで記述します。

• --json は、レポート全体を単一の JSON オブジェクト（{ compile, stats, explore }）として stdout に出力します。見栄えのする出力をスクレイピングする代わりにこれを解析してください。explore.passes は、制限付きのパスローカルな discoveryCurve（「この探索者が見つけたもの」）と、ポートフォリオ専用の portfolioMarginalCurve（「この探索者が最初に追加したもの」）を保持し、正確な終端、可視の結果、ランタイムエラー、アサーション、目標/ステージ、ノット、および同等の新規性を分離します。要約は、圧縮にもかかわらず、最初/最新の発見状態とドライギャップの事実を保持します。ポートフォリオレポートには、実際のインターリーブ実行順序での実行全体のカーブも含まれます。ウォールタイムは進行イベントでは観察的なままです。explore.schedule は、適応ラウンドが予算をどのように使ったかを示します。バージョン付きの shadowDecision は、将来の anytime ポリシーが何を推奨するか、その理由、保護されたパスごとのフロアと不確実性を含めて示します。これは観察専用（applied: false）であり、今日の検索を変更したり、制限付きカバレッジが証明であると主張したりすることはありません。

• --json-stream は、保持された数値の finding 証人を NDJSON として再生可能に出力し、その後、完全な拡張レポートやレポートサイズの JSON 文字列を具体化する代わりに、制限付きのターミナル要約を出力します。現在は --concurrency 1 が必要で、1 回の探索実行（--next や --profile なし）をサポートし、--save-report と組み合わせることはできません。予約済みの数値タグモードは、オラクル変数を検索に公開したり、すべての通常のエンディングをストリーミングしたりせずに、InkBench のオラクル中立スコアリングをサポートします。長い外部プロセス評価で、部分的な証拠がハードラッパー境界を生き残る必要がある場合に、ストリームを使用してください。制限付き証拠ストリーム契約 を参照してください。

• --progress=ndjson は、エージェントまたは CI ログパーサー向けに、バージョン付きのライフサイクルおよび作業進行イベントを stderr に出力します。statesExplored / stateBudget は予算の使用量であり、ストーリーのカバレッジではありません。最終的な stdout レポートが引き続き権威を持ちます。NDJSON 進行契約 を参照してください。

• --human は、エラー、警告、メモでグループ化された優先度付き修正リストを、利用可能な場合はファイル/行の場所、ランタイム障害の選択パス、各 finding の次のステップとともに出力します。

• --markdown は、CI をレビューする人間向けの GitHub Step Summary に適したレポートを出力します。

• 決定的な終了コード: 0 クリーン · 1 コンパイル/ランタイムエラー（または --strict 下では、警告、未訪問ノット、切り詰め、外部スタブ）· 2 使用法エラー。テキストを grep せず、終了コードで分岐してください。

• MCP: claude mcp add inkcheck -- npx -y inkcheck mcp は、コンパクトな 5 ツールのエージェントプロファイルを公開します。互換性カタログには INKCHECK_MCP_PROFILE=full を使用してください。

• ループ: .ink の編集 -> compile_story -> start_search -> 次の証拠アクションを inkcheck_workflow にルーティング -> 修正 -> コンパイルして検証。inkcheck は、生成または編集したストーリーグラフに対する反復可能な機械的チェックです。返す前に自分の作業を検証するために使用してください。

• カバレッジループ: explore_story（および CLI --json）は nextRun を返します。その recommendation（stop / deepen / broaden / reseed / investigate）をスイッチし、stop: true になるまで nextRun.flags で再実行します。または CLI に任せてください: inkcheck story.ink --next。

リポジトリルートの llms.txt は、上記すべてのコンパクトでモデルに優しい要約です。

仕組み

• コンパイルは、標準コンパイラである inklecate を使用します。これは $INKLECATE_PATH、次いで PATH から検出され、初回実行時には公式の ink 1.2.1 リリースからピン留めされた ~/.cache/inkcheck に自動ダウンロードされます。ダウンロードされたアーカイブは、展開前にピン留めされた SHA-256 ハッシュに対して検証されます。ストーリーは -c 付きでコンパイルされるため、すべてのノット訪問がカウントされます。

• 探索は、コンパイル済みストーリーを inkjs（公式 JS ランタイムの移植版）で実行し、プールされたストーリーインスタンスを再利用することで、コンパイル済み JSON がパスごとに一度だけ解析され、状態は LoadJson によって巻き戻されます。Inkcheck は --story-seed（デフォルト 1）からストーリーの乱数を初期化し、保存されたすべての分岐で Ink の RNG 状態を保持します。作成者が記述した SEED_RANDOM(...) は、実行時に引き続き優先されます。状態はコンテンツハッシュによって重複排除されます。INCLUDE は追跡されます。

• CLI は、境界付きの適応型ポートフォリオ探索を使用します。相補的なパス（最後選択優先、最初選択優先、内側から外側への DFS、多様性優先ビーム、シード付きランダムウォーク）が、10 の決定的なラウンドでインターリーブ実行されます。初期重み（およそ 20/20/26/15/20%、または --auto での形状プロファイルの提案）は、発見がまだ成長しているパスに向けて各ラウンドで再配分され、アクティブなパスごとに意図した 8% の小数フロアが設定されます。研究専用のポリシーリプレイは、その意図を監査可能な累積整数サービスに変換し、グローバルな状態数ではなく、各パスの観測された実行ウィンドウに新しさを正規化します。収量を推定する前に 3 つのウィンドウを必要とし、1 つまたは 2 つの測定ウィンドウで更新がない場合にシグナルを失効させ、実験的な割り当てオーバーレイは、更新されたランタイム/アサーションの証拠または明示的な目標の進捗がある場合にのみ許可されます。広範なカバレッジは確立されたスケジューラに委ねられます。本番スケジューラは、完全な昇格コーパスが合格するまで変更されません。パスは相補的です。DFS の順序付けはサブツリーを体系的に使い尽くし、ビームはハードなフロンティア上限内で可変状態系統に予算を分散し、ランダムウォークはすべての選択ポイントを再ロールするため、初期の選択の組み合わせが繰り返される代わりにサンプリングされます。発見は 1 つのレポートに統合され、それぞれに発見したパスがラベル付けされ、実行されたスケジュールが --json 出力に表示されます。

• ワークロード対応の --concurrency auto がローカルポートフォリオのデフォルトです。そのライブの 1,024 状態の内側から外側への DFS パイロットは、通常の最初の適応ラウンドのプレフィックスになり、その後、順次続行するか、境界付きの永続ワーカーで未処理のパスと重複します。そのパイロット中に時間またはメモリが制約になった場合、またはデッドラインがワーカーの初期化前に到来した場合、有効なパイロットは、状態予算の枯渇と誤ってラベル付けされることなく、明示的にリソース切り詰めの部分レポートとして返されます。80 セルの 100K ゲートは、2 回のオープンフロンティア起動のみで、正確な発見、証明、適応スケジュールを保持しました。一致した 5M The Intercept の depth-30/depth-100 ゲートは、正確な証拠を保持し、深さ制限ジョブを拒否し、持続ジョブを 657.7 秒から 489.0 秒に改善しました。すべての状態は 1 つのシーリング内に留まり、重複するパイロット評価はゼロです。明示的な 1 は順次実行を保持し、明示的な 2〜16 のシーリングは固定の並行性を保持します。並行性評価 を参照してください。

• 実験的な --search=shared は、1 つのグローバルな状態 ID を維持し、保留中の作業を深さ、新規性、シード付きフロンティアビューを通じて公開します。任意のビューによって選択された状態は 1 回だけ展開され、展開されたチェックポイント JSON は即座に解放され、コンパクトな親リンクは、保留中の子孫が正確な再現パスを必要とする間だけ存続し、古いビュー ID は定期的にコンパクト化されます。レポートは、コンポーネントの会計とオプションの明示的なチェックポイントエンベロープを公開します。可変状態と可変遷移の希少性は、評価テレメトリとして記録されます。

• 実験的な --search=shared-variable は、共有フロンティアの選択 8 回ごとに 1 回を可変希少性ビューに置き換えます。そのスコアは、宛先変数スナップショットの観測頻度と、そのエッジ上の最も希少な変更を組み合わせます。固定スライスを超えて消費することはできないため、グラフの新規性、深さ、シード付き探索は引き続き表現されます。

• 体系的なパスが制限に達することなくすべての到達可能な状態を訪問した瞬間、ポートフォリオ全体が停止します。それ以降のすべての状態は冗長になるためです。デフォルトの 10,000,000 状態予算での小さな完全探索可能なストーリーでも、実際に持っている少数の状態で完了します。ストーリーが使い尽くせる場合、大きなデフォルトはコストがかかりません。

• ビームパスは「ビームは何を最適化すべきか」に具体的に答えます。生存者は可変シグネチャグループ間でラウンドロビンで選択され（多様性優先）、各グループ内では新規性（新しく訪問されたノット、次に新しい変数シグネチャ、次に新しい提供選択肢セット）によってランク付けされます。シードなしで決定的であり、到達可能な状態を刈り込まなければならなかった場合は常に実行を切り詰めとして報告するため、ビームが完全なカバレッジを暗黙的に主張することはありません。

• --no-min-repro でスキップされない限り、CLI は要求された --max-states 予算の約 10% を幅優先の再現短縮スライス用に確保します。BFS は可能な場合に短い選択トレイルで共有発見に到達し、追加の浅い発見に貢献する場合があります。

• 境界（--max-depth、--max-states）は最悪の場合の組み合わせ爆発を抑えます。レポートは切り詰められたときに明示的に述べます。

カバレッジの制限

• 探索には境界があります。切り詰められたレポートは、訪問した状態に関する証拠であり、ストーリー全体に関する証明ではありません。

• レポートは、実行された制限（深さ、状態予算、探索シード、ストーリーシード）と、切り詰められた場合にどの制限が実際にカバレッジを削ったか（--json の truncatedBy、memory を含む）を、どのフラグを上げるべきかに関する的を絞ったアドバイスとともに述べます。

• メモリを使い果たすような大規模な実行は、クラッシュする代わりにクリーンに停止して部分レポート（truncatedBy.memory）を返します。メモリフットプリントは、重複排除ハッシュセット（個別状態にほぼ線形）と、深いループの少ないストーリーでは幅優先の再現フロンティアによって支配されるため、ストーリーが大きすぎて完了できない場合、--no-min-repro とより厳しい --max-states がレバーになります。

• 小さなストーリーはしばしば逆の保証を得ます。体系的なパスが制限に達することなくすべての到達可能な状態を訪問した場合、レポートはそれを明示します（exhaustive）。また、サンプリングスライスの予算枯渇はもはや切り詰めとしてカウントされません。

• EXTERNAL 関数は、ホストゲームが利用できないためゼロにスタブ化されます。レポートはすべてのスタブに名前を付けます。厳格モードは、完全なカバレッジを主張する代わりに失敗します。

• ランダムな動作は報告されたストーリーシードに対して再現可能ですが、1 回の実行で考えられるすべてのストーリーシードを列挙するわけではありません。結果の頻度が重要な場合は、意図的に --story-seed を変え、人間によるプレイテストをループに含めてください。

• 未訪問のノットは、意図的に休止しているか、エンジンによって入力されるか、到達不能である可能性があります。インバウンドダイバートのトリアージは、おそらく孤立したものと、おそらく制限に縛られたコンテンツを区別しますが、これはレビューのプロンプトであり、自動削除の指示ではありません。

ロードマップ

ロードマップは製品およびエンジニアリングの真実スコアカードによって管理されます。すべてのエピックは、境界付きカバレッジの正直さ、重要な証拠の保持、決定的なリプレイ、またはリソースのシーリングを弱めることなく、測定された価値を改善する必要があります。

• カバレッジの透明性: 切り詰め、深さ制限、訪問したエンディング、スキップされた探索空間、および探索されたかどうかについてのより明確なレポート。

• レポート品質: より良いソース位置、より短い再現パス、安定した問題 ID、およびランタイムエラー、未訪問ノット、カバレッジ制限のより明確なグループ化。

• 作成者定義のストーリーアサーション: 「金がマイナスにならない」「体力が最大を超えない」「必須変数がエンディング前に設定される」などの決定的なプロジェクトルール。

• 目標指向の変数探索: 作成者とエージェントが承認済み状態を求めることを可能にし、保護された一般探索予算と正確な境界付きカバレッジ言語を保持します。

• オプションのホスト型 AI 目標アシスタント: ファーストクラスの、明示的に有効化された人間向けインターフェースで、非技術的な作成者が変数目標とアサーションを承認用に提案するのを支援し、すべての実行と検証を Inkcheck の決定的な非 AI エンジンに委任します。プロバイダー、同意、ソース共有、保持、コスト、および無効化コントロールは明示的でなければなりません。生成されたルールが暗黙的に信頼されたり適用されたりすることはありません。

• 再現の永続化: 既知の失敗パスを記憶し、トラバーサル戦略が改善されても将来の実行がそれらをチェックし続けることを保証します。

• コンパクトなキャンペーンチェックポイント: チェックポイントアーティファクトがメモリやディスクを支配することなく、有用な大規模ストーリーフロンティアを保持して再開し、シリアル化制限の前に不変の部分レポートに劣化します。

• 公開互換性フィクスチャ: 回帰テスト、パフォーマンス比較、信頼構築のための同意安全な例と合成エッジケース。

• エージェント対応: 実行可能なエージェント対応ベンチマークは、隠しヒントなしのプロトコル、決定的なランタイム/アサーションフィクスチャ、ブートストラップ/ツール/参照/安全性/証明ターゲット、機械スコアラー、および個別のツール/スキル/モデル/環境帰属を固定します。異なるエージェント実装からの 2 回の合格観測実行がリリースゲートのままです（#67）。

• 探索昇格ハーネス: 実験的な戦略がデフォルトを変更できる前に、構造ファミリー、予算、深さ、シードにわたる広範な事前宣言スコアカード。

• 境界付き専門家探索: 機械的な形状を検出し、複合ゲート、ループ/カウンター、ストーリーレット適合性、アサーション境界、行動フロンティア多様性のための小さな専門家プローブを派遣します（#107〜#112）。専門家はポートフォリオ新規価値を通じて拡大を獲得し、保護された一般/ロングテール作業を保持します。

• 大規模ストーリーパフォーマンスコントロール: より明確な時間/カバレッジトレードオフを備えたクイック、標準、ディープチェックプリセット。

• 構造的 lint チェック: 欠落タグ、一貫性のないタグスキーマ、またはプロジェクト固有のメタデータ規約のためのオプションチェック。

ライセンス

MIT