pi-revit 0.2.17 → 0.3.0

package/src/Revit/ToolRegistry.cs

@@ -1,4 +1,5 @@
-using System.Text.Json;
+using System.Text.Json;
+using System.Text.Json.Nodes;
 using Autodesk.Revit.DB;
 using Autodesk.Revit.UI;
 using RevitBridge.Tools;
@@ -14,9 +15,9 @@ namespace RevitBridge
     internal sealed record ToolContext(Document? Document, UIApplication? UIApplication);
 
     /// <summary>
-    /// Optional tool return shape: compact text for model context plus the full payload for
-    /// details. Tools may instead return any plain JSON-serializable object, which the bridge
-    /// serializes into both channels (capped in content).
+    /// Optional tool return shape: complete structured payload plus a display summary.
+    /// The bridge/extension expose complete bounded data or explicit result retrieval to
+    /// the model; structured details remain available for rendering and diagnostics.
     /// </summary>
     internal sealed record ToolOutput(object? Payload, string? CompactText = null);
 
@@ -99,12 +100,36 @@ namespace RevitBridge
             description = tool.Description,
             category = tool.Write ? "write" : "read",
             tier = tool.Tier,
-            parameters = tool.ParametersSchema,
+            parameters = DescribeParameters(tool),
             executionMode = "sequential",
             write = tool.Write,
             requiresDocument = tool.RequiresDocument,
             promptSnippet = tool.PromptSnippet,
-            promptGuidelines = tool.PromptGuidelines,
-        };
+            promptGuidelines = tool.RequiresDocument
+                ? (tool.PromptGuidelines ?? Array.Empty<string>()).Concat(new[]
+                {
+                    $"{tool.Name}: use project.documentId from get_model_overview as expected_document_id to bind the call to that exact open document. It is required for model writes, open_view, and selection changes; legacy expected_document titles alone are insufficient. Refresh after closing/reopening or restarting Revit."
+                }).ToArray()
+                : tool.PromptGuidelines,
+        };
+
+        private static object DescribeParameters(ITool tool)
+        {
+            if (!tool.RequiresDocument) return tool.ParametersSchema;
+            var schema = JsonSerializer.SerializeToNode(tool.ParametersSchema)!.AsObject();
+            var properties = schema["properties"]!.AsObject();
+            properties["expected_document_id"] = new JsonObject
+            {
+                ["type"] = "string",
+                ["description"] = "Exact opaque project.documentId from get_model_overview. Required for document writes and UI mutations; optional for reads. Invalid after close/reopen or bridge restart."
+            };
+            if (DocumentGuard.AlwaysRequiresIdentity(tool.Name))
+            {
+                var required = schema["required"] as JsonArray ?? new JsonArray();
+                if (!required.Any(x => x?.GetValue<string>() == "expected_document_id")) required.Add("expected_document_id");
+                schema["required"] = required;
+            }
+            return schema;
+        }
     }
 }

package/src/Revit/Tools/DocumentGuard.cs

