@mcp-abap-adt/adt-clients 32.0.0 → 32.2.0

package/docs/usage/BATCH.md

@@ -0,0 +1,160 @@
+# Recording batch transport
+
+`AdtBatchConnection` implements `IAbapConnection`. Each member still issues one
+request; the wrapper records it and settles its promise after `execute()`.
+Do not await recorded calls before executing: their answers do not exist yet.
+The constructor requires `endpoint: 'communication' | 'debugger'` and accepts
+`logger?: ILogger`. It delegates connection initialization, base URL and session
+identity to the wrapped connection. Session switches while recording are local.
+
+```typescript
+import { AdtBatchConnection, AdtClient, utilDocuments } from '@mcp-abap-adt/adt-clients';
+import { analyseActivation, utilActivationRunId } from '@mcp-abap-adt/adt-strategies';
+
+const batch = new AdtBatchConnection(connection, { endpoint: 'communication' });
+const domains = new AdtClient(batch).getDomain();
+// configs: { domainName, packageName, transportRequest, description }[]
+const created = configs.map(config => domains.create(config));
+const locked = configs.map(config => domains.lock(config));
+await batch.execute();
+const handles = await Promise.all(created.map(async (pending, i) => {
+  const creation = await pending;
+  if (!creation.ok) throw new Error(creation.getError().message);
+  const lock = await locked[i];
+  if (!lock.ok) throw new Error(lock.getError().message);
+  return lock.getResult().value;
+}));
+const writes = configs.map((config, i) =>
+  domains.updateMetadata(config, {
+    source: documents[i], // Full domain XML, including datatype CHAR and length 000001.
+    lockHandle: handles[i],
+  }),
+);
+const unlocked = configs.map((config, i) => domains.unlock(config, handles[i]));
+await batch.execute();
+for (const answer of await Promise.all([...writes, ...unlocked])) {
+  if (!answer.ok) throw new Error(answer.getError().message);
+}
+const utils = new AdtClient(connection).getUtils({
+  ...utilDocuments,
+  activation: utilActivationRunId, // Reads the run id from Location.
+});
+const started = await utils.activateObjectsGroup(
+  configs.map(config => ({ type: 'DOMA', name: config.domainName })),
+  false,
+  { analyse: analyseActivation },
+);
+if (!started.ok) throw new Error(started.getError().message);
+const runId = started.getResult().value;
+if (!runId) throw new Error('Activation did not return a run id');
+const deadline = Date.now() + 300_000;
+// Polling and waiting belong to the consumer.
+for (;;) {
+  const run = await utils.getActivationRun(runId);
+  if (!run.ok) throw new Error(run.getError().message);
+  const body = String(run.getResult().value);
+  const status = /\b(?:\w+:)?status\s*=\s*["']([^"']*)["']/.exec(body)?.[1];
+  if (Date.now() >= deadline) throw new Error(`Activation ${runId} timed out`);
+  if (status === 'finished') break;
+  if (status === 'error' || status === 'failed') throw new Error(body);
+  await new Promise(resolve => setTimeout(resolve, 1000));
+}
+const activation = await utils.getActivationResults(runId, { analyse: analyseActivation });
+if (!activation.ok) throw new Error(activation.getError().message);
+const results = String(activation.getResult().value);
+if (!/activationExecuted\s*=\s*["']true["']/.test(results) || /type\s*=\s*["']E["']/.test(results)) {
+  throw new Error(`Activation refused: ${results}`);
+}
+```
+
+A lock handle comes from the lock envelope; placeholders cannot refer to another
+part's answer. A wrong UNLOCK handle can answer 200 while leaving the lock held.
+Use the real handles and inspect activation messages, including `type="E"`.
+The transport provides no transaction or rollback; callers own recovery and
+cleanup after partial failures.
+
+At an attached debugger stop, use the attached connection and its stateful session:
+
+```typescript
+import { AbapDebugger, AdtBatchConnection } from '@mcp-abap-adt/adt-clients';
+
+const batch = new AdtBatchConnection(debugConnection, { endpoint: 'debugger' });
+const debuggerApi = new AbapDebugger(batch);
+const pending = [
+  // Debugger recordings default to the attached stateful session.
+  debuggerApi.step('stepOver'),
+  debuggerApi.getStack(),
+  debuggerApi.getVariables(variableIds), // IDs obtained at the stop.
+];
+await batch.execute();
+const answers = await Promise.all(pending);
+for (const answer of answers) {
+  if (!answer.ok) throw new Error(answer.getError().message);
+}
+```
+
+`execute()` returns the last outer wire response. Empty execution returns a synthetic
+`{ status: 204, statusText: 'Empty batch', headers: {}, data: '' }` without sending.
+Recorded request promises receive inner responses, in order: 2xx resolves; other
+statuses reject with an Error carrying `response: { status, statusText, headers,
+data }`, matching direct HTTP failure handling. Members keep their usual
+`IAdtResponse` and strategy behavior. Envelope/parse failures stop execution immediately and reject `execute()` and
+parts in the failed envelope. Unsent runs and queued follow-ups reject with a
+library error saying the request was not sent because an earlier envelope failed;
+that error carries the cause, without a SAP response. Missing parts reject with a part-count error. A count
+mismatch also rejects `execute()`. Attach rejection handlers before execution when
+using raw connection promises. Each execute sends follow-up envelopes for requests recorded during settlement,
+including the automatic 406/415 corrected retry. It yields one event-loop turn
+after settling each envelope to let member continuations record requests. It
+returns the last outer response once that queue is empty. A limit of 100 envelopes
+rejects execution and all remaining requests rather than looping forever.
+Envelope failures also reject queued follow-ups. Concurrent executes are rejected;
+calls made after execution resolves belong to the next execute.
+
+On communication/batch, `execute()` partitions the queue into consecutive runs
+of LOCKs, UNLOCKs, or stateless requests and sends them in order, without
+reordering requests. Stateful actions are parsed from the URL query or request
+`params`. Other stateful requests use a separate `stateful` group; no ordinary
+member currently records one besides LOCK/UNLOCK. Debugger requests retain their
+single stateful group.
+For ordinary client members, LOCK and UNLOCK run stateful; creates, writes, reads,
+and deletes run stateless. Group creates before locks, and writes before unlocks,
+to avoid one envelope per alternating request. One execute can send several
+envelopes and provides no transaction across them. Inner HTTP failures remain
+per-part failures and do not stop later runs, allowing negotiation retries.
+
+Stateful parts carry `X-sap-adt-sessiontype: stateful`. The wrapped session mode
+is restored afterward. Connections exposing `getSessionMode()` or
+`getSessionType()` supply the previous mode; minimum-contract connections without
+a getter are assumed stateless. An explicit local `setSessionType` applies only
+to the next recorded request. Recording then returns to the endpoint default:
+communication is always stateless, independent of the wrapped connection's mode;
+debugger is always stateful because it uses an attached debugging session.
+
+Measurements on 2026-10-15 on an on-premise system and ABAP Cloud accepted mixed GET + POST on
+`/sap/bc/adt/communication/batch`, including a 404 part beside successful parts.
+The mixed-method 500 behind the 2026-09 removal was on `/debugger/batch`.
+Debugger step + stack + variables worked at a live stop on both systems; keep
+its member-specific variable Accept headers. RFC, payload limits and per-part
+authorization remain unmeasured.
+
+Several steps fit one debugger envelope: five `stepOver` + `getVariables` pairs
+after an initial read (11 parts) answered every part 200, and the variable
+history matched the one read step by step. Measured on 2026-10-16:
+
+| Way | Requests | On premise | ABAP Cloud |
+|---|---|---|---|
+| One envelope, one `execute()` | 1 | ~130–180 ms | ~570–610 ms |
+| One `execute()` per step | 6 | ~520 ms | ~2.7–3.6 s |
+| Plain `AbapDebugger`, no batch | 11 | ~1.1 s | ~6.4–6.8 s |
+
+Domains on the on-premise system: 100 created, locked, written and unlocked
+through the batch connection, then group-activated, in 19.3 s against 111.9 s
+for the same 500 requests one at a time.
+
+Integration configuration uses `batch.test_cases`: `domains` (params `count`,
+default 100; `name_prefix`, default `ZAC_BD_`; optional `package_name` and
+`transport_request`, otherwise environment defaults) and `debugger_client`.
+Both are disabled by default and support onprem/cloud. The debugger case uses
+the existing `runtime_debugger.adt_abap_debugger` params and debugger_batch fixture.
+The domain test writes timings to a temporary JSON file and logs its path via ILogger.

