# Rename Workflow Renaming is intentionally separate from auditing. `MiSTer_Audit.sh` only proposes changes; `MiSTer_Audit.sh` v1.4 is the mutation path. ## Audit handshake Before Preview or Apply, the updater reads `[AUDIT_METADATA]` from `/media/fat/GameLibraryAudit/MiSTer_Library_Audit.txt` and validates that the proposals came from a compatible, trustworthy audit. The updater requires the expected v1.4 audit contract, including: - audit schema version `4`; - exporter version `1.4`; - `self_check=PASS`; - `metadata_layer=MiSTer-aware`; - a recognized integrity verdict and Apply recommendation; and - the audit's exporter and hash-database SHA-1 fingerprints. It compares the recorded exporter fingerprint with the currently installed `MiSTer_Audit.sh` and the recorded database fingerprint with the currently installed `mister_hash_database.tsv`. If either changed after the audit was generated, the old proposals are considered stale and a fresh audit is required. Preview may still be useful when the audit reports warnings, but Apply is blocked unless the audit has `integrity_verdict=PASS` and an Apply recommendation that permits proceeding. `DO NOT APPLY` is enforced by the updater rather than being only a manual warning. ## Preview Preview validates the audit handshake and rebuilds a plan from `proposed_renames.csv` and, when present, `proposed_save_renames.csv`. It writes: - `/media/fat/GameLibraryAudit/apply_preview.tsv` - `/media/fat/GameLibraryAudit/apply_skipped.tsv` Candidates are skipped when the source is outside the expected games/saves root, the proposed filename is unsafe, the source is missing, the target already exists, or multiple proposals resolve to the same target. CUE game renames are disabled. ## Apply Apply runs Preview again, requires a fully passing audit, and revalidates the audit handshake immediately before file mutation. If safe candidates exist, the user must type `APPLY` exactly. Only after those checks does the updater rename files with `mv`. Each result is recorded in a timestamped manifest under: `/media/fat/GameLibraryAudit/RenameHistory/` The latest manifest is copied to `last_manifest.tsv` for rollback. This second validation means a script or database change between Preview and Apply cannot silently authorize stale proposals. ## Rollback Rollback remains intentionally independent of the current audit handshake so recovery stays available even if the auditor or database has changed since Apply. Rollback requires typing `ROLLBACK` exactly. Successful entries from the last manifest are processed in reverse order. A file is restored only when the renamed source exists and the original target path is free. ## Current implementation The auditor and updater are both **v1.4**. The previous v1.1/v1.2 mismatch has been resolved: Apply now consumes and enforces the auditor's v1.4 integrity metadata instead of relying on it only as a manual review gate. After Apply or Rollback, rerun the auditor to verify the library state. ## Curated destination moves Authoritative DAT-identified special releases use `curated_destination` during Preview/Apply. Retail/Standard games remain in their current system parent folder. Homebrew, Unlicensed, Aftermarket, Prototype, Beta, Demo/Sample, Translation, and Hack/Modified games move into the matching category subfolder. Paired saves mirror that category beneath their existing save-system folder. Missing category directories are created only during Apply after the normal audit handshake and explicit `APPLY` confirmation. Existing targets, duplicate targets, collision-blocked rows, unsafe paths, and CUE/BIN restrictions are still skipped. ## Curated filename policy For DAT-identified USA Retail/Standard ROMs, Apply keeps the ROM in the parent system folder and removes the redundant `(USA)`, `(US)`, or `(U)` region marker from the filename. Meaningful canonical qualifiers such as `(Rev 1)` remain so distinct retail variants do not collapse together. Non-retail ROM types remain in their shared category subfolders and retain canonical identifying markers such as `(Unl)`, `(Proto)`, and other release-specific qualifiers. Apply accepts `PASS WITH WARNINGS` + `SAFE TO PREVIEW (COLLISIONS SKIPPED)` only when the integrity notes are collision-only. The blocking collision rows remain excluded from the mutation plan; non-collision warnings still block Apply. ## Unknown Region Rows whose resolved region is `Unknown` are routed to `/!Unknown Region`. Apply creates the directory when necessary. This keeps uncertain-region ROMs out of the clean system parent while preserving the rule that USA Retail/Standard stays in the parent folder. Curated subfolders use a leading `!` (for example `!Prototype`, `!Unlicensed`, and `!Unknown Region`) so they sort ahead of normal ROM entries in MiSTer file lists. ## Regional retail routing Authoritative DAT region metadata controls ordinary Retail/Standard placement. USA retail remains in the clean system parent. Japan, Europe, World, Canada, Australia, Korea, and Brazil retail releases move to matching `!` folders; other known regions use `!Other Regions`. ROMs without an authoritative DAT match remain in `!Unknown Region` until identification improves. Special release categories take precedence, so a Japanese prototype remains in `!Prototype` rather than `!Japan`. ## Unknown Region safety Only hash/DAT-eligible ROMs participate in `!Unknown Region` routing. Unsupported inventory, documentation, disc media, and machine/support files stay in place without a regional rename. Unmatched eligible ROMs keep their exact current filename until a DAT match provides authoritative identity. Support/documentation rows collected during classification are retained in `support_files.csv`; report setup does not overwrite them. ## Virtual Console releases No-Intro-identified Virtual Console variants are not treated as original-system Retail/Standard copies. They retain the canonical Virtual Console qualifier and use `/!Virtual Console/`. Because release type takes precedence over geography, a USA Virtual Console build is kept out of the clean USA retail parent directory.