KITAQ DEVELOPMENT SYSTEM
USER'S MANUAL 2026.09

KITAQ SERIES • REFERENCE EDITION

KUROSAKI

NES・FDSの実行と解析

初めての一行から、実行・観測・再テストまで。
ローカルソース採取：2026年9月14日

1　KUROSAKIとは

KUROSAKIはKITAQFCの情報を読み込めるNES/Famicom/FDSの観測エミュレータです。ROM調査、実行、録音、診断、スナップショット、リプレイ、逆アセンブル、デコンパイルをCLIから行えます。マッパーごとに実装の範囲が違うため、最初にROM情報と対応状態を調べます。

2　ビルドと起動

powershell
Push-Location .\kurosaki
.\scripts\build.ps1
.\kurosaki.exe --help
Pop-Location

以後の短い kurosaki コマンド例は、EXEのあるフォルダーをPATHへ設定した場合の書式です。設定していない場合は & "EXEのフルパス" に置き換えます。

powershell
kurosaki inspect-rom .\out\hello.nes --json .\out\rom.json
kurosaki run .\out\hello.nes --frames 120 --png .\out\hello.png --json .\out\run.json

第4巻のhelloを使えば文字表示まで確かめられます。inspect-rom はヘッダーを調べる操作、run はCPU/PPUを進める操作です。前者が成功しても後者の動作保証にはなりません。

3　マッパー・基板の確認

画面RAMの割り当て

AxROMの下側・上側1画面、FME7の縦・横・下側・上側1画面、MMC5のCIRAMだけを使う16通りの配置をPPUの読み書きと描画へ反映します。MMC5のExRAMと塗りつぶし描画には対応していません。対応範囲の確認には、KITAQFCのマッパー別サンプルを参照してください。

設定値と実行サンプル

mapper-list は登録済みの種類、mapper-info は特定種類の情報、audit-board は基板条件の検査です。マッパー番号はROMヘッダーと実配線の前提をつなぎます。名前だけから容量・CHR-RAM・固定バンクの条件を決めつけません。

powershell
kurosaki mapper-list
kurosaki mapper-info 4
kurosaki audit-board .\out\surom.nes --expected-board surom512 --json .\out\board.json

--allow-unimplemented は未実装要素を許容して観測を進める指定です。これを付けて走ったことを、対応済みの証拠にはしません。

4　パッド入力

run --pad1 / --pad2 はNESの生ボタンマスクです。A=1、B=2、SELECT=4、START=8、UP=16、DOWN=32、LEFT=64、RIGHT=128です。複数同時押しは値を足します。

powershell
kurosaki run .\out\game.nes --frames 120 --pad1 1 --png .\out\held_a.png --json .\out\held_a.json

この例は120フレームAを押し続けます。タイトル→ゲーム→決定といった時間順の操作にはリプレイを使います。replay-record のCLI例は基準となる無操作実行を記録するためのもので、人がGUIで操作する録画とは異なります。

5　スナップショットとリプレイ

powershell
kurosaki snapshot-save .\out\game.nes --frames 120 --out .\out\title.kss.json
kurosaki snapshot-load .\out\title.kss.json
kurosaki replay-record .\out\game.nes --frames 120 --out .\out\baseline.replay.json
kurosaki replay-run .\out\game.nes .\out\baseline.replay.json --json .\out\replay.json

再開できる状態はversion 2のスナップショットです。ROMのSHA-256と状態の対応を保ちます。snapshot-resumeは保存時点から続きを進める操作、snapshot-rebaseは互換な別ROMへの明示的な契約付き付け替えです。修正ROMへ古い状態を無条件に流用すると、RAMやコード配置が変わっていて危険なので、通常は起動から同じ操作を再現します。

スナップショットJSONの音声タイミングの小数値は、f64の精度を保って保存・読込します。これらの数値を丸めたり書き換えたりしないでください。保存値が変わると、同じROMと入力でも再開後の完全一致を比較できません。

6　トレース・診断・プロファイル

powershell
kurosaki trace .\out\game.nes --frames 2 --cpu --ppu --apu --mapper --nmi --dma --out .\out\trace.jsonl
kurosaki diagnose .\out\game.nes --frames 120 --out .\out\diagnostics.json --md .\out\diagnostics.md
kurosaki profile .\out\game.nes --frames 120 --out .\out\profile.json

