KITAQ SERIES • REFERENCE EDITION

SARAKURA

Diagnostics, comparison and retesting

From your first line to execution, observation and retesting.
Source snapshot: September 14, 2026 · English edition: September 14, 2026

Prebuilt Windows CLI

The repository now includes sarakura.exe at its root. Download the repository ZIP and keep the license notices with the executable. This Windows x64 CLI needs no Rust, Python or .NET installation to run. The build steps below are for rebuilding from source. The independent project code is licensed by DAISUKE OBA under MIT; dependency terms are preserved in BINARY_NOTICES.md and licenses/.

1. SARAKURA's job

SARAKURA combines compiler build information with emulator diagnostic events and presents them in a form useful for repairs and retests. It is neither a ROM-executing emulator nor a program that silently edits your C code.

2. Build the tool

powershell

Push-Location .\sarakura
.\scripts\build.ps1
.\sarakura.exe --help
Pop-Location

Short sarakura commands assume it is on PATH. Otherwise use the path to the built executable. Select gb analyze for GB or fc analyze for FC.

3. Your first analysis

Two inputs are required: --metadata is build-time JSON, and --events is runtime diagnostic JSONL. JSONL contains one JSON object per line.

powershell

sarakura gb analyze --metadata .\out\build.json --events .\out\gb_events.jsonl --out .\out\report --fail-on error

Open the output report.html in a browser. Check the target, observed frames, error count and warning count before reading individual diagnostics. --frames describes analysis conditions; it does not ask SARAKURA to execute a ROM for that many frames.

4. Inspect the inputs first

powershell

sarakura inspect-metadata --metadata .\out\build.json
sarakura inspect-events --events .\out\gb_events.jsonl
sarakura emitter-check gb --metadata .\out\build.json --events .\out\gb_events.jsonl --strict

Separate unreadable files, mismatched platforms and unsupported event types before investigating game behavior. Passing an ordinary emulator report as an events file does not make it valid diagnostic input.

5. Interpret diagnostics

An error deserves priority, a warning may indicate a problem depending on circumstances, and an info item provides context. Severity helps triage but does not fully understand the game's intent. A repeated-PC observation alone may not distinguish a normal title-screen wait loop from a freeze.

Compare the ROM hash, input sequence, scene, screen, sound and source location. Keep conditions equal before and after a repair; otherwise fewer diagnostics might simply mean that a different scene ran.

6. Output files

Built-in explanations, diagnostic hints and repair instructions are in English, and HTML declares lang="en". User strings and event IDs are not automatically translated. Default redaction replaces selected project labels and paths; it does not anonymize every address or observation. Inspect reports before publishing analysis of private input.

File	Purpose
ai_diagnostics.json	Normalized diagnostics for automated processing
diagnostic_summary.json	Counts and summary
report.html	Human-readable report
repair_prompt.md	Starting context for a repair investigation
repair_plan.json / .md	Repair order and targets
automation_plan.json / .md	Work plan based on tool capabilities
retest_plan.json	Recheck plan
repro_bundle.zip	Reproduction information bundle

Producing a plan is different from executing it. After changing C source or a ROM, run the compiler, emulator and SARAKURA again.

7. Catalogs, filtering and coverage

powershell

sarakura catalog gb --json
sarakura catalog fc --json
sarakura pack-plan gb
sarakura coverage gb --events .\out\gb_events.jsonl --out .\out\coverage.json

catalog lists diagnostic rules, pack-plan groups them by area, and coverage examines which corresponding events were observed. A catalog entry does not guarantee that the current emulator emits that event.

powershell

sarakura gb analyze --metadata .\out\build.json --events .\out\gb_events.jsonl --out .\out\ppu_report --diagnostic-pack ppu --min-severity warn --fail-on error

--diagnostic-rule selects an event name or catalog ID, --phase selects a stage, and --diagnostic-pack selects an area. Filtering a diagnostic out of view does not resolve it.

8. Compare before and after

powershell

sarakura baseline-delta --baseline .\out\before --current .\out\after --out .\out\delta --markdown .\out\delta --fail-on-new error --fail-on-regression error --enforce

Results are classified as new, resolved, improved, persisting or regressed. Distinguish retained problems from newly introduced ones. Keep input, frame counts and diagnostic filters fixed during comparisons.

