# FriiDump 0.5.3.16-pf1 native compatibility reporting

## Status

This document records the implementation and accepted validation basis for
FriiDump 0.5.3.16-pf1. Candidate-specific reports remain historical evidence;
the release identity is the annotated tag and its exact commit/tree.

## 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.

## Accepted validation basis

The release campaign completed these gates:

1. Maintained Visual Studio 2019 32-bit build and fixture execution.
2. Linux/CMake build and raw-I/O authorization preflight.
3. Real-drive no-media and controlled-partial reporting.
4. Complete GameCube validation with an exact known-good image hash.
5. Original Xbox GDR-8050L game-view, XDVDFS, DMI/media-ID, native-report,
   controlled-cancellation, hashing, and STOP UNIT validation.
6. Exact report review and compatibility-database acceptance.
7. Candidate publication and exact fast-forward promotion to canonical `main`.

The copied Windows challenge-drive loops retain their documented cancellation
boundary. No broader cancellation claim is inferred from the portable Linux
path.