Bara

Bara は、x86_64 などの既存バイナリを ARM64 などへ変換する binary-to-binary compiler の研究プロジェクトです。

Rosetta の再実装ではなく、変換コア、runtime、検証系、OS/ABI/ローダー固有部分を分離し、Wine のような互換レイヤーへ接続しやすい構成を探ることを目的とします。

方針

• 初期実装はパフォーマンスより検証しやすさを優先する。
• 最初は raw x86_64 function bytes を関数単位で扱う。
• 最初の成功条件は mov eax, 42; ret 相当が 42 を返すこと。
• Rust を主実装にする。
• Haskell は仕様モデル、property test、検証器として使う。
• Rosetta はブラックボックス oracle としてのみ使い、内部実装を参考にしない。
• Linux user-space の既存変換レイヤーとして FEX-Emu、Box64、QEMU user-mode を研究対象にする。ただし、実装根拠は公開仕様と外部挙動に限定する。

初期スコープ

最初に扱うもの:

• x86_64 の小さな関数片
• 引数なし
• rax 戻り値
• 最小限の decode / IR / ARM64 emit / runner
• expected.json と actual.json の比較

最初に扱わないもの:

• PE/Wine 統合
• syscall
• libc import
• SSE / AVX / x87
• exception / unwind
• self-modifying code
• JIT/fallback
• 最適化

検証方針

arm64 macOS 上で x86_64 Mach-O を Rosetta 実行し、期待結果を JSON として取得します。

自前 BTB で同じ入力を ARM64 に変換し、native runner で実行した結果と比較します。

testcase
  |
  +-- x86_64 Mach-O -> Rosetta -> expected.json
  |
  +-- BTB compile -> ARM64 native runner -> actual.json
                                  |
                                  v
                               compare

Rosetta から使う情報は、テスト harness が出力する外部挙動だけです。Rosetta の逆アセンブルや内部 symbol は実装根拠にしません。

ドキュメント

• TODO: 線形実装ロードマップ。実装順はこの文書を上から読む
• 初期スコープ: 初期 raw function 対象、初期 ABI、扱わないもの
• クリーンルーム運用: Rosetta をブラックボックス oracle として扱うルール
• コーディングルール: シグネチャで仕様を表す方針と unsafe 境界
• 初期 IR 設計: 初期 IR、型境界、invariant
• Rosetta Oracle 検証ワークフロー: expected/actual 比較の流れ
• 進行履歴: タイムスタンプ付きの現在地、進行中作業、完了履歴
• Public ABI / import boundary: public ABI、imports、host helpers、syscall 相当境界の clean-room 設計
• Runtime architecture roadmap: B8-HWGUI 後の runtime、translation artifact、OS personality、Wine 接続の設計方向
• 将来構想メモ: 本流 TODO から外した未確立な派生研究の置き場

現在の実装順

実装順は TODO.md の 線形実装ロードマップ に一本化しています。 README には独立したマイルストーン一覧を置きません。

現在の本流は、B8-HWGUI Self-Authored Hello World GUI Completion 後の runtime architecture 整理に移っています。B8-ARCH 系で responsibility split、 guest image model、translation artifact / debug export、runtime dispatcher、 helper / ABI bridge、OS personality boundary を整えたうえで、B8-OSS0 の source-built OSS GUI app automation や B8-WINE0 の Wine bridge planning へ進みます。

初期成功ケースは以下でした。

x86_64 bytes:
  b8 2a 00 00 00 c3

meaning:
  mov eax, 42
  ret

result:
  return_value == 42

この raw function 成功ケースは完了済みロードマップとして docs/hello-world-roadmap.md に保存しています。

Rust workspace

初期 workspace は raw function translation の関心ごとに分けています。

crates/
  bara-isa-x86/   x86_64 raw bytes の decode / lift
  bara-ir/        typed IR と invariant validation
  bara-arm64/     ARM64 emit と PC map
  bara-runtime/   executable memory と generated function runner
  btbc-cli/       開発用の実行チェック入口

