genexus-mcp 3.16.0 → 4.0.1

package/README.md

@@ -117,62 +117,76 @@ does not claim the same feature parity as the native SDK contract for GeneXus
 
 ## Experimental `gx-engine` (Rust SDK Replacement Project)
 
-`src/gx-engine` is an experimental, independent Rust compiler and runtime designed to progressively replace the proprietary GeneXus SDK with an open, high-performance native toolchain ([Plan 129](plans/129-independent-rust-toolchain.md)).
+`src/gx-engine` is an independent, high-performance Rust compiler and runtime designed to completely replace the proprietary GeneXus SDK, eliminate the legacy 32-bit STA worker, and deliver sub-20s builds ([Plan 130](plans/130-direct-udm-kb-engine.md), [Plan 129](plans/129-independent-rust-toolchain.md)).
 
 ### 🎮 Decompilation / Parity Progress
 
-Similar to video game decompilation projects, progress is measured capability-by-capability against verified differential runs of the official GeneXus SDK in clean Knowledge Bases.
+Progress is measured against recorded SDK differential inputs and observable results, not the number of implemented modules or passing unit tests. At the published 4.0.0 baseline, the disposable `KBTeste` Rebuild All recorded **346/346, 0 skipped, 0 refused** and **byte for byte (328/328 files)** C# agreement, together with web scripts, `gxcfg.js`, messages and runtime configuration. These historical counts do not validate later changes or prove that unsupported database semantics were preserved. **Full SDK replacement is not verified** for arbitrary KBs: unsupported forms are still refused by name, and only one KB is the oracle. gx-engine is the **default backend** (`Engine.Backend=gxengine`: admitted builds and field-limited type-only queries; reads/edits and other shapes use SDK fallback; `auto` = builds only, `sdk` = engine off); see [engine routing](docs/engine_backend.md).
 
-```text
-Overall SDK Replacement: [🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜] 50.0% weighted (69.6% total areas touched: 39/56)
-```
+### What builds today
 
-| Subsystem | Progress | Status | Covered / Total |
-| :--- | :---: | :---: | :---: |
-| **Language & Runtime Core** (Math, Decimals, Text, Dates, Calendar) | `[🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩] 100.0%` | Native Parity | 8 / 8 areas |
-| **Control Flow & Procedure Pipeline** (`If`, `Iif`, `For`, `For In`, `Exit`, `Case`, `Sub`/`Do`, `Call`/`.UDP`, `IsEmpty`/`SetEmpty`/`Nullvalue`) | `[🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩] 100.0%` | Native Parity | 6 / 6 areas |
-| **Structured Data & Collections** (SDT, `Add`, `Remove`, `Clear`, `IndexOf`, `Item`, `ToJson`, `FromJson`, `ToXml`, `FromXml`) | `[🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩] 100.0%` | Native Parity | 5 / 5 areas |
-| **Portable KB Catalog & XML Projection** (Procedures, SDT, Domain, Attribute, Transaction, Rules in `ExportFile` XML and portable catalog) | `[🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩] 100.0%` | Native Parity | 6 / 6 areas |
-| **Specifier & SQL Navigation** (Physical Tables, DDL, Navigation, `For Each`) | `[🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜]  75.0%` | Navigation & Query Plan | 6 / 8 areas |
-| **Native KB Database Storage** (`.gxi`, `GXLOCK`, `DATA*`) | `[⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜]   0.0%` | Unsupported (SDK-only) | 0 / 5 areas |
-| **Full GeneXus Surface** (UI, Events, Generators) | `[⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜]   0.0%` | Unsupported | 0 / 18 areas |
+The counts and timings below describe the published 4.0.0 baseline, not a fresh
+validation of uncommitted generator changes. Checked emission now refuses
+unsupported database statements rather than accepting incomplete behavior;
+post-change whole-KB counts and SDK parity must be measured again.
 
-#### Gateway Capability Registry Gates
+| Lane | Verified evidence | Boundary |
+| :--- | :--- | :--- |
+| Package build | `build.ps1` built Gateway, Worker, gxwire and gx-engine; local publish/backend engine hashes match. | Building the MCP distribution is not building every object in a KB. |
+| Selected-object build | Five alternating local SDK/engine pairs regenerated and compiled `DCM37961700`; core APIs and actual CLI output matched. SDK median **14.756s**, engine **0.230s** (**64.19×**). | Synthetic warm fixture; AUTO_CLOSE=OFF on both sides, original ON restored. The packaged binary was not benchmarked; it passed a separate build/run smoke. |
+| Full native KB build (`KBTeste`) | `rebuild-all`: **346 generated / 346 compiled, 0 skipped, 0 refused**. Against the SDK's own output for the same KB: **328/328 C# files byte-identical, 0 missing**; 24/24 web `.js`, `gxcfg.js`, `messages.eng.txt/.js`, `log.config`, `log.console.config` (+ `bin/` copies) and `CloudServices.config` byte-identical. | One oracle KB. Extra SDT and assembly-info output remains outside the matching-file denominator. Developer Menu not written (its object selection is not established). |
+
+Use the SDK for required workflows outside validated engine coverage. See
+[Plan 131](plans/131-sdk-performance-benchmark.md) for the exact binary, commands,
+samples and caveats; [engine routing](docs/engine_backend.md) for default/explicit backend behavior.
 
