@mcp-abap-adt/adt-clients 37.3.0 → 38.0.0

package/README.md

@@ -8,7 +8,7 @@ TypeScript clients for SAP ABAP Development Tools (ADT).
 > member answers the document SAP sent unless you give it a reading when you
 > build it, and judges nothing unless you pass `analyse` with the call. Every
 > reading and verdict it used to apply is a strategy in
-> [`@mcp-abap-adt/adt-strategies`](packages/adt-strategies). The connection
+> [`@mcp-abap-adt/adt-strategies`](../adt-strategies). The connection
 > contract moved to `@mcp-abap-adt/interfaces-adt-connection`.
 > [`docs/usage/MIGRATION-23.md`](docs/usage/MIGRATION-23.md) has the replacing
 > code for every removed behaviour.
@@ -16,6 +16,19 @@ TypeScript clients for SAP ABAP Development Tools (ADT).
 > **From 18.x?** Read [`docs/usage/MIGRATION-19.md`](docs/usage/MIGRATION-19.md)
 > first: 19.0.0 is where members became one endpoint call each.
 >
+> **From 37.x?** 38.0.0 (on `interfaces-adt` ^23.1.1) is typed by the ADT type
+> tables: a client is fixed to its release variant (`AdtClientOnPrem`,
+> `AdtClientCloud`, `createAdtClient(connection, { variant })`), every type
+> code is a code of the tables (the `AdtObjectType*` unions, friendly names,
+> `FUNC` and the other codes no table holds are gone), an API with a parent
+> takes it, and `updateMetadata` is there for fifteen more types. It also puts
+> each contract where it is accepted: the result-set contracts (`IClassResults`,
+> …) are imported from `@mcp-abap-adt/interfaces-adt`, and each factory answers
+> its class — a consumer composes the contract it accepts from interfaces-adt.
+> See [Release variants and type codes](#release-variants-and-type-codes),
+> [The contract you accept is yours](#the-contract-you-accept-is-yours) and
+> [`docs/usage/MIGRATION-38.md`](docs/usage/MIGRATION-38.md).
+>
 > **From 36.x?** 37.0.0 (on `interfaces-adt` ^20.1.0) makes
 > `getSystemInformation` answer an `IAdtResponse` — present, absent (a `404`)
 > or failed — and adds the required `objectProperties` slot to `IUtilResults`
@@ -85,7 +98,7 @@ Nothing. Which part of a document you want, and whether an answer is a failure,
 are decisions about your system and your task; since 23.0.0 no member takes
 either on your behalf. The shipped result sets answer documents as they arrived;
 the readings and verdicts that used to be applied here are strategies in
-[`@mcp-abap-adt/adt-strategies`](packages/adt-strategies), which you pass by
+[`@mcp-abap-adt/adt-strategies`](../adt-strategies), which you pass by
 name. See [Strategies](#strategies-what-an-answer-becomes-and-whether-it-failed).
 
 #### What This Package Does NOT Do
@@ -104,7 +117,7 @@ This package interacts with external packages **ONLY through interfaces**:
 
   | package | what this package takes from it |
   |---|---|
-  | [`@mcp-abap-adt/interfaces-adt`](https://www.npmjs.com/package/@mcp-abap-adt/interfaces-adt) `^20.1.0` | the capability atoms, every object's config, `IAdtResponse`, `IAnalyse`, `IAdtAnalyseOptions`, `IAdtHeaders`, `IResultStrategy`, `ADT_NO_FAILURE`, `ADT_TASK_TYPE` |
+  | [`@mcp-abap-adt/interfaces-adt`](https://www.npmjs.com/package/@mcp-abap-adt/interfaces-adt) `^23.1.1` | the ADT type tables (`ADT_TYPES_ONPREM`, `ADT_TYPES_CLOUD`, `ADT_TYPES_BASIS_740`) and their code types (`AdtTypeCode`, …), the ABAP Unit run registry (`ABAP_UNIT_RUN_TYPES`, `AbapUnitRunObjectType`, `AbapUnitRunTarget`), the capability atoms, every object's config, the result-set contracts, `IAdtAnsweredObject`, `IAdtResponse`, `IAnalyse`, `IAdtAnalyseOptions`, `IAdtHeaders`, `IResultStrategy`, `ADT_NO_FAILURE`, `ADT_TASK_TYPE` |
   | [`@mcp-abap-adt/interfaces-adt-connection`](https://www.npmjs.com/package/@mcp-abap-adt/interfaces-adt-connection) `^3.0.0` | `IAbapConnection`, `IAdtWireResponse`, `IAbapRequestOptions`, the connection capability atoms, `ADT_SESSION_ERROR` |
   | [`@mcp-abap-adt/interfaces-network`](https://www.npmjs.com/package/@mcp-abap-adt/interfaces-network) `^2.0.1` | `IWebSocketTransport` and its four companions, `HttpError` |
   | [`@mcp-abap-adt/interfaces-utils`](https://www.npmjs.com/package/@mcp-abap-adt/interfaces-utils) `^1.1.1` | `ILogger`, `LogLevel`, `XmlNode` |
@@ -146,7 +159,8 @@ npm install @mcp-abap-adt/adt-clients
    - Every answer is a contract — a result or a failure, never a throw
    - Utility functions via `client.getUtils()`
    - Example: `await client.getClass().create({...}, { headers })` — the POST, and nothing else
-   - `AdtClientLegacy` (from `createAdtClient` on BASIS < 7.50) is an **RFC client**: supported, and measured on SAP_BASIS 7.40 SP04, over RFC only — HTTP to a legacy system is unsupported. Each member sends the request measured accepted on 7.40 SP04, or keeps an unmeasured request under a collection 7.40 advertises (listed as not measured in LEGACY.md), or answers a refusal without a request; a legacy `delete` takes the lock handle from your `lock()`, and there is no `checkDeletion`. See [LEGACY.md](docs/architecture/LEGACY.md)
+   - **Fixed to a release variant** (since 38.0.0): `AdtClientOnPrem` (S/4HANA 2025, `ADT_TYPES_ONPREM`), `AdtClientCloud` (ABAP cloud, `ADT_TYPES_CLOUD`), or a plain `AdtClient` served what both serve. A factory or member the variant's table lacks does not compile — see [Release variants and type codes](#release-variants-and-type-codes)
+   - **Legacy systems (SAP_BASIS 7.40, measured on 7.40 SP04) are a separate package**, [`@mcp-abap-adt/adt-clients-legacy`](https://github.com/fr0ster/mcp-abap-adt-clients/blob/main/packages/adt-clients-legacy/README.md): its `AdtClientLegacy` and `AdtExecutorLegacy` extend this package's classes. The consumer declares the system type by constructing them over an RFC connection (`new AdtClientLegacy(connection, logger)`); nothing here detects a system, and `createAdtClient(connection, { variant })` answers the declared modern variant's client and sends no request. They are **RFC clients**, supported and measured on SAP_BASIS 7.40 SP04 over RFC only — HTTP to a legacy system is unsupported. What each member does on 7.40 is in that package's [README](https://github.com/fr0ster/mcp-abap-adt-clients/blob/main/packages/adt-clients-legacy/README.md) and [LEGACY.md](https://github.com/fr0ster/mcp-abap-adt-clients/blob/main/packages/adt-clients-legacy/docs/LEGACY.md)
 
 2. **AdtRuntimeClient**
    - Stable runtime operations for traces, dumps, logs, feeds, ATC check runs, and more
@@ -161,13 +175,14 @@ npm install @mcp-abap-adt/adt-clients
      - `getClassTestRunner()` for a class's ABAP Unit tests: `run`, `getStatus`, `getResult` (asynchronous, the default), or `runSync` (synchronous)
      - `getProgramTestRunner()` for a report's ABAP Unit tests, in its source or its includes — `run` (asynchronous, the default) or `runSync`
      - `getFunctionGroupTestRunner()` / `getFunctionModuleTestRunner()` for a function group's tests, or a module's — `run` (asynchronous, the default) or `runSync`
+     - `getAbapUnitTestRunner()`, the generic runner: `run` of an object target of any type the run registry `ABAP_UNIT_RUN_TYPES` lists (a class include, a CDS view's assigned tests, …) or of a package target, `runSync` of ADT URIs, `getStatus`, `getResult`
      - `getProgramExecutor()` for `programrun` (on-premise systems)
    - Methods: `run`, `runWithProfiler`, and trace scheduling (`scheduleTrace`, `listRequests`, `getRequestsByUri`, `listObjectTypes`, `listProcessTypes`)
    - Each executor factory takes an optional result set, like the runtime client's
-   - `createAdtExecutor(connection)` picks `AdtExecutor` or `AdtExecutorLegacy` by system version, like `createAdtClient`. The legacy one (SAP_BASIS 7.40 SP04, over RFC) runs ABAP Unit through the synchronous `/abapunit/testruns` request for every runner, and refuses without a request what 7.40 does not serve — the class run (`/oo/classrun`, measured `404`), `getStatus`/`getResult` (no run id) and a function module's `run` (it names no group) — and, until a run measures them, what 7.40 SP04 does not advertise: the program run (`programrun`) and the trace type lists — see [LEGACY.md](docs/architecture/LEGACY.md#abap-unit-runners-and-executors)
+   - `createAdtExecutor(connection)` returns `AdtExecutor`, like `createAdtClient` detecting nothing. The legacy executor, `AdtExecutorLegacy` of `@mcp-abap-adt/adt-clients-legacy` (SAP_BASIS 7.40 SP04, over RFC), runs ABAP Unit through the synchronous `/abapunit/testruns` request for every runner, and refuses without a request what 7.40 does not serve — the class run (`/oo/classrun`, measured `404`), `getStatus`/`getResult` (no run id) and a function module's `run` (it names no group) — and, until a run measures them, what 7.40 SP04 does not advertise: the program run (`programrun`) and the trace type lists — see [LEGACY.md](https://github.com/fr0ster/mcp-abap-adt-clients/blob/main/packages/adt-clients-legacy/docs/LEGACY.md#abap-unit-runners-and-executors)
 
 4. **AdtAbapGitClient**
-   - Standalone: `new AdtAbapGitClient(connection, logger?, results?)` (the options argument, `contentTypeVersion`, was removed in 36.0.0)
+   - Standalone, not a factory on `AdtClient`: `AdtAbapGitClient.create(connection, { logger? })` answers the shipped documents (`abapGitDocuments`), `AdtAbapGitClient.create(connection, { logger?, results })` the caller's (since 38.0.0); `new AdtAbapGitClient(connection, { logger?, results })` takes its results always (the options argument, `contentTypeVersion`, was removed in 36.0.0)
    - `link`, `pull`, `unlink({ repositoryId })`, `listRepos`, `getErrorLog(logLink)`, `checkExternalRepo` — one request each; `pull` does not wait
 
 5. **AdtClientsWS**
@@ -175,7 +190,7 @@ npm install @mcp-abap-adt/adt-clients
    - Example: `await wsClient.request('<operation>', { … })` against a backend that speaks its envelope
 
 6. **AbapDebugger, AmdpDebugger, MemorySnapshots**
-   - Standalone, from `@mcp-abap-adt/adt-clients/runtime` or the root: `new AbapDebugger(connection, logger, results?, { onConflict? })`
+   - Standalone, from `@mcp-abap-adt/adt-clients/runtime` or the root: `AbapDebugger.create(connection, { logger?, onConflict? })` answers the shipped documents (`abapDebuggerDocuments`), `AbapDebugger.create(connection, { results, logger?, onConflict? })` the caller's; likewise `AmdpDebugger.create` and `MemorySnapshots.create` (`{ logger?, results? }`, since 38.0.0). `new AbapDebugger(connection, { results, logger?, onConflict? })` takes its results always
    - One member per request, contracts `IAbapDebugger`, `IAmdpDebugger`, `IMemorySnapshots` from `@mcp-abap-adt/interfaces-adt` (contract 18 pairs with clients 32)
    - **The identity states its mode.** `{ debuggingMode: 'user', requestUser, terminalId, ideId }`, or `{ debuggingMode: 'terminal', terminalId, ideId }`; `attach` takes the identity, not the user. A terminal-mode listener catches a run that carries its ids: `run(target, { debuggee: { terminalId, ideId } })` sends them in `SAP-PASSPORT` (since 29.1.0)
    - **Breakpoints are replaced, not added to.** `setBreakpoints` and `syncBreakpoints` replace the identity's set, and `stopListener` deletes it: arm the whole set in one call
@@ -184,28 +199,51 @@ npm install @mcp-abap-adt/adt-clients
 
 ## Supported Object Types
 
-| Object Type | AdtClient |
-|------------|-----------|
-| Classes (CLAS) | ✅ |
-| Behavior Implementations (CLAS) | ✅ |
-| Behavior Definitions (BDEF) | ✅ |
-| Interfaces (INTF) | ✅ |
-| Programs (PROG) | ✅ |
-| Includes (PROG/I) | ✅ |
-| Enhancements (ENHO/XHB, ENHO/XHH, ENHS/XSB) | ✅ |
-| Function Groups (FUGR) | ✅ |
-| Function Modules (FUGR/FF) | ✅ |
-| Function Includes (FUGR/I) | ✅ |
-| Domains (DOMA) | ✅ |
-| Data Elements (DTEL) | ✅ |
-| Structures (TABL/DS) | ✅ |
-| Tables (TABL/DT) | ✅ |
-| Views (DDLS) | ✅ |
-| Metadata Extensions (DDLX) | ✅ |
-| Packages (DEVC) | ✅ |
-| Authorization Fields (SUSO / AUTH) | ✅ |
-| Feature Toggles (FTG2/FT) | ✅ |
-| Transports (TRNS) | ✅ |
+What the library serves is declared by the ADT type tables of
+`@mcp-abap-adt/interfaces-adt`, one per release variant; the factory is the
+API, the codes are the tables'. ✅ the variant's table holds the API, — it does
+not (the factory does not compile there). 7.40 is `AdtClientLegacy` of
+`@mcp-abap-adt/adt-clients-legacy`, which serves less than its table lists
+where 7.40 is not measured (its [LEGACY.md](https://github.com/fr0ster/mcp-abap-adt-clients/blob/main/packages/adt-clients-legacy/docs/LEGACY.md)).
+
+| Object type | Factory | Codes | On premise | Cloud | 7.40 |
+|---|---|---|---|---|---|
+| Classes | `getClass()` | `CLAS/OC` | ✅ | ✅ | ✅ |
+| Behavior implementations | `getBehaviorImplementation()` | `CLAS/OC` | ✅ | ✅ | — |
+| Behavior definitions | `getBehaviorDefinition()` | `BDEF/BDO` | ✅ | ✅ | — |
+| Interfaces | `getInterface()` | `INTF/OI` | ✅ | ✅ | ✅ |
+| Programs | `getProgram()` | `PROG/P` | ✅ | ✅ | ✅ |
+| Includes | `getInclude()` | `PROG/I` | ✅ | ✅ | ✅ |
+| Enhancements | `getEnhancement()` | `ENHO/XHH`, `ENHO/XHB`, `ENHS/XSB` | ✅ | ✅ | — |
+| Function groups | `getFunctionGroup()` | `FUGR/F` | ✅ | ✅ | ✅ |
+| Function modules | `getFunctionModule()` | `FUGR/FF`, under its group | ✅ | ✅ | ✅ |
+| Function includes | `getFunctionInclude()` | `FUGR/I`, under its group | ✅ | ✅ | ✅ |
+| Domains | `getDomain()` | `DOMA/DD` | ✅ | ✅ | — |
+| Data elements | `getDataElement()` | `DTEL/DE` | ✅ | ✅ | — |
+| Structures | `getStructure()` | `TABL/DS` | ✅ | ✅ | — |
+| Append structures | `getAppendStructure()` | `TABL/DS` | ✅ | ✅ | — |
+| Tables | `getTable()` | `TABL/DT` | ✅ | ✅ | — |
+| Table types | `getTableType()` | `TTYP/DA` | ✅ | ✅ | — |
+| DDL sources (CDS views) | `getDdl()` | `DDLS/DF` | ✅ | ✅ | ✅ |
+| Access controls | `getAccessControl()` | `DCLS/DL` | ✅ | ✅ | — |
+| Metadata extensions | `getMetadataExtension()` | `DDLX/EX` | ✅ | ✅ | — |
+| Service definitions | `getServiceDefinition()` | `SRVD/SRV` | ✅ | ✅ | — |
+| Service bindings | `getServiceBinding()` | `SRVB/SVB` | ✅ | ✅ | — |
+| Scalar functions | `getScalarFunction()` | `DSFD/SCF` | ✅ | ✅ | — |
+| Scalar function implementations | `getScalarFunctionImplementation()` | `DSFI/SFI` | ✅ | ✅ | — |
+| Transformations | `getTransformation()` | `XSLT/VT` | ✅ | ✅ | — |
+| Message classes | `getMessageClass()` | `MSAG/N` | ✅ | ✅ | ✅ |
+| Messages | `getMessageClassMessage()` | `MSAG/NN`, read from its class | ✅ | ✅ | ✅ |
+| Packages | `getPackage()` | `DEVC/K` | ✅ | ✅ | — |
+| Authorization fields | `getAuthorizationField()` | `AUTH` | ✅ | ✅ | — |
+| Feature toggles | `getFeatureToggle()` | `FTG2/FT` | ✅ | ✅ | — |
+| Local includes of a class | `getLocalTestClass()`, `getLocalTypes()`, `getLocalDefinitions()`, `getLocalMacros()` | — | ✅ | ✅ | ✅ |
+| Transport requests | `getRequest()` | — | ✅ | ✅ | ✅ |
+
+Which operations each code has — `source`, `updateMetadata`, `run`, … — is the
+code's `operations` in the table; a member whose operation the variant's table
+does not list for the code does not compile (`getProgram().updateMetadata()`
+on a cloud client, say).
 
 `getEnhancement().updateMetadata()` writes the whole object document from
 `options.source` under the caller's lock, then the caller unlocks and activates.
@@ -229,7 +267,7 @@ import {
   AdtOnPremConnector,
   OnPremHttpTransport,
 } from '@mcp-abap-adt/connection';
-import { AdtClient, utilDocuments } from '@mcp-abap-adt/adt-clients';
+import { AdtClientOnPrem, utilDocuments } from '@mcp-abap-adt/adt-clients';
 import {
   utilSearchHits,
   utilWhereUsedReferences,
@@ -265,7 +303,9 @@ const connection = new AdtOnPremConnector(
 // surfacing later as `400 Session not found` mid-edit.
 await connection.connect();
 
-const client = new AdtClient(connection, console);
+// The release variant is yours to declare, like the system: an on-premise
+// client is typed by ADT_TYPES_ONPREM (AdtClientCloud for ABAP cloud).
+const client = new AdtClientOnPrem(connection, console);
 
 // One member, one request: this is the POST that makes the class shell.
 // Writing its source and activating it are calls of your own, below.
@@ -305,7 +345,7 @@ const utils = client.getUtils({
   whereUsed: utilWhereUsedReferences,
 });
 
-const found = await utils.search({ query: 'Z*', objectType: 'CLAS' });
+const found = await utils.search({ query: 'Z*', objectType: 'CLAS/OC' });
 if (found.ok) {
   found.getResult().value;        // ISearchResult[] — the document, without utilSearchHits
 } else {
@@ -318,7 +358,7 @@ if (found.ok) {
 // /usageReferences/scope sub-resource (some S/4 releases 404 it) is a decision
 // about your system, so it is yours rather than a fallback hidden in here.
 const scope = await utils.getWhereUsedScope(
-  { object_name: 'ZMY_TABLE', object_type: 'table' },
+  { object_name: 'ZMY_TABLE', object_type: 'TABL/DT' },
   { headers: WHERE_USED_SCOPE },
 );
 if (!scope.ok) {
@@ -334,7 +374,7 @@ const narrowed = utils.modifyWhereUsedScope(scope.getResult().value, {
 });
 
 const answer = await utils.getWhereUsed(
-  { object_name: 'ZMY_TABLE', object_type: 'table', scopeXml: narrowed },
+  { object_name: 'ZMY_TABLE', object_type: 'TABL/DT', scopeXml: narrowed },
   { headers: WHERE_USED },
 );
 
@@ -344,7 +384,8 @@ if (answer.ok) {
   const references = answer.getResult().value;
   console.log(`Found ${references.totalReferences} references`);
   for (const ref of references.references) {
-    console.log(`${ref.name} (${ref.type}) in ${ref.packageName}`);
+    // `type` for a code of the tables, `unknownType` for any other text.
+    console.log(`${ref.name} (${ref.type ?? ref.unknownType}) in ${ref.packageName}`);
   }
 }
 ```
@@ -438,8 +479,8 @@ const result = await runner.getResult(runId, { analyse: analyseUnitTest });
 ```
 
 `run` takes a class name (every test class in it) or a list of
-`{ containerClass, testClass }`. On a legacy system (measured on 7.40 SP04, over
-RFC) the runner's `run` sends the synchronous `/abapunit/testruns` request,
+`{ containerClass, testClass }`. On a legacy system (`@mcp-abap-adt/adt-clients-legacy`,
+measured on 7.40 SP04, over RFC) the runner's `run` sends the synchronous `/abapunit/testruns` request,
 `<options>` included, and answers the finished result; `getStatus`/`getResult`
 refuse without a request.
 
@@ -462,7 +503,7 @@ answer the same document — `aunit:runResult` in `http://www.sap.com/adt/aunit`
 — with the same methods and alerts. Two differences: the endpoint addresses
 whole classes, so `{ containerClass, testClass }` targets run each distinct
 container whole; and `title` and `context` are not sent. Scope, risk levels and
-durations are, with `run`'s defaults. On a legacy system `run` and `runSync`
+durations are, with `run`'s defaults. On a legacy system (`@mcp-abap-adt/adt-clients-legacy`) `run` and `runSync`
 send this same request, `<options>` included — `run` read by the `run` strategy,
 `runSync` by `result`.
 
@@ -472,7 +513,7 @@ through `executor.getProgramTestRunner().run(programName)`, with the same
 `getStatus`/`getResult`. A function group's are written in an include of the
 group (`getFunctionInclude()`) and run through `getFunctionGroupTestRunner()`
 for the whole group or `getFunctionModuleTestRunner()` for one module. On a
-legacy system (measured on 7.40 SP04, over RFC) the report and group runners'
+legacy system (`@mcp-abap-adt/adt-clients-legacy`, measured on 7.40 SP04, over RFC) the report and group runners'
 `run` and `runSync`, and the module runner's `runSync`, send the synchronous
 request below, with `<options>`; the module runner's `run` refuses without a
 request (it names no group, and the request needs the module's URI under its
@@ -508,14 +549,61 @@ Doc test relation (`"! @testing FUNC:<module>`) on a test class, the default
 scope answered the group's tests as a preview (`isForeign="true"`, nothing
 executed) and `scope: { foreignTests: true }` ran them.
 
-**AdtUtils read type safety:**
-`readObjectMetadata` and `readObjectSource` accept strict object type unions to prevent invalid inputs like `view:ZOBJ`.
+**The generic runner, `getAbapUnitTestRunner()`.** The four runners above each
+fix the `osl:object type` they send (`CLAS`, `PROG`, `FUGR`, `FUNC`). The
+generic one takes it from the caller, typed `AbapUnitRunObjectType` — every key
+of `ABAP_UNIT_RUN_TYPES` in `@mcp-abap-adt/interfaces-adt`, and nothing else —
+or runs a package:
 
 ```typescript
-import type { AdtObjectType, AdtSourceObjectType } from '@mcp-abap-adt/interfaces-adt';
+import { abapUnitTestRunnerDocuments } from '@mcp-abap-adt/adt-clients';
+
+const generic = executor.getAbapUnitTestRunner({
+  ...abapUnitTestRunnerDocuments,
+  run: unitTestRunId,
+});
+// An object target: one osl:object in an osl:flatObjectSet.
+await generic.run({ kind: 'object', name: 'ZCL_UNDER_TEST', type: 'CLAS/OC' });
+// A CDS view's tests are assigned tests: they execute only with foreignTests.
+await generic.run(
+  { kind: 'object', name: 'ZI_VIEW', type: 'DDLS/DF' },
+  { scope: { foreignTests: true }, analyse: analyseUnitTestStart },
+);
+// A package target: an osl:packageSet with one osl:package.
+await generic.run({ kind: 'package', name: '$ZPKG', includeSubpackages: true });
+// ADT URIs, on /abapunit/testruns, with the request's headers.
+await generic.runSync(['/sap/bc/adt/oo/classes/zcl_under_test'], {
+  headers: { accept: 'application/xml', contentType: 'application/xml' },
+  analyse: analyseUnitTest,
+});
+```
+
+Both targets go to `POST /sap/bc/adt/abapunit/runs` and are polled with
+`getStatus` and `getResult`, as every runner's. **A CDS view holds no test
+class**: its tests are local test classes elsewhere — a class's testclasses
+include — marked `"! @testing <view>`, and they execute by `DDLS/DF` (or
+`DDLS`) only when the scope sets `foreignTests: true`. Without it, the default
+`addForeignTestsAsPreview: true` lists them in the result **without executing
+them**: every method is there with no alert, so a failing test looks like a
+pass; with the preview off too, the result is empty (measured 2026-10-29 on
+S/4HANA 2025 and ABAP cloud). **A consumer reading a CDS run sets
+`foreignTests: true`.** **A package** runs only as an `osl:packageSet` — `osl:object
+type="DEVC/K"` answered empty (measured 2026-10-29, S/4HANA 2025 and ABAP
+cloud). **A wrong type is not an error**: the endpoint answers the start `201`
+and the result as an empty `<aunit:runResult/>`, which is why the type is the
+compiler's to check. On a legacy system the generic runner keeps `runSync` and
+refuses a target run, `getStatus` and `getResult` without a request (7.40 has
+no `/abapunit/runs`).
+
+**AdtUtils read type safety:**
+`readObjectMetadata` and `readObjectSource` take the codes of the tables they
+read (`AdtMetadataReadCode`, `AdtSourceReadCode`), so `'view'` or `'CLAS'` does
+not compile, and a function module's group is required:
 
-await utils.readObjectMetadata('DDLS/DF' satisfies AdtObjectType, 'ZOK_I_CDS_TEST');
-await utils.readObjectSource('view' satisfies AdtSourceObjectType, 'ZOK_I_CDS_TEST');
+```typescript
+await utils.readObjectMetadata('DDLS/DF', 'ZOK_I_CDS_TEST');
+await utils.readObjectSource('DDLS/DF', 'ZOK_I_CDS_TEST');
+await utils.readObjectSource('FUGR/FF', 'Z_MY_FM', 'ZMY_GROUP');
 ```
 
 **Benefits:**
@@ -578,10 +666,13 @@ change what you mean to change, pass the result. Anything you leave out is gone,
 because nothing is read on your behalf to keep it.
 
 For a class, a program or a DDL source the whole content is the **full source**.
-For domain, package, dataElement, tableType, transport, functionGroup and
-message class it is the object's own **document**, passed as `options.source` to
-`updateMetadata` — the first six fetched and patched it for you until 19.0.0,
-the message class until 23.0.0, and none of them does now.
+For domain, package, dataElement, tableType, transport and message class it is
+the object's own **document**, passed as `options.source` to `updateMetadata` —
+the first five and the function group fetched and patched it for you until
+19.0.0, the message class until 23.0.0, and none of them does now. Every type
+that has both — a class, a function group, a table, … (38.0.0 added
+`updateMetadata` to fifteen of them) — writes its metadata document the same way:
+read it, change it, pass the whole document back.
 
 ```typescript
 const cls = client.getClass();
@@ -609,7 +700,7 @@ relying on being caught.
 **No error strategy ships in this package**, and that is the design: whether an
 answer is a failure depends on which object types you touch and what you were
 doing. If you have no opinion yet,
-[`@mcp-abap-adt/adt-strategies`](packages/adt-strategies) has one — defaults
+[`@mcp-abap-adt/adt-strategies`](../adt-strategies) has one — defaults
 derived from recorded ADT answers, each tested against the refusal it came from
 and the success it must be told apart from.
 
@@ -694,6 +785,47 @@ The script uses the same environment variables as the main package:
 
 See [Tools Documentation](tools/README.md) for complete details and options.
 
+### The type tables' conformance check
+
+The ADT type tables of `@mcp-abap-adt/interfaces-adt` (`ADT_TYPES_ONPREM`,
+`ADT_TYPES_CLOUD`, `ADT_TYPES_BASIS_740`) are held to what each release
+answers: its `typestructure`, its `discovery` and, per sample object, its
+`urimapper` and metadata answers. The answers are recorded in `corpus/adt/`
+(`typestructure/`, `discovery/`, `conformance/<release>/`; see
+[`corpus/README.md`](corpus/README.md)).
+
+- **In CI** — `src/__tests__/unit/conformance/typeTablesConformance.test.ts`
+  runs the check against the recorded answers. What it finds is committed
+  beside it: the known divergences with their reasons, the list of creates
+  without `CREATE` and the collections that advertise no `app:accept` for an
+  `updateMetadata` (`recorded.ts`), and the coverage (`coverage.json`). A
+  change that changes what the check finds is an edit of those lists.
+- **On a live system** — `src/__tests__/integration/shared/typeTablesConformance.test.ts`
+  reads the same endpoints for the configured variant (`environment.system`)
+  and runs the same check. It prints the system's identity and writes it
+  nowhere:
+
+  ```bash
+  MCP_ENV_PATH=<env> MCP_TEST_OVERLAY=<overlay> \
+    npm test -- src/__tests__/integration/shared/typeTablesConformance.test.ts
+  ```
+
+**Refreshing a release's answers.** Run the live check with
+`CONFORMANCE_WRITE_DIR=<dir>` (refused when `CI` is set). It writes the
+answers, scrubbed with the corpus placeholders, under `<dir>` in the corpus
+layout: `typestructure/system-description-<release>--07-typestructure.*`,
+`discovery/system-description-<release>--03-discovery.*` and
+`conformance/<release>/` with its `_index.json`. Then:
+
+1. Review the written files: no host, user, system id or token may be left
+   (`src/__tests__/unit/corpusCarriesNoIdentity.test.ts` checks the corpus).
+2. Copy them over the release's files in `corpus/adt/`. A written
+   `_index.json` carries the sample, statuses, both addresses and the files;
+   keep the recorded index's notes and reasons where they still hold.
+3. Run `npm run corpus:format`, then the unit tests; edit `recorded.ts` and
+   `coverage.json` for what the check now finds, with a reason for each
+   divergence.
+
 ## API Reference
 
 ### AdtClient Overview
@@ -793,7 +925,7 @@ The shipped result sets (`classDocuments`, `transportDocuments`,
 document as it arrived (`rawDocument`), or nothing (`nothing`) where there is
 nothing to read. No member supplies an `analyse` of its own. Every reading and
 verdict this package used to apply is a named strategy in
-[`@mcp-abap-adt/adt-strategies`](packages/adt-strategies):
+[`@mcp-abap-adt/adt-strategies`](../adt-strategies):
 
 ```typescript
 import { transportDocuments } from '@mcp-abap-adt/adt-clients';
@@ -868,7 +1000,7 @@ await client.getClass().read(
 ```
 
 - Factory accessors for ADT objects: `client.getClass()`, `client.getProgram()`, `client.getDdl()` (DDL sources — CDS views, AMDP table functions; formerly `getView()`), `client.getTable()`, `client.getScalarFunction()`, `client.getScalarFunctionImplementation()`, `client.getAppendStructure()`, `client.getRequest()`, `client.getUtils()`, etc.
-- Each accessor returns an `Adt*` object typed to its **honest capability set** (since 8.0.0, completed in 12.0.0). Every accessor returns the intersection of the capability atoms that object actually supports, written positively — there is no composite at all, and none named for what an object lacks. Calling a capability a handler lacks — e.g. `client.getDomain().getVersions(...)` — is a **compile error** rather than a runtime throw. See the [Type System](#type-system) section.
+- Each accessor returns its `Adt*` class, typed to its **honest capability set** (since 8.0.0, completed in 12.0.0): the class implements only the capability atoms that object actually supports, written positively — there is no composite at all, and none named for what an object lacks. Since 38.0.0 the accessor answers the class itself (`AdtClass<R>`, …), not a composition of its atoms. Calling a capability a handler lacks — e.g. `client.getDomain().getVersions(...)` — is a **compile error** rather than a runtime throw. See the [Type System](#type-system) section.
 - See `src/index.ts` for the full type exports and object configs.
 
 ### AdtObject Methods (with Long Polling Support)
@@ -943,7 +1075,7 @@ still takes an optional `accept` (`IReadOptions`).
   metadata extension and a transport request — send the whole pair now. So do
   the requests that sent neither: a transport request's `checkDeletion`, and
   the direct `DELETE` of the legacy client's class, interface, program, DDL
-  source, function group and function module.
+  source, function group and function module (now in `@mcp-abap-adt/adt-clients-legacy`).
 - A message class message's `create`, `update` and `delete` are a chain (read,
   two locks, the `PUT`, two unlocks): the pair is the `PUT`'s; the chain's own
   requests keep their types.
@@ -1073,18 +1205,21 @@ hold yourself:
   headers) or `AdtContentTypesBase` (v1, universal) from that answer.
 - `fetchDiscoveryEndpoints(connection)` / `isEndpointInDiscovery(...)` — the
   discovery document and a membership test over it.
-- `createAdtClient(connection, logger?, options?)` — `AdtClient` or
-  `AdtClientLegacy`, from `isModernAdtSystem`. The legacy client is an RFC
-  client: supported, and measured on SAP_BASIS 7.40 SP04, over RFC only; HTTP to
-  a legacy system is unsupported. What it serves and what it refuses is in
-  [LEGACY.md](docs/architecture/LEGACY.md).
+- `createAdtClient(connection, { variant, logger?, …options })` —
+  `AdtClientOnPrem` for `variant: 'onprem'`, `AdtClientCloud` for `'cloud'`
+  (since 38.0.0; it took `(connection, logger?, options?)` before). It detects
+  nothing and sends no request (since 37.4.0): the consumer declares the system
+  type, and a legacy system is served by `AdtClientLegacy` of
+  `@mcp-abap-adt/adt-clients-legacy`, an RFC client constructed by the consumer.
+  What it serves and what it refuses is in
+  [LEGACY.md](https://github.com/fr0ster/mcp-abap-adt-clients/blob/main/packages/adt-clients-legacy/docs/LEGACY.md).
 
 **A probe answers only for an absent endpoint.** For `isModernAdtSystem` and
 `fetchDiscoveryEndpoints` a `404`, `405` or `501` is the answer `false` or an
 empty set stands for. Any other failure — no network, an expired session, a
 `401`, a `500` — is raised, since 23.0.0: it says nothing about the system, and
 swallowing it handed a legacy client to a modern system reached over a broken
-connection.
+connection (the factory no longer calls it).
 
 `getSystemInformation` answers rather than raises, and only a `404` is the
 endpoint absent. A malformed answer is not a system without the endpoint:
@@ -1118,7 +1253,7 @@ everything else is not.
 
 ### Single Definition Site: the contract packages
 
-Since **7.5.0**, every contract type is **defined once**, in the contract packages — today `@mcp-abap-adt/interfaces-adt` (`^20.1.0`) for the ADT contracts and `@mcp-abap-adt/interfaces-adt-connection` (`^3.0.0`) for the connection. This package declares no copies of its own — every `IXxxConfig`, the capability atoms, the option and response types and the cross-cutting shared types all live there.
+Since **7.5.0**, every contract type is **defined once**, in the contract packages — today `@mcp-abap-adt/interfaces-adt` (`^23.1.1`) for the ADT contracts and `@mcp-abap-adt/interfaces-adt-connection` (`^3.0.0`) for the connection. This package declares no copies of its own — every `IXxxConfig`, the capability atoms, the result-set contracts a factory accepts (`IClassResults`, …, since 38.0.0), the option and response types and the cross-cutting shared types all live there.
 
 **Import them from the package that owns them:**
 
@@ -1145,7 +1280,7 @@ the contract naming one would be describing an implementation.
 
 Since **9.0.0** this is the only route: the package no longer re-exports types it does not own. It used to republish 145 of them, which was more than half its public surface — so a consumer could hold `IClassConfig` believing it came from this client, and a type would appear to change whenever this client released, for reasons that had nothing to do with it. Types now travel on the contract package's release cycle, which is where they are actually decided.
 
-What this package exports is what it owns: the clients, the handler classes, the batch and runtime facades, the result sets each implementation is built with (`<x>Documents` and their `I…Results` types), the building blocks `rawDocument`, `nothing`, `wireItself` and `nothingIsARefusal`, and a few helpers.
+What this package exports is what it owns: the clients, the handler classes, the batch and runtime facades, the default result sets each implementation is built with (`<x>Documents`; the client result-set contracts they satisfy are interfaces-adt's since 38.0.0, the executor, runtime and abapGit ones are still here), the building blocks `rawDocument`, `nothing`, `wireItself` and `nothingIsARefusal`, and a few helpers.
 
 ### Honest capability types (since 8.0.0)
 
@@ -1166,11 +1301,11 @@ Since **9.0.0** no accessor returns the wide type, and since **12.0.0** none ret
 
 Since **24.0.0** there is no unit-test handler at all: every member `getUnitTest()` and `getCdsUnitTest()` had was another handler's request under a second name — the class's create, the local test class's read, update and delete. What was left, running, is `AdtExecutor.getClassTestRunner()` (`IAdtRunnable` plus `ITestRunInformation`), and the CDS test-doubles check is `getDdl().checkCdsTestDoubles()`. See [MIGRATION-24.md](docs/usage/MIGRATION-24.md).
 
-Since **25.0.0** ATC takes programs and every kind of include, `interfaces-adt` is `^12.0.0`, group operations refuse a reference they cannot address before any request, and a legacy client answers a refusal for an object type the system lacks instead of throwing. See [MIGRATION-25.md](docs/usage/MIGRATION-25.md).
+Since **25.0.0** ATC takes programs and every kind of include, `interfaces-adt` is `^12.0.0`, group operations refuse a reference they cannot address before any request, and a legacy client (since 37.4.0 in `@mcp-abap-adt/adt-clients-legacy`) answers a refusal for an object type the system lacks instead of throwing. See [MIGRATION-25.md](docs/usage/MIGRATION-25.md).
 
 The runtime client narrows the same way. `AdtRuntimeClient.getAtc()` implements `IAtcRunStatusReadable & IAtcFindings`, plus `resolveCheckVariant`, `listCheckVariants`, `createWorklist` and `startRun` — a check run is three requests, started and then read, never created, locked, activated or versioned, and the type says so rather than offering the rest and throwing. It is not `IAdtRunnable` since 19.0.0: that atom's `run` is one call.
 
-**A guard keeps this true.** `src/__tests__/unit/capabilities/` compares all 37 factory return types against the 12 atoms in both directions at compile time, calls every method of every declared capability against a recording connection to check it issues the request its capability names, and fails if a new factory appears without an entry. Adding a throwing method back to a narrowed handler stops compiling. The guard walks `AdtClient` and `AdtClientLegacy` only; the runtime accessors are pinned by `src/__tests__/unit/clients/AdtRuntimeClient.factory.test.ts`.
+**A guard keeps this true.** `src/__tests__/unit/capabilities/` compares what every factory answers (its class, since 38.0.0) against the atoms in both directions at compile time, refuses a public method of `AdtUtils`, `AdtFeatureToggle` or `AdtServiceBinding` that no interfaces-adt atom declares, calls every method of every declared capability against a recording connection to check it issues the request its capability names, and fails if a new factory appears without an entry. Adding a throwing method back to a narrowed handler stops compiling. The guard walks `AdtClient`; the legacy package runs the same guard over `AdtClientLegacy`; the runtime accessors are pinned by `src/__tests__/unit/clients/AdtRuntimeClient.factory.test.ts`.
 
 One category deliberately remains local, because it is code, not contract:
 
@@ -1200,6 +1335,91 @@ sourced from the contract packages.
 
 > **Version pairing.** `adt-clients` 32 pairs with `interfaces-adt` 18 and `interfaces-adt-connection` 3 (the enhancement subtype and host contracts), and `adt-strategies` 0.12.0 declares the same ranges. Because the types are sourced rather than copied, `@mcp-abap-adt/interfaces-adt` and `@mcp-abap-adt/interfaces-adt-connection` are hard peers of this package's public API. A major bump there implies a bump here; keep the two in step rather than letting a resolver pick a mismatched pair.
 
+### Release variants and type codes
+
+Since **38.0.0** the library is typed by the ADT type tables of
+`@mcp-abap-adt/interfaces-adt`: `ADT_TYPES_ONPREM` (S/4HANA 2025),
+`ADT_TYPES_CLOUD` (ABAP cloud) and `ADT_TYPES_BASIS_740` (SAP_BASIS 7.40). Each
+names the APIs the library offers on that release — one per factory — with
+their codes, and for each code its parent API, its name length and the
+operations the library performs there. The tables are the library's
+declaration; the [conformance check](#the-type-tables-conformance-check) holds
+them to what each release answers.
+
+- **The variant is declared, never detected.** `AdtClient<V>` is fixed to one:
+  `AdtClientOnPrem`, `AdtClientCloud`, or the plain `AdtClient`, served what
+  both modern tables serve. `createAdtClient(connection, { variant, logger })`
+  answers the declared one. A SAP_BASIS 7.40 system is `AdtClientLegacy`
+  (`AdtClient<'basis740'>`) of `@mcp-abap-adt/adt-clients-legacy`.
+- **The gates are types.** A factory takes `this: this & AdtServedBy<'<api>'>`
+  and a member whose availability differs by variant `this: this &
+  AdtPerformedBy<'<api>', '<operation>'>`: a factory or operation the variant's
+  table lacks is a compile error naming it. The executors and ABAP Unit runners
+  (`AdtExecutor<V>`) are gated the same way.
+- **A code is a code of the tables.** Every code taken or answered is an
+  `AdtTypeCode` (`'CLAS/OC'`, `'FUGR/FF'`, `'TABL/DT'`, …) or a subset of it
+  (`AdtSourceTypeCode`, `AdtCodeOf<V>`, the `getUtils()` code sets). No
+  friendly name, bare R3TR type or lower-case spelling is taken. `VIEW/DV` is
+  a group-only code: group activation, group deletion and where-used address
+  it, and no factory serves it.
+- **An API with a parent takes it.** A function module and a function include
+  are addressed under their function group: their members, a
+  `readObjectSource('FUGR/FF', name, group)` and an
+  `IObjectReference<'FUGR/FF'>` require the group.
+- **What an answer names is `type` or `unknownType`.** A reading of
+  `@mcp-abap-adt/adt-strategies` that takes a code from an answer answers an
+  `IAdtAnsweredObject`: `type` for a code a table holds, `unknownType` — the
+  text as ADT sent it — for any other.
+
+`src/__tests__/unit/typeCodeLiterals.test.ts` (one per package) holds the
+source to it: a code literal passes only where the compiler types it by the
+tables, and a code named in a comment or inside a longer string (a message,
+an XML template's span) is a code of the tables.
+
+### The contract you accept is yours
+
+Since **38.0.0** a contract lives in the package that accepts it. A factory
+accepts a result set, so the result-set contracts are
+`@mcp-abap-adt/interfaces-adt`'s; a consumer accepts the client, so the client
+contract is the consumer's. This package declares no composition: each factory
+answers its own class, and the class's members are what the factory offers.
+
+A consumer composes the contract it accepts from interfaces-adt alone — the
+factories it calls, each answering the atoms whose members it calls, generic
+over the result-set contract it is given — and types its code against it. The
+compiler checks, where the client is taken, that `AdtClient`,
+`AdtClientLegacy` or the consumer's own implementation satisfies it:
+
+```typescript
+import type {
+  IAdtLockable,
+  IAdtReadable,
+  IAdtUpdatable,
+  IClassConfig,
+  IClassResults,
+} from '@mcp-abap-adt/interfaces-adt';
+import { classDocuments, createAdtClient } from '@mcp-abap-adt/adt-clients';
+
+interface IMyClient {
+  getClass<R extends IClassResults>(
+    results: R,
+  ): IAdtReadable<IClassConfig, ReturnType<R['source']>> &
+    IAdtLockable<IClassConfig> &
+    IAdtUpdatable<Partial<IClassConfig>, ReturnType<R['updated']>>;
+}
+
+const client: IMyClient = await createAdtClient(connection, {
+  variant: 'onprem',
+  logger,
+});
+const classes = client.getClass(classDocuments); // read answers a string
+```
+
+`src/__tests__/unit/clients/consumerContract.test.ts` holds this package to it:
+such a contract accepts `AdtClient` and an object written by hand, and refuses
+one missing a member it names; the legacy package proves the same of
+`AdtClientLegacy`.
+
 ### Naming Conventions
 
 The package uses **dual naming conventions** to distinguish API layers:
@@ -1235,6 +1455,7 @@ See [Architecture Documentation](docs/architecture/ARCHITECTURE.md#type-system-a
 One document per breaking release, each written for a consumer on the contract
 before it:
 
+- **[37.x → 38.0.0](docs/usage/MIGRATION-38.md)** — the ADT type tables decide: a client is fixed to its release variant, every type code is a code of the tables, an API with a parent takes it, answered objects are `type` / `unknownType`, and `updateMetadata` covers fifteen more types; the result-set contracts are imported from `@mcp-abap-adt/interfaces-adt`, and each factory answers its class, so a consumer composes the contract it accepts from interfaces-adt.
 - **[36.x → 37.0.0](docs/usage/MIGRATION-37.md)** — `getSystemInformation` answers an `IAdtResponse` (present, absent for a `404`, or a failure, through `options.analyse`), and `IUtilResults` has the required `objectProperties` slot.
 - **[35.x → 36.0.0](docs/usage/MIGRATION-36.md)** — a request's `Accept` and `Content-Type` are the caller's: 32 members take the required `options.headers` and send exactly that pair.
 - **[34.x → 35.0.0](docs/usage/MIGRATION-35.md)** — accept negotiation is off by default: a `406`/`415` is the call's answer unless you switch it on.

package/dist/clients/AdtAbapGitClient.d.ts

@@ -3,7 +3,10 @@
  *
  * Standalone top-level class — NOT a factory on AdtClient (which is
  * reserved for IAdtObject<Config, State> implementations only).
- * Consumers instantiate directly: new AdtAbapGitClient(connection, logger, results?).
+ * Consumers build it themselves: `AdtAbapGitClient.create(connection, { logger })`
+ * answers the shipped documents, `create(connection, { logger, results })` the
+ * caller's; `new AdtAbapGitClient(connection, { logger, results })` takes its
+ * results always.
  *
  * Implements IAdtAbapGitClient. HTTP operations are delegated to
  * low-level functions in ./abapGit/*; this class owns the options,
@@ -12,7 +15,7 @@
  */
 import type { IAbapGitExternalRepoCredentials, IAbapGitLinkArgs, IAbapGitPullArgs, IAbapGitUnlinkArgs, IAdtAbapGitClient, IAdtAnalyseOptions, IAdtError, IAdtHeaders, IAdtResponse } from '@mcp-abap-adt/interfaces-adt';
 import type { IAbapConnection } from '@mcp-abap-adt/interfaces-adt-connection';
-import type { ILogger } from '@mcp-abap-adt/interfaces-utils';
+import type { AdtHandlerOptions, AdtShippedOptions } from '../core/shared/handlerOptions';
 import { abapGitDocuments, type IAbapGitResults } from './abapGit/types';
 /**
  * One request per member, each read by the strategy the client was built
@@ -28,7 +31,14 @@ export declare class AdtAbapGitClient<R extends IAbapGitResults = typeof abapGit
     private readonly connection;
     private readonly logger?;
     private readonly results;
-    constructor(connection: IAbapConnection, logger?: ILogger, results?: R);
+    /**
+     * An abapGit client with the shipped documents, or with the caller's results.
+     * No client hands one out, so this is where the shipped documents are the
+     * default, as a getter's are.
+     */
+    static create(connection: IAbapConnection, options?: AdtShippedOptions<'logger'>): AdtAbapGitClient<typeof abapGitDocuments>;
+    static create<R extends IAbapGitResults>(connection: IAbapConnection, options: AdtHandlerOptions<R, 'logger'>): AdtAbapGitClient<R>;
+    constructor(connection: IAbapConnection, options: AdtHandlerOptions<R, 'logger'>);
     /** Link a package to a repository. */
     link<E extends IAdtError = IAdtError>(args: IAbapGitLinkArgs, options: {
         headers: IAdtHeaders;