# FriiDump 0.5.3.16-pf1 native compatibility reporting

## Status

This is a source candidate for Windows and physical-drive validation. It is not
a promoted release and does not replace `v0.5.3.15-pf1`.

## Scope

The change adds native `friidump-test-result.v1` generation to normal dump
invocations. It deliberately excludes broad drive-research discovery; that
work remains assigned to a separate future utility.

## User-visible behavior

Native reports are created by default for normal dump invocations. The default
location is beside the final FriiDump log and the filename is derived from
that log filename.

```text
--report-json <file>       Override the complete report pathname
--report-dir <directory>   Override only the destination directory
--firmware-modified <note> Declare modified firmware; omission assumes stock
```

`--report-json` and `--report-dir` may be combined; the directory override is
applied to the filename supplied by `--report-json`. Derived-name collisions
receive the run UUID, while an explicit pathname is never overwritten. Native
reporting requires exactly one primary dump output; combined raw and ISO output
is rejected to keep output identity unambiguous. FriiDump does not infer
modified firmware from the selected drive profile.

## Implementation boundaries

- `src/native_report.c/.h` owns report state, validation, JSON escaping, UUIDs,
  path resolution, and atomic publication.
- `src/friidump.c` maps live FriiDump state into the report.
- `libfriidump/disc.c/.h` exposes exact live INQUIRY identity already held by
  the drive layer.
- `libfriidump/dumper.c/.h` exposes resume state and controlled-cancellation
  status without moving report serialization into the library.
- Existing dumping, Redump verification, and HLDS profile code remain the
  authorities for their observed results.

## Evidence behavior

The report records native evidence only. It contains no reconstruction
converter identity and does not claim a public compatibility status.

Complete, partial, failed, cancelled, seed-failure, no-media, stock-firmware,
and modified-firmware states are represented without inventing missing values.

Output size is measured from the actual output file. The report includes one
`dump_output` artifact whose path, byte count, and SHA-256 are cross-checked
against the primary dump fields. Resumed outputs are marked with measurement
scope `unknown` because file bytes may predate the current invocation, and
streaming hashes are suppressed because they cover only appended bytes. Xbox
logical/reconstructed output uses `assembled_output`; normal successful
GC/Wii/DVD output uses `full_optical_payload`.

## Atomicity and identity

- One version-4 UUID is generated per invocation.
- The report is UTF-8 JSON with non-ASCII input safely escaped.
- Temporary output is flushed and committed before publication.
- POSIX uses hard-link publication to enforce no-overwrite atomically.
- Windows uses `MoveFileExA` without replace-existing semantics.
- Stale per-run temporary files are removed only when they match the same UUID.

## Cancellation

When reporting is enabled, SIGINT/Ctrl+C becomes a controlled cancellation
request. FriiDump exits the active dump loop at the next boundary, finalizes the
partial stream, closes it, and records `user_cancelled`. Research, conversion, all-methods, and stop-only operations remain outside native reporting.

## Build integration

- CMake builds `native_report.c` and links `ole32` on Windows for UUIDs.
- `FRIIDUMP_BUILD_COMMIT` accepts only a full 40-character hexadecimal commit.
- The maintained MSVC response file includes the report module and `ole32.lib`.
- `build_msvc32.cmd` embeds an explicit commit or derives Git `HEAD`.
- `build_msvc32_native_report_tests.cmd` builds and executes the report fixture
  generator on Windows.

## Automated fixtures

The source includes fixtures for:

- successful GameCube optical dump;
- successful Xbox assembled output;
- partial read/write failure;
- controlled user cancellation;
- seed failure;
- no-media diagnostic;
- modified firmware;
- unique retry UUID and no-overwrite policy;
- recursive report-directory creation;
- rejection of invalid UUID, modified firmware without a note, successful
  dumps without sector/byte counts, incoherent attempted-state results, missing
  output artifacts, and mismatched artifact byte counts;
- preservation of valid UTF-8 text in JSON output.

The fixtures are validated against the exact Compatibility Database v1.2.0 JSON
Schema. The database PHP semantic validator is used during package validation.

## Remaining promotion gates

Before a release can be promoted:

1. Build with the maintained Visual Studio 2019 32-bit toolchain.
2. Run the MSVC fixture tests.
3. Validate no-media reporting on a real drive.
4. Validate a complete GameCube or Wii report.
5. Validate a controlled partial cancellation.
6. Validate Xbox assembled-output reporting on the applicable hardware path.
   The copied GDR-8050L reference dumper remains a special Windows-only path;
   complete output reporting must be validated there, and Ctrl+C cancellation
   must not be claimed for that path until its copied loops receive an explicit
   cancellation callback.
7. Submit generated reports to the live v1.2.0 database and confirm acceptance.
8. Review exact report contents before assigning a release tag.