d365fo-mcp 1.9.0 → 1.10.0

package/.github/copilot-instructions.md

@@ -34,8 +34,8 @@ PowerShell / any terminal command **WILL HANG** in VS 2022 / VS 2026 MCP integra
 | Edit an existing object | `d365fo_file(action="modify")` (applies immediately — confirm in chat first) |
 | Revert the last write | `undo_last_modification` |
 | Search objects | `search` — multiple via `search(queries[])`, custom-only via `search(scope="extensions")` |
-| Read any object's metadata | `get_object_info(objectType, name, options?)` — objectType ∈ class/table/form/query/view/enum/edt/report/data-entity/menu-item/service/map/config-key/security-policy/macro. 2+ known names: `batch_get_info(objects[])` |
-| Method signature for CoC | `get_method(include="signature")` (already returned by `prepare(mode="change")`) |
+| Read any object's metadata | `get_object_info(objectType, name, options?)` — objectType ∈ class/table/form/query/view/enum/edt/report/data-entity/menu-item/service/map/config-key/security-policy/macro. 2+ known names: `get_object_info(objects=[{objectType,objectName},…])` — ONE call, never a loop |
+| Method signature for CoC | `get_object_info(objectType="class", name, options={method, include:"signature"})` (already returned by `prepare(mode="change")`) |
 | Validate X++ before write | `validate_code(mode="syntax", code)` — offline BP check, <50 ms |
 | X++ rules & patterns | `get_knowledge(kind="knowledge", topic)` — select grammar, CoC, BP rules, SysOperation, workflow, … |
 | Create a NEW form | `object_patterns(domain="form", action="analyze", recommend={...})` → `object_patterns(domain="form", action="spec", pattern)` → `generate_object(mode="scaffold", objectType="form", cloneFrom=referenceForm, tableMapping={...})` → `object_patterns(domain="form", action="validate", xml)` |
@@ -43,6 +43,7 @@ PowerShell / any terminal command **WILL HANG** in VS 2022 / VS 2026 MCP integra
 | Resolve label / EDT / class refs | `validate_code(mode="references", code)` |
 | Build / BP / Sync | `build_d365fo_project` / `run_bp_check` / `trigger_db_sync` |
 | Error diagnosis | `get_knowledge(kind="error", errorText)` |
+| Parameters for a `d365fo_file` operation / `generate_object` mode | `get_knowledge(kind="op-spec", topic="add-index" \| "table" \| "scaffold:form")` — those two tools keep their parameters OUT of the tool schema; look the contract up once for the operation you picked, then nest the values in `params` (`properties` for `action="create"`) |
 
 ## Key Rules
 
@@ -80,6 +81,23 @@ PowerShell / any terminal command **WILL HANG** in VS 2022 / VS 2026 MCP integra
 11. **The post-write diff must be additive or narrowly targeted** — verify via `review_workspace_changes` (or re-read with `get_*_info`) that no unrelated XML nodes (`<DataSources>`, `<Controls>`, methods, pattern metadata) disappeared. If they did, the edit failed: `undo_last_modification`.
 12. **An example form named by the user is a pattern contract** — keep its pattern family and required scaffolding (datasources, ActionPane/Tab/grid/QuickFilter); missing pattern elements are a failed generation even if the XML is well-formed.
 