現在の最小テストは b8 2a 00 00 00 c3 を decode、IR 化、ARM64 machine code 化し、対応 host では no-args u64 関数として実行します。

最小 raw function smoke check だけを行う場合:

./scripts/check-m1

成功すると actual.json 相当の最小 JSON を標準出力へ出します。

開発メモ

必要なツールは Nix 経由で使い、グローバルインストールを前提にしません。

開発環境は Nix Flake で再現可能に定義します。Rust toolchain、formatter、linter、test runner、LLVM 系ツールは dev shell から使います。

nix develop

単発でコマンドを実行する場合:

nix develop -c cargo --version
nix develop -c ./scripts/verify
nix develop -c cargo fmt --all -- --check
nix develop -c ./scripts/check-no-invisible-chars
nix develop -c ./scripts/check-domain-types
nix develop -c ./scripts/verify-security
nix develop -c ./scripts/verify-supply-chain
nix develop -c ./scripts/verify-nix-package
nix develop -c cargo check --workspace --all-targets
nix develop -c cargo test --workspace
nix develop -c cargo run -p btbc-cli -- check-m1

通常のコード、script、設定、repository policy の変更では nix develop -c ./scripts/verify を完了前に通します。

依存関係、Cargo.lock、deny.toml、flake.nix を変更した場合は ./scripts/verify-supply-chain を必ず実行します。詳細は Supply Chain Policy を参照してください。 セキュリティ関連の変更では ./scripts/verify-security も実行します。

任意で pre-commit hook を入れる場合:

nix develop -c ./scripts/install-pre-commit-hook

direnv を使う場合は .envrc の use flake を有効にします。

エディタ間の基本整形は .editorconfig で揃えます。文字コード、改行、末尾改行、空白、インデントの最低限のルールは repository 側で管理し、言語固有の整形は rustfmt などに委譲します。

初期の実装では、unsafe は executable memory と function pointer 呼び出し境界に閉じ込めます。命令変換や IR 操作は、できるだけ型で仕様が読める構成にします。

エージェント操作メモ

長い指示を毎回入力しなくて済むように、エージェントには短い操作コマンドを渡せます。 詳細な運用規律は AGENTS.md にあります。

よく使うコマンド:

• /advance-large: 大マイルストーン完了まで進める。作業ブランチを切り、小ステップごとに commit / push し、大マイルストーン到達時にレビュー待ちで停止する。
• /advance-small: 次の小マイルストーンまで進める。作業ブランチ上で検証済みの小ステップを commit / push して停止する。
• /advance-pr: TODO.md の次の未完了 PR Gate まで進める。専用ブランチで検証済みステップを commit / push し、draft PR を開いて停止する。
• /continue-branch: 現在の作業ブランチで続きを進める。
• /review-gate: 追加実装せず、現在のブランチの成果物レビュー用サマリを出す。
• /merge-reviewed: レビュー済みの作業ブランチを main に取り込み、必要に応じてブランチを掃除する。
• /docs-only: ドキュメント更新のみを行う。原則 main のまま、commit / push はしない。
• /status: 現在の branch、worktree、TODO、次に進むべき候補を確認する。

VSCode の Codex 拡張で UI から選びたい場合は、repo-scoped skill として 同じ操作を .agents/skills/bara-* に置いています。チャット入力で $ を 入力し、Bara /advance-pr、Bara /advance-small、Bara /status などを 選んでください。Codex IDE には組み込みの /status もあるため、Bara 用の 状態確認は $bara-status から呼び出すのが確実です。

基本方針:

• マイルストーン進行は作業ブランチで行う。
• 作業ブランチではエージェントが commit / push まで自律的に行ってよい。
• main ではエージェントは自律的に commit / push しない。
• 大マイルストーン完了時はレビュー待ちで停止し、レビュー後に問題なければ main へ merge する。
• B8 以降のアプリ起動フェーズでは、TODO.md の PR Gate を提出地点として扱い、1 つの PR で一般アプリ対応全体を完了条件にしない。