トレースは何が起きたかの時系列、診断はルールに当たった観測、プロファイルはどこに処理が集中したかです。最初から長時間のfull traceを作るより、異常の直前直後を数フレームに絞ると読みやすくなります。

--kitaqfc-debug に同じビルドのデバッグJSONを渡します。ソース行までの情報がない観測を、自動で完全なソース行トレースだとは解釈しません。

7　音と画像の保存

powershell
kurosaki audio-export .\out\sound.nes --frames 180 --wav .\out\sound.wav --json .\out\audio.json
kurosaki run .\out\game.nes --frames 120 --png .\out\frame.png --snapshot .\out\frame.kss.json --json .\out\frame.json

音源レジスターが変わったこと、PCMが生成されたこと、意図した音に聞こえることは別の検証です。内蔵音源と拡張音源は、対象マッパーも記録します。静止PNGだけでは移動や入力の正常性はわからないので、前後の状態・入力も残します。

8　逆アセンブルとデコンパイル

powershell
kurosaki disasm .\out\game.nes --bytes 256 --text .\out\reset.txt
kurosaki decompile .\out\game.nes --format markdown --out .\out\decompile.md

disasmは命令列、decompileは関数境界候補・CFG・参照・疑似コードを出します。切り替え可能なバンクでは、CPUアドレスだけで元のROM位置が決まりません。必要なら --snapshot でマッパー状態を与え、実行トレースや注釈を補助情報として使います。元ソースの完全復元ではありません。

Reset・Nmi・Irqは、取得時のマッパー状態で読める各ベクターから識別します。それ以外のスナップショットの現在PCは、自動名sub_B...を持つcurrent_pc候補です。Resetの発生や関数境界の確定を意味しません。

9　SARAKURAへつなぐ

powershell
kurosaki run .\out\game.nes --frames 300 --emit-diagnostics .\out\kurosaki_events.jsonl --json .\out\run.json
sarakura fc analyze --metadata .\out\build.json --events .\out\kurosaki_events.jsonl --out .\out\fc_report --fail-on error

KUROSAKIの --emit-diagnostics は JSONLファイル を指定します。KOKURAと同様にファイル名を指定します。CPU traceファイルと診断イベントファイルを取り違えないでください。

10　公開範囲

KUROSAKI-GUIは未公開です。本書では公開済みのCLIと連携APIを扱います。

11　FDS・保存データ

fds-inspect はディスクの構造、export-assets は素材の抽出窓口です。FDSは起動方式・BIOS・ディスクアクセスの条件も関わるため、NESカートリッジの試験と分けます。バッテリー保存 .sav とスナップショット .kss.json は用途が違います。実装に対応した保存レイアウトを確認して使います。

powershell
kurosaki battery-export .\out\game.nes .\out\title.kss.json --out .\out\save.sav
kurosaki battery-run .\out\game.nes --sav .\out\save.sav --frames 120 --save-out .\out\next.sav --png .\out\battery.png

battery-exportは一致するROMとスナップショットから生の保存RAMを抽出します。battery-runはそのRAMを読み込んで電源投入から起動します。CPUやPPUの途中状態は復元しません。出力先は --save-out で明示します。保存RAMを持つ対応ROM用で、すべてのサンプルROMに使えるわけではありません。

コマンド書式辞典

下記のヘルプは本版で実行して採取しました。省略可能な引数、既定値、列挙値は採取結果に従ってください。説明用コマンドの入力ファイルは自分の出力名に合わせます。

kurosaki
help
KITAQFC-aware clean-room NES observation emulator CLI

Usage: kurosaki.exe <COMMAND>

Commands:
  battery-export   Export raw battery RAM from a matching snapshot (not a snapshot file)
  battery-run      Cold boot with an explicit battery file; no implicit save-file writes
  inspect-rom      
  audit-board      
  run              
  trace            
  audio-export     
  profile          
  diagnose         
  replay-record    
  replay-run       
  snapshot-save    
  snapshot-load    
  snapshot-rebase  Rebind a reviewed v2 snapshot to an explicitly allowlisted compatible ROM
  snapshot-resume  
  diff             
  decompile        Recover bounded function CFGs and readable pseudocode from a mapper context
  disasm           
  mapper-test      
  fds-inspect      
  export-assets    
  report           
  mapper-list      
  mapper-info      
  help             Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version
kurosaki battery-export — 状態から生のバッテリーRAMを取り出す
powershell
kurosaki battery-export out/game.nes out/state.kss.json --out out/save.sav
help
Export raw battery RAM from a matching snapshot (not a snapshot file)

