test: harden discovery and JSON preservation contracts (#8)

## Summary

Addresses the bounded follow-up notes from PRs #5 and #6.

- makes the experimental discovery result, observation, marker-kind, and
error contracts non-exhaustive, including record-style variants, and
documents downstream matching requirements
- strengthens discovery coverage for mixed marker kinds, error
payloads/formatting/sources, non-UTF-8 Linux filenames, and the known
trailing-separator symlink limitation
- replaces semantic-only structural deletion checks in the JSON study
with exact mutation-envelope assertions
- records exact insertion outputs across positions, compact/multiline
layouts, LF/CRLF, and unusual indentation
- records exact preservation of adversarial neighboring unknown data,
numeric lexemes, string escapes, and array contents across removal and
insertion
- updates ADR 0004 and the study ledger so their evidence claims match
the stronger tests

## Verification

- `cargo fmt --all --check`
- `cargo check --workspace --all-targets --all-features`
- `cargo test --workspace --all-targets --all-features` (43 tests passed
locally)
- `cargo clippy --workspace --all-targets --all-features -- -D warnings`
- `RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features
--no-deps`
- `git diff --check`

The invalid-byte filename fixture is Linux-only because the local macOS
filesystem rejects that filename at fixture creation time; Ubuntu CI
exercises it. Cargo continues to emit the pre-existing rustdoc
output-name collision warning between the library and CLI binary, while
the documentation command exits successfully.

## Deferred follow-up ledger

These items remain intentionally deferred because they require separate
design choices, evidence, or production seams rather than being
omissions from this hardening PR:

- typed views over retained CST nodes and the public raw/typed boundary
- stale-snapshot/hash refusal, semantic diffs, and stable resource
identity
- byte decoding and BOM policy
- scalar-replacement contracts and production mutation wrappers
- final diagnostic API and Unicode-width policy
- representative performance, dependency, and resource-limit budgets
- reproducible comparative evidence for alternative JSON representations
- broader format fixtures and production integration
- filesystem capability/root acquisition and deterministic
permission/race fault injection
- persistence, transaction, and write-safety design

Author: jasoncavinder

crates/tilewright/README.md

@@ -11,13 +11,17 @@ This crate is in early development. It currently exposes its package version and
 
 Candidate discovery identifies directories that appear to be RPG Maker MZ projects based on marker files. It does not validate the project contents.
 
+Discovery results, marker observations, marker kinds, and errors are
+non-exhaustive while this API is experimental. Downstream matches must retain a
+fallback arm and use `..` in record patterns.
+
 ```rust
 use std::path::Path;
 use tilewright::rpg_maker_mz::discovery::{discover_candidate, CandidateDiscovery};
 
 let path = Path::new("path/to/project");
 match discover_candidate(path) {
-    Ok(CandidateDiscovery::Candidate { marker }) => {
+    Ok(CandidateDiscovery::Candidate { marker, .. }) => {
         println!("Found candidate marker at: {}", marker.path.display());
     }
     Ok(CandidateDiscovery::NoMarker) => {

crates/tilewright/src/rpg_maker_mz/discovery.rs

@@ -13,9 +13,15 @@ use std::io;
 use std::path::{Path, PathBuf};
 
 /// Errors that can occur during candidate discovery.
+///
+/// This enum and its record-style variants are non-exhaustive so the
+/// experimental discovery API can add contextual failure modes and fields
+/// without making downstream matches exhaustive.
 #[derive(Debug)]
+#[non_exhaustive]
 pub enum DiscoveryError {
     /// Failed to inspect the root directory's metadata.
+    #[non_exhaustive]
     InspectRoot {
         /// The root path being inspected.
         root: PathBuf,
@@ -24,30 +30,35 @@ pub enum DiscoveryError {
     },
     /// The supplied root path is a symlink. This is a best-effort check of the
     /// final supplied path component at inspection time.
+    #[non_exhaustive]
     RootIsSymlink {
         /// The root path that was rejected.
         root: PathBuf,
     },
     /// The supplied root path is not a directory.
+    #[non_exhaustive]
     RootIsNotDirectory {
         /// The root path that was rejected.
         root: PathBuf,
     },
     /// Failed to read the contents of the root directory.
+    #[non_exhaustive]
     ReadRoot {
         /// The root directory being read.
         root: PathBuf,
         /// The underlying I/O error.
         source: io::Error,
     },
     /// Failed to read a directory entry.
+    #[non_exhaustive]
     ReadEntry {
         /// The root directory being read.
         root: PathBuf,
         /// The underlying I/O error.
         source: io::Error,
     },
     /// Failed to inspect the metadata of a potential marker entry.
+    #[non_exhaustive]
     InspectMarker {
         /// The path of the marker entry being inspected.
         path: PathBuf,
@@ -94,7 +105,11 @@ impl Error for DiscoveryError {
 }
 
 /// The kind of filesystem entry observed for a marker.
+///
+/// This enum is non-exhaustive so additional platform entry kinds can be
+/// represented without closing the experimental API prematurely.
 #[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
 pub enum MarkerEntryKind {
     /// A regular file.
     RegularFile,
@@ -107,7 +122,12 @@ pub enum MarkerEntryKind {
 }
 
 /// An observation of a potential marker entry.
+///
+/// This output record is non-exhaustive so later discovery phases can attach
+/// additional observation context without preventing callers from reading the
+/// currently exposed fields.
 #[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
 pub struct MarkerObservation {
     /// The exact path to the observed marker entry.
     pub path: PathBuf,
@@ -119,17 +139,23 @@ pub struct MarkerObservation {
 ///
 /// This API identifies candidates based on the presence of a marker file. It does
 /// not validate the project, parse its contents, or guarantee compatibility.
+/// The enum and its record-style variants are non-exhaustive so callers must
+/// retain a fallback for future experimental discovery outcomes and `..` when
+/// matching fields.
 #[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
 pub enum CandidateDiscovery {
     /// The directory contains exactly one regular file matching the expected
     /// lowercase marker name (`game.rmmzproject`).
+    #[non_exhaustive]
     Candidate {
         /// The observed marker entry.
         marker: MarkerObservation,
     },
     /// The directory contains exactly one regular file matching the marker name
     /// case-insensitively, but not exactly (e.g., `Game.rmmzproject`).
     /// This is a platform-limited case variant.
+    #[non_exhaustive]
     CaseVariantCandidate {
         /// The observed marker entry.
         marker: MarkerObservation,
@@ -138,16 +164,19 @@ pub enum CandidateDiscovery {
     NoMarker,
     /// The directory contains multiple entries matching the marker name
     /// case-insensitively.
+    #[non_exhaustive]
     AmbiguousMarkers {
         /// The observed marker entries, deterministically ordered by path.
         markers: Vec<MarkerObservation>,
     },
     /// The marker entry exists but is a symbolic link.
+    #[non_exhaustive]
     SymlinkMarker {
         /// The observed marker entry.
         marker: MarkerObservation,
     },
     /// The marker entry exists but is not a regular file or symlink (e.g., a directory).
+    #[non_exhaustive]
     NonRegularMarker {
         /// The observed marker entry.
         marker: MarkerObservation,
@@ -315,6 +344,27 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_classify_mixed_kind_ambiguity() {
+        let case_variant_directory = MarkerObservation {
+            path: PathBuf::from("Game.rmmzproject"),
+            kind: MarkerEntryKind::Directory,
+        };
+        let exact_symlink = MarkerObservation {
+            path: PathBuf::from("game.rmmzproject"),
+            kind: MarkerEntryKind::Symlink,
+        };
+
+        let result = classify_matches(vec![exact_symlink.clone(), case_variant_directory.clone()]);
+
+        assert_eq!(
+            result,
+            CandidateDiscovery::AmbiguousMarkers {
+                markers: vec![case_variant_directory, exact_symlink]
+            }
+        );
+    }
+
     #[test]
     fn test_classify_symlink() {
         let marker = MarkerObservation {
@@ -465,8 +515,16 @@ mod tests {
         let symlink_dir = temp.path().join("symlink_dir");
         symlink(&real_dir, &symlink_dir).unwrap();
 
-        let result = discover_candidate(&symlink_dir);
-        assert!(matches!(result, Err(DiscoveryError::RootIsSymlink { .. })));
+        let error = discover_candidate(&symlink_dir).unwrap_err();
+        assert!(matches!(
+            &error,
+            DiscoveryError::RootIsSymlink { root } if root == &symlink_dir
+        ));
+        assert_eq!(
+            error.to_string(),
+            format!("root path '{}' is a symlink", symlink_dir.display())
+        );
+        assert!(std::error::Error::source(&error).is_none());
     }
 
     #[cfg(windows)]
@@ -524,8 +582,16 @@ mod tests {
             panic!("Failed to create symlink: {e}");
         }
 
-        let result = discover_candidate(&symlink_path);
-        assert!(matches!(result, Err(DiscoveryError::RootIsSymlink { .. })));
+        let error = discover_candidate(&symlink_path).unwrap_err();
+        assert!(matches!(
+            &error,
+            DiscoveryError::RootIsSymlink { root } if root == &symlink_path
+        ));
+        assert_eq!(
+            error.to_string(),
+            format!("root path '{}' is a symlink", symlink_path.display())
+        );
+        assert!(std::error::Error::source(&error).is_none());
     }
 
     #[test]
@@ -620,20 +686,92 @@ mod tests {
     fn test_discover_missing_root() {
         let temp = TempDir::new().unwrap();
         let missing_path = temp.path().join("missing");
-        let result = discover_candidate(&missing_path);
-        assert!(matches!(result, Err(DiscoveryError::InspectRoot { .. })));
+        let error = discover_candidate(&missing_path).unwrap_err();
+        match &error {
+            DiscoveryError::InspectRoot { root, source } => {
+                assert_eq!(root, &missing_path);
+                assert_eq!(source.kind(), io::ErrorKind::NotFound);
+            }
+            other => panic!("expected InspectRoot, got {other:?}"),
+        }
+        assert_eq!(
+            error.to_string(),
+            format!("failed to inspect root path '{}'", missing_path.display())
+        );
+        assert_eq!(
+            std::error::Error::source(&error)
+                .and_then(|source| source.downcast_ref::<io::Error>())
+                .map(io::Error::kind),
+            Some(io::ErrorKind::NotFound)
+        );
     }
 
     #[test]
     fn test_discover_non_directory_root() {
         let temp = TempDir::new().unwrap();
         let file_path = temp.path().join("file.txt");
         File::create(&file_path).unwrap();
-        let result = discover_candidate(&file_path);
+        let error = discover_candidate(&file_path).unwrap_err();
         assert!(matches!(
-            result,
-            Err(DiscoveryError::RootIsNotDirectory { .. })
+            &error,
+            DiscoveryError::RootIsNotDirectory { root } if root == &file_path
         ));
+        assert_eq!(
+            error.to_string(),
+            format!("root path '{}' is not a directory", file_path.display())
+        );
+        assert!(std::error::Error::source(&error).is_none());
+    }
+
+    #[test]
+    fn test_discovery_read_error_contracts() {
+        let root = PathBuf::from("project");
+        let marker = root.join("game.rmmzproject");
+        let cases = [
+            (
+                DiscoveryError::ReadRoot {
+                    root: root.clone(),
+                    source: io::Error::new(io::ErrorKind::PermissionDenied, "fixture read root"),
+                },
+                format!("failed to read root directory '{}'", root.display()),
+                root.clone(),
+            ),
+            (
+                DiscoveryError::ReadEntry {
+                    root: root.clone(),
+                    source: io::Error::new(io::ErrorKind::PermissionDenied, "fixture read entry"),
+                },
+                format!("failed to read entry in directory '{}'", root.display()),
+                root.clone(),
+            ),
+            (
+                DiscoveryError::InspectMarker {
+                    path: marker.clone(),
+                    source: io::Error::new(io::ErrorKind::PermissionDenied, "fixture marker"),
+                },
+                format!("failed to inspect marker entry '{}'", marker.display()),
+                marker.clone(),
+            ),
+        ];
+
+        for (error, expected_display, expected_path) in cases {
+            match &error {
+                DiscoveryError::ReadRoot { root, .. } | DiscoveryError::ReadEntry { root, .. } => {
+                    assert_eq!(root, &expected_path)
+                }
+                DiscoveryError::InspectMarker { path, .. } => {
+                    assert_eq!(path, &expected_path);
+                }
+                other => panic!("unexpected error variant: {other:?}"),
+            }
+            assert_eq!(error.to_string(), expected_display);
+            assert_eq!(
+                std::error::Error::source(&error)
+                    .and_then(|source| source.downcast_ref::<io::Error>())
+                    .map(io::Error::kind),
+                Some(io::ErrorKind::PermissionDenied)
+            );
+        }
     }
 
     #[cfg(unix)]
@@ -657,6 +795,22 @@ mod tests {
         );
     }
 
+    #[cfg(target_os = "linux")]
+    #[test]
+    fn test_discover_non_utf8_filename_is_not_a_marker() {
+        use std::ffi::OsString;
+        use std::os::unix::ffi::OsStringExt;
+
+        let temp = TempDir::new().unwrap();
+        let invalid_name = OsString::from_vec(b"game.rmmzproject\xff".to_vec());
+        File::create(temp.path().join(invalid_name)).unwrap();
+
+        assert_eq!(
+            discover_candidate(temp.path()).unwrap(),
+            CandidateDiscovery::NoMarker
+        );
+    }
+
     #[cfg(unix)]
     #[test]
     fn test_discover_root_symlink_with_dot_is_not_rejected_known_limitation() {
@@ -676,4 +830,23 @@ mod tests {
         let result = discover_candidate(&dot_path).unwrap();
         assert!(matches!(result, CandidateDiscovery::Candidate { .. }));
     }
+
+    #[cfg(unix)]
+    #[test]
+    fn test_discover_root_symlink_with_trailing_slash_is_not_rejected_known_limitation() {
+        let temp = TempDir::new().unwrap();
+        let real_dir = temp.path().join("real_dir");
+        fs::create_dir(&real_dir).unwrap();
+        File::create(real_dir.join("game.rmmzproject")).unwrap();
+
+        let symlink_dir = temp.path().join("symlink_dir");
+        symlink(&real_dir, &symlink_dir).unwrap();
+
+        // A trailing separator requires directory resolution and causes
+        // symlink_metadata to observe the target directory rather than the link.
+        let mut trailing_slash = symlink_dir.as_os_str().to_os_string();
+        trailing_slash.push("/");
+        let result = discover_candidate(Path::new(&trailing_slash)).unwrap();
+        assert!(matches!(result, CandidateDiscovery::Candidate { .. }));
+    }
 }

docs/decisions/0004-lossless-json-representation.md

@@ -80,8 +80,9 @@ If accepted, this proposal would mean:
 
 A tracked prototype exercises the following bounded behavior:
 - **Structural edits:** Representative object and array insertions/deletions
-  remain valid. Exact assertions record selected insertion formatting and
-  layout invariants; deletion tests currently assert strict semantic validity.
+  remain valid and have exact output assertions. A combined mutation case also
+  records exact preservation of tested unknown nested data, numeric lexemes,
+  string escapes, and array contents outside the measured edit envelope.
 - **Strict syntax:** A strict AST pass with every extension disabled runs before
   CST construction. A lexical preflight rejects non-JSON whitespace and raw C0
   controls that the scanner otherwise accepts. CST construction itself preserves