KITAQ SISTEMA DE DESARROLLO
MANUAL DE USO 2026.09

SERIE KITAQ • EDICIÓN DE REFERENCIA

KUROSAKI

Ejecución y análisis de NES y FDS

Desde tu primera línea hasta la ejecución, la observación y la repetición de pruebas.
Código fuente recopilado: 14 de septiembre de 2026 · Edición inglesa: 14 de septiembre de 2026

CLI de Windows ya compilada

La raíz del repositorio incluye kurosaki.exe. Descarga el ZIP y conserva los avisos de licencia con el ejecutable. La CLI para Windows x64 no requiere Rust, Python ni .NET para ejecutarse. Los pasos de compilación son para reconstruirla desde las fuentes. El código independiente está licenciado por DAISUKE OBA bajo MIT; las dependencias conservan sus condiciones en BINARY_NOTICES.md y licenses/.

1. Para qué sirve KUROSAKI

KUROSAKI es un emulador de observación NES/Famicom/FDS que interpreta información de KITAQFC. Su CLI inspecciona ROM, ejecuta software, graba audio, diagnostica, guarda estados, reproduce entradas, desensambla y descompila funciones candidatas. Los mappers tienen distintos grados de implementación; comprueba primero la ROM y la información de soporte.

2. Compilar y empezar

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

Los comandos abreviados kurosaki suponen que la carpeta del ejecutable está en PATH. Si no, usa & "ruta completa del ejecutable".

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

Comprueba el texto con la ROM hello del volumen 4. inspect-rom analiza el encabezado; run avanza CPU y PPU. Inspeccionar correctamente no garantiza ejecutar correctamente.

3. Revisar mapper y placa

Mapeo de RAM de las tablas de nombres

Las lecturas, escrituras y el renderizado de PPU respetan la selección de pantalla única inferior/superior de AxROM, la selección vertical/horizontal/inferior/superior de FME7 y las dieciséis configuraciones de MMC5 que solo usan CIRAM. No se admite el renderizado mediante ExRAM ni por relleno de MMC5. Consulte los ejemplos de KITAQFC específicos de cada placa para conocer el comportamiento probado.

Valores de modo y ejemplos ejecutados

mapper-list enumera tipos registrados, mapper-info describe uno y audit-board comprueba restricciones de placa. El número de mapper relaciona el encabezado con supuestos de cableado físico. El nombre por sí solo no demuestra capacidad, presencia de CHR-RAM ni comportamiento de bancos fijos.

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

--allow-unimplemented deja continuar la observación tras encontrar partes no implementadas. Una ejecución con esta opción no demuestra soporte de esas partes.

4. Entrada de mandos

run --pad1 y --pad2 usan máscaras NES sin procesar: A=1, B=2, SELECT=4, START=8, UP=16, DOWN=32, LEFT=64 y RIGHT=128. Suma los valores para pulsaciones simultáneas.

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

El ejemplo mantiene A durante 120 fotogramas. Para acciones ordenadas, como título, inicio y confirmación, utiliza reproducción de entrada. El ejemplo CLI replay-record registra una ejecución de referencia sin entrada interactiva; no equivale a grabar a una persona manejando una GUI.

5. Instantáneas y reproducción

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

Los estados reanudables usan instantáneas de versión 2. Mantén la correspondencia SHA-256 con la ROM. snapshot-resume continúa desde el punto guardado. snapshot-rebase traslada explícitamente el estado a otra ROM compatible según un contrato. No reutilices sin comprobación un estado después de cambiar código o distribución de RAM; lo habitual es repetir las acciones desde el arranque.

El JSON de las instantáneas conserva toda la precisión f64 de los valores fraccionarios de temporización de audio al guardarlos y leerlos. No los redondees ni los reescribas: si cambian, una ROM y entradas idénticas no bastan para comparar con exactitud el estado tras la reanudación.

6. Trazas, diagnósticos y perfiles

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

