feat(project-system): recover malformed element files without ever rewriting them

docs/specs/001-agent-editing-toolkit/contracts/mcp-tools.md

@@ -97,7 +97,7 @@ A `session` may be **file-opened** (headless server) or **live** (in-app host bo
 
 ### `open_project`
 - **Input**: `{ "path": string }` (read — unrestricted).
-- **Output**: `{ "session": string, "source": "File", "summary": { scenes, elements, duration, frameSize } }`.
+- **Output**: `{ "session": string, "source": "File", "summary": { scenes, elements, duration, frameSize }, "warnings": string[], "recoveryIncidents": [{ "sceneId": string, "sceneName": string, "elementFile": string, "reason": "TypeNotFound" | "DeserializationFailed", "typeName": string | null, "message": string | null }] }`. `warnings` remains the presentation-oriented recovery summary; `recoveryIncidents` exposes the same incidents as stable structured data. `sceneId` and `sceneName` identify the containing scene when different scenes contain the same relative element path. `elementFile` is a forward-slash scene-relative path when available, otherwise the element name. `typeName` is the original serialized discriminator when available, otherwise `null`; `message` is the unmodified nullable deserialization error rather than a presentation fallback.
 - **Errors**: `media_not_found`, `schema_version_mismatch` (project written by an incompatible schema — surfaced, not silently dropped, per FR-031/FR-013).
 
 ### `attach_active_editor` *(in-app host only)*

src/Beutl.AgentToolkit/Reconciliation/Reconciler.cs

@@ -330,6 +330,7 @@ private ReconcileResult ApplyCore(IEditingSession session, JsonObject desired, I
     {
         JsonObject desiredDocument = PrepareDesired(session, desired);
         ReconcilePlan plan = PlanPrepared(session, desiredDocument, knownNewIds);
+        Element[] affectedSuppressedElements = GetAffectedSuppressedElements(session.Root, plan);
         session.History.ExecuteInTransaction(
             () =>
             {
@@ -338,6 +339,20 @@ private ReconcileResult ApplyCore(IEditingSession session, JsonObject desired, I
                 {
                     ProjectOperations.NormalizeSidecarUrisWithinProject(scene);
                 }
+
+                foreach (Element element in affectedSuppressedElements)
+                {
+                    if (Scene.TryResumeElementPersistence(element) is { } suppression)
+                    {
+                        session.History.Record(
+                            () => element.SuppressedStorageSource = null,
+                            () =>
+                            {
+                                suppression.WasReinstated = true;
+                                element.SuppressedStorageSource = suppression;
+                            });
+                    }
+                }
             },
             "Agent edit");
 
@@ -349,6 +364,31 @@ private ReconcileResult ApplyCore(IEditingSession session, JsonObject desired, I
         return new ReconcileResult(plan, session.Documents.Read(session.Root));
     }
 
+    private static Element[] GetAffectedSuppressedElements(CoreObject root, ReconcilePlan plan)
+    {
+        if (plan.Changes.Count == 0)
+        {
+            return [];
+        }
+
+        if (root is Element { SuppressedStorageSource: not null } element)
+        {
+            return [element];
+        }
+
+        if (root is not Scene scene)
+        {
+            return [];
+        }
+
+        return scene.Children
+            .Where(static child => child.SuppressedStorageSource is not null)
+            .Where(child => plan.Changes.Any(change =>
+                change.Path.StartsWith($"$/Elements[Id={child.Id}]", StringComparison.Ordinal)
+                || string.Equals(change.TargetId, child.Id.ToString(), StringComparison.Ordinal)))
+            .ToArray();
+    }
+
     // Build the plan on the editor's dispatcher: PlanPrepared reads session.Documents/Root, so off
     // the MCP request thread it would race the live scene the editor mutates on the UI thread.
     public ReconcilePlan PlanFromCurrent(
@@ -681,21 +721,16 @@ private static CoreObject CloneCurrentRoot(IEditingSession session, JsonObject c
     private static HashSet<Guid> CollectFallbackIds(CoreObject root)
     {
         var ids = new HashSet<Guid>();
-        if (root is IHierarchical hierarchical)
+        var visited = new HashSet<object>(ReferenceEqualityComparer.Instance);
+        TraverseSerializedGraph(root, "$", visited, (node, _) =>
         {
-            foreach (IFallback fallback in hierarchical.EnumerateAllChildren<IFallback>())
+            if (node is IFallback)
             {
-                if (fallback is CoreObject coreObject)
-                {
-                    ids.Add(coreObject.Id);
-                }
+                ids.Add(node.Id);
             }
-        }
 
-        if (root is IFallback rootFallback)
-        {
-            ids.Add(((CoreObject)rootFallback).Id);
-        }
+            return false;
+        });
 
         return ids;
     }
@@ -705,112 +740,170 @@ private static HashSet<Guid> CollectFallbackIds(CoreObject root)
         string path,
         HashSet<Guid> existingFallbackIds)
     {
-        var visited = new HashSet<Guid>();
-        return FindFirstNewFallbackCore(root, path, existingFallbackIds, visited);
+        FallbackOccurrence? result = null;
+        var visited = new HashSet<object>(ReferenceEqualityComparer.Instance);
+        TraverseSerializedGraph(root, path, visited, (node, nodePath) =>
+        {
+            if (node is not IFallback fallback || existingFallbackIds.Contains(node.Id))
+            {
+                return false;
+            }
+
+            fallback.TryGetTypeName(out string? fallbackTypeName);
+            result = new FallbackOccurrence(
+                nodePath,
+                node.Id,
+                fallbackTypeName,
+                fallback.Reason.ToString(),
+                fallback.ErrorMessage);
+            return true;
+        });
+        return result;
     }
 
-    private static FallbackOccurrence? FindFirstNewFallbackCore(
-        CoreObject node,
+    private static bool TraverseSerializedGraph(
+        object? value,
         string path,
-        HashSet<Guid> existingFallbackIds,
-        HashSet<Guid> visited)
+        HashSet<object> visited,
+        Func<CoreObject, string, bool> visitCoreObject)
     {
-        if (!visited.Add(node.Id))
+        if (value is null or string)
         {
-            return null;
+            return false;
         }
 
-        if (node is IFallback fallback && !existingFallbackIds.Contains(node.Id))
+        if (!value.GetType().IsValueType && !visited.Add(value))
         {
-            fallback.TryGetTypeName(out string? fallbackTypeName);
-            return new FallbackOccurrence(
-                path,
-                node.Id,
-                fallbackTypeName,
-                fallback.Reason.ToString(),
-                fallback.ErrorMessage);
+            return false;
         }
 
-        switch (node)
+        if (value is CoreObject coreObject)
         {
-            case Scene scene:
-                for (int i = 0; i < scene.Children.Count; i++)
-                {
-                    if (FindFirstNewFallbackCore(
-                            scene.Children[i],
-                            $"{path}/Elements[{i}]",
-                            existingFallbackIds,
-                            visited) is { } occurrence)
+            if (visitCoreObject(coreObject, path))
+            {
+                return true;
+            }
+
+            switch (coreObject)
+            {
+                case Scene scene:
+                    for (int i = 0; i < scene.Children.Count; i++)
                     {
-                        return occurrence;
+                        if (TraverseSerializedGraph(
+                                scene.Children[i],
+                                $"{path}/Elements[{i}]",
+                                visited,
+                                visitCoreObject))
+                        {
+                            return true;
+                        }
                     }
-                }
-                break;
+                    break;
 
-            case Element element:
-                for (int i = 0; i < element.Objects.Count; i++)
-                {
-                    if (FindFirstNewFallbackCore(
-                            element.Objects[i],
-                            $"{path}/Objects[{i}]",
-                            existingFallbackIds,
-                            visited) is { } occurrence)
+                case Element element:
+                    for (int i = 0; i < element.Objects.Count; i++)
                     {
-                        return occurrence;
+                        if (TraverseSerializedGraph(
+                                element.Objects[i],
+                                $"{path}/Objects[{i}]",
+                                visited,
+                                visitCoreObject))
+                        {
+                            return true;
+                        }
                     }
-                }
-                break;
+                    break;
+
+                case EngineObject engineObject:
+                    foreach (IProperty property in engineObject.Properties)
+                    {
+                        if (TraverseSerializedGraph(
+                                property.CurrentValue,
+                                $"{path}/{property.Name}",
+                                visited,
+                                visitCoreObject))
+                        {
+                            return true;
+                        }
+
+                        if (property.Animation is IKeyFrameAnimation animation)
+                        {
+                            int index = 0;
+                            foreach (IKeyFrame keyFrame in animation.KeyFrames)
+                            {
+                                if (TraverseSerializedGraph(
+                                        keyFrame.Value,
+                                        $"{path}/Animations/{property.Name}/KeyFrames[{index}]/Value",
+                                        visited,
+                                        visitCoreObject))
+                                {
+                                    return true;
+                                }
+
+                                index++;
+                            }
+                        }
+                    }
+                    break;
+            }
 
-            case EngineObject engineObject:
-                foreach (IProperty property in engineObject.Properties)
+            if (coreObject is IHierarchical hierarchical)
+            {
+                int index = 0;
+                foreach (IHierarchical child in hierarchical.HierarchicalChildren)
                 {
-                    if (FindFirstNewFallbackInValue(
-                            property.CurrentValue,
-                            $"{path}/{property.Name}",
-                            existingFallbackIds,
-                            visited) is { } occurrence)
+                    if (TraverseSerializedGraph(
+                            child,
+                            $"{path}/HierarchicalChildren[{index}]",
+                            visited,
+                            visitCoreObject))
                     {
-                        return occurrence;
+                        return true;
                     }
+
+                    index++;
                 }
-                break;
-        }
+            }
 
-        return null;
-    }
+            return false;
+        }
 
-    private static FallbackOccurrence? FindFirstNewFallbackInValue(
-        object? value,
-        string path,
-        HashSet<Guid> existingFallbackIds,
-        HashSet<Guid> visited)
-    {
-        switch (value)
+        if (value is IDictionary dictionary)
         {
-            case CoreObject coreObject:
-                return FindFirstNewFallbackCore(coreObject, path, existingFallbackIds, visited);
-            case IEnumerable enumerable when value is not string:
+            int index = 0;
+            foreach (object? item in dictionary.Values)
+            {
+                if (TraverseSerializedGraph(
+                        item,
+                        $"{path}[{index}]",
+                        visited,
+                        visitCoreObject))
                 {
-                    int index = 0;
-                    foreach (object? item in enumerable)
-                    {
-                        if (FindFirstNewFallbackInValue(
-                                item,
-                                $"{path}[{index}]",
-                                existingFallbackIds,
-                                visited) is { } occurrence)
-                        {
-                            return occurrence;
-                        }
-
-                        index++;
-                    }
+                    return true;
+                }
 
-                    break;
+                index++;
+            }
+        }
+        else if (value is IEnumerable enumerable)
+        {
+            int index = 0;
+            foreach (object? item in enumerable)
+            {
+                if (TraverseSerializedGraph(
+                        item,
+                        $"{path}[{index}]",
+                        visited,
+                        visitCoreObject))
+                {
+                    return true;
                 }
+
+                index++;
+            }
         }
 
-        return null;
+        return false;
     }
 
     private static string CreateFallbackHint(FallbackOccurrence occurrence)