DKR-R ACHIEVEMENTS - PATCH PIPELINE

This is our local achievement system. All 94 goals are wired to native game
state. There is no RetroAchievements login, API, runtime, cloud service or
downloaded achievement script. The challenge inventory follows the original
DKR base set; wording, badges, sound and tracking code are our own.

The checked-out submodules, RecompiledFuncs and RecompiledPatches must stay
untouched. configure.py composes the accepted release, review editor, custom
vehicles and texture-dumping pipeline, then applies this final overlay only
to an isolated build outside the checkout. Nothing is patched in place.

FILES
native/achievement_catalogue.cpp: stable IDs, descriptions and all 94 goals.
native/achievements.hpp: value-only snapshots, definitions and UI API.
native/achievements.cpp: bounded read-only RAM capture, evaluator, background
storage worker, atomic progress writes, backups and notification queue.
native/achievement_ui.inl: sidebar page, controller-first progress list,
detail view, filters, keyboard, preferences, pinning and unlock notifications.
pipeline.py: validated source transformations and source/hash receipts.
ReleaseOverlay.cmake: final source selection and include precedence.
audit.py: static coverage, source, protected-input and linked-byte checks.
inspect_rom.py: read-only extraction of numeric original staff ghost targets.
package.py: allowlisted Windows ZIP/Linux AppImage packaging and 94-goal
checklists. It never launches either binary or invokes a test target.

RULES AND OWNERSHIP
Adventure milestones watch new progress in the currently loaded adventure.
Five-balloon goals watch newly earned balloons for each base driver in the
current Adventure session. Changing saves or leaving Adventure resets the
attempt, not the collection. Cosmetic character mods keep base identities.

Time trials use all three original laps, original vehicle type, non-mirrored
mode and strict native-clock comparisons. Staff targets have been checked
against all 20 ghost headers in the original US 1.0 ROM. Developer targets
are paired with the ROM's MAIN_TRACKS_IDS order, exactly as the credits do,
not the different Track Select grid order. A custom course or trophy cannot stand in
for an original course. Silver goals require eight coins and first place
in the same original Adventure Two race. CPUs never earn player item goals.

Offline captures happen after each main_game_loop boundary in both US
revisions. Experimental Rollback captures value-only observations in the
owning RAM instance; replay replaces its frame projection, and only a
successful confirmed commit submits it. Local ownership filters exclude
other peers' item collection. These projections do not enter guest memory,
checkpoints, hashes, effect journals or the wire protocol. Other online
backends do not submit predicted observations. Every goal can be earned
through offline play; applicable item goals also support local multiplayer
and confirmed Experimental Rollback. Developer sessions pause tracking.

STORAGE
The one local profile is achievements/progress-v1.json under the existing
DKR-R user-data directory. It is separate from EEPROM and adventure files.
A worker merges existing unlocks under an OS file lease before atomic
replacement. A last-known-good backup is retained; a corrupt primary is
preserved during recovery. Unknown entry IDs survive normal writes.
Imports merge unlocks. Explicit recognition labels provable saved milestones
as recognised and does not manufacture session or time-trial history.

BUILD
python -B patches/achievements/configure.py --build OUTSIDE_BUILD --capsule
  ACCEPTED_SOURCE_CAPSULE --log CONFIGURE_LOG --cmake CMAKE_EXECUTABLE
python -B patches/release-prep/v1.0.7/release.py build --build OUTSIDE_BUILD
  --log BUILD_LOG --cmake CMAKE_EXECUTABLE --jobs 4
python -B patches/achievements/audit.py --stage OUTSIDE_BUILD/generated/achievements
  --binary RUNTIME_BINARY --output STATIC_RECEIPT.json
python -B patches/achievements/package.py windows|linux --compiled BIN_DIRECTORY
  --template PREVIOUS_PACKAGE_ROOT --output NEW_OUTPUT_DIRECTORY
  --stage OUTSIDE_BUILD/generated/achievements --trophy PINNED_TROPHY_UPDATER
  [--arch x86_64|aarch64] [--runtime-image PREVIOUS_LINUX_APPIMAGE]

Windows uses native CMake, not the MSYS executable. Linux uses WSL/Linux
toolchains. AppImage creation inspects/reuses a known runtime header and
constructs the squashfs payload without executing the AppImage.

Validation is compilation, linking, source and package inspection only.
The owner performs gameplay acceptance using the supplied 94-entry checklist.
Do not claim that compile success proves that all goals have been earned
or that platform/controller/hardware acceptance has already happened.