La traza registra qué ocurrió y cuándo; los diagnósticos señalan observaciones que cumplen reglas; el perfil muestra dónde se concentró la ejecución. Unos pocos fotogramas alrededor de la anomalía suelen ser más útiles que una traza extensa.

Entrega el JSON de depuración de esa compilación con --kitaqfc-debug. Una observación sin líneas de código no debe tratarse como una traza completa a nivel de fuente.

7. Guardar sonido e imágenes

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

Cambios de registros, PCM generado y sonido correcto son comprobaciones distintas. Registra el mapper al probar audio interno o de expansión. Un PNG aislado no prueba movimiento ni entrada: conserva también controles y estados anteriores y posteriores.

8. Desensamblado y descompilación

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

disasm muestra instrucciones. decompile produce candidatos a límites de función, CFG, referencias y pseudocódigo. Con bancos conmutables, una dirección de CPU no identifica por sí sola la posición física de ROM. Aporta el estado del mapper con --snapshot cuando haga falta y contrasta con trazas o anotaciones. No es una recuperación perfecta de las fuentes originales.

Reset, Nmi e Irq se identifican mediante sus vectores en el estado del mapper capturado. Otro PC de la instantánea es un candidato current_pc, con nombre automático sub_B..., no una prueba de reinicio ni de un límite de función confirmado.

9. Conectar con 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

Como en KOKURA, --emit-diagnostics de KUROSAKI recibe una ruta de archivo JSONL. Separa trazas de CPU y eventos de diagnóstico.

10. FDS y RAM de guardado

fds-inspect examina la estructura del disco y export-assets extrae recursos. Prueba FDS por separado de los cartuchos NES: arranque, BIOS y acceso al disco tienen otros requisitos. Los .sav de batería y las instantáneas .kss.json sirven a propósitos distintos. Usa una distribución de guardado admitida por la implementación.

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 obtiene RAM de guardado sin procesar de una ROM e instantánea coincidentes. battery-run carga esa RAM y arranca desde el encendido; no restaura la ejecución suspendida de CPU o PPU. Indica la salida con --save-out. Estas operaciones requieren una ROM compatible con RAM de guardado y no se aplican a todas las lecciones.

Referencia de sintaxis de comandos

La siguiente ayuda se capturó para esta edición del código fuente. Consúltala para conocer los argumentos opcionales, los valores predeterminados y los valores admitidos. Sustituye los nombres de archivo ilustrativos por tus propios archivos. Las respuestas capturadas de las herramientas conservan su redacción original.

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 — Exportar la RAM de batería sin procesar de un estado guardado
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 — Arrancar con RAM guardada
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 — Examinar la cabecera de la 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 — Comprobar los requisitos de la placa
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 — Ejecutar un número fijo de fotogramas
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 — Registrar una traza cronológica de eventos
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 — Escribir audio PCM en un archivo 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 — Localizar puntos de ejecución frecuentes
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 — Generar diagnósticos estáticos y de ejecución
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 — Registrar una reproducción de referencia
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 — Ejecutar una secuencia de entrada registrada
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 — Guardar el estado de la máquina
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 — Examinar un archivo de estado
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 — Transferir el estado a una ROM permitida por un contrato de compatibilidad
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 — Continuar desde un estado guardado
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 — Comparar resultados guardados
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 — Reconstruir funciones, grafos de flujo de control y pseudocódigo
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 — Mostrar instrucciones de 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 — Observar el comportamiento del mapper
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 — Examinar la estructura del disco
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 — Exportar recursos de una 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 — Crear un informe a partir de observaciones guardadas
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 — Enumerar mappers registrados
powershell
kurosaki mapper-list
help
Usage: kurosaki.exe mapper-list [OPTIONS]

Options:
      --all          
      --json <JSON>  
      --md <MD>      
  -h, --help         Print help
kurosaki mapper-info — Describir un mapper
powershell
kurosaki mapper-info 4
help
Usage: kurosaki.exe mapper-info [OPTIONS] <MAPPER>

Arguments:
  <MAPPER>  

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