@@ -0,0 +1,64 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+/// <summary>Opaque identity of one open native document in this loaded bridge session.</summary>
+internal static class DocumentGuard
+{
+    private sealed record Identity(Document Document, string Value);
+    private static readonly string Generation = Guid.NewGuid().ToString("N");
+    private static readonly List<Identity> Identities = new();
+
+    public static string GetIdentity(Document document)
+    {
+        if (!document.IsValidObject)
+            throw new ArgumentException("The target document is closed or invalid. Read get_model_overview again.");
+        // Revit can supply multiple managed wrappers for the same native document.
+        // Its documented Equals semantics identify that native document; reference identity cannot.
+        // All accesses happen on the Revit API thread. Pruning avoids retaining closed documents.
+        Identities.RemoveAll(entry => !entry.Document.IsValidObject);
+        var existing = Identities.FirstOrDefault(entry => entry.Document.Equals(document));
+        if (existing != null) return existing.Value;
+        var created = new Identity(document, Generation + ":" + Guid.NewGuid().ToString("N"));
+        Identities.Add(created);
+        return created.Value;
+    }
+
+    public static bool AlwaysRequiresIdentity(string toolName)
+        => toolName is "set_parameters" or "execute_csharp" or "export_documents" or "open_view";
+
+    /// <summary>Must run on the Revit API thread immediately before the tool action.</summary>
+    public static void CheckForTool(JsonElement args, Document document, string toolName)
+    {
+        bool required = AlwaysRequiresIdentity(toolName)
+            || (toolName == "manage_selection"
+                && (!string.Equals((JsonArgs.GetString(args, "action") ?? "get").Trim(), "get", StringComparison.OrdinalIgnoreCase)
+                    || JsonArgs.GetBool(args, "isolate_in_view", false)));
+        if (required && !args.TryGetProperty("expected_document_id", out _))
+            throw new ArgumentException("expected_document_id is required for this operation. Read project.documentId from get_model_overview for the intended open document and pass it unchanged. A title alone cannot identify a document. No action was performed.");
+        CheckExpectedDocument(args, document);
+    }
+
+    public static void CheckExpectedDocument(JsonElement args, Document document)
+    {
+        if (args.TryGetProperty("expected_document_id", out var id))
+        {
+            if (id.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(id.GetString()))
+                throw new ArgumentException("expected_document_id must be a non-empty identity from get_model_overview. No action was performed.");
+            if (!string.Equals(id.GetString(), GetIdentity(document), StringComparison.Ordinal))
+                throw new ArgumentException($"The active document '{document.Title}' is not the exact open document this call expected, or that identity is stale after reopening/restarting. No action was performed. Activate the intended document and read get_model_overview again.");
+        }
+
+        // Retained as an additional human-readable check, never as a substitute for identity.
+        string? expected = JsonArgs.GetString(args, "expected_document");
+        if (string.IsNullOrWhiteSpace(expected)) return;
+        static string Normalize(string title)
+        {
+            string value = title.Trim();
+            return value.EndsWith(".rvt", StringComparison.OrdinalIgnoreCase) ? value[..^4] : value;
+        }
+        if (!string.Equals(Normalize(expected), Normalize(document.Title), StringComparison.OrdinalIgnoreCase))
+            throw new ArgumentException($"Active document is '{document.Title}' but this call expected title '{expected}'. No action was performed. Read get_model_overview for the intended document.");
+    }
+}

package/src/Revit/Tools/ExecuteCsharp.cs

@@ -59,7 +59,7 @@ namespace RevitBridge.Tools
 
         public string Name => "execute_csharp";
         public string Label => "Execute C#";
-        public string Description => "Compile and run a C# script on the Revit API thread against the open model — the escape hatch for anything without a dedicated tool: element creation, deletion, geometry edits (move/copy/rotate), views, sheets, schedules, tagging, families, links, worksets. Globals: doc (Document), uidoc (UIDocument), uiapp (UIApplication), and Dump(value) to record intermediate values into the result's dumps[]. Default imports: System, System.Linq, System.Collections.Generic, Autodesk.Revit.DB, Autodesk.Revit.UI — add using directives at the top for sub-namespaces (e.g. using Autodesk.Revit.DB.Architecture;). The entire run is wrapped in ONE transaction named 'execute_csharp': committed on success, rolled back on any exception, so a failed script never changes the model (do not open your own Transaction; sub-transactions are fine). The script's final expression or return statement becomes returnValue; return primitives, strings, or anonymous objects/lists — Revit API values are projected to safe shapes (Element -> {id,name,category,typeName,levelId}, ElementId -> number, XYZ -> {x,y,z}, Parameter -> {name,value,displayValue}; other API objects become strings) with depth and item caps, so never rely on raw API objects round-tripping. Lengths are in internal units (decimal feet) — convert with UnitUtils. Prefer collector-level filtering (FilteredElementCollector .OfCategory/.OfClass/.WhereElementIsNotElementType) and bounded loops: the call budget is 120s and Revit cannot be interrupted mid-script. Scripts must be fully synchronous — await/async is rejected at compile time, and blocking on tasks (Task.Result/.Wait()) can freeze Revit. Modal dialogs raised while running are auto-dismissed and reported in suppressedDialogs — unrecognized dialogs are answered dismissively (Cancel/Close/No) rather than confirmed, so an operation that raises a confirmation prompt may be cancelled; check suppressedDialogs when a result looks incomplete. Verify unfamiliar signatures with search_api_docs first.";
+        public string Description => "Compile and run a C# script on the Revit API thread against the open model — the escape hatch for anything without a dedicated tool: element creation, deletion, geometry edits (move/copy/rotate), views, sheets, schedules, tagging, families, links, worksets. Globals: doc (Document), uidoc (UIDocument), uiapp (UIApplication), and Dump(value) to record intermediate values into the result's dumps[]. Default imports: System, System.Linq, System.Collections.Generic, Autodesk.Revit.DB, Autodesk.Revit.UI — add using directives at the top for sub-namespaces (e.g. using Autodesk.Revit.DB.Architecture;). The entire run is wrapped in ONE transaction named 'execute_csharp': committed on success; on failure rollback is attempted and its confirmed status is reported (do not open your own Transaction; sub-transactions are fine). The script's final expression or return statement becomes returnValue; return primitives, strings, or anonymous objects/lists — Revit API values are projected to safe shapes (Element -> {id,name,category,typeName,levelId}, ElementId -> number, XYZ -> {x,y,z}, Parameter -> {name,value,displayValue}; other API objects become strings) with depth and item caps, so never rely on raw API objects round-tripping. Lengths are in internal units (decimal feet) — convert with UnitUtils. Prefer collector-level filtering (FilteredElementCollector .OfCategory/.OfClass/.WhereElementIsNotElementType) and bounded loops: the call budget is 120s and Revit cannot be interrupted mid-script. Scripts must be fully synchronous — await/async is rejected at compile time, and blocking on tasks (Task.Result/.Wait()) can freeze Revit. Modal dialogs raised while running are auto-dismissed and reported in suppressedDialogs — unrecognized dialogs are answered dismissively (Cancel/Close/No) rather than confirmed, so an operation that raises a confirmation prompt may be cancelled; check suppressedDialogs when a result looks incomplete. Verify unfamiliar signatures with search_api_docs first.";
         public bool Write => true;
 
         public object ParametersSchema => new