9. Validation and CI

powershell

sarakura validate .\out\report\ai_diagnostics.json --strict
sarakura ci-summary --diagnostics .\out\report --fail-on error --enforce
sarakura schema export --out .\out\schemas

Continuous integration automates repeatable checks. ci-summary changes the process exit code only when --enforce is supplied; otherwise read its JSON verdict. For analyze, --fail-on error returns a nonzero exit code when errors occur. The default never does not fail the process for diagnostics, so choose a policy explicitly in CI. Selecting warn also makes warnings a failure condition.

powershell

sarakura ci-summary --diagnostics .\out\report --fail-on error --enforce
if ($LASTEXITCODE -ne 0) { throw "The diagnostic failure condition was met" }

Successful schema validation checks the data format. Verifying that a game plays as intended also requires input, screen and sound tests.

10. Handle reproduction files

normalize-events normalizes event records. inspect-repro examines a reproduction bundle. Before sharing, check that its information matches the intended ROM and includes the needed input steps. --allow-project-labels explicitly retains project-derived labels and identifiers.

11. Minimal practice inputs

The manual includes small GB/FC build-metadata and event samples. Open the GB synthetic report or FC synthetic report. samples/sarakura_demo.ps1 demonstrates analyzing them. These are synthetic inputs for learning the format, not evidence captured from an actual ROM. Use events recorded by KOKURA or KUROSAKI for real-ROM tests.

12. One repair and retest cycle

Reproduce the problem with the same ROM and input, retaining logs and pictures.
Organize candidates with SARAKURA and inspect the relevant source.
Make a focused change addressing the cause.
Rebuild and rerun the same actions.
Compare baseline-delta with pictures, audio and game behavior.

Keep this loop small so that each change and its effect remain understandable.

Command syntax reference

The following help was captured for the source edition. Consult it for optional arguments, defaults and accepted values. Replace the illustrative input filenames with your own outputs. Captured tool responses retain their original wording.

sarakura

help

SARAKURA diagnostic translation CLI

Usage: sarakura.exe <COMMAND>

Commands:
  gb                
  fc                
  validate          
  compare           
  catalog           
  inspect-events    
  inspect-metadata  
  retest-plan       
  emitter-check     
  normalize-events  
  ci-summary        
  coverage          
  pack-plan         
  repair-plan       
  automation-plan   
  baseline-delta    
  schema            
  inspect-repro     
  help              Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

sarakura gb

help

Usage: sarakura.exe gb <COMMAND>

Commands:
  analyze  
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

sarakura gb analyze — Collect Game Boy diagnostics

powershell

sarakura gb analyze --metadata out/build.json --events out/events.jsonl --out out/report --fail-on error

help

Usage: sarakura.exe gb analyze [OPTIONS] --metadata <METADATA> --events <EVENTS> --out <OUT>

Options:
      --metadata <METADATA>
          
      --events <EVENTS>
          
      --out <OUT>
          
      --frames <FRAMES>
          [default: 300]
      --diagnostic-summary-limit <DIAGNOSTIC_SUMMARY_LIMIT>
          [default: 200]
      --diagnostic-rule <DIAGNOSTIC_RULES>
          Analyze only this event_type or catalog ID. Can be repeated
      --phase <PHASE>
          Analyze only this phase, for example MVP-1. Can be repeated
      --diagnostic-pack <DIAGNOSTIC_PACKS>
          Analyze only this diagnostic pack/domain, for example core, ppu, audio, mapper, fds. Can be repeated
      --min-severity <MIN_SEVERITY>
          Keep only diagnostics at or above this severity [possible values: error, warn, info]
      --fail-on <FAIL_ON>
          Return a non-zero exit code if diagnostics at or above this severity remain [default: never] [possible values: never, error, warn, info]
      --no-report
          Do not emit report.html
      --no-repro-bundle
          Do not emit repro_bundle.zip
      --allow-project-labels
          Preserve project build labels, paths, and source identifiers in output
  -h, --help
          Print help

sarakura fc

help

Usage: sarakura.exe fc <COMMAND>

Commands:
  analyze  
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

sarakura fc analyze — Collect Famicom diagnostics

powershell

sarakura fc analyze --metadata out/build.json --events out/events.jsonl --out out/report --fail-on error