package/docs/usage/CLIENT_API_REFERENCE.md

@@ -734,7 +734,7 @@ had:
 - **A task created explicitly through `createTask()` is born unclassified,
   and the creating call cannot change that.** Measured against BTP ABAP on
   2026-09-23: `tm:type` passed to `newtask` is accepted and ignored, and every
-  task on that system read back as `Unclassified`. That system is a trial with
+  task on that system read back as `Unclassified`. That ABAP Cloud system has
   no transport system configured, so the CTS edit flow never creates a request
   there and every request and task is made by hand. All of them came through
   `newtask`, from this library's tests and from mcp-abap-adt's, and until
@@ -807,8 +807,9 @@ const request = client.getRequest({
 
 The `readObjects()` and `createTask()` examples above assume that set.
 
-**On a batch client** `list({ configUri })` records normally and resolves after
-`batchExecute()`, like any other member: it is one request now, so there is no
+**On a batch connection** (an `AdtClient` built on `AdtBatchConnection`, see
+[BATCH.md](BATCH.md)) `list({ configUri })` records normally and resolves after
+`batch.execute()`, like any other member: it is one request now, so there is no
 first answer a batch would have to deliver early.
 
 **Migration from filter parameters.** There is no server-side filtering to
@@ -1883,8 +1884,7 @@ if (done.ok) console.log(done.getResult().value.findingStats); // "0,0,1"
 `findingStats` is the server's `FINDING_STATS` triple verbatim, for example
 `"0,0,1"`. It is still not parsed into named counts, but the ordering is no
 longer a single observation: a worklist with one priority-3 finding read
-`"0,0,1"`, and a worklist with one priority-2 finding read `"0,1,0"` (BTP
-trial, 2026-09-08, `ZAC_SHR_ATC_DIRTY` under `ABAP_CLOUD_DEVELOPMENT_DEFAULT`).
+`"0,0,1"`, and a worklist with one priority-2 finding read `"0,1,0"` (the ABAP Cloud system, 2026-09-08, `ZAC_SHR_ATC_DIRTY` under `ABAP_CLOUD_DEVELOPMENT_DEFAULT`).
 Two points fitting `(priority 1, priority 2, priority 3)` and no other ordering
 that survives both. Position one has still never been seen non-zero, which is
 why this stays a string: `{ errors, warnings, infos }` would name a severity
@@ -1978,7 +1978,7 @@ const recentDumps = await dumps.list({
 });
 
 // Filter by user
-const userDumps = await dumps.listByUser('CB9980000423', {
+const userDumps = await dumps.listByUser('DEVELOPER', {
   inlinecount: 'allpages',
   top: 50,
   from: '20260401000000',

package/docs/usage/ERRATA.md

@@ -61,7 +61,7 @@ editing"*.
 **What Eclipse does.** It meets the same `403` on its own LOCK and publishes
 anyway:
 
-- Eclipse ADT 3.60.3 against the BTP trial, 2026-09-05: `LOCK` → `200` on its
+- Eclipse ADT 3.60.3 against the ABAP Cloud system, 2026-09-05: `LOCK` → `200` on its
   *"stateful, enqueue"* session; `POST …/odatav4/publishjobs` → `200`,
   stateless; `UNLOCK` → `200` only on *"Closing editor"*; a second `LOCK` before
   the unpublish → `403` while the first was still held.

package/docs/usage/STATEFUL_SESSION_GUIDE.md

@@ -21,8 +21,8 @@ This guide explains how `@mcp-abap-adt/adt-clients` manages ADT sessions for CRU
   since 23.0.2 — before that, `AdtInclude`, `AdtService` and `AdtMessageClass`
   did not. A caller with its own `IAbapConnection` needs the same: the cookie
   on the `LOCK` and the `UNLOCK`.
-- This is Eclipse's model, measured at two scales. A full run against the cloud
-  trial: 803 requests, of which exactly 100 carry `x-sap-adt-sessiontype:
+- This is Eclipse's model, measured at two scales. A full run against
+  the ABAP Cloud system: 803 requests, of which exactly 100 carry `x-sap-adt-sessiontype:
   stateful` — the 50 `LOCK`s and the 50 `UNLOCK`s, and nothing else. A probe
   doing two write windows on one class: 12 requests and 4 such headers, again
   the locks and the unlocks alone. The ratio is what the rule predicts, and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/adt-clients",
-  "version": "32.0.0",
+  "version": "32.2.0",
   "description": "ADT clients for SAP ABAP systems - AdtClient and AdtRuntimeClient",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",