@@ -119,9 +119,9 @@ namespace RevitBridge.Tools
 
             using var dialogGuard = new DialogGuard(uiapp);
             using var transaction = new Transaction(doc, "execute_csharp");
-            var failureGuard = FailureGuard.Attach(transaction);
-            if (transaction.Start() != TransactionStatus.Started)
-                throw new InvalidOperationException("Unable to start the execute_csharp transaction.");
+            if (transaction.Start() != TransactionStatus.Started)
+                throw new InvalidOperationException("Unable to start the execute_csharp transaction.");
+            var failureGuard = FailureGuard.Attach(transaction);
 
             object? returnValue;
             string? projectionError = null;
@@ -147,23 +147,24 @@ namespace RevitBridge.Tools
             }
             catch (Exception ex)
             {
-                try
-                {
-                    if (transaction.GetStatus() == TransactionStatus.Started)
-                        transaction.RollBack();
-                }
-                catch
-                {
-                    // Reporting the script failure outranks a rollback hiccup.
-                }
-                throw new InvalidOperationException(FormatRuntimeError(ex, dialogGuard.Suppressed));
-            }
-
-            if (transaction.Commit() != TransactionStatus.Committed)
-                throw new InvalidOperationException(
-                    "Revit rolled back the execute_csharp transaction during commit (failure processing rejected the changes); no model changes were saved."
-                    + failureGuard.DescribeErrors()
-                    + DescribeDialogs(dialogGuard.Suppressed));
+                throw new InvalidOperationException(
+                    FormatRuntimeError(ex, dialogGuard.Suppressed) + " " + FailureGuard.RollBackAndDescribe(transaction), ex);
+            }
+
+            try
+            {
+                var status = transaction.Commit();
+                var finalStatus = transaction.GetStatus();
+                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
+                    throw new InvalidOperationException($"The execute_csharp commit returned {status}; current transaction status is {finalStatus}.");
+            }
+            catch (Exception ex)
+            {
+                throw new InvalidOperationException(
+                    $"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}"
+                    + failureGuard.DescribeErrors()
+                    + DescribeDialogs(dialogGuard.Suppressed), ex);
+            }
 
             stopwatch.Stop();
 
@@ -240,8 +241,7 @@ namespace RevitBridge.Tools
             string line = TryGetScriptLine(ex) is { } scriptLine ? $" at script line {scriptLine}" : string.Empty;
             string inner = ex.InnerException is { } innerEx ? $" Inner: {innerEx.GetType().Name}: {innerEx.Message}" : string.Empty;
             return $"C# script threw {ex.GetType().Name}{line}: {ex.Message}.{inner}"
-                + " The execute_csharp transaction was rolled back; no model changes were saved."
-                + DescribeDialogs(suppressedDialogs);
+                + DescribeDialogs(suppressedDialogs);
         }
 
         private static string DescribeDialogs(IReadOnlyList<string> suppressed)

package/src/Revit/Tools/ExportDocuments.cs

@@ -1,4 +1,6 @@
-using System.IO;
+using System.IO;
+using System.Security.Cryptography;
+using System.Text;
 using System.Text.Json;
 using Autodesk.Revit.DB;
 