+### Spending tool calls
+
+13. **Issue independent read-only calls together, in one step.** Every tool call re-reads the whole conversation, so a turn costs the round trip, not the tool. `get_object_info`, `search`, `labels`, `get_knowledge`, `object_patterns` and `find_references` have no side effects and never need to wait for each other — five lookups are one step, not five.
+14. **Use the plural form when there is one** — `get_object_info(objects[])`, `run_bp_check(objects[])`, `verify_d365fo_project(objects[])`, `search(queries[])`. All three `objects[]` forms take `{objectType, objectName}`; `queries[]` takes `{query}`. Note `get_object_info`'s SINGLE-object form still spells it `name`, not `objectName` — take the key from the tool's schema, don't assume.
+15. **Plan the reads before the first one.** Decide which objects the change touches, then fetch them in a single step instead of discovering them one call at a time.
+
+### Reading D365FO objects
+
+16. **Use `get_object_info`, not `read_file`, for anything under `PackagesLocalDirectory`.** Raw AOT XML is verbose and stays in context for the rest of the session; `get_object_info` returns the same facts structured and an order of magnitude smaller. Read the raw file only when you need its literal bytes.
+17. **Never hand-edit AOT XML with text replacement** (rule 3) — whitespace and element ordering are load-bearing, so the match fails or the write corrupts the object. `d365fo_file(action="modify")` exists for exactly this.
+18. **Do not call `update_symbol_index` after `d365fo_file` create/modify** — the index is already refreshed. It is for files changed OUTSIDE the server. Sole exception: a brand-new AxEdt/AxEnum you are about to name in a `generate_object` `fieldsHint`.
+19. **Ask for the smallest result set that answers the question** — `labels(action="search")` returns 10 one-line hits; raise `maxResults` or set `verbose` only when that is genuinely not enough.
+
+### Finishing
+
+20. **Keep the closing summary to what changed and what to do next.** Long recaps are the most expensive single output of a session and are re-read by nothing.
+
 ## Full Instructions
 
 The complete X++ rules, query grammar, CoC authoring rules, and workflow details are delivered via the MCP prompt `xpp_system_instructions`. If that prompt is not loaded, request it or consult [src/prompts/systemInstructions.ts](../src/prompts/systemInstructions.ts) directly.

package/README.md

@@ -2,13 +2,13 @@
 
 <div align="center">
 
