# /audit - Production-Grade Sync Feature Audit **Mode:** This command runs in **Plan mode** (read-only). It does NOT directly apply code changes. The deliverable is a `.cursor/plans/*.plan.md` file containing every approved fix, ready to be executed in a subsequent Agent-mode session. **Workflow:** Analyze -> Report -> Quiz user on each fix -> Write plan file. ## Prerequisites Before beginning the audit, read `.cursor/rules/atlas.mdc` for the project's quality standards, architecture overview, and code conventions. The two standards below are extracted from that file and govern every audit finding: ### The Invariant (from `atlas.mdc` §Quality Standard) > **Round-trip identity:** Syncback (or two-way sync) writes a directory tree. Building an rbxl from that directory tree and forward-syncing it back must produce a bit-identical instance tree -- same names, same classes, same properties, same hierarchy, same ref targets. Any deviation is a bug. A "works most of the time" finding is NOT acceptable. If there is ANY code path where an instance name, property, or hierarchy relationship can be lost, mangled, or silently altered through a syncback/two-way-sync -> rebuild cycle, flag it as **critical**. ### CLI Syncback Parity (from `atlas.mdc` §Two-Way Sync Strategy) > Plugin-based sync must produce **exactly the same filesystem output** that `atlas syncback` would give for the same input. Byte-for-byte identical files, identical directory structures, identical naming. Any divergence between the two-way sync path and the CLI syncback path is a bug until proven otherwise. The CLI syncback is the ground truth. ### Code Quality (from `atlas.mdc` §Code Quality Standard) > Watch for duplicated logic -- the same slugify/dedup/meta-update pattern copy-pasted across `change_processor.rs`, `api.rs`, `dir.rs`, `project.rs`, etc. The goal is clean, DRY code that is easy to reason about and hard to get wrong. - **Small refactor** (helper function, 2-3 call sites): flag it and include it in the fix plan. - **Major rewrite** (10+ call sites, pipeline redesign): flag it in a "Deferred Refactors" section of the plan. --- ## Sync System Layout The auditor MUST read the relevant files from each pipeline when tracing round-trip identity. This section maps every file involved in both sync systems. Read these files -- do not skip any that are in the scope of the feature being audited. ### CLI Syncback Pipeline (`atlas syncback`) One-shot command: reads a Roblox binary/XML file, diffs it against the existing project tree, and writes the result to the filesystem. ``` CLI Entry └── src/cli/syncback.rs Entry point. Loads project, reads .rbxl/.rbxm, creates ServeSession for existing tree, calls syncback_loop(), writes FsSnapshot to disk. Syncback Core ├── src/syncback/mod.rs Main orchestration. syncback_loop() runs the full │ pipeline: compile ignore patterns, prune unknown │ children, filter hidden services, collect/link │ referents, hash trees, process snapshots recursively. ├── src/syncback/snapshot.rs SyncbackSnapshot struct. Carries instance + path + │ middleware context through the pipeline. Methods: │ with_joined_path(), get_path_filtered_properties(). ├── src/syncback/file_names.rs Filename generation. slugify_name() replaces forbidden │ chars with '_'. deduplicate_name() appends ~1, ~2 on │ collision. name_for_inst() is the main entry point. │ adjacent_meta_path() computes .meta.json5 paths for │ scripts (strips .server/.client suffixes from stem). ├── src/syncback/property_filter.rs Property filtering. filter_properties() removes Name, │ Parent, Source (scripts), Value (StringValue), Contents │ (LocalizationTable), Ref/UniqueId, unscriptable props. ├── src/syncback/ref_properties.rs Ref property resolution. collect_referents() finds all │ Ref properties. link_referents() writes Rojo_Ref_* or │ Rojo_Target_* attributes. Path-based preferred, falls │ back to ID-based for ambiguous paths. ├── src/syncback/hash/mod.rs Content hashing. hash_tree() hashes entire tree bottom- │ └── src/syncback/hash/variant.rs up with blake3. hash_instance() hashes class + filtered │ properties + children hashes. Ref properties hashed as │ paths, not raw Refs. ├── src/syncback/fs_snapshot.rs Filesystem operation buffer. FsSnapshot collects added │ files/dirs and removed files/dirs. write_to_vfs_parallel() │ creates dirs (sequential), writes files (parallel with │ retry on Windows), removes files (parallel), removes │ dirs (sequential). ├── src/syncback/meta.rs Meta/model file helpers. upsert_meta_name() / remove_ │ meta_name() for .meta.json5. upsert_model_name() / │ remove_model_name() for .model.json5. update_ref_paths_ │ in_file() updates Rojo_Ref_* attribute paths. └── src/syncback/stats.rs Statistics tracking for syncback operations. Snapshot Middleware (syncback direction: instance → filesystem) ├── src/snapshot_middleware/mod.rs Dispatcher. Middleware enum routes to handler. │ get_best_middleware() selects middleware for an instance. │ Each middleware has syncback() producing SyncbackReturn │ { fs_snapshot, children }. ├── src/snapshot_middleware/dir.rs Directory handler. syncback_dir() processes children, │ creates init.meta.json5, handles .gitkeep for empty dirs. │ syncback_dir_no_meta() handles child dedup and recursion. ├── src/snapshot_middleware/lua.rs Script handler. syncback_lua() for file-based scripts, │ syncback_lua_init() for directory-based (init.luau). │ Extracts Source property into file body, remaining props │ go into adjacent .meta.json5. ├── src/snapshot_middleware/json_model.rs Model handler. syncback_json_model() recursively converts │ instance tree into .model.json5. Name stored inline in │ the model file, NOT adjacent meta. ├── src/snapshot_middleware/meta_file.rs Meta file types. AdjacentMetadata (file.meta.json5) and │ DirectoryMetadata (init.meta.json5). Handles property/ │ attribute overlay, $id, name override. ├── src/snapshot_middleware/project.rs Project handler. syncback_project() updates .project.json5 │ with instance properties. Handles nested projects. ├── src/snapshot_middleware/csv.rs CSV handler. Extracts Contents → .csv file. ├── src/snapshot_middleware/txt.rs Text handler. Extracts Value → .txt file. ├── src/snapshot_middleware/rbxm.rs Binary model. Serializes instance tree → .rbxm. ├── src/snapshot_middleware/rbxmx.rs XML model. Serializes instance tree → .rbxmx. ├── src/snapshot_middleware/json.rs JSON data → ModuleScript. ├── src/snapshot_middleware/toml.rs TOML data → ModuleScript. ├── src/snapshot_middleware/yaml.rs YAML data → ModuleScript. └── src/snapshot_middleware/util.rs Shared utilities (PathExt). Binary/XML Parsing (rbx-dom submodule) ├── rbx-dom/rbx_binary/ rbx_binary::from_reader() parses .rbxl/.rbxm → WeakDom. │ rbx_binary::to_writer() serializes WeakDom → binary. └── rbx-dom/rbx_xml/ rbx_xml::from_reader() / to_writer() for .rbxlx/.rbxmx. ``` ### Two-Way Sync Pipeline (`atlas serve` + Studio Plugin) Live bidirectional sync. The plugin detects Studio changes and sends them to the server (Plugin → Server), and the server detects filesystem changes and pushes them to the plugin (Server → Plugin). ``` PLUGIN → SERVER (Studio changes written to filesystem) ====================================================== Change Detection (Plugin) ├── plugin/src/InstanceMap.lua Tracks Studio instances. __connectSignals() connects │ Changed events (or GetPropertyChangedSignal for │ ValueBase). Fires onInstanceChanged callback. │ Guards: skips if paused, if RunService:IsRunning(). └── plugin/src/Settings.lua User settings. oneShotSync blocks outgoing writes. twoWaySync enables/disables the feature entirely. Change Batching (Plugin) ├── plugin/src/ChangeBatcher/init.lua Batches changes on 200ms interval. add() records │ property change. __cycle() runs on RenderStepped, │ __flush() converts pending → PatchSet. pause()/resume() │ prevents feedback loops during reconciliation. ├── plugin/src/ChangeBatcher/createPatchSet.lua │ Converts pending property changes → PatchSet. Parent │ changed to nil → removed. Otherwise → encodePatchUpdate. │ syncSourceOnly mode filters to Source property only. ├── plugin/src/ChangeBatcher/encodePatchUpdate.lua │ Encodes property updates for existing instances. Handles │ Name changes, Ref properties (with deferral for unresolved │ targets), other properties via encodeProperty. ├── plugin/src/ChangeBatcher/encodeProperty.lua │ Encodes a single property value using RbxDom.EncodedValue. │ encode(). Maps Roblox values to wire format. ├── plugin/src/ChangeBatcher/encodeInstance.lua │ Full instance encoding for additions. Duplicate detection │ (skips instances with duplicate-named siblings). │ Recursive children encoding. Attributes/Tags support. └── plugin/src/ChangeBatcher/propertyFilter.lua Filters which properties are synced. Controls which data types and property names are included/excluded. Session & Transport (Plugin) ├── plugin/src/ServeSession.lua Orchestrates the session. onInstanceChanged → guards │ __twoWaySync, calls ChangeBatcher:add(). onChangesFlushed │ → guards oneShotSync, calls ApiContext:write(). Also │ handles __confirmAndApplyInitialPatch (confirmation │ dialog flow -- a SECOND entry point for encodePatchUpdate). ├── plugin/src/ApiContext.lua HTTP client. write(patch) encodes PatchSet as MessagePack │ via Http.msgpackEncode(), POSTs to /api/write. ├── plugin/src/PatchSet.lua PatchSet data structure: { removed, added, updated }. │ Utility functions for combining and inspecting patches. └── plugin/src/PatchTree.lua Tree structure for patch visualization in the UI. Server Write Processing (receives plugin writes) ├── src/web/api.rs /api/write endpoint. handle_api_write() deserializes │ MessagePack → WriteRequest. Processes in order: │ (1) removals → syncback_removed_instance() deletes files. │ (2) additions → syncback_added_instance() creates files. │ (3) updates → syncback_updated_properties() writes meta/ │ model files. Sends PatchSet to tree_mutation_sender. │ CRITICAL: file writes and PatchSet must stay consistent. ├── src/change_processor.rs handle_tree_event() receives PatchSet from api.rs. │ Processes removals (tree update), updates (Source writes, │ renames with slugify/dedup/meta lifecycle, ClassName │ transitions), additions (tree insert). Applies patch via │ apply_patch_set(). Broadcasts via message_queue. └── src/serve_session.rs Server-side session. Owns RojoTree, ChangeProcessor, MessageQueue. Coordinates serve lifecycle. SERVER → PLUGIN (Filesystem changes pushed to Studio) ===================================================== Filesystem Watching (Server) ├── crates/memofs/src/lib.rs VFS abstraction. Vfs struct with file watching, │ caching, event_receiver() for change events. ├── crates/memofs/src/std_backend.rs Real filesystem backend using notify crate. Debounced │ file watching, cross-platform support. └── src/change_processor.rs handle_vfs_event() processes VFS events. apply_patches() finds affected instance IDs, re-snapshots, computes diff via compute_patch_set(). reconcile_tree() does full re-snapshot 200ms after events to correct drift. suppress_path() prevents echo from API writes. Snapshot Generation (Server, forward-sync direction: filesystem → instance) ├── src/snapshot_middleware/mod.rs snapshot_from_vfs() reads filesystem → InstanceSnapshot. │ Detects directories (checks for init.* files), applies │ user sync rules + default rules, dispatches to handler. ├── src/snapshot_middleware/dir.rs snapshot_dir() reads directory → Folder snapshot. │ Recurses into children, applies init.meta.json5. ├── src/snapshot_middleware/lua.rs snapshot_lua() reads .luau → Script snapshot. Reads │ adjacent .meta.json5 for properties/attributes. │ snapshot_lua_init() for init scripts (usurps parent dir). ├── src/snapshot_middleware/json_model.rs snapshot_json_model() reads .model.json5 → instance tree. ├── src/snapshot_middleware/meta_file.rs Parses .meta.json5 files. AdjacentMetadata and │ DirectoryMetadata types used as overlays. ├── src/snapshot_middleware/project.rs snapshot_project() reads .project.json5. Resolves nodes, │ infers class names for services, merges $properties. └── (other middleware: csv.rs, txt.rs, json.rs, toml.rs, yaml.rs, rbxm.rs, rbxmx.rs) Patch & Delivery (Server) ├── src/snapshot/patch_compute.rs compute_patch_set() diffs old snapshot vs tree → │ PatchSet. Matches children by name+class. Handles │ ref property rewriting (snapshot IDs → instance IDs). ├── src/snapshot/patch_apply.rs apply_patch_set() applies PatchSet to RojoTree → │ AppliedPatchSet. Deferred ref resolution (path-based │ and ID-based). Cleans Rojo_Ref_*/Rojo_Target_*/Rojo_Id │ from Attributes before sending to plugin. ├── src/message_queue.rs MessageQueue batches and queues AppliedPatchSets. │ subscribe(cursor) returns receiver. Cursor system │ allows reconnection recovery. └── src/web/api.rs WebSocket endpoint. handle_websocket_subscription() sends AppliedPatchSets as MessagePack SocketPackets. Validates tree on connect, sends corrections. Patch Application (Plugin) ├── plugin/src/ApiContext.lua WebSocket client. connectWebSocket() connects to │ /api/socket/:cursor. Decodes MessagePack, validates │ session ID, routes to packet handlers. ├── plugin/src/ServeSession.lua __onWebSocketMessage() receives patches. Combines │ multiple messages into single patch. Shows confirmation │ UI if needed, pauses ChangeBatcher, applies patch. ├── plugin/src/Reconciler/applyPatch.lua applyPatch() applies PatchSet to Studio DOM. │ Removals → instanceMap:destroyId(). Additions → │ reifyInstance(). Updates → hydrate(). Deferred Refs │ applied last. Pauses instances during update. ├── plugin/src/Reconciler/reify.lua reifyInstance() creates Studio instances from virtual │ data. Recursive. Defers Ref properties. Sets Parent last. ├── plugin/src/Reconciler/hydrate.lua hydrate() matches existing Studio instances to server │ IDs by Name+ClassName. Recursive child matching. ├── plugin/src/Reconciler/decodeValue.lua decodeValue() converts encoded values → Roblox types. │ Handles Ref resolution (maps server ID → Studio instance │ via instanceMap). ├── plugin/src/Reconciler/diff.lua diff() compares virtual instance data against Studio. │ Used for confirmation dialog to show what will change. ├── plugin/src/Reconciler/setProperty.lua setProperty() applies a single property to an instance. │ Handles special cases and error recovery. ├── plugin/src/Reconciler/getProperty.lua getProperty() reads a property from an instance. │ Handles special cases for property access. └── plugin/src/Reconciler/Error.lua Error types for reconciliation failures. ``` ### Shared Infrastructure (used by both pipelines) ``` Snapshot System ├── src/snapshot/mod.rs System overview and public exports. ├── src/snapshot/instance_snapshot.rs InstanceSnapshot struct: snapshot_id, metadata, name, │ class_name, properties, children. ├── src/snapshot/metadata.rs InstanceMetadata, InstanceContext (ignore/sync rules), │ InstigatingSource (Path vs ProjectNode), SyncRule. ├── src/snapshot/tree.rs RojoTree: enhanced WeakDom with metadata. path_to_ids │ mapping, specified_id_to_refs tracking, get_instance_ │ by_path() for path-based lookups. ├── src/snapshot/patch.rs PatchSet, AppliedPatchSet, PatchAdd, PatchUpdate, │ AppliedPatchUpdate data structures. ├── src/snapshot/patch_compute.rs compute_patch_set(): diffs snapshot vs tree. └── src/snapshot/patch_apply.rs apply_patch_set(): applies patch to tree. Project System └── src/project.rs Project loading. Project, ProjectNode, PathNode types. load_fuzzy() / load_exact() for discovery. Parses sync rules, syncback rules, glob ignore patterns. VFS (Virtual Filesystem) ├── crates/memofs/src/lib.rs Vfs interface. File watching, caching, event delivery. ├── crates/memofs/src/std_backend.rs Real filesystem backend (notify crate). ├── crates/memofs/src/in_memory_fs.rs In-memory backend (used in tests). ├── crates/memofs/src/noop_backend.rs No-op backend. └── crates/memofs/src/snapshot.rs VFS snapshot types. rbx-dom (Roblox format libraries, git submodule) ├── rbx-dom/rbx_dom_weak/ WeakDom: in-memory instance tree representation. ├── rbx-dom/rbx_binary/ Binary format (.rbxl/.rbxm) read/write. ├── rbx-dom/rbx_xml/ XML format (.rbxlx/.rbxmx) read/write. ├── rbx-dom/rbx_reflection/ Property metadata and type information. └── rbx-dom/rbx_reflection_database/ Reflection database (class/property/enum definitions). Plugin Shared Modules ├── plugin/src/InstanceMap.lua Instance ID ↔ Studio instance mapping. Signal management. ├── plugin/src/PatchSet.lua PatchSet data structure and utilities. ├── plugin/src/Config.lua Protocol version, server version compatibility. ├── plugin/src/Types.lua Shared type definitions. ├── plugin/src/strict.lua Module export wrapper (strict mode enforcement). └── plugin/src/DiffUtil.lua Diff utilities for comparing instance data. ``` ### Audit Reading Order When auditing a feature, read files in this order to build understanding before tracing bugs: 1. **Shared infrastructure first:** `src/snapshot/mod.rs`, `src/snapshot/metadata.rs`, `src/snapshot/tree.rs` -- understand the data model 2. **Forward-sync path:** The relevant `src/snapshot_middleware/*.rs` file for the file type involved -- understand how filesystem becomes instances 3. **Syncback path:** `src/syncback/mod.rs`, then the relevant middleware's `syncback()` function -- understand how instances become filesystem 4. **Two-way sync server:** `src/web/api.rs` (`handle_api_write`, `syncback_*` functions), then `src/change_processor.rs` (`handle_tree_event`) -- understand how plugin writes are processed 5. **Two-way sync plugin:** `plugin/src/ChangeBatcher/` (encoding path), then `plugin/src/Reconciler/` (decoding path) -- understand both directions in the plugin 6. **File naming:** `src/syncback/file_names.rs` -- understand slugification, dedup, meta path computation 7. **Ref properties:** `src/syncback/ref_properties.rs`, `src/snapshot/patch_apply.rs` (deferred ref section) -- understand cross-instance references --- ## Instructions ### 0. Read Project Standards Read `.cursor/rules/atlas.mdc` in full. This file defines architecture, conventions, and quality bars that inform every audit step. Do not proceed without reading it. ### 1. Identify the Feature Scope **Default behavior:** Audit all changes in the current workspace against `origin/master`. This captures everything: committed branch changes, unpushed commits, staged changes, and unstaged changes. Run: ```bash git log origin/master..HEAD --oneline git diff origin/master --stat git diff origin/master ``` Read the commit log (for intent) and the full diff (for code). If the user provides plan files (via `@` reference), read those for additional context. Do NOT search for or read plan files on your own -- plans may be stale and describe outdated designs or already-fixed issues. **If the user specifies a feature or branch:** Scope the audit to that feature's changes only. From the diff, identify: - Which files were modified (plugin Lua, server Rust, test fixtures) - What the feature does (new property type support, naming change, sync flow change, etc.) - What the correct round-trip behavior should be - Which sync paths are affected (forward sync, reverse sync, two-way sync, all three) ### 2. Trace Round-Trip Identity (MOST CRITICAL) For each operation the feature introduces, trace the **complete lifecycle** through every path: #### 2a. Two-Way Sync -> Forward Sync Round-Trip Pick a concrete example. Trace: 1. **Plugin encodes** -- How does the plugin read the property/change from Studio? What format does it send to the server? What encoding is used (msgpack, JSON, etc.)? 2. **Server receives** -- How does `handle_api_write` deserialize the data? Any type conversions? 3. **Server writes to disk** -- Which function writes to the filesystem? What file format (meta.json5, model.json5, .luau, etc.)? What path computation is used? 4. **Server applies to tree** -- How is the PatchSet built? Does `apply_patch_set` handle this data type correctly? Any special-case skips (like `Ref::none()` skip in `apply_update_child`)? 5. **VFS echo prevention** -- Is `suppress_path()` called before `fs::write()` for updates? Is suppression correctly NOT used for additions? 6. **Forward sync reads** -- When the file is read back by the snapshot system, does it produce the exact same property value? Any lossy conversion? 7. **Plugin receives** -- Does `decodeValue.lua` correctly decode the value back to a Studio-compatible type? **Verify:** After the full round-trip, is the value identical? If you killed the server and ran `atlas build`, would the property have the correct value? #### 2b. Nil/Removal Round-Trip Trace what happens when the property is set to nil or removed: - Plugin encoding of nil values - Server handling (property removal vs. nil sentinel) - Filesystem representation (attribute removed? file deleted? empty value?) - Forward sync behavior (absent property = default value?) #### 2c. Change/Update Round-Trip Trace what happens when the value changes from A to B: - Does the old value get properly overwritten? - Any merge conflicts with existing file content? - Ordering issues (removal before addition? addition before removal?) #### 2d. Rename/Move Interactions Trace what happens when an instance involved in the feature is renamed or moved: - Do stored paths/references become stale? - Does the ChangeProcessor update dependent data? - Is there a window of inconsistency during the rename? ### 3. Audit Plugin-Side Encoding Every code path in the plugin that encodes the feature's data must be checked: - **Property filter** (`propertyFilter.lua`): Is the data type correctly included/excluded? - **Patch update encoding** (`encodePatchUpdate.lua`): Does the encoding handle all cases (nil, valid, edge)? - **Instance encoding** (`encodeInstance.lua`): For newly added instances, is the data type handled correctly? Any fragile error paths (pcall catching errors instead of explicit checks)? - **Patch creation** (`createPatchSet.lua`): Are all required parameters passed through? - **All callers**: Search for ALL callers of modified functions. Any call site that was NOT updated when a function signature changed? (Use grep to find every caller.) **CRITICAL -- Lua silent argument mismatch:** In Lua/Luau, calling `foo(a, b, c)` when the function signature is `function(a, b, c, d)` does NOT produce any error -- `d` is simply `nil`. This means adding a new parameter to a function signature produces **zero errors** at callers that weren't updated. The missing argument silently becomes `nil`, and the function may take a fallback path that drops data without warning. **Grep for every caller of any modified function and verify the argument count matches.** This is the #1 source of silent data loss bugs in the plugin. **Multiple plugin entry points:** Property changes flow through the plugin via TWO separate paths: 1. **ChangeBatcher flow** (live two-way sync): `Instance.Changed` -> `InstanceMap.__connectSignals` -> `ChangeBatcher:add()` -> `createPatchSet()` -> `encodePatchUpdate()` -> `ApiContext:write()` 2. **Confirmation dialog flow** (initial sync pull): `ServeSession.__confirmAndApplyInitialPatch` -> `encodePatchUpdate()` -> `ApiContext:write()` Both paths must be audited. A function modified in path 1 may not have been updated in path 2. **Change detection signals:** `Instance.Changed` fires for all scriptable properties on regular instances, but ValueBase instances (ObjectValue, IntValue, etc.) override Changed to only fire for `Value`. The InstanceMap connects `GetPropertyChangedSignal` for `Name`, `Value`, and `Parent` on ValueBase instances. Verify the feature's data type is detected by the correct signal. ### 4. Audit Server-Side Processing Every code path in `api.rs` and `change_processor.rs`: - **Data extraction**: Is the feature's data extracted correctly from the write request? - **Path/value computation**: Are computed values correct? **Verify inverse consistency:** if you compute a value from data (e.g., `full_path_of(ref)` -> path), then resolve it back (e.g., `get_instance_by_path(path)` -> ref), do you get the same original data? Any case where the round-trip fails (e.g., instance names containing the path separator `/`)? - **Meta/model file writing**: Correct file format? Correct section (properties vs. attributes)? Merge with existing content? Creation from scratch? - **PatchSet construction**: Data included correctly? Any type conversions that lose information? - **Filter functions**: Any filter that should now pass the data type but was not updated? - **Dual write path consistency**: `handle_api_write` does TWO things: (1) writes files to disk via `syncback_updated_properties`, and (2) sends a PatchSet to the ChangeProcessor to update the in-memory tree. These MUST stay consistent. If the file write succeeds but the PatchSet doesn't include the same change (or vice versa), the tree and filesystem diverge silently. - **Processing order**: `handle_api_write` processes removals, then additions, then updates. Property writes (`syncback_updated_properties`) happen BEFORE the PatchSet is sent to the ChangeProcessor. This ordering matters: if a property change references an instance that was renamed in the same batch, the path is computed from the PRE-rename tree state. - **Sentinel values in patch system**: Check `apply_update_child` and `apply_add_child` for any data type that is silently skipped or treated as a no-op. Example: `Variant::Ref(Ref::none())` is skipped with `continue` at line 281-282 of `patch_apply.rs`. If the feature's nil/empty representation matches a sentinel, the patch system may silently ignore it instead of applying it. ### 5. Audit Forward-Sync Resolution The filesystem -> server -> plugin direction: - **Snapshot middleware**: Does the middleware that reads the file format correctly parse the feature's data? - **Patch computation**: Does `compute_patch_set` handle the data type? Any special-case resolution (like `compute_ref_properties` for Rojo_Ref_* attributes)? - **Patch application**: Does `apply_patch_set` correctly apply the data? Any sentinel values that are skipped? - **Attribute cleanup**: Are internal attributes (Rojo_Ref_*, Rojo_Target_*, etc.) cleaned from the Attributes property before being sent to Studio? - **Plugin decoding**: Does `decodeValue.lua` handle the type? ### 6. Audit Interactions with Existing Systems - **Legacy systems**: Does the new feature coexist with legacy systems? Priority conflicts? Duplicate data? - **Other callers**: Are there callers of modified functions from OUTSIDE the feature's scope? Were they updated? - **Shared filters/helpers**: Were shared data structures (like `UNENCODABLE_DATA_TYPES`) modified? Does this affect other code paths that import them? ### 7. Audit Meta File Lifecycle - **Creation**: New file with just the feature's data works? - **Merge**: Adding to existing file with other content preserves everything? - **Update**: Changing the value overwrites correctly? - **Deletion**: Removing the value cleans up correctly? Empty sections removed? - **Orphaned data**: Instance deleted -> file deleted -> no orphaned data? ### 8. Audit VFS Echo Prevention The suppression system uses per-path counters. Verify: - **Updates to existing files**: MUST call `suppress_path()` before `fs::write()` - **New instance additions**: Must NOT suppress (VFS watcher needs to pick up new files) - **All write branches**: Every branch that writes a file must be checked ### 9. Audit CLI Syncback Parity Compare two-way sync output with CLI syncback output: - Same data format on disk? - Same file placement (attributes section vs. properties)? - Same nil handling? - Shared helpers used consistently? - Any divergence is a bug per `atlas.mdc` ### 10. Audit Wire Format - **Msgpack serialization**: Does the data type survive the plugin -> server msgpack round-trip? - **Type parsing**: Does the server's deserializer correctly parse the wire format? - **Edge values**: Does nil/zero/empty round-trip correctly? ### 11. Check Sync-Specific Patterns These are patterns specific to Atlas's sync system that every audit must verify: #### 11a. The 4 File Format Branches `syncback_updated_properties` has 4 branches for writing property changes. EVERY audit must verify the feature works in ALL 4: 1. **Directory format**: `init.meta.json5` inside the instance's directory 2. **Standalone script**: adjacent `ScriptName.meta.json5` (strips `.server`/`.client`/`.plugin`/`.local`/`.legacy` suffix from stem) 3. **Model file**: inline in `.model.json5` (writes directly into the file, NOT adjacent meta) 4. **Other file types** (`.txt`, `.csv`, `.toml`): adjacent `FileName.meta.json5` Common bug: treating model files like scripts (writing adjacent meta instead of inline). #### 11b. Compound File Extensions `.server.luau`, `.client.luau`, `.model.json5`, `.meta.json5`, `.project.json5` are multi-part extensions that need special handling: - **Rename**: Must preserve the compound extension. The suffix list in `change_processor.rs` must include all compound parts. Missing `.model` from the suffix list caused a critical bug where `.model.json5` became `.json5` on rename. - **Meta pairing**: `Foo.server.luau` pairs with `Foo.meta.json5` (NOT `Foo.server.meta.json5`). Script suffixes are stripped from the stem before computing the meta path. - **Model files store `name` inline**: `.model.json5` has `"name"` in the root JSON object. `.meta.json5` has `"name"` as a top-level field. These are different locations. #### 11c. InstigatingSource Every instance in the RojoTree tracks where it came from: - `InstigatingSource::Path(PathBuf)` -- created from a file, can be written back - `InstigatingSource::ProjectNode { path, name, node, parent_class }` -- defined in project file, CANNOT be modified via two-way sync **Verify:** Does the feature correctly guard against writing to ProjectNode instances? Is `InstigatingSource` set correctly for new instances created by the feature? #### 11d. Pre-seeding Dedup Sets When adding instances, `sibling_slugs` (or `taken_names`) must be seeded from existing tree children via their `instigating_source` paths (not instance names). This prevents slug collisions with existing files on disk. **Verify:** Does the feature seed the dedup set correctly? Does it use `strip_middleware_extension` to derive the dedup key from filesystem paths? #### 11e. Init File Detection `init.luau`, `init.server.luau`, etc. inside directories make the directory represent the script instance. When auditing: - **Renames**: Renaming a directory instance must rename the directory AND its init file path. The meta file is `init.meta.json5` inside the directory. - **Deletions**: Deleting a directory instance deletes the entire directory. Also clean up adjacent `DirName.meta.json5` at the grandparent level. - **Property writes**: Properties for directory instances go into `init.meta.json5` inside the directory, NOT an adjacent file. #### 11f. File-to-Folder and Folder-to-File Transitions Instances can flip between single-file representation (e.g., `Script.server.luau`) and directory representation (e.g., `Script/init.server.luau` + children). This transition is one of the most fragile areas of the sync system and a persistent source of bugs. Every audit must verify: **When a file becomes a folder (child added to a file-represented instance):** - The original file is removed and replaced with a directory of the same stem - An `init.*` file is created inside the new directory with the original file's content - The meta file transitions correctly: `Script.meta.json5` (adjacent) must become `Script/init.meta.json5` (inside directory). The old adjacent meta must be removed. No duplication. - Existing properties, name overrides, and attributes from the old meta file are preserved in the new `init.meta.json5` - The directory is not duplicated (e.g., creating `Script/` when `Script/` already exists from a prior partial operation) **When a folder becomes a file (all children removed from a directory-represented instance):** - The directory is removed and replaced with a single file - `init.meta.json5` content migrates to an adjacent `Script.meta.json5` (or is dropped if empty). No orphaned `init.meta.json5` left behind. - Children are not silently lost during the collapse -- verify the child list is genuinely empty before collapsing - The init file's content becomes the new single file's content **Path indexing during transitions:** - `InstigatingSource` paths are updated to reflect the new location (file path vs. directory path) - Any in-memory path lookups (ChangeProcessor path maps, VFS entries, suppression counters) are invalidated/updated for both the old and new paths - Meta file path resolution (`get_meta_path`, `meta_path_of`, or equivalent) returns the correct path for the current representation -- not a stale path from the prior state - Model files (`.model.json5`) follow the same transition rules: inline `name` field, not adjacent meta **Round-trip identity through transitions:** - Adding a child to a file-represented instance, then removing that child, must produce a filesystem state identical to the original (same file, same meta, same content) - The transition must be idempotent: if the VFS watcher fires mid-transition, the snapshot system must not produce a corrupt intermediate state (e.g., both the old file and new directory existing simultaneously) This area has historically produced bugs including: incorrect meta file indexing after transitions, folder duplication when the old path isn't cleaned up, child loss when directory contents aren't migrated, and stale path references in the in-memory tree. Treat any code touching file-to-folder or folder-to-file transitions as high-risk. #### 11g. Atomicity and File Watcher Races When an operation involves multiple filesystem changes (delete old file + create new file, or rename + meta update), there is a window where the VFS watcher could fire between operations and produce incorrect intermediate state. **Verify:** Are multi-step operations ordered to minimize race windows? Does `suppress_path` cover all intermediate states? Could the ChangeProcessor snapshot an inconsistent state? #### 11h. Determinism Given the same instance tree, does the feature ALWAYS produce the same filesystem output? - Is child ordering stable (sorted, not random)? - Are generated identifiers (dedup suffixes, IDs) deterministic? - Non-determinism = different builds from the same source = git churn = invariant violation. #### 11i. Syncback Idempotency Running the operation twice should produce zero changes on the second run. If re-running writes the same files again (even with identical content), something is unstable. #### 11j. Edge Cases - **ProjectNode instances**: Can the feature interact with instances defined in project files? Is there a guard? - **Nested projects**: Does data span project boundaries correctly? - **Concurrent changes**: Multiple changes in one batch handled correctly? - **Non-existent targets**: Graceful handling when referenced data doesn't exist? - **Name conflicts**: Instance names with special characters (`/`, `:`, `?`, `*`, `<`, `>`, `|`, `"`, `\`) that affect the feature? - **Script type transitions**: ClassName changes (ModuleScript -> Script) cause file extension changes. Does the feature handle this? - **One-shot mode**: Does `Settings:get("oneShotSync")` correctly block the feature's outgoing writes? ### 12. Run Static Analysis Run `cargo clippy` on the modified code to catch Rust issues the audit might miss: ```bash cargo clippy --all-targets 2>&1 ``` Focus on warnings in files modified by the feature. Clippy catches: unused variables, dead code, redundant clones, suspicious patterns, missing error handling, and type conversion issues that could silently lose data. Also run `selene plugin/src` for Lua linting if plugin files were modified. ### 13. Produce the Report Structured report with: - **Critical issues** -- data loss, incorrect values, silent corruption on round-trip - **Correctness concerns** -- edge cases that might not manifest immediately - **Missing test coverage** -- specific test cases needed, prioritized by risk - **Known limitations** -- for each limitation: what it is, the concrete scenario, severity, and what fixing it would require - **Challenged limitations** -- for each limitation: what it is, user's decision (accept/fix), and if accepted, confirmation that warnings are logged and no silent corruption occurs beyond the accepted scope - **Code quality items** -- DRY violations, dead code, fragile error paths - **Deferred refactors** -- major structural improvements too large to do inline - For each issue: **file path, line numbers, description, and suggested fix** ### 14. Challenge Known Limitations Do NOT blindly accept "known limitations" from implementation plans. For every limitation that violates round-trip identity: 1. **Present each limitation to the user** using the AskQuestion tool. State: - What the limitation is - The concrete scenario where data is lost or corrupted - The severity (how likely is this to hit users?) - What fixing it would require 2. **Ask the user to explicitly confirm** it's acceptable for this release, or whether it should be fixed now. 3. **Never silently skip a round-trip violation** just because a plan document says "known limitation." Plans are written before implementation -- the user may have changed their mind, or the severity may be worse than anticipated. ### 15. Quiz User on Each Planned Fix **No code changes may be applied until the user explicitly approves each one.** After producing the report and challenging limitations, present EVERY planned fix to the user for approval before writing any code. For each fix identified in the report (bug fixes, refactors, test additions, etc.), use the **AskQuestion tool** to present: 1. **What the fix changes** -- which file(s), what code, what behavior changes 2. **Why it's needed** -- which audit finding it addresses (reference the report section) 3. **Risk assessment** -- could this fix break anything else? What's the blast radius? 4. **Options:** - **Apply** -- proceed with this fix - **Skip** -- do not apply this fix (document the reason) - **Modify** -- the user wants a different approach (wait for their input before proceeding) **Rules:** - Present fixes **one at a time** so the user can evaluate each independently - Group closely related fixes (e.g., a bug fix + its regression test) into a single question, but never bundle unrelated fixes - If the user selects "Modify," wait for their revised instructions before continuing to the next fix - After all fixes are quizzed, summarize which were approved, skipped, and modified - Only proceed to step 16 with the approved and modified fixes ### 16. Create the Fix Plan After all fixes have been quizzed and the user has made their decisions, write a plan file to `.cursor/plans/`. This plan is the deliverable of the audit -- do NOT directly apply any code changes. **Filename:** `.cursor/plans/.plan.md` (e.g., `fix_ref_round_trip_issues.plan.md`) **Plan structure:** ```markdown # > This plan was generated by `/audit` from a Plan-mode session. > Refer to `.cursor/rules/atlas.mdc` for full project standards. ## Standards These standards govern every fix in this plan. An implementer MUST read `.cursor/rules/atlas.mdc` before starting. ### Round-Trip Identity (from `atlas.mdc` §Quality Standard) Syncback (or two-way sync) writes a directory tree. Building an rbxl from that directory tree and forward-syncing it back must produce a **bit-identical instance tree** -- same names, same classes, same properties, same hierarchy, same ref targets. Any deviation is a bug. ### CLI Syncback Parity (from `atlas.mdc` §Two-Way Sync Strategy) Plugin-based sync must produce **exactly the same filesystem output** that `atlas syncback` would give for the same input. Byte-for-byte identical files, identical directory structures, identical naming. Any divergence is a bug until proven otherwise. ### Code Quality (from `atlas.mdc` §Code Quality Standard) DRY code that is easy to reason about and hard to get wrong. The same slugify/dedup/meta-update pattern should not be copy-pasted across files. Small refactors (2-3 call sites) are included as fixes. Major rewrites (10+ call sites) are deferred. ## Context <Brief summary of what was audited, which branch/feature, and the audit findings.> ## Fixes Each fix below was approved by the user during the audit quiz (step 15). Implement them in order. Each fix includes its test requirements -- a fix is not complete until its tests pass. ### Fix N: <Short title> - **Status:** Approved | Modified - **Finding:** <Which audit section identified this (e.g., "Step 2a: Round-trip identity")> - **Files:** <List of files to modify> - **Problem:** <What's wrong, with file paths and line numbers> - **Solution:** <Exact description of what to change -- specific enough to implement without re-reading the audit. For modified fixes, this reflects the user's revised approach.> - **Risk:** <Blast radius, what else could break> - **Verify round-trip:** <How to confirm this fix preserves round-trip identity -- specific test scenario> - **Verify syncback parity:** <How to confirm two-way sync output matches CLI syncback -- or "N/A" if this fix doesn't touch sync paths> - **Tests required:** - <Specific test description, which test layer (unit/integration/spec/snapshot), expected behavior> ## Skipped Fixes Documented so they aren't lost -- they may be revisited later. ### Skipped: <Short title> - **Finding:** <Audit section> - **Problem:** <What's wrong> - **Reason skipped:** <User's stated reason> ## Accepted Limitations For each limitation the user accepted in step 14: - **Limitation:** <What it is> - **Scenario:** <When data is lost/corrupted> - **User decision:** Accepted for this release - **Mitigation:** <Any warnings/logging that should be in place> ## Deferred Refactors Major structural improvements flagged during the audit that are too large to include. These should be evaluated after the fixes above are complete. - <Refactor description, affected files, estimated scope> ## Test Plan Tests are not optional. Every approved fix must have test coverage. A fix is not complete until its tests pass (or intentionally fail, for known limitations). Summary of ALL tests to be written across every fix, organized by layer. Each entry references back to the fix that requires it. ### Rust Unit Tests (`#[cfg(test)]` blocks) For isolated logic: helpers, path computation, patch compute/apply. - <test description> (Fix N) ### Rust Integration Tests (`tests/tests/`) For end-to-end server behavior: serve tests, two-way sync via `/api/write`, connected mode, syncback. - <test description> (Fix N) ### Lua Spec Tests (`.spec.lua` files) For plugin-side encoding, decoding, batching, reconciliation. - <test description> (Fix N) ### Snapshot Tests (`insta` crate) For forward-sync patch output verification. - <test description> (Fix N) ### Failing Tests for Known Limitations - <test description -- these assert correct behavior and are expected to fail> (Accepted Limitation) ## Test Rules The implementer MUST follow these rules when writing tests for this plan: ### For bugs found and fixed Every bug fix MUST have a test that: 1. Would have **FAILED** before the fix 2. **PASSES** after the fix 3. Prevents the bug from regressing ### For missing coverage identified For each "missing test coverage" gap: 1. Write the test 2. Verify it passes against the current implementation 3. If it fails, investigate -- it may have found another bug ### For known limitations (Accepted Limitations section) For each known limitation that violates round-trip identity: 1. Write a test that asserts the **correct** behavior 2. The test SHOULD FAIL against the current implementation 3. **Leave the test failing** -- do NOT mark it `#[ignore]` or fix the implementation 4. If a test unexpectedly PASSES, analyze why. If correct, keep it as free coverage 5. These tests serve as acceptance criteria for future fixes ### Scope: test every affected layer For each finding, determine which test layers are affected and write tests in ALL of them: - Does the bug manifest at the plugin level? -> Lua spec test - Does it manifest at the server level? -> Rust unit test or integration test - Does it affect the round-trip? -> Integration test with `/api/write` + filesystem verification - Does it affect forward-sync? -> Serve test with `recv_socket_packet` - Could it regress from a different code path? -> Test that code path too ## Final Step: Run CI After ALL fixes and tests are implemented, run the `/ci` command (see `.cursor/commands/ci.md`) to execute the full CI pipeline. Every fix must pass CI before the plan is considered complete. Do not skip this step. ``` ### 17. Run CI After Plan Execution After the plan has been fully executed in Agent mode (all approved fixes applied, all tests written), run the `/ci` command (`.cursor/commands/ci.md`) as the final step. The plan is not complete until CI passes clean. **Rules for the plan file:** - The plan must be **self-contained**: an implementer should be able to execute it in Agent mode by reading only the plan file and `atlas.mdc`, without re-reading the audit chat - The Standards section is mandatory -- it anchors every fix to the project's quality bars - Every fix must include `Verify round-trip` and `Verify syncback parity` fields so the implementer knows how to validate correctness - Include exact file paths and line numbers (as of the current commit) - For each fix, list the tests that must accompany it -- a fix without a test entry is incomplete - Tests for known limitations must assert the **correct** behavior (they are expected to fail against the current implementation and should be left failing) - Skipped fixes are documented with their problem description so future audits don't rediscover them - The plan file is the single source of truth for post-audit work; do not leave information only in the chat