@@ -19,7 +21,7 @@ namespace RevitBridge.Tools
 
         public string Name => "export_documents";
         public string Label => "Export Documents";
-        public string Description => "Export documents from the open Revit model. format 'pdf'/'dwg'/'png' export the given sheet/view ids to files: pdf combines everything into one file by default (combine=false writes one PDF per sheet/view, named by Revit's naming rule); png renders 2048 px wide; ifc exports the whole model, or just what one given view shows. Files sort themselves per model: with output_dir omitted they land in Documents\\pi-revit\\Models\\<model title>\\exports, derived from the document being exported (pass output_dir only for a different explicit target); file_name_prefix sets the base file name (default: the document title; Revit appends view/sheet suffixes for multi-file exports). Returns the produced file paths with sizes. Find sheet/view ids with get_elements (category 'Sheets' or 'Views') first.";
+        public string Description => "Export documents from the open Revit model. format 'pdf'/'dwg'/'png' export the given sheet/view ids to files: pdf combines everything into one file by default (combine=false writes one PDF per sheet/view, named by Revit's naming rule); png renders 2048 px wide; ifc exports the whole model, or just what one given view shows. Files sort themselves per model: with output_dir omitted they land in Documents\\pi-revit\\Models\\<model title>--<identity hash>\\exports, derived from the document being exported (pass output_dir only for a different explicit target); file_name_prefix sets the base file name (default: the document title; Revit appends view/sheet suffixes for multi-file exports). Returns the produced file paths with sizes. Find sheet/view ids with get_elements (category 'Sheets' or 'Views') first.";
         public bool Write => true;
         public string Tier => "advanced";
 
@@ -43,7 +45,7 @@ namespace RevitBridge.Tools
                 output_dir = new
                 {
                     type = "string",
-                    description = "Output directory, created if missing. Default: Documents\\pi-revit\\Models\\<model title>\\exports — files sort under the exported model automatically; omit unless the user names a different target.",
+                    description = "Output directory, created if missing. Default: Documents\\pi-revit\\Models\\<model title>--<identity hash>\\exports — files sort under the exported model automatically; omit unless the user names a different target.",
                 },
                 file_name_prefix = new
                 {
@@ -86,17 +88,37 @@ namespace RevitBridge.Tools
             // recent (a shared output_dir, another tool writing alongside) does not.
             var before = SnapshotWriteTimes(outputDir);
 
-            switch (format)
-            {
-                case "pdf": ExportPdf(doc, views, outputDir, baseName, combine); break;
-                case "dwg": ExportDwg(doc, views, outputDir, baseName); break;
-                case "png": ExportPng(doc, views, outputDir, baseName); break;
-                default: ExportIfc(doc, views, outputDir, baseName); break;
-            }
-
-            var files = Directory.GetFiles(outputDir)
-                .Where(path => !before.TryGetValue(path, out DateTime writtenBefore) || SafeWriteTime(path) != writtenBefore)
-                .OrderBy(path => path, StringComparer.OrdinalIgnoreCase)
+            IReadOnlyList<string> commitWarnings = Array.Empty<string>();
+            try
+            {
+                switch (format)
+                {
+                    case "pdf": ExportPdf(doc, views, outputDir, baseName, combine); break;
+                    case "dwg": ExportDwg(doc, views, outputDir, baseName); break;
+                    case "png": ExportPng(doc, views, outputDir, baseName); break;
+                    default: commitWarnings = ExportIfc(doc, views, outputDir, baseName); break;
+                }
+            }
+            catch (Exception ex)
+            {
+                // A failed export may already have written some files. A Revit
+                // transaction rollback cannot undo those filesystem changes.
+                string observed;
+                try
+                {
+                    var changed = FindChangedFiles(outputDir, before).ToList();
+                    observed = changed.Count == 0
+                        ? "No changed files were observed."
+                        : $"Observed {changed.Count} new or changed file(s): {string.Join(", ", changed.Take(20))}{(changed.Count > 20 ? " (additional files omitted)" : string.Empty)}.";
+                }
+                catch (Exception scanError)
+                {
+                    observed = $"Could not inspect remaining files: {scanError.Message}.";
+                }
+                throw new InvalidOperationException($"{ex.Message} The export failed; files in '{outputDir}' may be incomplete and were not removed. {observed}", ex);
+            }
+
+            var files = FindChangedFiles(outputDir, before)
                 .Select(path => new Dictionary<string, object?>
                 {
                     ["path"] = path,
@@ -107,15 +129,23 @@ namespace RevitBridge.Tools
                 throw new InvalidOperationException($"The {format} export finished but produced no files in {outputDir}.");
 
             string sample = string.Join(", ", files.Take(3).Select(file => Path.GetFileName((string)file["path"]!)));
-            string compact = $"Exported {files.Count} {format.ToUpperInvariant()} file(s) to {outputDir}: {sample}{(files.Count > 3 ? $" (+{files.Count - 3} more)" : string.Empty)}.";
+            string compact = $"Exported {files.Count} {format.ToUpperInvariant()} file(s) to {outputDir}: {sample}{(files.Count > 3 ? $" (+{files.Count - 3} more)" : string.Empty)}.";
+            if (commitWarnings.Count > 0)
+                compact += $" {commitWarnings.Count} Revit warning(s) auto-dismissed (see commitWarnings).";
             return new ToolOutput(new
             {
                 format,
                 outputDir,
                 fileCount = files.Count,
-                files,
-            }, compact);
-        }
+                files,
+                commitWarnings,
+            }, compact);
+        }
+
+        private static IEnumerable<string> FindChangedFiles(string directory, IReadOnlyDictionary<string, DateTime> before)
+            => Directory.GetFiles(directory)
+                .Where(path => !before.TryGetValue(path, out DateTime writtenBefore) || SafeWriteTime(path) != writtenBefore)
+                .OrderBy(path => path, StringComparer.OrdinalIgnoreCase);
 
         /// <summary>path -> last write time for the files already in the output directory.
         /// A file whose time cannot be read is left out, so the export reports it if it
