NotAlterra/docs/DECISIONS.md

Design Decisions

This file captures the rationale behind significant architecture and format choices, so the reasoning is preserved for future maintainers (including yourself six months from now).

---

Sentinel File vs config.ini (v0.3.2)

Problem

config.ini persisted the save folder path to disk, including the user's filesystem-username. This is a privacy concern — paths are visible next to the binary.

Decision

Remove config.ini entirely. The save folder is session-only — set it each time via Set save folder. The disclaimer acceptance is tracked via a 0-byte sentinel file (NotAlterra_LICENSE_ACCEPTED) alongside the binary.

Rationale

Privacy — no paths written to disk. The save folder exists only in memory while the tool runs.

Simplicity — no config parsing, no INI format to maintain, no migration code for renamed keys.

Sentinel, not config — a 0-byte file communicates exactly one boolean (disclaimer accepted). It cannot grow into a configuration file over time. The format intentionally prevents scope creep.

What was removed:

• AppConfig struct (save_path, ini_path, save_scan, disclaimer_accepted)
• load_config() / save_config() with INI parsing
• Cached ini_path — now derived from save folder at runtime
• Four integration tests for config round-trips

---

Manual Path Entry vs Auto-Discovery (v0.3.0)

Problem

Auto-discovery scanned user profiles and system directories for Subnautica 2 save folders. This is a privacy concern — it traverses /home/* (Linux) and C:\Users\* (Windows).

Decision

Replace full auto-discovery with manual path entry via Set save folder. Keep a lightweight quick_discover() that checks only the current user's default install paths at startup.

Rationale

Privacy — no scanning of other users' profiles or system drives.

Current-user convenience — quick_discover() checks 1 path on Windows, 3 paths on Linux, all within the current user's own directories. Returns the first match silently, no UI. If nothing is found, the user enters their path manually.

Discovery module retained — validate_custom_path() and derive_ini_path() still live in discovery.rs for the manual entry flow. The aggressive scan functions (discover_save_folders(), scan_other_users(), walk_for_subnautica()) are removed.

---

tar.gz Backup Format (v0.4.0)

Problem

Directory-tree backups (NotAlterra_Backups/notalterra_copy_<timestamp>/) are messy, uncompressed, and have no integrity guarantees.

Decision

One tar.gz archive per backup event, stored in backups/saves/.

Rationale

No vendor lock-in — standard tar -xzf recovers data without the tool. If NotAlterra stops working, the user's backups are still accessible with standard system utilities.

Single file per event — reduces clutter. One backup = one file, not a directory tree with 15+ loose save files.

Compression — save files compress well (~75MB → ~20MB). Reduces disk usage without user effort.

Pure Rust implementation — tar + flate2 crates, 200M+ downloads combined. No system dependencies, no external tools.

Per-entry restore — extracting a single save file from the archive does not require decompressing the entire archive.

Safeguards

• Atomic write: backup written to .tmp file, then atomically renamed. Power loss during backup discards a temp file, not a real backup.
• Integrity check after creation: archive is read back and validated before reporting success.
• SHA256 manifest: a MANIFEST file inside each archive records the hash of every contained save file. On restore, each extracted file is verified against its expected hash — silent bit-rot detected before bad data reaches the save folder.
• Fuzz target: round-trip fuzzing (create archive from diverse inputs → restore → compare) catches logic bugs.

Migration

Existing NotAlterra_Backups/ directory-tree backups are detected and transparently imported on first run after upgrade. No manual migration required.

---

GVAS Heuristic Parser vs Structural Walker (v0.4.0)

Problem

The GVAS save-file parser in src/gvas.rs uses byte-scanning to find property names as raw string patterns. It does not walk the full UE5 GVAS schema tree. This means:

• Properties the scanner isn't written to look for are silently skipped
• Byte sequences that happen to match a property name can produce false positives (mitigated by validating the preceding length field)
• Overall GVAS structure (header magic, version, property ordering) is not validated

The GVAS format is defined by the public Unreal Engine 5 source code — the SaveGame system and its binary serialization are part of the engine's open API.

Decision

Keep the heuristic byte-scan parser. Marked as Won't fix.

Rationale

No published schema — Unknown Worlds does not publish the GVAS property layout for Subnautica 2. A structural walker would require reverse- engineering the full property type system without ground truth.

No user-facing benefit — the tool reads six properties (SlotName, DisplayName, bIsMultiplayerSave, playtime, etc.) for display purposes. The byte-scan finds all of them reliably on known save files. A structural walker would produce the same output.

Graceful degradation — when the scanner cannot find a property, the picker falls back to the filename. The tool never crashes or presents incorrect data.

Fuzz coverage — three fuzz targets (parse_gvas, full_metadata, backup_roundtrip) verify the parser does not panic on adversarial input. If a future game update changes the binary layout, fuzzing will catch it.

---

Dead-Code Cleanup (v0.4.0)

Problem

src/main.rs had #![allow(dead_code)] at the crate level, silencing compiler warnings for four unused functions. This prevented the compiler from flagging real dead code.

Decision

Remove _game_running_windows() and _backup_root(). Retain _game_running_linux() and available_space() for planned future use.

Rationale

Removed:

• _game_running_windows() — process detection via tasklist was intentionally disabled across the project to avoid Windows Defender false positives (Trojan:Win32/Wacatac.C!ml). The startup reminder modal is the replacement. No plan to re-enable.
• _backup_root() — returned the legacy NotAlterra_Backups/ path, replaced by backups/saves/ and backups/config/ in v0.4.0.

Retained (each with its own #[allow(dead_code)]):

• _game_running_linux() — kept for possible opt-in process detection on Linux where AV false positives are not a concern.
• available_space() — kept for a planned disk-space warning before backup operations.

---

Persistent app.ini vs Session-Only Paths (v0.4.1)

Problem

Save-folder and backup-root paths were session-only — re-entered each time the tool launched. This was a deliberate privacy choice (v0.3.2), but in practice users expected paths to persist between sessions.

Decision

Persist both paths to app.ini under the platform config directory (data_local_dir/NotAlterra/config/). Backup data stays in ~/NotAlterra/backups/ (user-facing, not in AppData).

Rationale

Usability — re-entering paths every session was friction with no real privacy benefit. The paths already existed on the user's filesystem; persisting them simply saves keystrokes.

Transparency, not silence — instead of claiming "no data stored," the documentation now accurately describes what is stored (save-folder and backup-root paths, which may contain the system username), why (minimal convenience data), and that it never leaves the machine.

Platform standards — config goes to the OS-designated config directory (AppData/Local on Windows, ~/.local/share on Linux). User-facing backup data stays in the home directory where users expect to find it. This separation is standard convention.

Plain text, user-controlled — app.ini is a simple key=value file. Users can inspect or delete it at any time. No binary format, no registry, no opaque storage.

---

No CLI Flags for Automation (v0.4.3 → v0.5.0)

Problem

The v0.4.0 roadmap listed CLI flags (--backup, --extract, --inspect, --list) as a planned feature. These would allow scripting and cron-driven backups without the TUI.

Decision

Removed from the roadmap. Will not implement.

Rationale

TUI is the feature. The file picker with live metadata preview, split layout, pip navigation, and archive integrity checks IS the interface. Dumping raw metadata to stdout or parsing command-line flags for a non-interactive backup loses all the value the tool provides.

No demand. The tool serves a single user (you). You interact with it through the TUI. There is no automation use case driving this feature.

Overengineered for scope. Adding CLI parsing, non-interactive modes, and a separate output formatter would nearly double the surface area for a feature neither the maintainer nor any hypothetical user would use.

Previous error: The CLI flags were carried over as an assumption from "every CLI tool should have flags" without questioning whether they serve the tool's actual purpose. They don't. This decision documents that realization.