Usage: kurosaki.exe battery-export --out <OUT> <ROM> <SNAPSHOT>

Arguments:
  <ROM>       
  <SNAPSHOT>  

Options:
      --out <OUT>  
  -h, --help       Print help
kurosaki battery-run — 保存RAMだけを読み込んで電源投入から実行する
powershell
kurosaki battery-run out/game.nes --sav out/save.sav --frames 120 --png out/loaded.png --save-out out/next.sav
help
Cold boot with an explicit battery file; no implicit save-file writes

Usage: kurosaki.exe battery-run [OPTIONS] --sav <SAV> <ROM>

Arguments:
  <ROM>  

Options:
      --sav <SAV>            
      --frames <FRAMES>      [default: 600]
      --replay <REPLAY>      
      --json <JSON>          
      --snapshot <SNAPSHOT>  
      --png <PNG>            
      --save-out <SAVE_OUT>  
  -h, --help                 Print help
kurosaki inspect-rom — ROMヘッダーを調べる
powershell
kurosaki inspect-rom out/game.nes --json out/rom.json
help
Usage: kurosaki.exe inspect-rom [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --json <JSON>  
      --md <MD>      
  -h, --help         Print help
kurosaki audit-board — 基板条件を検査する
powershell
kurosaki audit-board out/game.nes --expected-board surom512 --json out/board.json
help
Usage: kurosaki.exe audit-board [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --expected-board <EXPECTED_BOARD>  [default: surom512]
      --metadata <METADATA>              
      --json <JSON>                      
  -h, --help                             Print help
kurosaki run — 指定フレーム実行する
powershell
kurosaki run out/game.nes --frames 120 --png out/game.png --json out/run.json
help
Usage: kurosaki.exe run [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>                                  [default: 1]
      --max-instructions <MAX_INSTRUCTIONS>              
      --headless                                         
      --state-hash <STATE_HASH>                          
      --json <JSON>                                      
      --md <MD>                                          
      --png <PNG>                                        
      --snapshot <SNAPSHOT>                              
      --observe-json <OBSERVE_JSON>                      
      --trace-jsonl <TRACE_JSONL>                        
      --emit-diagnostics <EMIT_DIAGNOSTICS>              
      --repro-bundle <REPRO_BUNDLE>                      
      --break-on-diagnostic <BREAK_ON_DIAGNOSTIC>        
      --png-on-diagnostic <PNG_ON_DIAGNOSTIC>            
      --snapshot-on-diagnostic <SNAPSHOT_ON_DIAGNOSTIC>  
      --kitaqfc-debug <KITAQFC_DEBUG>                    
      --allow-unimplemented                              
      --pad1 <PAD1>                                      [default: 0]
      --pad2 <PAD2>                                      [default: 0]
  -h, --help                                             Print help
kurosaki trace — イベントを時系列に記録する
powershell
kurosaki trace out/game.nes --frames 2 --cpu --ppu --out out/trace.jsonl
help
Usage: kurosaki.exe trace [OPTIONS] --out <OUT> <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>                [default: 1]
      --out <OUT>                      
      --cpu                            
      --mem-read                       
      --mem-write                      
      --ppu                            
      --apu                            
      --mapper                         
      --nmi                            
      --dma                            
      --full                           
      --kitaqfc-debug <KITAQFC_DEBUG>  
      --allow-unimplemented            
      --pad1 <PAD1>                    [default: 0]
      --pad2 <PAD2>                    [default: 0]
  -h, --help                           Print help
kurosaki audio-export — PCM音声をWAVへ書く
powershell
kurosaki audio-export out/game.nes --frames 120 --wav out/audio.wav
help
Usage: kurosaki.exe audio-export [OPTIONS] --wav <WAV> <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>      [default: 60]
      --wav <WAV>            
      --json <JSON>          
      --allow-unimplemented  
      --trace-audio          
      --pad1 <PAD1>          [default: 0]
      --pad2 <PAD2>          [default: 0]
  -h, --help                 Print help
kurosaki profile — 処理の集中場所を集計する
powershell
kurosaki profile out/game.nes --frames 120 --out out/profile.json
help
Usage: kurosaki.exe profile [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>                [default: 60]
      --out <OUT>                      
      --md <MD>                        
      --kitaqfc-debug <KITAQFC_DEBUG>  
      --allow-unimplemented            
  -h, --help                           Print help
kurosaki diagnose — 静的／動的な診断を出す
powershell
kurosaki diagnose out/game.nes --frames 120 --out out/diagnostics.json
help
Usage: kurosaki.exe diagnose [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>
          [default: 0]
      --out <OUT>
          
      --md <MD>
          
      --emit-diagnostics <EMIT_DIAGNOSTICS>
          
      --check <CHECK>
          [possible values: ppu, nmi, mapper, apu, abi, input, fds, asset]
      --kitaqfc-debug <KITAQFC_DEBUG>
          
      --allow-unimplemented
          
      --pad1 <PAD1>
          [default: 0]
      --pad2 <PAD2>
          [default: 0]
  -h, --help
          Print help
kurosaki replay-record — 再生用の基準実行を記録する
powershell
kurosaki replay-record out/game.nes --frames 120 --out out/replay.json
help
Usage: kurosaki.exe replay-record [OPTIONS] --out <OUT> <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>      [default: 60]
      --out <OUT>            
      --allow-unimplemented  
  -h, --help                 Print help
kurosaki replay-run — 保存した操作列を再実行する
powershell
kurosaki replay-run out/game.nes out/replay.json --json out/replay-result.json
help
Usage: kurosaki.exe replay-run [OPTIONS] <ROM> <REPLAY>

Arguments:
  <ROM>     
  <REPLAY>  

Options:
      --load-snapshot <LOAD_SNAPSHOT>
          Restore this version-2 snapshot before applying the replay timeline. With this option, --frames and trace bounds are absolute emulator frames
      --frames <FRAMES>
          
      --verify
          
      --json <JSON>
          
      --png <PNG>
          
      --snapshot <SNAPSHOT>
          
      --observe-json <OBSERVE_JSON>
          
      --wav <WAV>
          
      --trace-jsonl <TRACE_JSONL>
          
      --trace-start-frame <TRACE_START_FRAME>
          
      --trace-end-frame-exclusive <TRACE_END_FRAME_EXCLUSIVE>
          
      --cpu
          
      --mem-read
          
      --mem-write
          
      --ppu
          
      --apu
          
      --mapper
          
      --nmi
          
      --dma
          
      --full
          
      --allow-unimplemented
          
  -h, --help
          Print help
kurosaki snapshot-save — 状態を保存する
powershell
kurosaki snapshot-save out/game.nes --frames 120 --out out/state.kss.json
help
Usage: kurosaki.exe snapshot-save [OPTIONS] --out <OUT> <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>      [default: 1]
      --out <OUT>            
      --allow-unimplemented  
      --pad1 <PAD1>          [default: 0]
      --pad2 <PAD2>          [default: 0]
  -h, --help                 Print help
kurosaki snapshot-load — 状態ファイルをロードする
powershell
kurosaki snapshot-load out/state.kss.json --json out/state-summary.json
help
Usage: kurosaki.exe snapshot-load [OPTIONS] <SNAPSHOT>

Arguments:
  <SNAPSHOT>  

Options:
      --json <JSON>  
  -h, --help         Print help
kurosaki snapshot-rebase — 契約で許可した別ROMへ状態を付け替える
powershell
kurosaki snapshot-rebase out/before.nes out/after.nes out/state.kss.json --contract out/compatibility.json --out out/rebased.kss.json
help
Rebind a reviewed v2 snapshot to an explicitly allowlisted compatible ROM

Usage: kurosaki.exe snapshot-rebase [OPTIONS] --contract <CONTRACT> --out <OUT> <SOURCE_ROM> <TARGET_ROM> <SNAPSHOT>

Arguments:
  <SOURCE_ROM>  
  <TARGET_ROM>  
  <SNAPSHOT>    

Options:
      --contract <CONTRACT>               
      --prg-ram-patch <ADDRESS=FILE>      
      --cpu-ram-patch <ADDRESS=HEXBYTES>  
      --out <OUT>                         
      --json <JSON>                       
  -h, --help                              Print help
kurosaki snapshot-resume — 状態の続きから実行する
powershell
kurosaki snapshot-resume out/game.nes out/state.kss.json --frames 60 --json out/resumed.json
help
Usage: kurosaki.exe snapshot-resume [OPTIONS] <ROM> <SNAPSHOT>

Arguments:
  <ROM>       
  <SNAPSHOT>  

Options:
      --reset-at-start               Reset the CPU after restoring the snapshot while retaining mapper RAM
      --frames <FRAMES>              [default: 1]
      --out <OUT>                    
      --json <JSON>                  
      --png <PNG>                    
      --observe-json <OBSERVE_JSON>  
      --trace-jsonl <TRACE_JSONL>    
      --cpu                          
      --mem-read                     
      --mem-write                    
      --ppu                          
      --apu                          
      --mapper                       
      --nmi                          
      --dma                          
      --full                         
      --allow-unimplemented          
      --pad1 <PAD1>                  [default: 0]
      --pad2 <PAD2>                  [default: 0]
  -h, --help                         Print help
kurosaki diff — 保存結果の違いを調べる
powershell
kurosaki diff --before out/before.kss.json --after out/after.kss.json --json out/diff.json
help
Usage: kurosaki.exe diff [OPTIONS] --before <BEFORE> --after <AFTER>

Options:
      --before <BEFORE>  
      --after <AFTER>    
      --json <JSON>      
      --md <MD>          
  -h, --help             Print help
kurosaki decompile — 関数・CFG・疑似コードを回復する
powershell
kurosaki decompile out/game.nes --format markdown --out out/decompile.md
help
Recover bounded function CFGs and readable pseudocode from a mapper context

Usage: kurosaki.exe decompile [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --out <OUT>
          Write the rendered report here; stdout is used when omitted
      --format <FORMAT>
          [default: json] [possible values: json, markdown, text]
      --function <FUNCTIONS>
          Function name or Bnnn:$AAAA physical PRG-bank selector. Repeatable
      --all
          Also start a bounded candidate analysis at $8000 in every physical 8 KiB PRG bank
      --annotations <ANNOTATIONS>
          JSON annotation sidecar. ROM.decompile.json is loaded automatically when present
      --snapshot <SNAPSHOT>
          Restore a version-2 snapshot before capturing the PRG-bank windows
      --trace-jsonl <TRACE_JSONL>
          KUROSAKI trace JSONL to overlay exact physical-bank/PC hit counts
      --max-instructions <MAX_INSTRUCTIONS>
          Per-function static-analysis cap, preventing data from causing unbounded output [default: 2048]
  -h, --help
          Print help
kurosaki disasm — CPU命令を表示する
powershell
kurosaki disasm out/game.nes --bytes 256 --text out/disasm.txt
help
Usage: kurosaki.exe disasm [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --bytes <BYTES>              [default: 256]
      --start <START>              CPU address in decimal or with a 0x/$ hexadecimal prefix
      --snapshot <SNAPSHOT>        Restore a version 2 snapshot before reading mapped CPU bytes
      --prg-bank-8k <PRG_BANK_8K>  Read one exact physical 8 KiB PRG-ROM bank, independent of mapper state
      --json <JSON>                
      --text <TEXT>                
  -h, --help                       Print help
kurosaki mapper-test — マッパー用の観測試験を行う
powershell
kurosaki mapper-test out/game.nes --json out/mapper-test.json
help
Usage: kurosaki.exe mapper-test [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --json <JSON>  
  -h, --help         Print help
kurosaki fds-inspect — ディスク構造を読む
powershell
kurosaki fds-inspect out/game.fds
help
Usage: kurosaki.exe fds-inspect [OPTIONS] <DISK>

Arguments:
  <DISK>  

Options:
      --json <JSON>  
  -h, --help         Print help
kurosaki export-assets — ROM内の素材を書き出す
powershell
kurosaki export-assets out/game.nes --out out/assets
help
Usage: kurosaki.exe export-assets --out <OUT> <ROM>

Arguments:
  <ROM>  

Options:
      --out <OUT>  
  -h, --help       Print help
kurosaki report — 保存情報から報告を作る
powershell
kurosaki report out/run.json --md out/report.md
help
Usage: kurosaki.exe report --md <MD> <INPUT>

Arguments:
  <INPUT>  

Options:
      --md <MD>  
  -h, --help     Print help
kurosaki mapper-list — 登録済みマッパーを一覧にする
powershell
kurosaki mapper-list
help
Usage: kurosaki.exe mapper-list [OPTIONS]

Options:
      --all          
      --json <JSON>  
      --md <MD>      
  -h, --help         Print help
kurosaki mapper-info — 指定マッパーの情報を読む
powershell
kurosaki mapper-info 4
help
Usage: kurosaki.exe mapper-info [OPTIONS] <MAPPER>

Arguments:
  <MAPPER>  

Options:
      --json <JSON>  
  -h, --help         Print help