docs/NATIVE_REPORTS.md

   1 # Native compatibility reports
   2
   3 FriiDump 0.5.3.16-pf1 creates one native evidence report by default for each
   4 normal dump invocation accepted by the FriiDump Compatibility Database v1.2.0.
   5
   6 ## Default behavior
   7
   8 No report option is required:
   9
  10 ```text
  11 friidump -d <drive> -8 -s -i game.iso
  12 ```
  13
  14 FriiDump writes the report beside the final FriiDump log and derives its
  15 name from that log filename:
  16
  17 ```text
  18 game.iso.log
  19 game.iso.friidump.json
  20 ```
  21
  22 The report is written atomically. A derived report name never overwrites prior
  23 evidence; a collision receives the run UUID as a suffix.
  24
  25 For partial or cancelled dumps, FriiDump's console summary distinguishes the
  26 expected disc size from completed output and computes observed throughput only
  27 from the completed bytes represented by the report. Resumed runs do not claim
  28 throughput because their output size includes data from an earlier invocation.
  29
  30 ## Path overrides
  31
  32 Override the complete report pathname:
  33
  34 ```text
  35 friidump -d <drive> -8 -s -i game.iso \
  36   --report-json custom-evidence.json
  37 ```
  38
  39 Override only the destination directory while retaining the derived filename:
  40
  41 ```text
  42 friidump -d <drive> -8 -s -i game.iso \
  43   --report-dir reports
  44 ```
  45
  46 The options may be combined. In that form, `--report-json` supplies the
  47 filename and `--report-dir` replaces its directory:
  48
  49 ```text
  50 friidump -d <drive> -8 -s -i game.iso \
  51   --report-json ignored/path/custom-evidence.json \
  52   --report-dir reports
  53 ```
  54
  55 The final path is `reports/custom-evidence.json`.
  56
  57 ## Modified firmware
  58
  59 Firmware is assumed to be stock when `--firmware-modified` is omitted.
  60 Modified or cross-flashed firmware must be declared explicitly with a non-empty
  61 explanation:
  62
  63 ```text
  64 friidump -d <drive> -8 -s -i game.iso \
  65   --firmware-modified "patched to allow 0xe7 mem dumps"
  66 ```
  67
  68 The flag does not require either report-path option because reporting is enabled
  69 by default. FriiDump does not infer modified firmware from a selected profile.
  70
  71 ## Recorded evidence
  72
  73 Each report uses `friidump-test-result.v1` and records:
  74
  75 - one UUID for the invocation;
  76 - authoritative UTC start, completion, and generation times;
  77 - FriiDump version and optional full build commit;
  78 - exact live INQUIRY vendor, product, and firmware revision;
  79 - platform, title, region, and disc ID when known;
  80 - for unforced Nintendo runs, GameCube/Wii platform identity from the
  81   unscrambled sector-0 platform magic rather than capacity probing alone;
  82 - seed-stage and dump-stage outcomes;
  83 - actual output sectors, bytes, and elapsed dump time;
  84 - failure stage and sector for partial or failed runs;
  85 - CRC32, MD5, SHA-1, and SHA-256 when hashing was enabled;
  86 - Redump verification independently of compatibility status;
  87 - selected HLDS support tier, CDB offset, and firmware gate evidence;
  88 - an explicit measurement-scope note.
  89
  90 FriiDump reports observed facts. It does not publish or change a compatibility
  91 assessment. An administrator must accept and link the report in the database.
  92
  93 ## Measurement scopes
  94
  95 FriiDump emits one of these controlled notes for attempted dumps:
  96
  97 ```text
  98 Measurement scope: full_optical_payload.
  99 Measurement scope: assembled_output.
 100 Measurement scope: partial_progress.
 101 Measurement scope: unknown.
 102 ```
 103
 104 `full_optical_payload` is used for successful GameCube, Wii, and ordinary DVD
 105 optical reads. Xbox ISO/XISO output uses `assembled_output` because logical or
 106 synthetic output regions make its rate non-comparable to an optical-only read.
 107 A failed run with actual completed bytes uses `partial_progress`.
 108
 109 A resumed output uses `unknown`: the file size includes bytes from an earlier
 110 invocation, so FriiDump suppresses throughput inference from the current run's
 111 elapsed time.
 112
 113 ## Cancellation
 114
 115 When native reporting is enabled, Ctrl+C requests a controlled cancellation.
 116 The active dumper stops at the next cancellation boundary, closes the partial
 117 output, and writes an honest report:
 118
 119 ```text
 120 run.test_type = partial_dump
 121 run.result = partial
 122 dump.result = partial
 123 dump.failure_stage = user_cancelled
 124 Measurement scope: partial_progress.
 125 ```
 126
 127 When no output bytes were completed, cancellation is recorded as a failed
 128 `other` run rather than fabricated partial progress. Some low-level drive
 129 commands are synchronous; cancellation is observed after the active command
 130 returns.
 131
 132 ## Report restrictions
 133
 134 Native reporting currently requires one normal device dump invocation and
 135 exactly one primary dump output. Combined raw and ISO output is rejected so the
 136 reported output path, bytes, hashes, and `dump_output` artifact remain
 137 unambiguous. It cannot be combined with:
 138
 139 - raw-file conversion;
 140 - `--allmethods`;
 141 - stop-only operation;
 142 - HLDS research scans or sweeps;
 143 - XGD1 layout or raw-ID research probes.
 144
 145 Broad INQUIRY, VPD, GET CONFIGURATION, and MODE SENSE discovery belongs in the
 146 separate optical-drive research utility, not FriiDump.
 147
 148 ## Build identity
 149
 150 CMake builds may embed the exact source commit:
 151
 152 ```bash
 153 cmake -S . -B build \
 154   -DFRIIDUMP_BUILD_COMMIT=<full-40-character-commit>
 155 ```
 156
 157 The Windows helper uses `FRIIDUMP_BUILD_COMMIT` when supplied, or derives the
 158 current Git `HEAD` when the source tree contains `.git`:
 159
 160 ```powershell
 161 $env:FRIIDUMP_BUILD_COMMIT = "<full-40-character-commit>"
 162 .\build_msvc32.cmd
 163 ```
 164
 165 When no trustworthy commit is supplied, the JSON field is `null` rather than a
 166 guess.
 167
 168 ## Tests
 169
 170 Linux/CMake fixture build:
 171
 172 ```bash
 173 cmake -S . -B build-native-report-tests \
 174   -DBUILD_NATIVE_REPORT_TESTS=ON \
 175   -DBUILD_STATIC_BINARY=ON
 176 cmake --build build-native-report-tests
 177 mkdir -p build-native-report-tests/report-fixtures
 178 ./build-native-report-tests/src/friidump-report-fixtures \
 179   build-native-report-tests/report-fixtures
 180 python3 tests/validate_native_reports.py \
 181   --fixtures build-native-report-tests/report-fixtures
 182 ```
 183
 184 Validate one or more live reports without requiring the built-in fixture names:
 185
 186 ```text
 187 python3 tests/validate_native_reports.py \
 188   --fixtures <report-directory> \
 189   --allow-arbitrary
 190 ```
 191
 192 Windows/MSVC fixture build:
 193
 194 ```powershell
 195 .\build_msvc32_native_report_tests.cmd
 196 ```
 197
 198 Strict validation requires Python's `jsonschema` package. Database semantic
 199 validation can also be run by passing the v1.2.0 `bin/validate-report.php` path
 200 to `tests/validate_native_reports.py`.
 201
 202 The complete field and acceptance requirements are in
 203 `docs/FRIIDUMP_NATIVE_REPORT_REQUIREMENTS.md`.