help

Usage: sarakura.exe fc analyze [OPTIONS] --metadata <METADATA> --events <EVENTS> --out <OUT>

Options:
      --metadata <METADATA>
          
      --events <EVENTS>
          
      --out <OUT>
          
      --frames <FRAMES>
          [default: 300]
      --diagnostic-summary-limit <DIAGNOSTIC_SUMMARY_LIMIT>
          [default: 200]
      --diagnostic-rule <DIAGNOSTIC_RULES>
          Analyze only this event_type or catalog ID. Can be repeated
      --phase <PHASE>
          Analyze only this phase, for example MVP-1. Can be repeated
      --diagnostic-pack <DIAGNOSTIC_PACKS>
          Analyze only this diagnostic pack/domain, for example core, ppu, audio, mapper, fds. Can be repeated
      --min-severity <MIN_SEVERITY>
          Keep only diagnostics at or above this severity [possible values: error, warn, info]
      --fail-on <FAIL_ON>
          Return a non-zero exit code if diagnostics at or above this severity remain [default: never] [possible values: never, error, warn, info]
      --no-report
          Do not emit report.html
      --no-repro-bundle
          Do not emit repro_bundle.zip
      --allow-project-labels
          Preserve project build labels, paths, and source identifiers in output
  -h, --help
          Print help

sarakura validate — Validate the diagnostic format

powershell

sarakura validate out/report/ai_diagnostics.json --strict

help

Usage: sarakura.exe validate [OPTIONS] <PATH>

Arguments:
  <PATH>  

Options:
      --strict  
  -h, --help    Print help

sarakura compare — Compare two diagnostic results

powershell

sarakura compare --before out/before --after out/after --out out/comparison

help

Usage: sarakura.exe compare --before <BEFORE> --after <AFTER> --out <OUT>

Options:
      --before <BEFORE>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --after <AFTER>    Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>        
  -h, --help             Print help

sarakura catalog — List diagnostic rules

powershell

sarakura catalog gb --json

help

Usage: sarakura.exe catalog [OPTIONS] <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --json  Emit JSON instead of a Markdown table
  -h, --help  Print help

sarakura inspect-events — Summarize events

powershell

sarakura inspect-events --events out/events.jsonl

help

Usage: sarakura.exe inspect-events [OPTIONS] --events <EVENTS>

Options:
      --events <EVENTS>  
      --out <OUT>        Optional path to write the JSON inspection summary
      --json             Emit JSON to stdout instead of a compact text summary
  -h, --help             Print help

sarakura inspect-metadata — Inspect build information

powershell

sarakura inspect-metadata --metadata out/build.json

help

Usage: sarakura.exe inspect-metadata [OPTIONS] --metadata <METADATA>

Options:
      --metadata <METADATA>  
      --out <OUT>            Optional path to write the JSON inspection summary
      --json                 Emit JSON to stdout instead of a compact text summary
  -h, --help                 Print help

sarakura retest-plan — Create a retest plan

powershell

sarakura retest-plan --diagnostics out/report --out out/retest.json

help

