nightrun

NightRun

NightRun は、量子化されたローカル LLM（Llama 3.2、Qwen3、または密な Granite 4.1）のチャットプロンプトを直接起動する、単一の no_std Rust UEFI アプリケーションです。 Linux、カーネル、ブラウザー、ネットワークスタックは必要ありません。モデルは CRC-32 による インライン検証を行いながら RAM にストリーミングされ、読み込み後はストレージが封印され、 推論はすべて CPU 上で実行されます（x86_64 では AVX2+FMA+F16C、Pi 5 では NEON）。 このスキルを使って、ビルド → 変換 → テスト → 書き込みのワークフローを安全に進めます。

このスキルを使う場面

• ソースから BOOTX64.EFI または起動可能な完全な nightrun.img をビルドするとき
• nrconvert で GGUF チェックポイントを .nrm コンテナーに変換するとき
• QEMU を使う前に、ホスト上で推論エンジン（nrhost）を実行／デバッグするとき
• スクリーンショットの撮影やスクリプトによる検証のため、QEMU/OVMF で NightRun を起動するとき（cargo xtask run）
• install.sh で実際の USB メモリまたは Raspberry Pi 5 の SD カードに書き込むとき
• llama.cpp の参照フィクスチャと照合して、トークナイザー／パリティの失敗を診断するとき

このスキルを使わない場面

• ベアメタル／OS なしの制約がない一般的なローカル LLM のサービング → このスキルではなく、通常の推論ランタイムを使います
• 起動／モデル／カーネルの経路と無関係な一般的な Rust ワークスペースのリファクタリング → build-fix を使います
• x86_64 UEFI／Raspberry Pi 5 以外のターゲットへのクロスコンパイル → 対象外です。NightRun は UEFI 専用で、レガシー BIOS には対応していません

手順

ステップ 1：まずクローンし、ワークスペースのルールを読む

git clone https://github.com/hardrave/NIGHTRUN.git
cd NIGHTRUN

crates/nr-boot に手を加える前に CLAUDE.md を読んでください。厳守すべきルールは 2 つです。

• cargo build --workspace／cargo test --workspace は絶対に実行しないでください。nr-boot は cargo xtask（nightly + -Zbuild-std + カスタムの ハードフロートターゲット x86_64-nightrun-uefi.json）でのみビルドされます。パニックハンドラーがホストの std ターゲットと衝突します。
• ExitBootServices() を追加したり、AP ワーカーコードからファームウェアサービスを呼び出したりしないでください（nr-tensor::parallel のワーカーはアトミック操作と計算のみを行います）。

ステップ 2：動作する最小のモードを選ぶ

コマンドの全リファレンスは references/commands.md を参照してください。次から 1 つ選びます。

1. ホスト側でのエンジン作業（カーネル、トークナイザー、サンプリング）→ cargo test、 cargo run --release -p nrhost
2. モデル変換 → cargo run --release -p nrconvert
3. ファームウェアのみのビルド → cargo xtask build
4. 完全なイメージと QEMU での検証 → cargo xtask image の後に cargo xtask run
5. 実機への書き込み → ./install.sh（対話式、確認が必要）

QEMU で正常に起動する前に、実際のメディアへの書き込みに進まないでください。

ステップ 3：起動を試みる前にモデルを変換する

cargo run --release -p nrconvert -- path/to/model.gguf models/model.nrm

変換ツールは成功を報告する前に、自身の出力を再解析してチェックサムを再検証します。 Qwen では QEMU に 6 GB の RAM（--mem 6G）が必要です。それ以外のモデルでは 4 GB が必要です。

ステップ 4：実機に書き込む前に、ホストで検証し、その後 QEMU で検証する

cargo run --release -p nrhost -- models/model.nrm --prompt "..." --temp 0
cargo xtask image --model models/model.nrm
cargo xtask run --img --model models/model.nrm --mem 4G --smp 8 \
  --shot 5:boot.png

./install.sh（実際の USB／SD デバイスに書き込みます）に進むのは、QEMU の起動とチャットの応答が正しいことを確認してからにしてください。インストーラーはリムーバブルでないディスクを拒否し、FLASH /dev/sdX と一字一句そのまま入力するよう求めます。この確認を回避するスクリプトは絶対に作成しないでください。

ステップ 5：ラッパーを使って、ガイド付きの非破壊ドライランを行う

bash .agent-skills/nightrun/scripts/nightrun.sh doctor /path/to/NIGHTRUN
bash .agent-skills/nightrun/scripts/nightrun.sh build /path/to/NIGHTRUN
bash .agent-skills/nightrun/scripts/nightrun.sh convert /path/to/NIGHTRUN in.gguf models/model.nrm
bash .agent-skills/nightrun/scripts/nightrun.sh qemu /path/to/NIGHTRUN models/model.nrm

doctor は前提条件の状態（Rust ツールチェーン、QEMU、ディスク容量）を報告するだけで、ディスクへの書き込みは行いません。実際のメディアへの書き込みは、手動で対話式に ./install.sh を実行する必要があります。ラッパーは意図的に書き込みを自動化しません。

ステップ 6：参照フィクスチャでパリティの失敗をデバッグする

すべてのモデルファミリーで、greedy 出力は llama.cpp とトークン単位で照合されます（crates/nr-model/tests/parity.rs）。カーネル／rope／rmsnorm の変更でパリティが崩れた場合、誤っているのはカーネルであり、フィクスチャではありません。トークナイザーまたはチャットテンプレートを変更したときは、scripts/gen_tokenizer_fixtures.py でトークナイザーフィクスチャを再生成してください。

ベストプラクティス

1. フラッシュ時の確認を絶対に省略しないでください — install.sh では FLASH /dev/sdX と正確に入力する必要があります。この入力をスクリプト化しないでください。
2. 必ず実機より先に QEMU で確認してください — QEMU の起動に失敗する場合、実際のメディアもまだ準備できていません。
3. パリティの不一致はエンジンのバグとして扱ってください — 正解は llama.cpp のフィクスチャであり、新しいカーネルではありません。
4. nr-boot は xtask 経由で実行してください — nightly と -Zbuild-std、カスタムのハードフロートターゲットを使用し、通常の cargo build --workspace は使わないでください。
5. トークナイザーやフォーマットを変更したらモデルを再生成してください — 古い .nrm ファイルがあると、テストの失敗が古いフィクスチャによるものなのに、リグレッションのように見えてしまいます。

参考資料

• 上流リポジトリ：hardrave/NIGHTRUN
• コマンドの全リファレンス：references/commands.md
• ラッパースクリプト：scripts/nightrun.sh
• プロジェクト標準：.agent-skills/skill-standardization/SKILL.md

使用例

例 1：実機に触れずに新しいモデルを試作する

bash .agent-skills/nightrun/scripts/nightrun.sh doctor ~/src/NIGHTRUN
cargo run --release -p nrconvert -- ~/models/llama-3.2-1b-q8_0.gguf ~/src/NIGHTRUN/models/model.nrm
cargo run --release -p nrhost -- ~/src/NIGHTRUN/models/model.nrm --prompt "hello" --temp 0

例 2：USB メモリにフラッシュする前に QEMU で完全な検証を行う

bash .agent-skills/nightrun/scripts/nightrun.sh qemu ~/src/NIGHTRUN models/model.nrm --shot 5:boot.png
# only after a correct boot + chat response:
cd ~/src/NIGHTRUN && ./install.sh