genexus-mcp 3.15.0 → 4.0.0

package/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/genexus-mcp.svg)](https://www.npmjs.com/package/genexus-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![SafeSkill 85/100](https://img.shields.io/badge/SafeSkill-85%2F100_Passes%20with%20Notes-yellow)](https://safeskill.dev/scan/lennix1337-genexus18mcp)
-[![MCP Badge](https://lobehub.com/badge/mcp/lennix1337-genexus18mcp)](https://lobehub.com/mcp/lennix1337-genexus18mcp)
+[![Awesome AI Plugins](https://img.shields.io/badge/Awesome-AI%20Plugins-c5203e?logo=awesomelists&logoColor=white)](https://github.com/hashgraph-online/awesome-ai-plugins)
 
 > **¿Hablás español?** → [Guía de inicio en español](docs/GETTING_STARTED.es.md)
 > **Fala português?** → [Guia de início em português](docs/GETTING_STARTED.pt-br.md)
@@ -115,6 +115,124 @@ 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 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
+
+Progress is measured against recorded SDK differential inputs and observable results, not the number of implemented modules or passing unit tests. On the disposable `KBTeste` KB, a whole-KB Rebuild All now generates and compiles every targeted object (**346/346, 0 skipped, 0 refused**) and the C# the SDK writes for that KB is reproduced **byte for byte (328/328 files)**, together with the web scripts, `gxcfg.js`, messages and runtime configuration. **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).
+
+### What builds today
+
+| 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. The engine also writes 18 files the SDK's current output lacks (13 SDT classes identical to an earlier SDK generation, sidebar/program-name SDTs it reaches, 2 assembly-info files). 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.
+
+| 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 a capability gate (`EngineCapabilityRegistry`). The `Parity` labels below describe registered, bounded evidence, not complete SDK equivalence; routing boundaries and fallbacks are documented in [engine_backend.md](docs/engine_backend.md):
+
+| 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`, `CToD`/`DToC`/`TToC`, and `.ToString()`: 133 native `DateTimeUtil` oracle rows verified (1=Sunday DOW, leap clamping, second rollover, whole-day truncated DDiff, completed years Age, measured `CToD` parse grammar with the environment two-digit-year window, ISO `yyyy-MM-dd` and `yyyy-MM-ddTHH:mm:ss` exchange pictures). |
+| `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` | 🟩 **Parity** | Foundational runtime capabilities behind the four Native Parity subsystems above; each `EngineCapabilityRegistry` entry lists its native differential corpus or bounded portable fixture (`decimal_oracle`, `numeric_math`, `text_extended`, `calendar_ops`, `date_conversions`, `collection_ops`, `subroutines`, `exchange`, `sdt_xml`, `catalog`). |
+| `udm_storage_access` | 🟩 **Parity** (bounded reads) | Direct native UDM reads without COM/STA Worker (`knowledgebase.connection`, SQL Server, LocalDB); registered read/query consumers. Live engine writes are not implemented: `genexus_edit` remains SDK-backed or is refused under strict engine verification. Portable writer/lock tests are not live persistence evidence. |
+| `csharp_emitter` | **Bounded coverage** | C# generation and Roslyn compilation tests for supported object forms; unsupported native forms still fail closed. Compilation alone does not establish SDK behavior parity. |
+| `parallel_rebuild_all` | **Bounded coverage** | Parallel specification, C# emission and compilation; consumers `genexus_lifecycle.build` / `rebuild`. `KBTeste` Rebuild All: 346/346 compiled, 0 skipped/refused; paired speed ratios below are `KBTeste`-only and do not establish full SDK parity. |
+
+### ⚡ Performance Benchmarks (gx-engine vs. GeneXus SDK)
+
+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. |
+| **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
+
+As new capabilities reach parity and additional optimizations land, follow this protocol to update this ledger:
+
+1. **Verify Parity First:** No benchmark is valid without zero diffs against the official SDK or recorded native differential fixture:
+   ```powershell
+   python src/gx-engine/scripts/benchmark.py --iterations 100
+   ```
+2. **Standardized Environment:** Keep compiler flags, hardware specifications, and iterations explicit (see [src/gx-engine/VALIDATION.md](src/gx-engine/VALIDATION.md)).
+3. **Record in Ledger:** Update this table and [plans/129-implementation-progress.md](plans/129-implementation-progress.md) with: workload description, GeneXus SDK baseline, gx-engine timing, observed speedup ratio, and the committed evidence fixture.
+
+### Activation Flag & Safety Seam
+
+> [!IMPORTANT]
+> **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.
+
+No backend setting is needed. To narrow routing to builds (`"auto"`) or turn the engine off (`"sdk"`), configure `config.json`:
+
+```json
+{
+  "Engine": {
+    "Backend": "auto",
+    "Fallback": "sdk",
+    "TimeoutSeconds": 120
+  }
+}
+```
+
+- **`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 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`.
+
+To run compiler tests or standalone projects from checkout:
+
+```powershell
+cargo test --manifest-path src/gx-engine/Cargo.toml
+cargo run --manifest-path src/gx-engine/Cargo.toml -- check src/gx-engine/fixtures/demo.json
+```
+
+See [docs/engine_backend.md](docs/engine_backend.md), the [engine guide](src/gx-engine/README.md), and the [capability matrix](plans/129-sdk-capability-matrix.md) for full architecture and evidence ledgers.
+
+---
+
 ## Sharing one Worker between MCP clients
 
 The Gateway and the GeneXus SDK Worker have different responsibilities. By
@@ -181,7 +299,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 |
@@ -448,7 +566,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,68 @@ 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 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 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, /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/docs/llm_cli_mcp_playbook.md

@@ -231,7 +231,8 @@ For a complete incremental build of the selected Knowledge Base, use
 `BuildAll` task when available, reports completion evidence, and returns
 `ReorgRequired` instead of applying a schema reorganization implicitly. Use
 `action='build'` for a directed target and `action='rebuild'` for the forced
-Rebuild All contract.
+Rebuild All contract; `rebuild` is KB-global like `build_all` and rejects
+`target` with `TargetNotSupported`.
 
 ## Pagination and Token Budgeting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genexus-mcp",
-  "version": "3.15.0",
+  "version": "4.0.0",
   "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.15.0": {
+      "GxMcp.Gateway/4.0.0": {
         "dependencies": {
           "Newtonsoft.Json": "13.0.3",
           "System.Management": "10.0.5",
@@ -66,7 +66,7 @@
     }
   },
   "libraries": {
-    "GxMcp.Gateway/3.15.0": {
+    "GxMcp.Gateway/4.0.0": {
       "type": "project",
       "serviceable": false,
       "sha512": ""

package/publish/config.json

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

package/publish/gxmcp-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": "gxmcp-release-manifest/1",
-  "version": "3.15.0",
-  "sourceCommit": "b9de0a5ae4cdf0e3932b486b2f01702a60e7e3cd",
+  "version": "4.0.0",
+  "sourceCommit": "62272a9c499ff02698c5b3300d64e294f888f4fa",
   "sourceCommitPolicy": "exact-tag",
-  "generatedAtUtc": "2026-10-14T02:50:52.1311513Z",
+  "generatedAtUtc": "2026-10-21T13:01:38.4377788Z",
   "runtime": {
     "gateway": "net10.0-windows",
     "worker": "net48-x86",
@@ -15,33 +15,33 @@
     "2026-07-28"
   ],
   "schema": "tool_definitions.json",
-  "schemaSha256": "2227b1b13d39abac30434dc38ff39bc00b6d6e044bd091fbe3d09bc74a27d7d1",
+  "schemaSha256": "562b893790fcd2e5e456c82935c86ea82e7612bc9457230184f6e018ed87fd47",
   "provenance": "gxmcp-sbom.json",
   "artifacts": [
     {
       "path": "gxmcp-sbom.json",
-      "size": 591,
-      "sha256": "0fc27c489ff17be6d2a43f2627a66a5c7981907b33ad49d4d92ceb47a49e746a"
+      "size": 590,
+      "sha256": "1a853dda42fee5ebfc7240e7ede0454bd06d558aad4e8020f297a695c17f8ed8"
     },
     {
       "path": "GxMcp.Gateway.exe",
       "size": 162304,
-      "sha256": "1654d0ad829f6a7ce0fc17ce699cc34ada78de0e6ba5119a51bcfd8012b6ac79"
+      "sha256": "50d2195c03a4f013e1b6ecb6325fa37474e551c81f7368f858a5bfcf0a568a24"
     },
     {
       "path": "nexus-ide.vsix",
-      "size": 1319954,
-      "sha256": "e25e399f972541299878a1b2ed0077ce95f906c36af03b3b0650d15f148b9fa7"
+      "size": 1325108,
+      "sha256": "52bb58f43a7278c3fea90d5d0e541bee82ce9212caf9f9e6edc8e8070df3a5f3"
     },
     {
       "path": "tool_definitions.json",
-      "size": 152308,
-      "sha256": "2227b1b13d39abac30434dc38ff39bc00b6d6e044bd091fbe3d09bc74a27d7d1"
+      "size": 158549,
+      "sha256": "562b893790fcd2e5e456c82935c86ea82e7612bc9457230184f6e018ed87fd47"
     },
     {
       "path": "worker/GxMcp.Worker.exe",
-      "size": 4196352,
-      "sha256": "17f2bd30498ffeef44addaeca5684cc0e50030c4da4de521e8647a9f30fb2080"
+      "size": 4590080,
+      "sha256": "bfe06ca5a6cbe2995105646b01608a0c9fab5b3699d05e1f017e69207e147b70"
     }
   ]
 }

package/publish/gxmcp-sbom.json

@@ -1,20 +1,20 @@
 {
   "schemaVersion": "gxmcp-provenance/1",
-  "version": "3.15.0",
-  "sourceCommit": "b9de0a5ae4cdf0e3932b486b2f01702a60e7e3cd",
+  "version": "4.0.0",
+  "sourceCommit": "62272a9c499ff02698c5b3300d64e294f888f4fa",
   "sourceCommitPolicy": "exact-tag",
   "components": [
     {
       "name": "genexus-mcp",
       "lockfile": "package-lock.json",
-      "size": 38806,
-      "sha256": "4146279bf184d197427c77a1dd812b1e8bd4b1b34aa8eef911c91aae51d0def6"
+      "size": 38804,
+      "sha256": "8fe3effecc9074ba753d819c4a1c2607f64cb80d880444f2ab2d586e73b6ee15"
     },
     {
       "name": "nexus-ide",
       "lockfile": "src/nexus-ide/package-lock.json",
-      "size": 179499,
-      "sha256": "518eae0cfbb109b67a5fb76633e597c60747b6e39322eb9a2eefcb40137e8bb5"
+      "size": 179503,
+      "sha256": "5f51a13844440860665aa8dbe0c978ba0c573a2bf1de025cf0e76f3961af24f2"
     }
   ]
 }