docs/reports/FRIIDUMP_NATIVE_COMPATIBILITY_REPORTING_0.5.3.16.md

   1 # FriiDump 0.5.3.16-pf1 native compatibility reporting
   2
   3 ## Status
   4
   5 This is a source candidate for Windows and physical-drive validation. It is not
   6 a promoted release and does not replace `v0.5.3.15-pf1`.
   7
   8 ## Scope
   9
  10 The change adds native `friidump-test-result.v1` generation to normal dump
  11 invocations. It deliberately excludes broad drive-research discovery; that
  12 work remains assigned to a separate future utility.
  13
  14 ## User-visible behavior
  15
  16 Native reports are created by default for normal dump invocations. The default
  17 location is beside the final FriiDump log and the filename is derived from
  18 that log filename.
  19
  20 ```text
  21 --report-json <file>       Override the complete report pathname
  22 --report-dir <directory>   Override only the destination directory
  23 --firmware-modified <note> Declare modified firmware; omission assumes stock
  24 ```
  25
  26 `--report-json` and `--report-dir` may be combined; the directory override is
  27 applied to the filename supplied by `--report-json`. Derived-name collisions
  28 receive the run UUID, while an explicit pathname is never overwritten. Native
  29 reporting requires exactly one primary dump output; combined raw and ISO output
  30 is rejected to keep output identity unambiguous. FriiDump does not infer
  31 modified firmware from the selected drive profile.
  32
  33 ## Implementation boundaries
  34
  35 - `src/native_report.c/.h` owns report state, validation, JSON escaping, UUIDs,
  36   path resolution, and atomic publication.
  37 - `src/friidump.c` maps live FriiDump state into the report.
  38 - `libfriidump/disc.c/.h` exposes exact live INQUIRY identity already held by
  39   the drive layer.
  40 - `libfriidump/dumper.c/.h` exposes resume state and controlled-cancellation
  41   status without moving report serialization into the library.
  42 - Existing dumping, Redump verification, and HLDS profile code remain the
  43   authorities for their observed results.
  44
  45 ## Evidence behavior
  46
  47 The report records native evidence only. It contains no reconstruction
  48 converter identity and does not claim a public compatibility status.
  49
  50 Complete, partial, failed, cancelled, seed-failure, no-media, stock-firmware,
  51 and modified-firmware states are represented without inventing missing values.
  52
  53 Output size is measured from the actual output file. The report includes one
  54 `dump_output` artifact whose path, byte count, and SHA-256 are cross-checked
  55 against the primary dump fields. Resumed outputs are marked with measurement
  56 scope `unknown` because file bytes may predate the current invocation, and
  57 streaming hashes are suppressed because they cover only appended bytes. Xbox
  58 logical/reconstructed output uses `assembled_output`; normal successful
  59 GC/Wii/DVD output uses `full_optical_payload`.
  60
  61 ## Atomicity and identity
  62
  63 - One version-4 UUID is generated per invocation.
  64 - The report is UTF-8 JSON with non-ASCII input safely escaped.
  65 - Temporary output is flushed and committed before publication.
  66 - POSIX uses hard-link publication to enforce no-overwrite atomically.
  67 - Windows uses `MoveFileExA` without replace-existing semantics.
  68 - Stale per-run temporary files are removed only when they match the same UUID.
  69
  70 ## Cancellation
  71
  72 When reporting is enabled, SIGINT/Ctrl+C becomes a controlled cancellation
  73 request. FriiDump exits the active dump loop at the next boundary, finalizes the
  74 partial stream, closes it, and records `user_cancelled`. Research, conversion, all-methods, and stop-only operations remain outside native reporting.
  75
  76 ## Build integration
  77
  78 - CMake builds `native_report.c` and links `ole32` on Windows for UUIDs.
  79 - `FRIIDUMP_BUILD_COMMIT` accepts only a full 40-character hexadecimal commit.
  80 - The maintained MSVC response file includes the report module and `ole32.lib`.
  81 - `build_msvc32.cmd` embeds an explicit commit or derives Git `HEAD`.
  82 - `build_msvc32_native_report_tests.cmd` builds and executes the report fixture
  83   generator on Windows.
  84
  85 ## Automated fixtures
  86
  87 The source includes fixtures for:
  88
  89 - successful GameCube optical dump;
  90 - successful Xbox assembled output;
  91 - partial read/write failure;
  92 - controlled user cancellation;
  93 - seed failure;
  94 - no-media diagnostic;
  95 - modified firmware;
  96 - unique retry UUID and no-overwrite policy;
  97 - recursive report-directory creation;
  98 - rejection of invalid UUID, modified firmware without a note, successful
  99   dumps without sector/byte counts, incoherent attempted-state results, missing
 100   output artifacts, and mismatched artifact byte counts;
 101 - preservation of valid UTF-8 text in JSON output.
 102
 103 The fixtures are validated against the exact Compatibility Database v1.2.0 JSON
 104 Schema. The database PHP semantic validator is used during package validation.
 105
 106 ## Remaining promotion gates
 107
 108 Before a release can be promoted:
 109
 110 1. Build with the maintained Visual Studio 2019 32-bit toolchain.
 111 2. Run the MSVC fixture tests.
 112 3. Validate no-media reporting on a real drive.
 113 4. Validate a complete GameCube or Wii report.
 114 5. Validate a controlled partial cancellation.
 115 6. Validate Xbox assembled-output reporting on the applicable hardware path.
 116    The copied GDR-8050L reference dumper remains a special Windows-only path;
 117    complete output reporting must be validated there, and Ctrl+C cancellation
 118    must not be claimed for that path until its copied loops receive an explicit
 119    cancellation callback.
 120 7. Submit generated reports to the live v1.2.0 database and confirm acceptance.
 121 8. Review exact report contents before assigning a release tag.