@@ -197,27 +227,29 @@ namespace RevitBridge.Tools
         /// <summary>The IFC exporter writes IFC GUID parameters onto exported elements,
         /// so the Revit API requires a transaction around it — owned here, matching
         /// Revit's own behavior of committing those GUIDs on export.</summary>
-        private static void ExportIfc(Document doc, List<View> views, string outputDir, string baseName)
+        private static IReadOnlyList<string> ExportIfc(Document doc, List<View> views, string outputDir, string baseName)
         {
             var options = new IFCExportOptions();
             if (views.Count == 1)
                 options.FilterViewId = views[0].Id;
 
             using var transaction = new Transaction(doc, "export_documents: ifc");
-            if (transaction.Start() != TransactionStatus.Started)
-                throw new InvalidOperationException("Unable to start the IFC export transaction.");
+            if (transaction.Start() != TransactionStatus.Started)
+                throw new InvalidOperationException("Unable to start the IFC export transaction.");
+            var failureGuard = FailureGuard.Attach(transaction);
             try
             {
                 if (!Run(() => doc.Export(outputDir, baseName, options), "IFC"))
                     throw new InvalidOperationException("Revit reported a failed IFC export.");
-                if (transaction.Commit() != TransactionStatus.Committed)
-                    throw new InvalidOperationException("The IFC export transaction failed to commit.");
-            }
-            catch
-            {
-                if (transaction.GetStatus() == TransactionStatus.Started)
-                    transaction.RollBack();
-                throw;
+                var status = transaction.Commit();
+                var finalStatus = transaction.GetStatus();
+                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
+                    throw new InvalidOperationException($"The IFC export commit returned {status}; current transaction status is {finalStatus}." + failureGuard.DescribeErrors());
+                return failureGuard.Warnings;
+            }
+            catch (Exception ex)
+            {
+                throw new InvalidOperationException($"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}", ex);
             }
         }
 
@@ -278,27 +310,72 @@ namespace RevitBridge.Tools
         }
 
         /// <summary>Per-model folder under the pi-revit workspace:
-        /// Documents\pi-revit\Models\&lt;model title&gt;. The exporting tool is the one
-        /// component that knows with certainty which model a file belongs to, so the
-        /// sorting is automatic — never an agent or user decision. model.txt records
-        /// the model's identity so same-titled models stay distinguishable.</summary>
-        private static string ModelFolder(Document doc)
+        /// Documents\pi-revit\Models\&lt;model title&gt;--&lt;identity hash&gt;.
+        /// Existing title-only folders are left untouched; identity markers are
+        /// diagnostic records, not the mechanism that separates exports.</summary>
+        private static string ModelFolder(Document doc)
         {
             string workspace = Path.Combine(
                 Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments), "pi-revit");
