Add audit documentation and enhance two-way sync handling

- Introduced a comprehensive audit guide for the production-grade sync feature, detailing the evaluation criteria for round-trip identity and code quality.
- Added a new plan for auditing the two-way sync Ref property feature, outlining specific tasks and expected behaviors.
- Updated `ServeSession.lua` to include the instance map in patch updates, ensuring accurate property encoding.
- Enhanced `encodeInstance.lua` to prevent encoding Ref properties during instance addition, delegating this to the patch update process.
- Implemented regression tests to highlight known limitations in Ref handling, ensuring better coverage and identification of existing bugs.

These changes improve the clarity of the sync feature's audit process and strengthen the handling of Ref properties in the system.

src/syncback/meta.rs

@@ -90,6 +90,54 @@ pub fn remove_model_name(model_path: &Path) -> anyhow::Result<RemoveNameOutcome>
     Ok(RemoveNameOutcome::FieldRemoved)
 }
 
+/// Update `Rojo_Ref_*` attribute paths in a meta/model JSON5 file.
+///
+/// For each attribute whose key starts with `Rojo_Ref_` and whose string
+/// value starts with `old_prefix`, replaces the prefix with `new_prefix`.
+/// Returns true if any attribute was updated.
+pub fn update_ref_paths_in_file(
+    file_path: &Path,
+    old_prefix: &str,
+    new_prefix: &str,
+) -> anyhow::Result<bool> {
+    use crate::REF_PATH_ATTRIBUTE_PREFIX;
+
+    if !file_path.exists() {
+        return Ok(false);
+    }
+
+    let bytes = match fs::read(file_path) {
+        Ok(b) => b,
+        Err(_) => return Ok(false),
+    };
+    let mut val = match crate::json::from_slice::<serde_json::Value>(&bytes) {
+        Ok(v) if v.is_object() => v,
+        _ => return Ok(false),
+    };
+
+    let mut updated = false;
+    if let Some(attrs) = val.get_mut("attributes").and_then(|a| a.as_object_mut()) {
+        for (key, value) in attrs.iter_mut() {
+            if key.starts_with(REF_PATH_ATTRIBUTE_PREFIX) {
+                if let Some(path_str) = value.as_str() {
+                    if path_str == old_prefix || path_str.starts_with(&format!("{old_prefix}/")) {
+                        let new_path = format!("{new_prefix}{}", &path_str[old_prefix.len()..]);
+                        *value = serde_json::Value::String(new_path);
+                        updated = true;
+                    }
+                }
+            }
+        }
+    }
+
+    if updated {
+        let content = crate::json::to_vec_pretty_sorted(&val)?;
+        fs::write(file_path, &content)?;
+    }
+
+    Ok(updated)
+}
+
 /// Remove the `name` field from a `.meta.json5` file.
 ///
 /// If the file becomes an empty object after removal, deletes it entirely.

src/syncback/ref_properties.rs

@@ -10,8 +10,8 @@ use rbx_dom_weak::{
 };
 
 use crate::{
-    ref_attribute_name, syncback::snapshot::inst_path, REF_ID_ATTRIBUTE_NAME,
-    REF_PATH_ATTRIBUTE_PREFIX, REF_POINTER_ATTRIBUTE_PREFIX,
+    ref_attribute_name, ref_target_attribute_name, syncback::snapshot::inst_path,
+    REF_ID_ATTRIBUTE_NAME, REF_PATH_ATTRIBUTE_PREFIX, REF_POINTER_ATTRIBUTE_PREFIX,
 };
 
 pub struct RefLinks {
@@ -248,7 +248,7 @@ pub fn link_referents(links: RefLinks, dom: &mut WeakDom) -> anyhow::Result<()>
                 let id =
                     get_existing_id(target).expect("all ID-based targets should have an ID by now");
                 id_attrs.push((
-                    format!("{REF_POINTER_ATTRIBUTE_PREFIX}{}", link.name),
+                    ref_target_attribute_name(&link.name),
                     Variant::String(id.to_owned()),
                 ));
             }

src/syncback/snapshot.rs

@@ -373,7 +373,8 @@ pub fn filter_out_property(inst: &Instance, prop_name: &str) -> bool {
 }
 
 pub fn inst_path(dom: &WeakDom, referent: Ref) -> String {
-    dom.full_path_of(referent, "/")
+    // Use ref_target_path which handles escaping "/" in instance names
+    crate::ref_target_path(dom, referent)
 }
 
 #[cfg(test)]