DroidDeck/docs/development/gog-maintenance.md

GOG maintenance

Installed GOG games are checked after library refresh and when details open. Successful automatic checks are throttled to 30 minutes; two metadata workers run at most. Manual checks bypass the throttle. Downloads and application always require a user action. Unknown metadata, authentication failures, and network errors remain distinct from a current installation.

Records and recovery

.droiddeck-gog/installed.json is a schema-versioned installation inventory. It retains source, generation, opaque build identifier, branch, display version, language, installed products, sanitized manifests, and file hashes/chunks. Migration uses the existing marker, sidecar, and authentic GOG metadata; missing historical content is never replaced with the latest manifest as an assumed description of installed files. Authentic goggame-*.id build metadata takes precedence over legacy markers; the numeric version field in a GOG info file is a schema, not a game version.

operation.json pins the operation, exact folder, previous sidecar/inventory, target, and phase. Staged chunks are durable work and are rehashed on resume. The existing download queue persists GOG operation/folder details; older queue entries keep their install behavior. Uncertain external patch operations cannot be retried as ordinary downloads. Existing sidecar choices and prefix locations are retained. Newly entitled DLC is not added automatically.

Depot updates and repair verify files, reuse matching chunks, and stage changed files on the installation filesystem. Replacements are atomic per file. There is no whole-game rollback: interrupted application keeps the journal and blocks launch until recovery. Obsolete managed files are deleted only when they still match their previous content. Untracked and modified obsolete files survive.

The native maintenance contract separates network, reused, and applied bytes. Generation 1 range downloads retain authentic hashes and never trust equal size alone. A verified Java file-download path remains available when the native library is unavailable. Free-space checks include staged replacements and transfer payloads; a full offline refresh uses a conservative size estimate.

Deltas and installers

Galaxy deltas are requested for the exact source/target pair, and used only when smaller than missing chunks. Source, payload, and reconstructed target are verified independently. Decoder errors, unsupported features, or changed source content fall back to verified chunks. Reconstruction is serialized and bounded below 64 MiB. Upstream decoder sources and notices are pinned under app/src/main/rust/stores/vendor/xdelta3; Gradle tracks those build inputs.

Offline patches preserve provider grouping and filenames. Download metadata is resolved before confirmation; no patch chain is inferred from a filename. Installer application is interactive through the selected game's Proton tool and actual prefix. A detached Linux helper owns the installer, tracks prefix children, writes durable status, and excludes cloud/achievement game-launch hooks. Registry setup uses the existing GOG script path and authentic setup payloads. Installer exit alone does not establish the installed version: the app reconciles the resulting build against a manifest and checks its files. Unverifiable results require recovery/full refresh instead of silently restoring the previous manifest. External installer cancellation belongs to the installer. Setup runs the script interpreter only when an actual GOG script exists, and registers the authentic installation path, version, and build in the selected prefix. Patch filenames are decoded from provider URLs without changing literal plus signs or multipart names. Offline refresh retains the existing executable layout and includes empty files and directories. Installers can put payload files at the extraction root while placing placeholders under app/; refresh combines both locations and verifies the selected executable before changing installed files. Installer language selection accepts the installed locale's base language and never silently chooses an unrelated language. Refresh with selected DLC also requires authentic matching depot metadata and completes the selected depots before publishing the installed record or deleting obsolete content.

Short helper status requests detect a dead installer owner or abandoned start. Session loss or suspension requires recovery; it never triggers automatic replay. The maintenance menu offers result verification for interrupted patch operations.

The same POSIX record lease excludes maintenance and game launches from DD or Steam. Session staging publishes the helper to existing Linux installations. Maintenance processes use full x87 precision. Some installers copy 64-bit data through x87 integer loads/stores; FEX's reduced-precision mode rounds those values and corrupts path strings. This override is local to maintenance and leaves the saved game performance profile unchanged. See FEX issue #5827.

References and validation

The manifest/chunk/delta approach follows heroic-gogdl. Generation 1 layout is checked against actual public Rayman 2 manifests in app/src/test/resources/gog. Setup requirements are informed by Heroic's GOG setup. The separation of depot and offline maintenance is also reflected in Lutris. innoextract extracts data; it does not run installer scripts and checks.

Automated coverage includes hash verification, moved/repeated chunk reuse, interrupted staging, corrupt deltas and fallback, generation 1 same-size corruption, path protection, multipart metadata, external patch recovery, launch leases, prefix process detection, and the Java fallback. Run Rust and Linux helper suites in WSL. JVM results, release/native/runtime-input checks, CI results, and actual-device evidence must be reported separately in the PR.

Thor testing has verified a real Rayman 2 depot update, repair of deliberately corrupted Rayman content, process-death download recovery, shared Java/Linux launch exclusion, and a Neo Cab repair on external SD storage with its sidecar unchanged. The owned ELDERBORN 1.08-to-1.09 standalone patch initially failed with Path not found: a Wine file trace showed corrupted path characters under reduced x87 precision. With full precision, the actual patch completed through DD's normal installer UI, returned zero, and its files matched all 381 entries in target build 55745895026856358. The saved performance configuration was byte-for-byte unchanged. The patched game then reached its main menu through the existing Steam shortcut; its process used the ordinary reduced-precision setting rather than the installer's full-precision override. The original sidecar remained identical and the operation journal cleared after verification. Rayman 2 also launches through its existing Steam shortcut after maintenance and reaches its interactive language menu. Its existing cloud download remains on the ordinary game-launch path; patch execution bypasses that path.