-**26 AI tools that know every X++ class, table, form, and EDT in your D365FO codebase**
+**23 AI tools that know every X++ class, table, form, and EDT in your D365FO codebase**
 
 [![npm](https://img.shields.io/npm/v/d365fo-mcp.svg?logo=npm&color=cb3837)](https://www.npmjs.com/package/d365fo-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D24.0.0-brightgreen.svg)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-7.0-blue.svg)](https://www.typescriptlang.org/)
-[![Tests](https://img.shields.io/badge/tests-2500%2B-brightgreen.svg)](docs/TESTING.md)
+[![Tests](https://img.shields.io/badge/tests-2800%2B-brightgreen.svg)](docs/TESTING.md)
 <!-- coverage-badge:start -->
 [![Core coverage](https://img.shields.io/badge/core_coverage-100%25-brightgreen.svg)](eval/COVERAGE.md) [![Total coverage](https://img.shields.io/badge/total_coverage-100%25-lightgrey.svg)](eval/COVERAGE.md)
 <!-- coverage-badge:end -->
@@ -29,7 +29,7 @@
 
 AI assistants excel at C#, Python, and JavaScript. X++ is different: your D365FO codebase is private, deeply customized, and invisible to every model — so AI confidently generates code that doesn't compile.
 
-This server pre-indexes your entire D365FO installation (580 000+ symbols across standard, ISV, and custom models) and exposes it as 26 specialized MCP tools. Every signature, every CoC wrapper, every label, every form pattern — verified against your real metadata **before** the AI writes a single line.
+This server pre-indexes your entire D365FO installation (580 000+ symbols across standard, ISV, and custom models) and exposes it as 23 specialized MCP tools. Every signature, every CoC wrapper, every label, every form pattern — verified against your real metadata **before** the AI writes a single line.
 
 ![Solution Architecture](docs/img/solution-architecture-diagram.svg)
 
@@ -115,12 +115,12 @@ Deployment guide: [docs/SETUP_AZURE.md](docs/SETUP_AZURE.md) — includes CI/CD
 
 | Getting started | Reference | Operations |
 |-----------------|-----------|------------|
-| [Quick Start](docs/QUICK_START.md) — connect or install | [All 26 tools](docs/MCP_TOOLS.md) | [Azure deployment](docs/SETUP_AZURE.md) |
+| [Quick Start](docs/QUICK_START.md) — connect or install | [All 23 tools](docs/MCP_TOOLS.md) | [Azure deployment](docs/SETUP_AZURE.md) |
 | [Setup scenarios A–F](docs/SETUP.md) | [`.mcp.json` reference](docs/MCP_CONFIG.md) | [DevOps pipelines](docs/SETUP_AZURE.md#azure-devops-pipelines) |
 | [Claude Code setup](docs/SETUP.md#claude-code-cli) | [Configuration](docs/CONFIGURATION.md) | [Testing](docs/TESTING.md) |
 | [Usage examples](docs/USAGE_EXAMPLES.md) — real tool chains | [Architecture](docs/ARCHITECTURE.md) | [Custom / ISV models](docs/CUSTOM_EXTENSIONS.md) |
-| | | [Coverage](eval/COVERAGE.md) — what the badge counts |
-| | | [Eval loop](docs/AGENT_EVAL_LOOP.md) — the self-improvement harness |
+| [Changelog](CHANGELOG.md) | [Knowledge authoring](docs/KNOWLEDGE_AUTHORING.md) | [Coverage](eval/COVERAGE.md) — what the badge counts |
+| [Backlog](docs/BACKLOG.md) — deferred work | [New tool checklist](docs/NEW_TOOL_CHECKLIST.md) | [Eval loop](docs/AGENT_EVAL_LOOP.md) — the self-improvement harness |
 
 ## License
 

package/bridge/D365MetadataBridge/Models/Models.cs

@@ -781,23 +781,46 @@ namespace D365MetadataBridge.Models
         /// <summary>
         /// Deserializes a typed parameter from the Params dictionary.
         /// Values arrive as JsonElement from System.Text.Json — convert to the target type.
+        ///
+        /// The old `catch { return null; }` made a WRONGLY SHAPED parameter
+        /// indistinguishable from an absent one, and the dispatcher's
+        /// `?? throw new ArgumentException("Missing: fields")` then told the caller the key
+        /// was missing while it sat right there in the request. That is the param-shape
+        /// contract bug this project keeps re-living — e.g. constraints sent as
+        /// [{fieldName, relatedFieldName}] when this side reads [{field, relatedField}], or
+        /// index fields sent as [{fieldName}] when this side reads a flat string[]. A
+        /// failure now names the parameter and shows what actually arrived.
+        ///
+        /// JsonOptions.Default is used so the batch path resolves property names exactly the
+        /// way the single-op BridgeRequest.GetParam&lt;T&gt; does; deserializing without it was
+        /// a second, quieter way for the two paths to disagree.
         /// </summary>
         public T? GetTypedParam<T>(string key) where T : class
         {
             if (Params == null || !Params.TryGetValue(key, out var raw) || raw == null)
                 return null;
+            // Already the correct type (in-process caller, not a JSON round trip).
+            if (raw is T typed) return typed;
+
+            var json = raw is System.Text.Json.JsonElement je
+                ? je.GetRawText()
+                : System.Text.Json.JsonSerializer.Serialize(raw, Protocol.JsonOptions.Default);
             try
             {
-                if (raw is System.Text.Json.JsonElement je)
-                    return System.Text.Json.JsonSerializer.Deserialize<T>(je.GetRawText());
-                // Already correct type
-                if (raw is T typed) return typed;
-                // Fallback: serialize then deserialize
-                var json = System.Text.Json.JsonSerializer.Serialize(raw);
-                return System.Text.Json.JsonSerializer.Deserialize<T>(json);
+                // A JSON `null` deserializes to null here — same as an absent key, which is
+                // what the caller's "Missing: <key>" message correctly describes.
+                return System.Text.Json.JsonSerializer.Deserialize<T>(json, Protocol.JsonOptions.Default);
+            }
+            catch (System.Text.Json.JsonException ex)
+            {
+                throw new System.ArgumentException(
+                    $"Parameter '{key}' has the wrong shape: {ex.Message} Received: {Preview(json)}");
             }
-            catch { return null; }
         }
+
+        /// <summary>Caps the echoed payload — a batch op can carry a large array.</summary>
+        private static string Preview(string json) =>
+            json.Length <= 300 ? json : json.Substring(0, 300) + "…(truncated)";
     }
 
     public class BatchOperationResult

package/bridge/D365MetadataBridge/Protocol/BridgeProtocol.cs

@@ -48,18 +48,19 @@ namespace D365MetadataBridge.Protocol
         }
 
         /// <summary>
-        /// Helper to extract a boolean parameter from Params
+        /// Helper to extract a boolean parameter from Params.
+        /// Reads through ParamCoercion so this path and HandleBatchModify cannot disagree
+        /// about what a given value means.
         /// </summary>
         public bool? GetBoolParam(string name)
         {
             if (Params == null || Params.Value.ValueKind != JsonValueKind.Object)
                 return null;
 
-            if (Params.Value.TryGetProperty(name, out var prop) &&
-                (prop.ValueKind == JsonValueKind.True || prop.ValueKind == JsonValueKind.False))
-                return prop.GetBoolean();
+            if (!Params.Value.TryGetProperty(name, out var prop))
+                return null;
 
-            return null;
+            return ParamCoercion.ToBool(prop, name);
         }
 
         /// <summary>
@@ -116,6 +117,80 @@ namespace D365MetadataBridge.Protocol
         }
     }
 
+    /// <summary>
+    /// Parameter coercion shared by BOTH dispatch paths.
+    ///
+    /// The single-op path reads its params straight off the request's JsonElement; the
+    /// batch path gets them as Dictionary&lt;string, object&gt;, whose values System.Text.Json
+    /// boxes as JsonElement. JsonElement does not implement IConvertible, so the batch
+    /// path's Convert.ToBoolean(value) threw InvalidCastException ("Object must implement
+    /// IConvertible") for EVERY operation carrying a bool — mandatory, allowDuplicates,
+    /// alternateKey, extendBaseFieldGroup — and HandleBatchModify's per-op catch reported
+    /// that cast as the operation's reason for failing. Booleans are read by JSON kind, in
+    /// one place, so the two paths cannot drift apart again.
+    /// </summary>
+    public static class ParamCoercion
+    {
+        /// <summary>
+        /// Boolean from a raw (boxed) batch parameter value.
+        /// </summary>
+        public static bool? ToBool(object? value, string paramName)
+        {
+            switch (value)
+            {
+                case null: return null;
+                case bool b: return b;
+                case JsonElement el: return ToBool(el, paramName);
+                case string s: return ParseBoolText(s, paramName, s);
+                default:
+                    throw new ArgumentException(
+                        $"Parameter '{paramName}' must be a boolean — got {value.GetType().Name} '{value}'.");
+            }
+        }
+
+        /// <summary>
+        /// Boolean from a JSON value. Absent/null yields null so the caller's own default
+        /// applies; a value that is present but not readable as a boolean throws rather
+        /// than degrading to false — a silent false writes a field that is not mandatory,
+        /// or an index that allows duplicates, and reports success either way.
+        ///
+        /// The string spellings are accepted because the AxTable XML value is No/Yes and
+        /// callers reach for that form (#27); it is a typo, not a shape, that fails here.
+        /// </summary>
+        public static bool? ToBool(JsonElement el, string paramName)
+        {
+            switch (el.ValueKind)
+            {
+                case JsonValueKind.True: return true;
+                case JsonValueKind.False: return false;
+                case JsonValueKind.Null:
+                case JsonValueKind.Undefined: return null;
+                case JsonValueKind.String: return ParseBoolText(el.GetString(), paramName, el.GetRawText());
+                case JsonValueKind.Number when el.TryGetInt32(out var n) && (n == 0 || n == 1):
+                    return n == 1;
+                default:
+                    throw new ArgumentException(
+                        $"Parameter '{paramName}' must be a boolean — got {el.ValueKind} {el.GetRawText()}. " +
+                        "Accepted: true/false, \"true\"/\"false\", \"Yes\"/\"No\", 1/0.");
+            }
+        }
+
+        private static bool? ParseBoolText(string? text, string paramName, string received)
+        {
+            switch (text?.Trim().ToLowerInvariant())
+            {
+                case null:
+                case "": return null;
+                case "true": case "yes": case "1": return true;
+                case "false": case "no": case "0": return false;
+                default:
+                    throw new ArgumentException(
+                        $"Parameter '{paramName}' must be a boolean — got {received}. " +
+                        "Accepted: true/false, \"true\"/\"false\", \"Yes\"/\"No\", 1/0.");
+            }
+        }
+    }
+
     /// <summary>
     /// JSON-RPC style response sent to the Node.js MCP server
     /// </summary>

package/bridge/D365MetadataBridge/Protocol/RequestDispatcher.cs

@@ -461,9 +461,12 @@ namespace D365MetadataBridge.Protocol
                             // path inside AddField; both are absent for table/table-extension.
                             // This is the single-op RPC that BridgeClient.addField() calls —
                             // it must forward the same parameters as the batch-modify case below.
+                            // `type`/`extendedDataType` are the spellings the create path's
+                            // fields[] uses for the same two things; accepting only the
+                            // add-field spelling silently defaulted them (String, no EDT).
                             return _writeService!.AddField(tableName, fieldName,
-                                request.GetStringParam("fieldType") ?? "String",
-                                request.GetStringParam("edt"),
+                                request.GetStringParam("fieldType") ?? request.GetStringParam("type") ?? "String",
+                                request.GetStringParam("edt") ?? request.GetStringParam("extendedDataType"),
                                 request.GetBoolParam("mandatory") ?? false,
                                 request.GetStringParam("label"),
                                 request.GetStringParam("dataField"),
@@ -951,7 +954,12 @@ namespace D365MetadataBridge.Protocol
 
                         // Extract string helper
                         string? S(string key) => p.TryGetValue(key, out var v) ? v?.ToString() : null;
-                        bool? B(string key) => p.TryGetValue(key, out var v) && v != null ? Convert.ToBoolean(v) : null;
+                        // System.Text.Json boxes every params value as JsonElement, which does
+                        // not implement IConvertible — Convert.ToBoolean(v) therefore threw
+                        // InvalidCastException on every batch op carrying a bool, and the catch
+                        // below reported that cast as the operation's failure. Same coercion as
+                        // the single-op arms' request.GetBoolParam.
+                        bool? B(string key) => p.TryGetValue(key, out var v) ? ParamCoercion.ToBool(v, key) : null;
 
                         switch (op.Operation.ToLowerInvariant())
                         {
@@ -972,10 +980,11 @@ namespace D365MetadataBridge.Protocol
                             case "add-field":
                                 // dataField/dataSource select the data-entity-extension mapped-field
                                 // path inside AddField; both are absent for table/table-extension.
+                                // Same `type`/`extendedDataType` aliasing as the single-op RPC.
                                 writeResult = _writeService.AddField(objectName,
                                     S("fieldName") ?? throw new ArgumentException("Missing: fieldName"),
-                                    S("fieldType") ?? "String",
-                                    S("edt"),
+                                    S("fieldType") ?? S("type") ?? "String",
+                                    S("edt") ?? S("extendedDataType"),
                                     B("mandatory") ?? false,
                                     S("label"),
                                     S("dataField"),
@@ -1096,9 +1105,18 @@ namespace D365MetadataBridge.Protocol
                             case "addenumvalue":
                             case "add-enum-value":
                                 {
+                                    // A value that would not parse used to fall through as 0 —
+                                    // so add-enum-value(value:"three") wrote element 0, a
+                                    // duplicate of the enum's first member, and reported success.
                                     int enumVal = 0;
                                     if (p.TryGetValue("enumValue", out var ev) || p.TryGetValue("value", out ev))
-                                        int.TryParse(ev?.ToString(), out enumVal);
+                                    {
+                                        var evText = ev?.ToString();
+                                        if (!string.IsNullOrWhiteSpace(evText) && !int.TryParse(evText, out enumVal))
+                                            throw new ArgumentException(
+                                                $"add-enum-value: value '{evText}' is not an integer — nothing was written. " +
+                                                "Enum values are integers 0-250; omit the parameter to take the next free position.");
+                                    }
                                     writeResult = _writeService.AddEnumValue(objectName,
                                         S("enumValueName") ?? S("valueName") ?? throw new ArgumentException("Missing: enumValueName"),
                                         enumVal, S("label"), S("countryRegionCodes"));

package/bridge/D365MetadataBridge/Services/CrossReferenceService.cs

@@ -10,9 +10,36 @@ namespace D365MetadataBridge.Services
     /// <summary>
     /// Provides cross-reference queries using the DYNAMICSXREFDB SQL database.
     /// This replaces the FTS5 text-search approach with real compiler-resolved references.
+    ///
+    /// ## Query failures are errors, never empty results
+    ///
+    /// Every method here answers one question — "what else touches this?" — and the answer
+    /// drives whether it is safe to change something. A failed query used to be returned as
+    /// a SUCCESSFUL response carrying count=0 plus an `error` field, which reads to any
+    /// caller that does not inspect the extra field as the strongest possible clearance:
+    /// "nothing references this, go ahead". A down or unreachable xref database therefore
+    /// produced false negatives on exactly the question the service exists to answer, and
+    /// the more broken the database, the safer everything looked.
+    ///
+    /// So failures throw. RequestDispatcher.HandleXref turns them into a JSON-RPC error, and
+    /// the TS adapters already treat a rejected call as "no answer from the bridge" and fall
+    /// back to their own scan instead of trusting a zero.
     /// </summary>
     public class CrossReferenceService
     {
+        /// <summary>
+        /// Rethrows a failed xref query as an error the dispatcher will surface, with the
+        /// query's subject in the message so the caller can see what was NOT answered.
+        /// </summary>
+        private static Exception QueryFailed(string operation, string subject, Exception cause)
+        {
+            Console.Error.WriteLine($"[CrossRefService] {operation}({subject}) failed: {cause.Message}");
+            return new InvalidOperationException(
+                $"Cross-reference query {operation}('{subject}') failed: {cause.Message}. " +
+                "This is NOT an empty result — the cross-reference database did not answer, so nothing " +
+                "can be concluded about references to this object.", cause);
+        }
+
         private readonly string _connectionString;
 
         public CrossReferenceService(string server, string database)
@@ -209,8 +236,7 @@ namespace D365MetadataBridge.Services
             }
             catch (SqlException ex)
             {
-                Console.Error.WriteLine($"[CrossRefService] SQL error: {ex.Message}");
-                return new { objectPath, count = 0, references = new List<ReferenceInfoModel>(), error = ex.Message };
+                throw QueryFailed("findReferences", objectPath, ex);
             }
 
             return new { objectPath, count = references.Count, references };
@@ -335,15 +361,7 @@ namespace D365MetadataBridge.Services
             }
             catch (Exception ex)
             {
-                Console.Error.WriteLine($"[WARN] FindExtensionClasses({baseClassName}): {ex.Message}");
-                return new
-                {
-                    baseClassName,
-                    count = 0,
-                    extensions = new List<ExtensionClassDetailModel>(),
-                    error = ex.Message,
-                    _source = "C# bridge (DYNAMICSXREFDB)"
-                };
+                throw QueryFailed("findExtensionClasses", baseClassName, ex);
             }
         }
 
@@ -447,8 +465,7 @@ namespace D365MetadataBridge.Services
             }
             catch (Exception ex)
             {
-                Console.Error.WriteLine($"[WARN] FindEventSubscribers({targetName}): {ex.Message}");
-                return new { targetName, count = 0, handlers = results, error = ex.Message, _source = "C# bridge (DYNAMICSXREFDB)" };
+                throw QueryFailed("findEventSubscribers", targetName, ex);
             }
         }
 
@@ -574,8 +591,7 @@ namespace D365MetadataBridge.Services
             }
             catch (SqlException ex)
             {
-                Console.Error.WriteLine($"[CrossRefService] FindApiUsageCallers SQL error: {ex.Message}");
-                return new { apiName, count = 0, callers = new List<ApiUsageCallerModel>(), error = ex.Message, _source = "C# bridge (DYNAMICSXREFDB)" };
+                throw QueryFailed("findApiUsageCallers", apiName, ex);
             }
 
             // Group by caller class for pattern summary

package/bridge/D365MetadataBridge/Services/MetadataReadService.cs

@@ -125,13 +125,36 @@ namespace D365MetadataBridge.Services
         {
             var sw = System.Diagnostics.Stopwatch.StartNew();
             var factory = new MetadataProviderFactory();
+            var previous = _provider;
             _provider = CreatePrimaryProvider(factory, _packagesPath, _referencePackagesPath);
+            // Hand the new provider over BEFORE releasing the old one, so nothing is
+            // holding a provider that is about to be disposed.
             OnProviderRefreshed?.Invoke(_provider);
+            // Every write auto-refreshes (HandleWrite refreshAfterSuccess), so a long
+            // authoring session builds one DiskProvider per write. Dropping the old one
+            // on the floor kept its file handles and per-package metadata caches alive
+            // over the whole PackagesLocalDirectory until GC felt like it — the bridge
+            // grew until it stopped answering, which is the state the client sees as a
+            // wedged process.
+            DisposeProvider(previous);
             sw.Stop();
             Console.Error.WriteLine($"[MetadataService] Provider refreshed in {sw.ElapsedMilliseconds}ms");
             return new { refreshed = true, elapsedMs = sw.ElapsedMilliseconds };
         }
 
+        /// <summary>
+        /// Releases a superseded provider. Whether DiskProvider implements IDisposable
+        /// varies across metamodel versions, so this asks rather than assumes; a failure
+        /// to release is logged and swallowed because the replacement is already live and
+        /// the refresh itself succeeded.
+        /// </summary>
+        private static void DisposeProvider(IMetadataProvider? provider)
+        {
+            if (provider is not IDisposable disposable) return;
+            try { disposable.Dispose(); }
+            catch (Exception ex) { Console.Error.WriteLine($"[WARN] Failed to dispose superseded metadata provider: {ex.Message}"); }
+        }
+
         /// <summary>
         /// Asks IMetadataProvider to read back an object that was just written to disk.
         /// Returns field/method counts and a success flag — proves the XML is well-formed
@@ -144,11 +167,23 @@ namespace D365MetadataBridge.Services
                 switch (objectType.ToLowerInvariant())
                 {
                     case "table":
-                    case "table-extension":
                         if (!_provider.Tables.Exists(objectName)) return new { valid = false, reason = $"Table '{objectName}' not found by IMetadataProvider after refresh" };
                         var t = _provider.Tables.Read(objectName);
                         return new { valid = true, objectType, objectName, fieldCount = t?.Fields?.Count ?? 0, methodCount = t?.Methods?.Count ?? 0, indexCount = t?.Indexes?.Count ?? 0 };
 
+                    // Extensions live in their OWN provider collection, keyed by the dotted
+                    // "Base.ModelExtension" name. Tables/Forms are keyed by plain names, so
+                    // looking an extension up there always misses — a false negative on every
+                    // extension write, regardless of refresh.
+                    case "table-extension":
+                    {
+                        var tx = _provider.TableExtensions.Read(objectName);
+                        if (tx == null) return new { valid = false, reason = $"TableExtension '{objectName}' not found by IMetadataProvider after refresh" };
+                        int txMethods = 0;
+                        try { dynamic dtx = tx; if (dtx?.Methods != null) foreach (var _ in dtx.Methods) txMethods++; } catch { }
+                        return new { valid = true, objectType, objectName, fieldCount = tx.Fields?.Count ?? 0, methodCount = txMethods, indexCount = tx.Indexes?.Count ?? 0 };
+                    }
+
                     case "class":
                     case "class-extension":
                         if (!_provider.Classes.Exists(objectName)) return new { valid = false, reason = $"Class '{objectName}' not found by IMetadataProvider after refresh" };
@@ -167,10 +202,13 @@ namespace D365MetadataBridge.Services
                         return new { valid = true, objectType, objectName };
 
                     case "form":
-                    case "form-extension":
                         if (!_provider.Forms.Exists(objectName)) return new { valid = false, reason = $"Form '{objectName}' not found by IMetadataProvider after refresh" };
                         return new { valid = true, objectType, objectName };
 
+                    case "form-extension":
+                        if (_provider.FormExtensions.Read(objectName) == null) return new { valid = false, reason = $"FormExtension '{objectName}' not found by IMetadataProvider after refresh" };
+                        return new { valid = true, objectType, objectName };
+
                     case "query":
                         if (!_provider.Queries.Exists(objectName)) return new { valid = false, reason = $"Query '{objectName}' not found by IMetadataProvider after refresh" };
                         return new { valid = true, objectType, objectName };
@@ -235,7 +273,6 @@ namespace D365MetadataBridge.Services
                 switch (objectType.ToLowerInvariant())
                 {
                     case "table":
-                    case "table-extension":
                     {
                         var prov = PickProvider(p => p.Tables.Exists(objectName));
                         if (prov == null) return null;
@@ -243,6 +280,17 @@ namespace D365MetadataBridge.Services
                         try { var mi = prov.Tables.GetModelInfo(objectName); if (mi?.Count > 0) model = mi.First().Name; } catch { }
                         return new { exists = true, objectType, objectName, model };
                     }
+                    // Probed against TableExtensions/FormExtensions, not Tables/Forms — see
+                    // the note in ValidateObject: the dotted extension name is never a key
+                    // in the base collection, so probing there never resolves an extension.
+                    case "table-extension":
+                    {
+                        var prov = PickProvider(p => p.TableExtensions.Read(objectName) != null);
+                        if (prov == null) return null;
+                        string? model = null;
+                        try { var mi = prov.TableExtensions.GetModelInfo(objectName); if (mi?.Count > 0) model = mi.First().Name; } catch { }
+                        return new { exists = true, objectType, objectName, model };
+                    }
                     case "class":
                     case "class-extension":
                     {
@@ -269,7 +317,6 @@ namespace D365MetadataBridge.Services
                         return new { exists = true, objectType, objectName, model };
                     }
                     case "form":
-                    case "form-extension":
                     {
                         var prov = PickProvider(p => p.Forms.Exists(objectName));
                         if (prov == null) return null;
@@ -277,6 +324,14 @@ namespace D365MetadataBridge.Services
                         try { var mi = prov.Forms.GetModelInfo(objectName); if (mi?.Count > 0) model = mi.First().Name; } catch { }
                         return new { exists = true, objectType, objectName, model };
                     }
+                    case "form-extension":
+                    {
+                        var prov = PickProvider(p => p.FormExtensions.Read(objectName) != null);
+                        if (prov == null) return null;
+                        string? model = null;
+                        try { var mi = prov.FormExtensions.GetModelInfo(objectName); if (mi?.Count > 0) model = mi.First().Name; } catch { }
+                        return new { exists = true, objectType, objectName, model };
+                    }
                     case "query":
                     {
                         var prov = PickProvider(p => p.Queries.Exists(objectName));