This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Lython は LLVM/MLIR 23 ベースの Python コンパイラツールチェーン。Python ソースを独自の py dialect (MLIR) に変換し、LLVM IR まで下げて JIT 実行または AOT コンパイルする。C++17 / CMake + Ninja。LLVM/MLIR はメジャーバージョン 23 に固定されており、CMake が version mismatch を FATAL_ERROR で拒否する。
プロジェクトの性格: Python を静的型付けコンパイル言語として再実装するプロジェクトである。基本的に静的に解決できるコードのみを受け入れ、object / Any に対するランタイム操作は実装しない (動的ディスパッチへのフォールバックは存在せず、静的に解決できない構造は最も早い静的境界で診断を出して拒否する — "never silently mis-execute")。
安全性設計: メモリ安全証明を根冠とする。根拠は (1) Hindley-Milner 準拠の型推論 — Algorithm J 基盤 (union-find + occurs check、emitter/lib/TypeInference.h) と Algorithm M 的な期待型伝播の複合で、manifest 駆動 subtype/protocol は subsumption レイヤとして共存する。facade は TypeSystem (emitter/lib/TypeSystem.h)、詳細は docs/type-inference.md。(2) 量的型理論 (QTT) に基づく参照カウントの挿入・最適化 — Own(rho) を affine capability として扱い、quantitative ownership verifier が挿入・elision・検証を通して同一の alias 関係を共有する。証明カーネルの定義は rfc/memory-safety-proof.md (実装の詳細はこの judgment を具体化する場合にのみ有効)。
uv sync # Python 依存 (pyright のみ)
cmake -B build -S . # LLVM/MLIR 23 を Homebrew / apt パスから自動検出
cmake --build build -j$(nproc)
# JIT 実行
./build/bin/lyc jit examples/hello.py
# AOT コンパイル
./build/bin/lyc examples/fib.py -o fib_aot
# AST ダンプ (parse サブコマンド)
./build/bin/lyc parse examples/hello.py
# 型チェック (src/lyrt のスタブに対して strict モード)
uv run pyright
# Nix (nixpkgs の llvmPackages_23 を使う。LLVM はビルドしない)
nix develop # cmake / LLVM / MLIR / clang / lld が揃ったシェル
nix build .#lython # lyc (AOT 用の clang と lld を PATH に持つ wrapper)
nix flake check # ctest -LE bench をサンドボックスでNix ビルドは nixpkgs の LLVM 23 に対して行う。Linux の libMLIR は GCC ビルドなのでパターンのデバッグ名が clang と違い ({anonymous}:: / (anonymous namespace)::)、macOS は nixpkgs の ld64 でリンクする。どちらも Homebrew / apt では見えない差で、.github/workflows/nix.yml が 3 システムで検査する。
主な lyc フラグ: --emit-llvm (LLVM IR で停止)、--release (verifier パス無効化)、-O2 / -Os / -Oz (AOT 実行ファイルの最適化目標。既定 -O2。-Os / -Oz は全関数に optsize / minsize を付ける: examples/genexpr.py の wasm は 137 KB → 84 KB になるが、dict と str 中心の処理は 1.3〜2 倍遅くなる。JIT では拒否される。AOT は C の入口と JS ホスト向け export 以外をすべて internal にしてから最適化する)、--target / -mcpu / -mfpu (クロスコンパイル)、--fsanitize=...、--audit-runtime-manifest、-jit-codegen-opt=none|less|default|aggressive (JIT の命令選択品質) と -jit-opt=0..3 (JIT の LLVM IR 最適化レベル。AOT は常に O2)。どちらも既定は初回出力レイテンシ優先の最低値。実測の分岐点: -jit-codegen-opt=less は jit-build を約 180 ms 増やして実行を約半分にするので、実行が 360 ms を超えるプログラムから得になる (examples/tarai.py は合計 1.60 s → 1.11 s、examples/hello.py は 0.18 s → 0.35 s)、-mmatrix=auto|sme|amx|none (行列エンジン選択。auto は公開 ISA の SME 優先、amx は Apple AMX を runtime probe 付きで強制)、--target wasm32-wasip1 (-o prog.wasm は wasmtime でそのまま動く WASI モジュール。リンクは lyc がリンクしている LLVM の clang と wasm-ld で行う。wasi-libc と wasm32 の compiler-rt は Homebrew の wasi-libc / wasi-runtimes か wasi-sdk から探す: --sysroot、WASI_SDK_PATH、LLVM の prefix、Homebrew の share、/opt/wasi-sdk、~/.local/wasi-sdk*)、--js-host (WASI のプログラムを JS ホストの下で動かす。-o prog.js がローダで、prog.wasm が隣に出る。docs/js-host.md)。
ctest スイート (LYTHON_BUILD_TESTS, デフォルト ON)。CI (.github/workflows/ci.yml) も ctest を実行する:
ctest --test-dir build -j8 --output-on-failure # 全件 (768 件、74 s / RelWithDebInfo, -j14)
ctest --test-dir build -L fast # lowering を通らない層 (100 件、1.0 s)
ctest --test-dir build -L emit # emitter を触ったとき
ctest --test-dir build -LE bench # 実行律速のベンチを除く
ctest --test-dir build -N -L fast # 何が選ばれるか (実行しない)ラベルは「テストが到達するパイプライン段」で切ってある。ファイル名やディレクトリでは切らない。
tests/unit/ には 0.05 s の emit テストと 17 s の matmul フルコンパイルが同居し、golden.errors 109 件は emit で 0.09 s、lowering 中 0.20 s、実行が必要な 60 件に分かれる。「unit = 安い」「golden = 高い」はどちらも成り立たない (rfc/test-suite-debt.md)。
- 段ラベル (1 テスト 1 つ):
parse/emit/tables/meta/lower/e2e - コストラベル:
fast(lowering を通らない) /slow(単体 20 s 超・コンパイル律速) /bench(単体 20 s 超・実行律速) - スイートラベル:
unit/golden/golden-cases/golden-errors/examples/python
slow と bench を分けてあるのは、前者は lowering の改善で縮み後者は縮まないから (examples.tarai は 96.9% が実行なので lowering 改善の上限は 3%)。混ぜると修正が効いたかが見えなくなる。ラベルの妥当性は機械が検査する: unit 側は LayerManifestTest がどの層にも属さないテストと何も掴まないパターンを名前付きで落とし、golden 側は tests/golden/layers.txt の宣言を run_case.py --expect-layer がコンパイラ自身の PerfScope 痕跡と照合する。
- ユニットテスト (
tests/unit/, GoogleTest) — C++ API を直接叩く。ドライバ API (src/lython/driver/include/Driver.h) は lyc・テスト・fuzzer が共有するコンパイル入口。 - golden テスト (
tests/golden/) —cases/*.pyは stdout 完全一致、errors/*.pyは exit code + stderr 正規表現。実行前に止まるケースはlayers.txtに段を宣言する。 - unittest のテスト (
tests/python/test_*.py) — CPython のLib/testと同じくunittestで書いたモジュール。python.<name>がlyc jitで走らせ、unittest.main()の終了コードで判定する。同じファイルを CPython 3.14 でも走らせる (python.<name>.cpython、meta fast) ので、期待値は CPython が実際に出すものになる。test_で始まらない.pyは補助モジュールで、テストクラスを置くならimport x as yで取り込む (from x import Cはunittest.main()がそのクラスも集める)。 - バッチ golden (
golden.batch.NNN,-L golden-batch) — 1 件 0.7 s の大半はコンパイルと JIT build の固定費なので、batch_cases.pyがまとめられるcases/(約 575 件) を 6 件ずつ 1 プログラムに連結して払う。各ケースは module レベルのまま、module で束縛する名前だけ_c<i>_にリネームする (ソースのトークン位置で書き換え、綴りは保つ)。まとめられないケース (名前が出力に出る / 文脈を観測する / 隣のモジュールを import する / stderr や exit code を見る) は従来どおり単独で登録される。理由はbatch_cases.py --why tests/golden/cases/*.py。バッチ内で落ちたケースは単独で再実行され、単独で通るのにバッチで答えが変わったら BATCH-DISAGREE で赤(ケース間の干渉は欠陥として扱う。round(-15, -1)が共有の小さい int を書き換えた欠陥はこれで見つかった)。意図的に文脈依存なケースは理由付きでbatch-exclusions.txtに書く。1 件を名前で再実行するには FAILED 行のコマンドか-DLYTHON_GOLDEN_BATCH=OFF。6 件より大きくしないのは、連結した module 本体が 1 関数になり ownership 系フェーズが超線形に伸びるため (25 件で 1 件あたり 0.99 s)。 - examples smoke — golden とバイト同一でないものだけ exit code 検証。同一な 20 件は golden がより強い assertion を持つので登録しない (
golden.example_twinsが同一性を守る)。
上から順に、最初に該当した層に置く。下の層で落とせるものを golden に書かない。 同じプログラムで emit のみ 0.05 s、フルコンパイル 1.7 s。
- parse だけで決まるか →
ParserTests.cpp。 - emitter の診断か (名前解決 / 型解決 / 未対応構文の拒否) →
emitMLIRFromSourceで診断文字列を assert (EmitterTests.cpp)。golden を書かない。 - verifier / lowering の拒否か →
compilePythonSourceToLLVMIRの失敗を assert (DriverTests.cpp)。jit-build と実行を払わない。 - stdout / traceback / 実行時の値が必要か → そのときだけ golden。「なぜ実行が必要か」を 1 行書く。書けないなら 3 で足りる。
- 実行前に止まる golden は
layers.txtに段を宣言する。ctest -L fastに入り、段がずれたら赤になる。 - unit テストを足したら層に登録する。 どの層にも入っていないテストはどこでも走らない。
LayerManifestTestが落として教えるが、落ちてから直すより先に書くほうが安い。
PR に書くこと:
- この経路を覆う既存のテストは何か。無いことをどう確かめたか。 名前や見た目の類似は根拠にしない — 83,028 ペアで同一は 20 組、SUBSET は 1 組だけだった。「似ているから重複」は 3 回外れている。
- その golden が赤になれる根拠。 修正と同時に書く golden は修正前のバイナリで赤になることを確認する (
tests/probe/tools/redcheck.py --sentinel)。していないならそう書く。 - 20 s を超えるテストを足したら
LYTHON_PERF=1のフェーズ内訳を貼る。 それはテスト設計ではなくコンパイラの欠陥の報告である可能性が高い。そしてLYTHON_SLOW_TESTS/LYTHON_BENCH_TESTSのどちらかを測って決める (ビルド種別を跨いで比較しない)。
やらないこと:
examples/に golden の twin を置かない。 サンプルはexamples/にだけ置く。.stderr-reに^アンカーを増やさない。 stderr に書くデバッグ機能で静かに壊れる (現存 11 件)。- cwd にファイルを書く golden を増やさない。 同名を足した瞬間に
-j8で非決定的になる。 - 新しい重量フェーズを sub-
PerfScopeなしで追加しない。 計装の穴はコストの穴と同じ場所に開く。
slow / bench の所属は手動であり、上の PR チェックリストだけが強制する — スイートは新たに遅くなったテストを自力では検出できない。
fuzz/ に 3 つの harness: fuzz_parser (parse のみ)、fuzz_emitter (parse→emit)、fuzz_pipeline (フルパイプライン、JIT 実行なし)。ツリー全体を ASan + カバレッジ計装するため専用ビルドディレクトリが必要 (macOS は Homebrew LLVM clang 必須、AppleClang 不可):
cmake -B build-fuzz -S . -G Ninja \
-DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" \
-DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" \
-DLYTHON_ENABLE_FUZZERS=ON -DLYTHON_BUILD_TESTS=OFF -DCMAKE_BUILD_TYPE=RelWithDebInfo
ASAN_OPTIONS=detect_leaks=0:detect_container_overflow=0:allow_user_poisoning=0 cmake --build build-fuzz -j$(nproc)
ASAN_OPTIONS=detect_leaks=0:detect_container_overflow=0:allow_user_poisoning=0 \
./build-fuzz/bin/fuzz_pipeline -max_total_time=300 -timeout=10 -rss_limit_mb=4096 \
-dict=fuzz/dictionaries/python.dict fuzz/corpora/fuzz_pipeline tests/golden/casesctest --test-dir build-fuzz はチェックイン済みコーパス + golden cases の無変異リプレイ (regression)。テストは harness ごとに corpus (チェックイン済みコーパス、crash regression) と goldens.1..4 (golden の .py を 4 分割) に分かれる — 1 プロセスで全部 replay すると ASan 下で 13 分 (CI ではその 2.5 倍) かかり、golden が増えるほど伸びるため。-j で並列に走らせること。発見した crash 入力は診断化して修正後、該当 fuzz/corpora/<harness>/ に追加する。
LYTHON_IR_DUMP=allまたはフェーズ名のカンマ区切り (例:frontend,runtime-lowering) — 各 lowering フェーズ後の MLIR / LLVM IR を stderr にダンプLYTHON_DUMP_ON_FAILURE=1— lowering フェーズが失敗したとき、そのフェーズ終了時点のモジュールを stderr にダンプする (LYTHON_IR_DUMPは成功したフェーズの後にしか出力しないので、壊れた IR を作ったフェーズ自身の出力はこれでしか見えない)LYTHON_DUMP_LOCS=1—LYTHON_DUMP_ON_FAILUREのダンプに各 op の source location を付ける (location しか持たない診断が、どの op を指しているかを探すため)LYTHON_PERF=1— フェーズごとの wall time を出力LYTHON_PASS_TIMING=1— lowering の各フェーズの中を、パスごとの時間 (MLIR の pass timing) に分けて出す。LYTHON_PERFの 1 フェーズ 1 行では分からない内訳LYTHON_COMPILE_THREADS=N— 1 回のコンパイルが使うスレッド数。関数単位のパス、所有権検証、JIT のコード生成がこれを使う。既定はハードウェアスレッド数と 4 の小さいほう、1 にすると全部を呼び出しスレッドで行う。4 より多くしても壁時間はほとんど縮まず、CPU だけが増える (ctest のように 1 コアに 1 コンパイルを割り当てる使い方では、その増分がそのまま効く)。出力はスレッド数によらない (IR 同一を全コーパスで確認済み)LYTHON_JIT_PARTITIONS=N— JIT のモジュールを N 個のオブジェクトに分けて並列にコード生成する。既定は命令数とスレッド数から決まり、1 なら従来どおり 1 モジュールのままLYTHON_ABLATE_PARALLEL_OWNERSHIP_VERIFIER=1/LYTHON_ABLATE_PARALLEL_UNWIND_CLEANUP=1— 所有権検証 / refcount 挿入の例外辺クリーンアップを、関数ごとの並列でなく逐次で回す。同じバイナリで両者を比べるためのスイッチLYTHON_TRACE_METHOD_CALLS=1— 大きなメソッドを呼び出し点に複製せず、記号として呼んだ呼び出しを stderr に出す。メソッド自身の本体を呼んだもの (exact: 受け手が構築された値か、サブクラスのないクラス) と、受け手のクラスが分からない呼び出しのためにselfを exact とみなさない本体を出したもの (open) を区別する。LYTHON_CALLED_METHOD_NODES=Nは、呼び出しに切り替えるメソッドの大きさ (AST ノード数、既定 100) を変える。0 にすると、呼べるメソッドはすべて呼ぶ。コーパス全体で呼び出しの経路を試すときに使う。LYTHON_ABLATE_METHOD_CALLS=1で、従来どおりすべて複製するLYTHON_ABLATE_PRECOMPILED_RUNTIME=1— ビルド時にホスト向けに事前コンパイルして lyc に埋め込んだネイティブランタイム (LythonNativeRuntimeBitcode) を使わず、コンパイルのたびに下げる。両者が同じモジュールであることをlyc.precompiled_runtime_is_the_lowered_runtimeが検査するLYTHON_TRACE_REPR_CLOSURE=1— 箱詰めの値のフック (repr / str / eq / hash / lt / release) の分岐を絞る根拠 (プログラムが持ち得るクラスの閉包) を stderr に出す。開いた (全分岐を残した) ときはその型と op の位置を出す。LYTHON_ABLATE_REPR_CLOSURE=1で常に全分岐を残す (release は例外の系統を常に残す)LYTHON_VERIFY_OWNERSHIP_BEFORE_CLEANUP=1— 所有権の経路検査を post-cleanup の後だけでなく、挿入直後 (pre-cleanup) にも走らせる。挿入の欠陥か cleanup の欠陥かを分けるため。既定では pre-cleanup は契約だけを検査するLYTHON_TRACE_OWNERSHIP_JOINS=1— 所有権の経路検査で、資源ごとに、同じブロックの入口へ何通りの状態で着いたかとその差 (token / retained / parked / borrowed / slot / group) を stderr に出す。合流点で状態を 1 つにまとめる検査に替えたとき新たに拒否される箇所の見積もり。LYTHON_COMPILE_THREADS=1と使うLYTHON_OWNERSHIP_MUTATE=drop:N|dup:N|dropretain:N— refcount 挿入の後で、プログラムの関数の N 番目の release を消す / 二重にする / retain を消す。所有権検証器が何を捕まえるかを測るため (候補数を stderr と remark に出す)。DriverTest.EveryDroppedOrDoubledReleaseIsRefusedがこれで検証器の検出力を守るLYTHON_ABLATE_OWNERSHIP_HANDOFF=1/LYTHON_ABLATE_RETAIN_MINTED_RESOURCES=1— 所有権検証器で、合流引数への引き継ぎをやめて元の資源の探索で名前を付け替えて追う / どの資源も覆わない値への retain を資源にしない (旧来の検証器。同じバイナリで判定を比べるため)LYTHON_ABLATE_IMPORT_SCOPE_MEMO=1/LYTHON_VERIFY_IMPORT_SCOPE_MEMO=1— 取り込んだモジュールの import の束縛を、記録して再生せず毎回読む / 毎回読んで再生と照合し、違えば abort するLYTHON_ABLATE_SYMBOL_MEMO=1/LYTHON_VERIFY_SYMBOL_MEMO=1— runtime lowering と type-objects フェーズで、モジュールのシンボル検索の答えを覚えず毎回モジュールを線形に引く / 覚えた答えを毎回引き直して照合し、違えば abort する (lowering/Common/ModuleSymbolMemo.h)LYTHON_ABLATE_BARE_POINTER_ABI=1/LYTHON_VERIFY_BARE_POINTER_ABI=1/LYTHON_TRACE_BARE_POINTER_ABI=1— memref の受け渡し (静的形状は 1 ポインタ、rank 1 の動的形状はポインタと大きさ、Passes/Runtime/Cleanup/MemRefCallABI.cpp) を、プログラム内の private 関数どうしではやめて従来の記述子で渡す (ネイティブランタイムとの境界は事前コンパイルしたランタイムの ABI なので外れない) / すべての解放と、先頭と判定した受け渡しで、記述子の確保ポインタと整列ポインタが一致することを実行時に確かめ、違えばその箇所を出して abort する / 記述子のまま残した引数・結果を stderr に出すLYTHON_ABLATE_RETURN_PROPAGATION=1— Python の例外を戻り値 (LyEH_Propagatingのフラグと呼び出し後の分岐) ではなく、従来の invoke と unwinder で伝える。比較用 (docs/exceptions.md)LYTHON_NUM_THREADS=N— 実行時: 大きい行列積の fork-join ワーカー数 (デフォルト 4、1 で逐次)
コンパイルパイプライン: parser → C++ AST → emitter (py dialect MLIR) → lowering pipeline → LLVM dialect → LLVM IR → ORC JIT / AOT リンク。ドライバは tools/CLI.cpp (単一ファイルの lyc)。
src/lython/parser/— CPython 3.14 の PEG parser (parser.c,python.gram,Python.asdl) をベンダリングし、CPython ランタイムなしでリンクできるようパッチしたもの。生成パーサが受理した後に C++ AST builder が公開Nodeツリーを作る二段構え。改変の詳細と制約はsrc/lython/parser/CPYTHON_PATCHES.md必読。src/lython/dialects/— py dialect の TableGen 定義 (PyDialect.td) と型・プロトコル実装。生成ヘッダに依存するターゲットはPyDialectIncGenへの明示的依存が必要 (並列ビルドの race 対策)。src/lython/emitter/— AST → py dialect の emit と型システム (TypeSystem.cpp,PrimitiveTypes.cpp)。src/lython/lowering/Passes/LoweringPipeline.cpp— フェーズ順序の single source of truth。番号付きフェーズが verifier → 最適化 → runtime import → manifest strategy 適用 → runtime lowering → refcount 挿入/elision → LLVM 変換の順に走る。src/lython/runtime/— 標準モジュール群と組み込み型の実装。lib/・modules/・objects/・python/はそれぞれ CPython のLib/・Modules/・Objects/・Python/に対応する:lib/*.pyは pure-Python で記述できる標準モジュール (ディレクトリはパッケージ:lib/unittest/__init__.py、lib/unittest/case.py)、modules/*.mlirは CPython が C で実装しているようにネイティブ実装が必要な標準モジュール (contract + ネイティブ実装 + transform dialect による lowering strategy を 1 ファイルに同居させたマニフェスト)、objects/*.mlirは組み込み型 (Objects/longobject.c→objects/long.mlir、unicodeobject.c→unicode.mlir、例外階層はexceptions.mlir)、python/*.mlirは型どうしが共有するインタプリタ層の部品 (Python/errors.c→errors.mlir、pyhash.c、dtoa.c、formatter_unicode.c)。modules/builtins.mlirに残るのはPython/bltinmodule.cに当たる組み込み関数 (print、lenなど) だけ。マニフェストはすべて全プログラムに取り込まれ、ファイルをまたぐ参照は呼ぶ側の宣言で書く (定義があれば宣言は置き換えられない)。いずれも typeshed に基づく型契約 (ly.typing.*属性 /.pyi準拠の annotation) と CPython 本流に基づく実装 (well-typed で静的コンパイル可能な表面に制限した port) を持つ。CPython からの逸脱はファイル冒頭 docstring に明記する慣行 (collections.py参照)。lib/*.pyは全 def の完全注釈を規約とする — 未注釈パラメータ推論はメインモジュールの pre-pass 限定で import 経路には走らないうえ、typeshed 契約との一致検証は明示注釈が前提。lib/*.pyはさらに二種類: runtime-internal モジュール (stackguard_support.pyなど、LythonRuntimePyLoweringでターゲット triple ごとに MLIR bytecode へ事前 lowering され全プログラムにリンク、import 不可) と、stdlib モジュール (それ以外全部、ソースのままlycに埋め込まれ import 解決される)。埋め込み処理はtools/CMakeLists.txtにある。src/lython/verifier/— フェーズ間をゲートする verifier 群 (evidence / native / affine-ownership)。src/lyrt/— lyrt (Lython runtime library) の型スタブのみ (.pyi)。pyright strict の対象。
新しい変換をどこに置くかはこのドキュメントの層構造に従う:
- フェーズ間で必ず走る変換 →
LoweringPipeline.cppのフェーズ。 - py op の lowering →
RuntimeBundleLowererのlower*メソッド (lowering/Passes/Runtime/Core/Dispatch.cppの TypeSwitch でディスパッチ)。この層は意図的にDialectConversionを使わない: lowering がRuntimeBundle(Runtime/Model/Bundles.h) に蓄積される SSA 値ごとの evidence に依存するため。 - 物理型マッピング →
runtimeValueTypesForの隣 (Runtime/ABI/)。 - bundle 状態不要の stateless rewrite → py dialect の canonicalization パターン。
- モジュール固有・スケジュール的な変換 →
runtime/modules/*.mlir内の__lython_strategy_*transform named sequence (C++ に書かない)。
プロジェクトの基本原則: never silently mis-execute — 未対応の構造は最も早い静的境界で明示的な診断を出して拒否する。legality の保証は ConversionTarget ではなくフェーズ間 verifier が担う。
ctypes.CFUNCTYPE コールバック本体は allocation-free でなければならない (Ly* ランタイム呼び出し・malloc 系到達禁止)。最終 LLVM dialect IR に対して Passes/Runtime/Ctypes/CallbackThunks.cpp の verifyCallbackSignalSafety が強制する。詳細は docs/lowering-architecture.md 参照。
- コードには How を書く。
- テストコードには What を書く。
- コミットログには Why を書く。
- コードコメントには Why NOT を書く (なぜ別のやり方をしなかったか。How の説明や変更の正当化はコメントに書かない)。