Usage: sarakura.exe retest-plan [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>                  Optional path to write retest_plan.json. If omitted, JSON is printed to stdout
  -h, --help                       Print help

sarakura emitter-check — Check emitter contract compliance

powershell

sarakura emitter-check gb --metadata out/build.json --events out/events.jsonl --strict

help

Usage: sarakura.exe emitter-check [OPTIONS] --events <EVENTS> <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --metadata <METADATA>      
      --events <EVENTS>          
      --strict                   Fail when compatibility warnings are found
      --check-snapshot-refs      Check that snapshot_ref paths exist
      --check-trace-window-refs  Check that trace_window_ref paths exist
      --base-dir <BASE_DIR>      Base directory for snapshot_ref and trace_window_ref existence checks
      --out <OUT>                Optional path to write the compatibility summary JSON
  -h, --help                     Print help

sarakura normalize-events — Normalize the event format

powershell

sarakura normalize-events --events out/events.jsonl --out out/normalized.jsonl

help

Usage: sarakura.exe normalize-events [OPTIONS] --events <EVENTS> --out <OUT>

Options:
      --events <EVENTS>  
      --out <OUT>        
      --json-array       Also write a pretty JSON array next to the JSONL output for fixture review
  -h, --help             Print help

sarakura ci-summary — Evaluate CI failure conditions

powershell

sarakura ci-summary --diagnostics out/report --fail-on error --enforce

help

Usage: sarakura.exe ci-summary [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --fail-on <FAIL_ON>          CI policy. `error` fails only on errors, `warn` fails on errors or warnings [default: error] [possible values: never, error, warn, info]
      --out <OUT>                  Optional path to write sarakura_ci_summary.json
      --enforce                    Return a non-zero exit code when the CI policy fails
  -h, --help                       Print help

sarakura coverage — List observed rules

powershell

sarakura coverage gb --events out/events.jsonl --out out/coverage.json

help

Usage: sarakura.exe coverage [OPTIONS] --events <EVENTS> <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --events <EVENTS>  
      --out <OUT>        Optional path to write catalog coverage JSON. If a directory is given, diagnostic_coverage.json is created inside it
      --json             Emit JSON to stdout instead of a compact text summary
  -h, --help             Print help

sarakura pack-plan — Describe rule plans by area

powershell

sarakura pack-plan gb

help

Usage: sarakura.exe pack-plan [OPTIONS] <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --out <OUT>  Optional path to write pack plan JSON. If a directory is given, diagnostic_pack_plan.json is created inside it
      --json       Emit JSON to stdout instead of a Markdown summary
  -h, --help       Print help

sarakura repair-plan — Create a repair plan

powershell

sarakura repair-plan --diagnostics out/report --out out/repair.json --markdown out/repair.md

help

Usage: sarakura.exe repair-plan [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>                  Optional path to write repair_plan.json. If omitted, JSON is printed to stdout
      --markdown <MARKDOWN>        Optional path to write repair_plan.md. If a directory is given, repair_plan.md is created inside it
  -h, --help                       Print help

sarakura automation-plan — Match plans to tool capabilities

powershell

sarakura automation-plan --diagnostics out/report --tool kokura --out out/automation.json

help

Usage: sarakura.exe automation-plan [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>    Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --tool <TOOL>                  Tool name for generated commands. Use auto, kokura, or kurosaki [default: auto]
      --out <OUT>                    Optional path to write automation_plan.json. If omitted, JSON is printed to stdout
      --markdown <MARKDOWN>          Optional path to write automation_plan.md. If a directory is given, automation_plan.md is created inside it
      --capabilities <CAPABILITIES>  Optional SARAKURA tool capability JSON. Unsupported options are omitted from generated commands
  -h, --help                         Print help

sarakura baseline-delta — Measure improvements and regressions from a baseline

powershell

sarakura baseline-delta --baseline out/before --current out/after --out out/delta --markdown out/delta

help

Usage: sarakura.exe baseline-delta [OPTIONS] --baseline <BASELINE> --current <CURRENT>

Options:
      --baseline <BASELINE>
          Baseline directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --current <CURRENT>
          Current directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>
          Optional path to write baseline_delta.json. If omitted, JSON is printed to stdout
      --markdown <MARKDOWN>
          Optional path to write baseline_delta.md. If a directory is given, baseline_delta.md is created inside it
      --fail-on-new <FAIL_ON_NEW>
          Fail when new diagnostics at or above this severity are introduced [default: error] [possible values: never, error, warn, info]
      --fail-on-regression <FAIL_ON_REGRESSION>
          Fail when existing diagnostics regress at or above this severity [default: error] [possible values: never, error, warn, info]
      --enforce
          Return a non-zero exit code when the baseline policy fails
  -h, --help
          Print help

sarakura schema

help

Usage: sarakura.exe schema <COMMAND>

Commands:
  export  
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

sarakura schema export — Export JSON schemas

powershell

sarakura schema export --out out/schemas

help

Usage: sarakura.exe schema export [OPTIONS] --out <OUT>

Options:
      --out <OUT>            
      --manifest <MANIFEST>  
  -h, --help                 Print help

sarakura inspect-repro — Inspect a reproduction bundle

powershell

sarakura inspect-repro out/report/repro_bundle.zip --json

help

Usage: sarakura.exe inspect-repro [OPTIONS] <BUNDLE>

Arguments:
  <BUNDLE>  

Options:
      --out <OUT>  
      --json       
  -h, --help       Print help