Free File Recovery 8.1.0 native engine
Modified 2026-10-20 from the official TestDisk/PhotoRec 7.2 source release.
This is a real source fork with a new headless Windows entry point, original-name
NTFS adapter, JSONL events, cancellation hooks and a rejecting source-write backend.
The normal TestDisk partition repair UI is not exposed or shipped in the app.

Native runtime payload (one file):
  bin/ffr-engine.exe
zlib, iconv/libcharset and libntfs are linked statically into this EXE. Neither
zlib1.dll nor libiconv-2.dll is required or copied into the native runtime payload.
The exact static link inputs and PE imports are in bin/Engine-Link-Manifest.json.
Windows supplies bcrypt, Kernel32 and Universal CRT; they are not bundled here.
This native preview EXE is asInvoker. It does not request elevation or bypass UAC.
Restricted volume access may fail without administrator permissions. No physical
device was opened, enumerated or scanned in development/QA.

Protocol (stdout UTF-8, one flushed JSON object per line; no UI dialogs):
  --version
  --inspect --source C:\Images\copy.img
  --scan --source C:\Images\copy.img [--partition INDEX]
  --recover --source C:\Images\copy.img --source-id STAMP --ids OPAQUE_IDS
            --destination D:\Recovered [--partition INDEX]
  --carve --source C:\Images\copy.img --destination D:\Recovered
          [--partition INDEX] [--types jpg,png,pdf,zip]
  optional --cancel-file C:\SafeTarget\cancel.marker
  Explicit volume input only: --device-readonly --source \\.\E:

Input images must be existing local .img/.raw/.dd ordinary single-link files.
No automatic disk discovery or arbitrary PhysicalDrive/device input is provided.
--partition indexes come from each inspect response, not Windows partition numbers.
The raw NTFS fixture returns index 0 unknown Whole disk and index 1 NTFS; default
scan selects its NTFS entry. A whole-source entry supports carving unknown volumes.
Always treat sourceId and file.id as opaque; do not parse IDs in a GUI.
Batch selected IDs to fit the Windows command line (the GUI uses <12000 chars).

Events:
  hello: protocol=1, engine/version/upstream, capabilities
  source: sourceId, size, readOnly=true, kind=image|volume, sectorSize
  partition: index, fs, offset, size, label
  progress: phase=source-check|scan|recover|carve, current, total
  file: id, name, path, size, estimatedRecoverability=unknown,
        metadataEstimatePercent, contentVerified=false
  output: path of a new unique Recovery-<random-hex>-<counter> job folder
  recovered: id, path, size, contentVerified=false, contentCheck
  done: status=ok|cancelled|error, count, sourceUnmodifiedByEngine=true
  error: code, message; nonzero exit means failure
Normal user cancellation emits done(cancelled) with exit 0, no error event.
Errors before the job starts can emit error and exit without done.
Exit codes: 2 arguments/selection; 3 source open/check; 4 changed source/partition;
5 safe output/create/carving disk-full; 6 metadata unsupported/stale/write error;
7 I/O failure. Runtime capability flags do not imply real-device QA.

Source protections:
The source is opened GENERIC_READ only; the disk write callback always fails EROFS.
libntfs is mounted MS_RDONLY with its default real-device backend compiled out.
Images are held without write/delete sharing and their full SHA256 is included in
sourceId together with file identity and length. Recover reopens/rechecks the whole
image and rejects changed bytes even when timestamps and size are preserved.
Live volumes remain live: sourceId uses volume GUID+serial+disk extents+size+boot
SHA256, not a point-in-time full-volume snapshot. Candidate IDs include MFT number,
sequence and full current MFT-record SHA256; all requested records are validated
before any selected file contents are written, and rechecked while recovering.
Ordinary-file QA tests exercise the byte-alignment bounce path for volume reads;
this is not a claim of physical-volume recovery qualification.

Destination protections:
Existing local folders only; parent junctions/symlinks are rejected. A new random
job folder is created, never reused. Real-volume destination extents must be on a
different physical device; unknown mappings fail closed. The GUI must put logs,
temporary/cancel markers and its own operation state on safe target storage too.
Image files may be processed on their host disk because only the explicit immutable
copy is read. Recovery names are untrusted: traversal components are rejected,
Windows-invalid chars/reserved names are sanitized, existing files are never
truncated and partially failed/cancelled selected-file copies are removed.

Honest preview boundaries:
NTFS metadata mode lists deleted primary unnamed streams that upstream reports
potentially recoverable. It preserves surviving names and parent paths. Compressed
NTFS, EFS, multi-record attribute lists and named alternate streams are excluded.
The percentage is only an allocation estimate; 100% does not prove original bytes.
ContentCheck=signature-present only checks a small header, never full integrity.
An overwritten PDF fixture correctly reports signature-mismatch, not verified.
FAT/exFAT original-name metadata recovery is not implemented in this preview.
PhotoRec carving writes files during the scan, with generated names; it scans the
whole selected area and can recover currently allocated files/duplicates as well
as deleted content. It does not preserve original folders. No pause/resume or
scan-checkpoint import is supported. Cancellation is supported.
Overwrites, SSD TRIM, encryption/BitLocker and failing hardware can prevent useful
recovery. Do not promise a permanent success rate. The application never executes
recovered files. SourceUnmodifiedByEngine describes this engine's read-only access;
it does not freeze Windows or other writers on a live mounted volume.

Build and corresponding source:
See BUILD.txt, patches/testdisk-7.2-ffr.patch, patches/overlay-manifest.json and
Engine-Freeze-Manifest.json. Preserve all original headers and COPYING files.
The engine and libntfs use GPL-2.0-or-later. Distribute modified corresponding
source, the build scripts and licenses with the binary distribution/source ZIP.
The source bundle also includes exact matching MSYS2 source packages for statically
linked libiconv/libcharset 1.19-1 (LGPL-2.1-or-later) and zlib 1.3.2-2 (zlib license)
in redistribution-sources (PKGBUILDs and upstream source included). Keep the full
engine/application sources and build/relink scripts available, so recipients can
modify the LGPL library and relink the executable. Original license notices are
under Licenses/. This does not relicense upstream components or replace their terms.

Reproducible QA evidence is recorded for each exact engine SHA in the current
Engine-Freeze-Manifest.json and the referenced reports. Static-link repair includes
a standalone test: only ffr-engine.exe in an empty directory, a separate empty cwd,
and PATH restricted to Windows System32. Version/inspect/NTFS scan and seven-file
SHA-checked recovery/FAT32 four-format SHA-checked carving all pass in that setup.
All fixture source SHA256 values remained unchanged; no user disk or vault used.