-            string title = SanitizeFileName(string.IsNullOrWhiteSpace(doc.Title) ? "untitled" : doc.Title);
-            string folder = Path.Combine(workspace, "Models", title);
-            Directory.CreateDirectory(folder);
-            TryRecordModelIdentity(folder, doc);
-            return folder;
-        }
-
-        private static void TryRecordModelIdentity(string folder, Document doc)
+            string identity = GetModelIdentity(doc);
+            string folder = Path.Combine(workspace, "Models", GetModelFolderName(doc.Title, identity));
+            Directory.CreateDirectory(folder);
+            TryRecordModelIdentity(folder, doc, identity);
+            return folder;
+        }
+
+        internal static string GetModelFolderName(string title, string identity)
+        {
+            string cleanTitle = SanitizeFileName(string.IsNullOrWhiteSpace(title) ? "untitled" : title);
+            // Bound the default path component, leaving room for the identity and exports.
+            if (cleanTitle.Length > 80)
+                cleanTitle = cleanTitle[..80];
+            string hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(identity))).ToLowerInvariant()[..24];
+            return $"{cleanTitle}--{hash}";
+        }
+
+        // Revit can return different managed wrappers for one open native document.
+        // Document.Equals/GetHashCode identify that open document, unlike reference
+        // equality in ConditionalWeakTable. Closed document entries are pruned below.
+        // Tool execution and this dictionary are confined to the Revit API thread.
+        private static readonly Dictionary<Document, string> OpenDocumentIdentities = new();
+
+        internal static string GetModelIdentity(Document doc)
+        {
+            try
+            {
+                if (doc.IsModelInCloud)
+                {
+                    var path = doc.GetCloudModelPath();
+                    return $"cloud:{path.Region.ToUpperInvariant()}:{path.GetProjectGUID():D}:{path.GetModelGUID():D}";
+                }
+                string pathName = doc.PathName;
+                if (!string.IsNullOrWhiteSpace(pathName))
+                {
+                    // Revit file paths are Windows paths; canonicalize separators,
+                    // relative segments and case. Revit Server identities use RSN URLs.
+                    if (pathName.StartsWith("RSN://", StringComparison.OrdinalIgnoreCase))
+                        return "server:" + pathName.Replace('\\', '/').TrimEnd('/').ToUpperInvariant();
+                    return "file:" + Path.GetFullPath(pathName).Replace('/', '\\').ToUpperInvariant();
+                }
+            }
+            catch
+            {
+                // An unavailable identity must not collapse unrelated documents into
+                // a shared title-only directory. Use the same safe fallback as unsaved docs.
+            }
+            foreach (var closed in OpenDocumentIdentities.Keys.Where(key => !key.IsValidObject).ToList())
+                OpenDocumentIdentities.Remove(closed);
+            if (!OpenDocumentIdentities.TryGetValue(doc, out string? identity))
+                OpenDocumentIdentities[doc] = identity = $"session:{Guid.NewGuid():N}";
+            return identity;
+        }
+
+        private static void TryRecordModelIdentity(string folder, Document doc, string identity)
         {
             try
             {
-                string guid = doc.ProjectInformation?.UniqueId ?? string.Empty;
-                string line = $"{guid}\t{doc.PathName}";
+                string line = $"{identity}\t{doc.PathName}";
                 string marker = Path.Combine(folder, "model.txt");
                 if (!File.Exists(marker) || !File.ReadAllLines(marker).Contains(line))
                     File.AppendAllLines(marker, new[] { line });

package/src/Revit/Tools/FailureGuard.cs

@@ -16,15 +16,36 @@ namespace RevitBridge.Tools
         public List<string> Warnings { get; } = new();
         public List<string> Errors { get; } = new();
 
-        public static FailureGuard Attach(Transaction transaction)
-        {
-            var guard = new FailureGuard();
+        public static FailureGuard Attach(Transaction transaction)
+        {
+            if (transaction.GetStatus() != TransactionStatus.Started)
+                throw new InvalidOperationException("FailureGuard must be attached after the transaction starts; Start resets failure handling options.");
+            var guard = new FailureGuard();
             var options = transaction.GetFailureHandlingOptions();
             options.SetFailuresPreprocessor(guard);
             options.SetClearAfterRollback(true);
             transaction.SetFailureHandlingOptions(options);
-            return guard;
-        }
+            return guard;
+        }
+
+        /// <summary>Best-effort cleanup that preserves the original failure and never
+        /// claims a rollback unless Revit confirms its final transaction status.</summary>
+        public static string RollBackAndDescribe(Transaction transaction)
+        {
+            try
+            {
+                if (transaction.GetStatus() == TransactionStatus.Started)
+                    transaction.RollBack();
+                var status = transaction.GetStatus();
+                return status == TransactionStatus.RolledBack
+                    ? "The transaction was rolled back; no changes from this transaction were saved."
+                    : $"Transaction status is {status}; rollback is not confirmed. Inspect Revit before retrying.";
+            }
+            catch (Exception ex)
+            {
+                return $"Rollback could not be confirmed ({ex.GetType().Name}: {ex.Message}). Inspect Revit before retrying.";
+            }
+        }
 
         public FailureProcessingResult PreprocessFailures(FailuresAccessor accessor)
         {

package/src/Revit/Tools/GetElementDetails.cs

@@ -36,7 +36,7 @@ namespace RevitBridge.Tools
                     properties = new
                     {
                         parameters = new { type = "boolean", description = "Instance parameter values. Default true." },
-                        type_parameters = new { type = "boolean", description = "Also include the element type's parameters, marked isType=true. Default false." },
+                        type_parameters = new { type = "boolean", description = "Include the element type's parameters, marked isType=true, independently of the instance parameters flag. Default false." },
                         location = new { type = "boolean", description = "Location point or curve (coordinates in internal feet). Default false." },
                         bounding_box = new { type = "boolean", description = "Model bounding box min/max (internal feet). Default false." },
                         materials = new { type = "boolean", description = "Material ids/names with area/volume (internal units). Default false." },
@@ -70,8 +70,9 @@ namespace RevitBridge.Tools
             JsonElement include = args.TryGetProperty("include", out var includeElement) && includeElement.ValueKind == JsonValueKind.Object
                 ? includeElement
                 : default;
-            bool withParameters = JsonArgs.GetBool(include, "parameters", true);
-            bool withTypeParameters = JsonArgs.GetBool(include, "type_parameters", false);
+            bool withParameters = JsonArgs.GetBool(include, "parameters", true);
+            bool withTypeParameters = JsonArgs.GetBool(include, "type_parameters", false);
+            bool withAnyParameters = withParameters || withTypeParameters;
             bool withLocation = JsonArgs.GetBool(include, "location", false);
             bool withBoundingBox = JsonArgs.GetBool(include, "bounding_box", false);
             bool withMaterials = JsonArgs.GetBool(include, "materials", false);
@@ -102,10 +103,11 @@ namespace RevitBridge.Tools
 
                 int parameterCount = 0;
                 int parameterTotal = 0;
-                if (withParameters)
-                {
-                    var parameters = new List<Dictionary<string, object?>>();
-                    parameterTotal += AppendParameters(doc, element, nameFilter, isType: false, parameters);
+                if (withAnyParameters)
+                {
+                    var parameters = new List<Dictionary<string, object?>>();
+                    if (withParameters)
+                        parameterTotal += AppendParameters(doc, element, nameFilter, isType: false, parameters);
                     if (withTypeParameters && elementType != null)
                         parameterTotal += AppendParameters(doc, elementType, nameFilter, isType: true, parameters);
                     dto["parameters"] = parameters;
@@ -122,7 +124,7 @@ namespace RevitBridge.Tools
                 elements.Add(dto);
                 // With a name filter active, "0 params" is ambiguous (none matched vs none
                 // exist): report matched-of-total so a localization miss is visible.
-                string paramSummary = !withParameters ? string.Empty
+                string paramSummary = !withAnyParameters ? string.Empty
                     : nameFilter != null ? $", {parameterCount} of {parameterTotal} params matched parameter_names"
                     : $", {parameterCount} params";
                 compactParts.Add($"'{element.Name}' (id {id}, {element.Category?.Name ?? "no category"}{paramSummary})");

package/src/Revit/Tools/GetElements.cs

@@ -21,7 +21,7 @@ namespace RevitBridge.Tools
 
         public string Name => "get_elements";
         public string Label => "Get Elements";
-        public string Description => "Query Revit elements: scope by category (display name like 'Walls' or enum name like 'OST_Walls'), element class, level, type id, or active view; filter by parameter rules; paginate with offset/limit or just count with count_only. Returns identity fields only (id, name, category, typeName, levelId) — read parameter values with get_element_details. Most filter rules evaluate inside Revit's collector; 'regex' rules (and rules on parameters that cannot be quick-filtered) run as a slower post-collector scan. Prefer combining display-name filter rules with a category or of_class scope: the same display name (e.g. 'Width') can resolve to different parameters per category, which forces the slower per-element scan in unscoped queries. Numeric rule values are interpreted in the document's display units for that parameter unless 'unit' is given.";
+        public string Description => "Query Revit elements: scope by category (display name like 'Walls' or enum name like 'OST_Walls'), element class, level, type id, or active view; filter by parameter rules; paginate with offset/limit or just count with count_only. Returns identity fields only (id, name, category, typeName, levelId) — read parameter values with get_element_details. Rules with an explicit BuiltInParameter or shared GUID can evaluate inside Revit's collector; display-name rules, regex rules, and unsupported quick filters run as a per-element scan. A display name can identify different parameters even within one category or class. Scope queries to reduce the scan, or use an explicit parameter identity when appropriate. Numeric rule values are interpreted in the document's display units for that parameter unless 'unit' is given.";
 
         public object ParametersSchema => new
         {
@@ -292,8 +292,9 @@ namespace RevitBridge.Tools
             if (rules.Count == 0)
                 return (null, null, Array.Empty<string>());
 
-            // Probe a few in-scope elements so display-name parameters resolve to ids
-            // and value typing / unit conversion can use the parameter's storage + spec.
+            // Probe a few in-scope elements for missing-name diagnostics and to find
+            // storage/spec exemplars for explicit parameter identities. A sample must
+            // never turn a display name into an assumed globally uniform identity.
             var probes = new List<Element>(ProbeSize);
             foreach (Element element in createBaseCollector())
             {
@@ -325,30 +326,19 @@ namespace RevitBridge.Tools
                 }
             }
 
-            // Display-name promotion is only trustworthy inside one category/class: the
-            // probe sees just the first ProbeSize elements in collector order, so in an
-            // unscoped query a unanimous sample can still hide other categories further
-            // on whose same-named parameter has a different id — and a pinned quick rule
-            // would silently drop their matches.
-            bool scoped = !string.IsNullOrWhiteSpace(JsonArgs.GetString(args, "category"))
-                || !string.IsNullOrWhiteSpace(JsonArgs.GetString(args, "of_class"));
-
-            foreach (var rule in rules)
-            {
-                if (rule.Op is RuleOp.Regex or RuleOp.IsEmpty or RuleOp.IsNotEmpty)
-                    continue; // always post-scan (missing-parameter semantics)
-                var found = probes.Select(probe => FindParameter(probe, rule)).Where(parameter => parameter != null).ToList();
-                if (found.Count == 0)
-                    continue;
-                // BuiltInParameter/guid rules address one global parameter id. A plain
-                // display name can resolve to DIFFERENT ids per category or family
-                // (e.g. 'Width' -> DOOR_WIDTH vs WINDOW_WIDTH). Promote a display-name
-                // rule only when the query is scoped AND all probed elements agree on
-                // the id; otherwise it stays on the (per-element, correct) post-scan path.
-                bool oneGlobalId = rule.BuiltIn != null || rule.SharedGuid != null
-                    || (scoped && found.All(parameter => parameter!.Id == found[0]!.Id));
-                if (oneGlobalId)
-                    rule.QuickRule = TryBuildQuickRule(doc, rule, found[0]!);
+            foreach (var rule in rules)
+            {
+                if (rule.Op is RuleOp.Regex or RuleOp.IsEmpty or RuleOp.IsNotEmpty)
+                    continue; // always post-scan (missing-parameter semantics)
+                // Category/class scope and unanimous samples do not establish a
+                // uniform parameter identity across later families. Resolve display
+                // names per element; only explicit identities may use a quick rule.
+                if (rule.BuiltIn is null && rule.SharedGuid is null)
+                    continue;
+                var found = probes.Select(probe => FindParameter(probe, rule)).Where(parameter => parameter != null).ToList();
+                if (found.Count == 0)
+                    continue;
+                rule.QuickRule = TryBuildQuickRule(doc, rule, found[0]!);
             }
 
             var quickRules = rules.Where(rule => rule.QuickRule != null).ToList();

package/src/Revit/Tools/GetModelOverview.cs

@@ -45,7 +45,8 @@ namespace RevitBridge.Tools
             string? lengthUnit = DisplayUnitName(units, SpecTypeId.Length);
             var project = new Dictionary<string, object?>
             {
-                ["title"] = doc.Title,
+                ["title"] = doc.Title,
+                ["documentId"] = DocumentGuard.GetIdentity(doc),
                 ["name"] = info?.Name,
                 ["number"] = info?.Number,
                 ["clientName"] = info?.ClientName,