-The MCP Gateway exposes a strict capability gate (`EngineCapabilityRegistry`) where operations are classified by measured parity before any traffic can be routed:
-
-| Capability | Status | Evidence & Performance |
-| :--- | :---: | :--- |
-| `str_format` | 🟩 **Parity** | `Str()` numeric picture rules: 36,246 native rows verified, 0 diffs. Measured ~121 ns/row vs ~280 ns/row SDK (~2.3x faster). |
-| `numeric_render` | 🟩 **Parity** | `&var.ToString()` / `Print()`: 120 native boundary cases verified (precision 1..18, scale corners, padding). |
-| `date_display` | 🟩 **Parity** | Date/DateTime rendering: 18 native boundary cases verified (`MM/dd/yy`, 12h AM/PM, empty sentinels). |
-| `text_functions` | 🟩 **Parity** | `Substr`/`Upper`/`Lower`/`StrReplace`: 63 native KBTeste cases verified (1-based, expand-casing, exact replace). |
-| `text_extended_functions` | 🟩 **Parity** | `LTrim`/`RTrim`/`PadL`/`PadR`/`Space`/`Concat`/`StartsWith`/`EndsWith`/`Contains`/`StrSearch`: 95 native `StringUtil` oracle rows verified (exact ASCII space trim, left/right pad truncation, single-sided concat trim, ordinal comparisons, 1-based index clamping). |
-| `numeric_math_functions` | 🟩 **Parity** | `Int`/`Round`/`Trunc`/`Val`/`Left`/`Right`/`Asc`/`Chr`/`NotNumeric`/`LTrimStr`: 107 native `NumberUtil` and `StringUtil` oracle rows verified (`Math.Floor`, `AwayFromZero` with negative digit support, truncation toward zero, numeric string parsing, ASCII char conversions). |
-| `collection_operations` | 🟩 **Parity** | `Add`/`Remove`/`Clear`/`IndexOf`, `For In` iteration and `Exit`: 24 native `GxSimpleCollection` and `GXBaseCollection` oracle rows verified (1-based indexing, insertion, out-of-bounds silent removal, element aliasing in loops, loop exit). |
-| `calendar_operations` | 🟩 **Parity** | `Day`/`Month`/`Year`/`Hour`/`Minute`/`Sec`/`Dow`, `AddYr`/`AddMth`/`DAdd`/`TAdd`, `DDiff`/`TDiff`, `Age`, `EndOfMonth`, `ResetTime`, and `.ToString()`: 83 native `DateTimeUtil` oracle rows verified (1=Sunday DOW, leap clamping, second rollover, whole-day truncated DDiff, completed years Age). |
-| `subroutine_control_flow` | 🟩 **Parity** | `Sub 'Name' ... EndSub` and `Do 'Name'`: 13 native-verified tests (procedure-scoped variable mutation, case-insensitive resolution, quote styles, nested subroutine calls, early `Return` propagation via `returnInSub` semantics, depth limit 128). |
-| `conditional_and_state_operations` | 🟩 **Parity** | `Iif(cond, trueExpr, falseExpr)` short-circuit conditional, universal `.IsEmpty()`/`IsEmpty()` and `.SetEmpty()` across all types, `Nullvalue(&var)`, `.UDP(...)` calls, and `Format`/`NewLine`/`Replicate`/`CharAt`/`StrSearchRev`/`.LastIndexOf`/`BoolToStr`/`ToBoolean`/`StrToBool`: 57 native `StringUtil` and state oracle rows verified. |
-| `sdt_and_collection_json` | 🟩 **Parity** | `&sdt.ToJson()`, `&sdt.FromJson()`, `&col.ToJson()`, `&col.FromJson()`: 32 native `GxUserType` and `GXBaseCollection<T>` oracle rows verified (compact representation, escaped strings, `"0000-00-00"` empty dates, case-insensitive keys, partial updates, and safe array repopulation). |
-| `sdt_and_collection_xml` | 🟩 **Parity** | `&sdt.ToXml([root])`, `&sdt.FromXml(xml, [root])`, `&col.ToXml([root])`, `&col.FromXml(xml, [root])`: 40 native `GxUserType` and `GXBaseCollection<T>` XML oracle rows verified (indentation, self-closing tags `<Tag />`, XML entity escaping, ISO `yyyy-MM-ddT00:00:00` date/time, booleans, case-insensitive element parsing, empty reset, and fail-closed error returns). |
-| `domain_attribute_projection` | 🟩 **Parity** | Domain (`00972a17-9975-449e-aab1-d26165d51393`) and Attribute (`adbb33c9-0906-4971-833c-998de27e0676`) projection and `BasedOn` resolution in portable catalog and SDK `ExportFile` XML: 10 native-verified integration tests (procedure variables, chained domains, SDT items, cycle detection, domain-cannot-be-based-on-attribute enforcement, and end-to-end `xml-run`). |
-| `transaction_structure_projection` | 🟩 **Parity** | Transaction (`1db606f2-af09-4cf9-a3b5-b481519d28f6`) structure, keys, and multi-level hierarchy projection in portable catalog and `ExportFile` XML: 10 native-verified integration tests (nested levels, root and child primary key enforcement, attribute references, recursion depth limit 16, Business Component `RecordType` schema lowering, procedure interoperability). |
-| `rules_and_parm_parity` | 🟩 **Parity** | GeneXus Rules part (`9b0a32a3-de6d-4be1-a4dd-1b85d3741534`) parser and AST with Parm interface parity in portable catalog and SDK `ExportFile` XML: 10 native-verified integration tests (`Parm`, `Error`, `Msg`, `Default`, `NoAccept`, `Accept`, `Order`, `Prompt`, `Serial`, `Hidden`, single/multi-line comments, strings with semicolons/escaped quotes, fail-closed diagnostics, procedure-scope enforcement, catalog and XML exchange integration). |
-| `transaction_control` | 🟩 **Parity** | Database transaction control procedural statements (`Commit` and `Rollback`, bare keywords or call syntax `Commit()`, `Rollback()` with optional semicolons): 7 native-verified integration tests (conditionals, loops, subroutines, while loops, format_version 1 fail-closed rejection, compiled executable execution, and ExportFile XML exchange). |
-| `physical_table_ddl` | 🟩 **Parity** | Physical Table schema normalization and multi-dialect SQL DDL generation (`CREATE TABLE`, primary keys, parent-child and cross-transaction foreign keys, indexes, ANSI/SQL Server/PostgreSQL/Oracle data types): 9 native-verified integration tests without database writes. |
-| `sql_navigation` | 🟩 **Parity** | Specifier, base table inference, For Each navigation, extended table joins, and multi-dialect SQL query planning (ANSI, SQL Server, PostgreSQL, Oracle): 10 native-verified integration tests, 13 frontend tests, fail-closed diagnostics (`spc0004`, `spc0005`), and zero SQL writes. |
-| `numeric_core`, `text_core`, `calendar_values`, `records_collections`, `procedure_pipeline`, `xml_projection`, `kb_catalog` | 🟨 **Partial** | Independently implemented in portable compiler and tested with synthetic or bounded fixtures; pending full parity claims. |
-| `native_kb_read`, `general_gx_surface` | ⬜ **Unsupported** | Not yet implemented in Rust. Always served 100% by the GeneXus SDK / Worker. |
+| Subsystem | Evidence boundary / remaining work |
+| :--- | :--- |
+| Language, runtime, control flow, SDTs and collections | Bounded native differential corpora; not exhaustive GeneXus semantics. |
+| Portable catalog and XML projection | Fixture-backed support; does not establish native KB round-trip parity. |
+| Specifier, SQL navigation and datastore behavior | Portable tests do not prove complete live SDK navigation or database behavior. |
+| Native UDM storage | Live read evidence and targeted tests; not a general SDK persistence replacement. |
+| C# generation and Rebuild All | Live generated-object checks pass within a bounded set; refusals, missing objects and SDK-oracle gaps remain. |
+| Web UI, Transactions, Reports and BCs | Partial implementations; a successful compile is not end-to-end product parity. |
+
+See the [current acceptance/evidence ledger](plans/129-implementation-progress.md#current-acceptance-status--2026-10-18) for the tested binary, scope, failures and next actions.
+
+#### Gateway Capability Registry Gates
 
+The MCP Gateway exposes an evidence gate (`EngineCapabilityRegistry`). See the
+[current capability table](docs/engine_backend.md) for each bounded status,
+consumer and evidence source. Runtime oracle fixtures, portable model tests and
+live MCP compatibility are different kinds of evidence; none is an overall SDK
+replacement percentage.
+
+- Native-runtime oracle rows cover only their recorded inputs, encodings and
+  environment; synthetic library tests alone do not establish native parity.
+- Admitted type-only queries and blocking builds/rebuilds are the current native
+  MCP surface. Reads and edits remain SDK-backed or fail closed; routing a call
+  to a deferral guard is not native implementation coverage.
+- Storage decoding, navigation planning, object modeling and C# emission remain
+  partial. Unsupported database statements must fail generation rather than
+  produce a successful Procedure with missing database behavior.
+
+The published 4.0.0 `KBTeste` result (346 compiled classes, 328 matching SDK C#
+files and 20 extra files) is historical, bounded evidence. It is not a fresh
+validation of later safety changes, all object families or whole-SDK behavior.
+The [full-parity acceptance plan](plans/132-gxengine-full-parity.md) tracks the
+remaining workflows and evidence required.
 
 ### ⚡ Performance Benchmarks (gx-engine vs. GeneXus SDK)
 
-Every performance comparison requires **exact output parity** verified before measuring timings (zero mismatches, identical hash/byte output). The initial differential benchmarks measured on local Windows x86_64 hardware:
+A speed comparison requires the same input workload, target, dependency closure, observable results and success criteria. Independent generators need not emit byte-identical source or assemblies. Keep full SDK specify/generate/compile timings separate from compile-only MSBuild timings and bounded runtime microbenchmarks. On the disposable `KBTeste`, a whole-KB Rebuild All with a full compile measures 51.7× against the SDK's specify + generate alone (median of a paired run); the selected-object result meets 50× only within its stated warm-fixture scope. Historical microbenchmarks do not establish a whole-KB speed goal:
 
 | Benchmark Workload | GeneXus SDK (.NET / MSBuild) | `gx-engine` (Rust) | Speedup / Gain | Verification & Oracle |
 | :--- | :---: | :---: | :---: | :--- |
+| **Warm selected-object C# build** (`DCM37961700`) | **14,755.9 ms** *(local specify + generate + Rebuild/Publish)* | **229.9 ms** *(live read + emit + guarded compiler replay, setup included)* | **64.19×** | Five alternating pairs; bounded API and direct CLI checks, stable sources. Synthetic fixture, AUTO_CLOSE=OFF; not cold/full-KB or packaged-binary performance. [Protocol](plans/131-sdk-performance-benchmark.md). |
 | **`Str()` Numeric Picture Formatting** (Microbenchmark) | 274 – 286 ns / row *(1.75 ms / pass)* | **121 – 130 ns / row** *(0.75 ms / pass)* | **~2.25x faster** | 6,152 rows (`str_matrix.tsv`), 80,235 chars, identical FNV-1a UTF-16 hash (`0xb9e1b48fb72067b0`), 0 mismatches against official `GeneXus.Classes.Core` runtime. |
-| **End-to-end Procedure Compilation & Build** | 10,930 ms *(SDK stages)*<br>16,366 ms *(MSBuild total)* | **223 ms** *(Rust parse + emit + rustc link)* | **~49x faster** | Synthetic `RustTimingProbe` in authorized `KBTeste` (`21 * 2 = 42`). Identical exit 0 and stdout `42`. |
+| **Live KB Metadata & Part Hydration** | 12,000 – 18,000 ms *(serial COM STA)* | **320 ms** *(direct TDS queries)* | **> 35x faster** | Verified on live LocalDB `GX_KB_KBTeste` (`test_udm_real_kb_live_read_procedure`). |
+| **Whole-KB generation** (`KBTeste`, specify + generate, no compile; earlier engine binary) | **33.4 – 39.9 s** *(MSBuild `SpecifyAllOnly` + `GenerateOnly`, 3 runs)* | **0.61 – 0.68 s** *(`rebuild-all --skip-compile`, 3 runs alternating with the SDK runs; ~0.45 s of it is the KB catalog read)* | **~58× (median pair)** | Paired, one machine, 2026-10-21; neither side compiles; engine output unchanged after the SDK runs. Not a 50× claim: output parity is 328/328 C# identical with 20 extra files and no Developer Menu, so full SDK parity is unverified. The previous engine binary measured 1.29 – 1.40 s (12 alternating runs). |
+| **Whole-KB Rebuild All, nothing changed** (`KBTeste`, 346 classes) | **42.2 s** median *(32.3 – 46.2 s; MSBuild `SpecifyAllOnly` + `GenerateOnly`, no compile, 3 runs)* | **289 ms** median *(271 – 306 ms, 9 runs: catalog ~150 ms + emit ~70 ms; compile skipped as up to date)* | **~146× (median)** | Paired and alternating, one machine, 2026-10-21, database held open by an idle connection as an opened KB holds it. The SDK side does not compile, the engine side does (or proves its outputs current). Output parity: 328/328 C# identical, 20 extra files, 0 missing; full SDK parity unverified. Script `bench-s42.py`. |
+| **Whole-KB Rebuild All, forced full compile** (`KBTeste`, 346 classes) | **42.2 s** median *(same SDK runs, no compile)* | **816 ms** median *(739 – 989 ms, 9 runs: direct `csc` with `/shared` and `/skipanalyzers+`, ~0.6 – 0.7 s)* | **~51.7× (median)** | Same paired run; the compile record is removed before each sample so all 346 classes compile again. The ratio is a median of medians: against the fastest SDK run (32.3 s) and slowest engine run it is ~33×. A first build into a new folder takes ~1.9 s (`dotnet build`); a cold compiler server was measured once at ~22.8 s. The former 480,000 ms / 1,250 ms (>380×) comparison had no matched IDE measurement and stays withdrawn. |
+| **Historical arithmetic fixture build** | 10,930 ms *(SDK stages)*<br>16,366 ms *(MSBuild process wall)* | **223 ms** *(Rust CLI + rustc build)* | **Not a whole-SDK speed ratio** | `RustTimingProbe` (`21 * 2 = 42`), three recorded samples, exit/output checked. Different pipelines and targets; the former ~49× stage/build ratio applies only to that tiny fixture. [Evidence and caveats](src/gx-engine/VALIDATION.md#verified-custom-msbuild--sdk-pipeline). |
 | **Generated Artifact Startup & Execution** | 123.06 ms *(CLR bootstrap + run)* | **5.75 ms** *(native binary bootstrap)* | **~21x faster** | Cold process launch and console output for the compiled arithmetic procedure artifact. |
 
 #### 📈 Benchmark Protocol & How to Record Improvements
@@ -189,23 +203,23 @@ As new capabilities reach parity and additional optimizations land, follow this
 ### Activation Flag & Safety Seam
 
 > [!IMPORTANT]
-> **Zero Automatic Routing:** By default, `Engine.Backend` is `"sdk"`. The Gateway serves 100% of tool calls through the official GeneXus SDK. Even when `gxengine` is enabled, the router fails closed: only capabilities with measured `Parity` and an explicitly registered consumer can route to the engine; everything else stays on the SDK.
+> **Engine-first:** `Engine.Backend` defaults to `"gxengine"`. Blocking `genexus_lifecycle` builds/rebuilds inside the admitted space use gx-engine, and so do admitted type-only `genexus_query` calls selecting only `name`/`type` fields. A directed `build` with `mode=compile_check`, explicit `callers=false` and transitive callees also uses gx-engine, building only the target closure. Edits, async/other directed builds, all reads, `usedby:` searches, ranked fuzzy queries and unsupported request shapes fall back to the SDK. Capability and argument gates still apply. Build errors or uncertain outcomes after engine start never trigger automatic SDK replay. `"auto"` routes only builds to the engine; `"sdk"` keeps every operation on the SDK and never invokes the engine.
 
-To test or benchmark the engine from a source checkout, configure `config.json`:
+No backend setting is needed. To narrow routing to builds (`"auto"`) or turn the engine off (`"sdk"`), configure `config.json`:
 
 ```json
 {
   "Engine": {
-    "Backend": "gxengine",
+    "Backend": "auto",
     "Fallback": "sdk",
     "TimeoutSeconds": 120
   }
 }
 ```
 
-- **`Engine.Backend`**: `"sdk"` (default) or `"gxengine"` (opt-in).
-- **`Engine.Fallback`**: `"sdk"` (fallback to GeneXus SDK when not at parity) or `"error"` (fails closed with `EngineCapabilityNotParity` for strict verification).
-- **Diagnostics**: `genexus_doctor` inspects the engine via `--version` handshake and reports an `engine` status block with `backend`, `available`, `version`, `capabilities`, and `routedOperations`.
+- **`Engine.Backend`**: `"gxengine"` (default: admitted builds and field-limited type-only queries; reads/edits use SDK fallback), `"auto"` (admitted builds only), or `"sdk"` (SDK only, engine never invoked).
+- **`Engine.Fallback`**: `"sdk"` (fallback to GeneXus SDK outside admitted native coverage) or `"error"` (fails closed: `EngineCapabilityNotParity` for evidence-gate rejection; `EngineOperationOutsideAdmittedSpace` for read/edit deferrals and unsupported query/build arguments).
+- **Diagnostics**: `genexus_doctor` inspects the engine via `--version` handshake and reports an `engine` status block with `backend`, `available`, `version`, and `capabilities`. Its `routedOperations` lists served native operations; `deferredOperations` lists read/edit deferrals separately, never as parity.
 
 To run compiler tests or standalone projects from checkout:
 
@@ -284,7 +298,7 @@ A quick map of what the agent can do against your real KB through the **60 tools
 | Area | What the agent can do |
 |---|---|
 | 🔎 **Explore** | Search & list objects, read any part (source, rules, events, structure, docs, pattern XML), inspect metadata & callers, regex-search source, view the navigation report |
-| 🧭 **Orient & trace** | Rank the objects a task touches, list direct and transitive callers, trace the shortest call path between two objects, check blast radius and safe-delete, follow one variable's data flow. Runs on exported sources through `genexus_wire` (read-only, token-budgeted) |
+| 🧭 **Orient & trace** | Rank the objects a task touches, list direct and transitive callers, trace the shortest call path between two objects, check blast radius and safe-delete, follow one variable's data flow. Runs on exported sources through `genexus_wire` (read-only, token-budgeted); `pack_task` also works directly on the open native KB |
 | ✏️ **Edit code** | Edit any object part (`full`/`patch`/`ops` modes), variables CRUD, format, create & delete objects, scaffold a Procedure from a **curl command**, edit + rebuild callers in one shot |
 | 🗄️ **Author the data model** | Transaction structure (DSL), **unique/non-unique indexes** (create & drop), **attribute formulas & subtypes**, level Description/Image attributes, **Domain enum values**, folders & modules, table↔transaction relations & redundant-attribute detection |
 | 🧩 **Author other objects** | External Object methods & properties, Menu options, REST API objects, WorkWithPlus / WorkWith patterns, typed .NET generator references |
@@ -551,7 +565,7 @@ The worker exposes **60 tools** to the MCP router, grouped by capability below.
 **Architecture discovery & call graph**
 - `genexus_wire` — read-only, token-budgeted call-graph engine (bundled `gxwire.exe`). Actions: `pack_task` (default; one-shot orientation bundle for a task), `for` (intent ranking with domain synonyms such as `fat` → `faturamento`), `status` (graph size and top hubs), `callers` (direct and transitive), `impact` (blast radius, writers, readers), `path` (shortest call path from `from` to `to`), `slice` (definitions and uses of one variable, `target` = `Object:Variable`), `safe_delete` (blockers before deleting a symbol), `index` (rebuild the cache), `doctor` (engine and cache diagnostics)
 
-`genexus_wire` does not go through the Worker or the GeneXus SDK. The Gateway runs `gxwire.exe` on the target folder (`dir`, `kb`, or the active KB path) and returns its output. It reads exported source text (`.prc`, `.trn`, `.wp`, `.sdp`, `.xml`, `.txt`, `.gx`, `.gxd`) with regex heuristics, so answers reflect the exported files, not the live KB; an empty folder returns `empty="true"`. Use it to decide where to look and what a change touches. Use `genexus_query` to search live objects and `genexus_read` to read their parts. Parameters: `task` (`pack_task`, `for`), `target` (`callers`, `impact`, `slice`, `safe_delete`), `from`/`to` (`path`), `format`, `token_budget` (default 1200), `full`, `kb`/`dir`. `format` is `toon` (compact, recommended), `xml` (default), `json`, or `mermaid`; mermaid renders `status`, `callers`, `impact`, `path` and `pack_task`, and other actions return XML. The only file it writes is `.gxwire_cache.bin` in the target folder, on `index` and when the cache is stale.
+`genexus_wire` goes through neither the Worker nor the GeneXus SDK, with one exception: `action=pack_task` on the native KB the session has open is answered by that KB's Worker from the SDK-backed index, with no text export. Pass `targets` (object names, `Type:Name` to disambiguate) and/or name the objects in `task`; the result lists the resolved objects with their direct callers and callees, and names every object it could not resolve, found ambiguous, skipped or left out of the token budget. It is read-only and reads no part body. For every other action the Gateway runs `gxwire.exe` on the target folder (`dir`, `kb`, or the active KB path) and returns its output; a native KB folder is refused with `GXWIRE_REQUIRES_TEXT_SOURCE_TREE`, so point `dir` at an exported text tree. It reads exported source text (`.prc`, `.trn`, `.wp`, `.sdp`, `.xml`, `.txt`, `.gx`, `.gxd`) with regex heuristics, so answers reflect the exported files, not the live KB; an empty folder returns `empty="true"`. Use it to decide where to look and what a change touches. Use `genexus_query` to search live objects and `genexus_read` to read their parts. Parameters: `task` (`pack_task`, `for`), `target` (`callers`, `impact`, `slice`, `safe_delete`), `from`/`to` (`path`), `format`, `token_budget` (default 1200), `full`, `kb`/`dir`. `format` is `toon` (compact, recommended), `xml` (default), `json`, or `mermaid`; mermaid renders `status`, `callers`, `impact`, `path` and `pack_task`, and other actions return XML. The only file it writes is `.gxwire_cache.bin` in the target folder, on `index` and when the cache is stale.
 
 **Search & discovery**
 - `genexus_query` — object search (prefixes `name:`, `type:`, `usedby:`, `parent:`, …)

package/cli/docs.test.js

@@ -75,6 +75,107 @@ test('the README release section describes the release flow that actually ships'
     assert.match(section, /OIDC Trusted Publishing/);
 });
 
+test('engine documentation keeps fixture results distinct from SDK replacement', () => {
+    const section = markdownSection(read('README.md'), '## Experimental `gx-engine` (Rust SDK Replacement Project)');
+
+    assert.doesNotMatch(section, /Overall SDK Replacement:[^\n]*100(?:\.0)?%/);
+    assert.doesNotMatch(section, /\*\*>\s*380x faster\*\*/);
+    assert.match(section, /Full SDK replacement is not verified/);
+    assert.match(section, /64\.19×/);
+    assert.match(section, /plans\/131-sdk-performance-benchmark\.md/);
+    assert.match(section, /plans\/129-implementation-progress\.md#current-acceptance-status--2026-10-18/);
+    assert.match(section, /Historical arithmetic fixture build/);
+    assert.match(section, /Different pipelines and targets/);
+});
+
+test('engine guidance separates package builds, fixture speed and full-KB coverage', () => {
+    const coverage = markdownSection(read('README.md'), '### What builds today');
+    assert.match(coverage, /Package build/);
+    assert.match(coverage, /Selected-object build/);
+    assert.match(coverage, /Full native KB build/);
+    assert.match(coverage, /346 generated \/ 346 compiled, 0 skipped, 0 refused/);
+    assert.match(coverage, /328\/328 C# files byte-identical/);
+    assert.match(coverage, /One oracle KB/);
+    assert.match(coverage, /packaged binary.*not benchmarked/);
+
+    const guidance = markdownSection(read('AGENTS.md'), '## gx-engine development');
+    assert.match(guidance, /full SDK replacement/);
+    assert.match(guidance, /refusals/);
+    assert.match(guidance, /Engine\.Backend/);
+    assert.match(guidance, /disposable/);
+    for (const document of ['src/gx-engine/README.md', 'docs/engine_backend.md', 'plans/131-sdk-performance-benchmark.md']) {
+        assert.ok(guidance.includes(`](${document})`), `Missing agent pointer: ${document}`);
+        assert.ok(fs.existsSync(path.join(repoRoot, document)), `Missing agent document: ${document}`);
+    }
+
+    const artifactSkill = '.agents/skills/gxe-artifact-parity/SKILL.md';
+    assert.ok(guidance.includes(`](${artifactSkill})`), 'Missing artifact-parity skill pointer');
+    assert.match(read(artifactSkill), /^name: gxe-artifact-parity$/m);
+    assert.match(read(artifactSkill), /scripts\/artifact_diff\.py/);
+    assert.ok(fs.existsSync(path.join(repoRoot, 'src/gx-engine/scripts/artifact_diff.py')));
+
+    const engineReadme = read('src/gx-engine/README.md');
+    const engineCoverage = markdownSection(engineReadme, '## Build coverage and routing');
+    assert.match(engineCoverage, /full SDK replacement is not established/);
+    assert.doesNotMatch(engineReadme, /Full Object Model:\*\* Complete support|compilation in < 20s/);
+    assert.match(engineReadme, /packaged binary was smoke-tested, not benchmarked/);
+});
+
+test('engine SQL authentication guidance distinguishes safe preflight fallback from replay', () => {
+    const guide = read('docs/engine_backend.md');
+    const auth = markdownSection(guide, '## SQL authentication (issue #635)');
+    assert.match(auth, /SQLCMDUSER/);
+    assert.match(auth, /SQLCMDPASSWORD/);
+    assert.match(auth, /private credential store/);
+    assert.match(auth, /exit \*\*5\*\*/);
+    assert.match(auth, /sql_credentials_unavailable/);
+    assert.match(auth, /EngineSqlCredentialsUnavailable/);
+    assert.match(auth, /must not\s+trigger automatic SDK build replay/);
+    const auto = markdownSection(guide, '### Exactly what `auto` routes');
+    assert.match(auto, /compile_check callers=false includeCallees=transitive/);
+    assert.match(auto, /Whole-KB/);
+    assert.match(auto, /estimated_seconds/);
+    assert.match(auto, /Read, query, edit/);
+});
+
+test('engine capability guidance does not duplicate synthetic parity claims', () => {
+    const section = markdownSection(read('README.md'), '#### Gateway Capability Registry Gates');
+    assert.match(section, /\[current capability table\]\(docs\/engine_backend\.md\)/);
+    assert.doesNotMatch(section, /\|\s*`[^`]+`[^\n]*\*\*Parity\*\*/);
+    assert.match(section, /deferral guard is not native implementation coverage/);
+    assert.match(section, /historical, bounded evidence/);
+    assert.match(section, /plans\/132-gxengine-full-parity\.md/);
+});
+
+test('engine default policy is gxengine and preserves auto/SDK opt-out and reconciliation', () => {
+    const section = markdownSection(read('README.md'), '### Activation Flag & Safety Seam');
+    assert.match(section, /defaults to `"gxengine"`/);
+    assert.match(section, /async\/other directed builds/);
+    assert.match(section, /mode=compile_check/);
+    assert.match(section, /callers=false/);
+    const backend = read('docs/engine_backend.md');
+    assert.match(backend, /engine\.scope=target-closure/);
+    assert.match(backend, /successful target build does not imply whole-KB success/);
+    assert.match(backend, /default `callers=true`/);
+    assert.match(section, /`"auto"` routes only builds/);
+    assert.match(section, /`"sdk"` keeps every operation on the SDK/);
+    assert.match(section, /never trigger automatic SDK replay/);
+    assert.match(section, /EngineCapabilityNotParity.*evidence-gate rejection/);
+    assert.match(section, /EngineOperationOutsideAdmittedSpace.*read\/edit deferrals/);
+    for (const document of ['src/gx-engine/README.md', 'docs/engine_backend.md']) {
+        const text = read(document);
+        assert.match(text, /planning skips.*Partial|Partial when skipped during planning/);
+        assert.match(text, /checked-emission errors.*Failed/);
+    }
+    assert.match(section, /admitted type-only `genexus_query` calls/);
+    assert.match(section, /all reads/);
+    assert.match(backend, /No read shape is currently admitted/);
+    assert.match(backend, /all object-name\/text searches \(including\s+`exactMatch:true`\)/);
+    assert.match(read('docs/engine_backend.md'), /`Engine\.Backend=gxengine` \(also when the section is absent\)/);
+    assert.match(read('src/gx-engine/README.md'), /defaults to `Engine\.Backend=gxengine`/);
+    assert.match(read('AGENTS.md'), /`Engine\.Backend` defaults to `gxengine`/);
+});
+
 test('the docs index lists every top-level document and every link resolves', () => {
     const docsDir = path.join(repoRoot, 'docs');
     const index = read('docs/README.md');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genexus-mcp",
-  "version": "3.16.0",
+  "version": "4.0.1",
   "mcpName": "io.github.lennix1337/genexus",
   "description": "GeneXus 16, GeneXus 17, GeneXus 18 MCP server with native SDK support; basic legacy compatibility for GeneXus Evolution 3, GeneXus Evolution 2, GeneXus Evolution 1, GeneXus 15, GeneXus 9.0, GeneXus 8.0 via com-gxpublic and dotnet-reflection drivers — read, edit, and analyze Knowledge Base objects directly from Claude, Cursor, and other AI agents over the Model Context Protocol.",
   "keywords": [

package/publish/GxMcp.Gateway.deps.json

@@ -7,7 +7,7 @@
   "targets": {
     ".NETCoreApp,Version=v10.0": {},
     ".NETCoreApp,Version=v10.0/win-x64": {
-      "GxMcp.Gateway/3.16.0": {
+      "GxMcp.Gateway/4.0.1": {
         "dependencies": {
           "Newtonsoft.Json": "13.0.3",
           "System.Management": "10.0.5",
@@ -66,7 +66,7 @@
     }
   },
   "libraries": {
-    "GxMcp.Gateway/3.16.0": {
+    "GxMcp.Gateway/4.0.1": {
       "type": "project",
       "serviceable": false,
       "sha512": ""

package/publish/config.json

@@ -1,19 +1,19 @@
 {
-  "GatewayMode": "stdio-isolated",
+  "ConfigSchemaVersion": 2,
   "Environment": {
     "ResolutionPolicy": "strict"
   },
-  "ConfigSchemaVersion": 2,
-  "Server": {
-    "EmitStructuredContent": false,
-    "HttpPort": 0,
-    "TerseResponses": true,
-    "SessionIdleTimeoutMinutes": 10,
-    "WorkerIdleTimeoutMinutes": 5,
-    "McpStdio": true
-  },
+  "GatewayMode": "stdio-isolated",
   "GeneXus": {
     "WorkerExecutable": "worker\\\\GxMcp.Worker.exe",
     "InstallationPath": "C:\\Program Files (x86)\\GeneXus\\GeneXus18"
+  },
+  "Server": {
+    "WorkerIdleTimeoutMinutes": 5,
+    "HttpPort": 0,
+    "TerseResponses": true,
+    "EmitStructuredContent": false,
+    "McpStdio": true,
+    "SessionIdleTimeoutMinutes": 10
   }
 }

package/publish/gxmcp-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": "gxmcp-release-manifest/1",
-  "version": "3.16.0",
-  "sourceCommit": "5084cdc8f9d1b4624c208809fb6077c27af65f38",
+  "version": "4.0.1",
+  "sourceCommit": "290aff51e3a7c810619eaed2cc5059622eb0939b",
   "sourceCommitPolicy": "exact-tag",
-  "generatedAtUtc": "2026-10-17T13:05:11.7186683Z",
+  "generatedAtUtc": "2026-10-21T18:49:57.9694364Z",
   "runtime": {
     "gateway": "net10.0-windows",
     "worker": "net48-x86",
@@ -15,33 +15,33 @@
     "2026-07-28"
   ],
   "schema": "tool_definitions.json",
-  "schemaSha256": "be4c1f74a47cada8e265bc632a7b87cdd1132020edcb5ea43b5a341829feba7a",
+  "schemaSha256": "562b893790fcd2e5e456c82935c86ea82e7612bc9457230184f6e018ed87fd47",
   "provenance": "gxmcp-sbom.json",
   "artifacts": [
     {
       "path": "gxmcp-sbom.json",
-      "size": 591,
-      "sha256": "3182ae289ba22a351be87976719de89744ab7953b6f35e31b8fd1c237c09f0fa"
+      "size": 590,
+      "sha256": "fb7abeca06e3c06c0a4dc346c86e0b1dad5056ef1c442a99feab4cc2b5ae187f"
     },
     {
       "path": "GxMcp.Gateway.exe",
       "size": 162304,
-      "sha256": "d8a368d30952ec8b0b69455f7296a11052b2f70f4110b78885532bfd4ace3391"
+      "sha256": "e829a6ba15543bf92c65d1ab59bce6c480133e622de30e3d33c18cf09604911b"
     },
     {
       "path": "nexus-ide.vsix",
-      "size": 1325114,
-      "sha256": "24cb9e2cdc533a1595e94a505344141180944bb29aef212b4d12569e4833aeee"
+      "size": 1325111,
+      "sha256": "b872a9df865037e84d2188247d374485a4de2681d2a4c861a5e411a1c5b7dda2"
     },
     {
       "path": "tool_definitions.json",
-      "size": 155111,
-      "sha256": "be4c1f74a47cada8e265bc632a7b87cdd1132020edcb5ea43b5a341829feba7a"
+      "size": 158549,
+      "sha256": "562b893790fcd2e5e456c82935c86ea82e7612bc9457230184f6e018ed87fd47"
     },
     {
       "path": "worker/GxMcp.Worker.exe",
-      "size": 4302848,
-      "sha256": "6f33014505f3c3564e6e9fc255bd8f3962f8d774e96e6ddcbe944741f61cc5af"
+      "size": 4594688,
+      "sha256": "1427ffb13fd69b0f72ea3bac949f53dd67f510d327426dd4b1c9ef55989b5eaf"
     }
   ]
 }

package/publish/gxmcp-sbom.json

@@ -1,20 +1,20 @@
 {
   "schemaVersion": "gxmcp-provenance/1",
-  "version": "3.16.0",
-  "sourceCommit": "5084cdc8f9d1b4624c208809fb6077c27af65f38",
+  "version": "4.0.1",
+  "sourceCommit": "290aff51e3a7c810619eaed2cc5059622eb0939b",
   "sourceCommitPolicy": "exact-tag",
   "components": [
     {
       "name": "genexus-mcp",
       "lockfile": "package-lock.json",
-      "size": 38806,
-      "sha256": "53dad4a00a3756eb5e24be271a3e80c5325b387c0c1ec1aba2f197560d6b84b3"
+      "size": 38804,
+      "sha256": "db0291b993484bcc255896278ba1416ebaaae00b4afb0d97b73e357d41f67016"
     },
     {
       "name": "nexus-ide",
       "lockfile": "src/nexus-ide/package-lock.json",
-      "size": 179505,
-      "sha256": "c44b3a41911e1defe5cd0639f3e1dcf164b95e26e906d49d867805dd234604ec"
+      "size": 179503,
+      "sha256": "030671cb319b730ab2c6893ff540b8809e7aefc7df1d2b97631a46315786c977"
     }
   ]
 }