@mcp-abap-adt/adt-clients 23.0.2 → 23.0.3

package/README.md

@@ -940,7 +940,7 @@ member uses it on your behalf; `create()` and `update()` issue one request each.
 - **[Documentation index](docs/README.md)**
 - **[Migrating to 23.0.0](docs/usage/MIGRATION-23.md)** – the replacing code for every removed behaviour
 - **[Client API reference](docs/usage/CLIENT_API_REFERENCE.md)** – every client, member and result set
-- **[Workarounds](docs/usage/WORKAROUNDS.md)** – SAP-side behaviour a consumer has to work around, with the evidence for each
+- **[SAP ADT errata](docs/usage/ERRATA.md)** – what SAP answers that it does not mean, and what to do: the object tree with each branch's cases (a `403` on a service binding's LOCK that is to be ignored, among them), then every case with its evidence. Ships in this package under `docs/usage/`, and in `@mcp-abap-adt/adt-strategies`
 - **[Architecture](docs/architecture/ARCHITECTURE.md)** – package structure and design decisions
 - **[Decisions](docs/architecture/DECISIONS.md)** – the choices that could have gone the other way, and why
 - **[Operation Delays](docs/usage/OPERATION_DELAYS.md)** – configurable delays for SAP operations in tests

package/dist/core/package/AdtPackage.d.ts

@@ -48,7 +48,7 @@ export declare class AdtPackage<R extends IPackageResults = typeof packageDocume
      * package before it is ever locked.
      *
      * A package can be saved only once per ABAP session: PAK/058 — see
-     * docs/usage/WORKAROUNDS.md. Over RFC the create counts as that save.
+     * docs/usage/ERRATA.md. Over RFC the create counts as that save.
      */
     create<E extends IAdtError = IAdtError>(config: Omit<IPackageConfig, 'source'> & {
         source?: never;
@@ -63,7 +63,7 @@ export declare class AdtPackage<R extends IPackageResults = typeof packageDocume
      * Update the package's metadata.
      *
      * A package can be saved only once per ABAP session: PAK/058 — see
-     * docs/usage/WORKAROUNDS.md. Opening a new session is the caller's.
+     * docs/usage/ERRATA.md. Opening a new session is the caller's.
      *
      * **The whole content, every time.** This is a replace, never a merge. Read
      * what the object holds, change what you mean to change, and pass the result:
@@ -82,7 +82,7 @@ export declare class AdtPackage<R extends IPackageResults = typeof packageDocume
      * Delete the package.
      *
      * A package can be saved only once per ABAP session: PAK/058 — see
-     * docs/usage/WORKAROUNDS.md. A delete from a session that saved the package
+     * docs/usage/ERRATA.md. A delete from a session that saved the package
      * is refused; from a new session it succeeds.
      *
      * The answer is a 200 either way, and `isDeleted="false"` is in its body: a

package/dist/core/package/AdtPackage.js

@@ -86,7 +86,7 @@ class AdtPackage {
      * package before it is ever locked.
      *
      * A package can be saved only once per ABAP session: PAK/058 — see
-     * docs/usage/WORKAROUNDS.md. Over RFC the create counts as that save.
+     * docs/usage/ERRATA.md. Over RFC the create counts as that save.
      */
     async create(config, options) {
         // **No guard here, unlike every other create.**
@@ -134,7 +134,7 @@ class AdtPackage {
      * Update the package's metadata.
      *
      * A package can be saved only once per ABAP session: PAK/058 — see
-     * docs/usage/WORKAROUNDS.md. Opening a new session is the caller's.
+     * docs/usage/ERRATA.md. Opening a new session is the caller's.
      *
      * **The whole content, every time.** This is a replace, never a merge. Read
      * what the object holds, change what you mean to change, and pass the result:
@@ -189,7 +189,7 @@ class AdtPackage {
      * Delete the package.
      *
      * A package can be saved only once per ABAP session: PAK/058 — see
-     * docs/usage/WORKAROUNDS.md. A delete from a session that saved the package
+     * docs/usage/ERRATA.md. A delete from a session that saved the package
      * is refused; from a new session it succeeds.
      *
      * The answer is a 200 either way, and `isDeleted="false"` is in its body: a

package/dist/core/package/types.d.ts

@@ -43,7 +43,7 @@ export type PackageValidationResult = string;
  *
  * A refusal arrives as **200** carrying `isDeleted="false"`, so the document,
  * not the status, is the verdict. A package can be saved only once per ABAP
- * session: PAK/058 — see docs/usage/WORKAROUNDS.md.
+ * session: PAK/058 — see docs/usage/ERRATA.md.
  */
 export type PackageDeletionResult = string;
 /**

package/docs/README.md

@@ -25,8 +25,7 @@ Complete documentation for the `@mcp-abap-adt/adt-clients` package.
 - [**STATEFUL_SESSION_GUIDE.md**](usage/STATEFUL_SESSION_GUIDE.md) - Guide for stateful session management
 - [**CHECK_LOCAL_TEST_CLASS.md**](usage/CHECK_LOCAL_TEST_CLASS.md) - Guide for validating ABAP Unit test classes
 - [**DEBUG.md**](usage/DEBUG.md) - Debugging and troubleshooting guide
-- [**WORKAROUNDS.md**](usage/WORKAROUNDS.md) — SAP-side behaviour a consumer has to work around (PAK/058, refusals inside a `200`, empty `200` reads, activation flags, transport search, …): symptom, cause, rule, workaround and evidence for each
-- [TROUBLESHOOTING.md](usage/TROUBLESHOOTING.md) — what ADT answers when it refuses, and why the message is often accurate about the wrong thing
+- [**ERRATA.md**](usage/ERRATA.md) — what SAP answers that it does not mean: the object tree with each branch's cases, then every case with symptom, cause, rule, workaround and evidence
 - [**OPERATION_DELAYS.md**](usage/OPERATION_DELAYS.md) - Detailed guide on operation delays and timing
 - [**OPERATION_DELAYS_SUMMARY.md**](usage/OPERATION_DELAYS_SUMMARY.md) - Quick reference for operation delays
 
@@ -55,8 +54,7 @@ docs/
 │   ├── OBJECT_LIFECYCLE.md           # The create → … → activate flow and its exceptions
 │   ├── CLIENT_API_REFERENCE.md       # Client API reference
 │   ├── STATEFUL_SESSION_GUIDE.md     # Session management
-│   ├── WORKAROUNDS.md                # SAP-side behaviour and its workarounds
-│   ├── TROUBLESHOOTING.md            # Refusals that name the wrong cause
+│   ├── ERRATA.md                # SAP ADT errata: the object tree, then every case
 │   ├── CHECK_LOCAL_TEST_CLASS.md     # Local test class validation
 │   ├── DEBUG.md                      # Debugging guide
 │   ├── OPERATION_DELAYS.md           # Operation delays (detailed)

package/docs/usage/ANSWER_SHAPES.md

@@ -126,8 +126,7 @@ caller who asks for those shapes rather than the document.
 - [`MIGRATION-23.md`](MIGRATION-23.md) — the readings and verdicts that moved
   to `@mcp-abap-adt/adt-strategies` in 23.0.0
 - [`MIGRATION-19.md`](MIGRATION-19.md) — what moved to the consumer in 19.0.0
-- [`WORKAROUNDS.md`](WORKAROUNDS.md) — the SAP-side behaviour behind several of
-  these answers, and what a consumer does about it
-- [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md) — answers that are accurate about
-  the wrong thing, including the `S_ABPLNGVS` language-version refusal
+- [`ERRATA.md`](ERRATA.md) — the SAP-side behaviour behind several of
+  these answers, by object, and what a consumer does about it — including the
+  `S_ABPLNGVS` language-version refusal
 - [`../../examples`](../../examples) — the sequences, written out

package/docs/usage/CLIENT_API_REFERENCE.md

@@ -1067,11 +1067,19 @@ Unpublishing is the same, against `…/unpublishjobs`.
 it for you:
 
 ```typescript
-import { analysePublication } from '@mcp-abap-adt/adt-strategies';
+import {
+  analysePublication,
+  analysePublicationLock,
+} from '@mcp-abap-adt/adt-strategies';
 
 const bindings = client.getServiceBinding();
 
-const locked = await bindings.lock({ bindingName: 'ZAC_SRVB01' });
+// analysePublicationLock: a 403 (an editor holds the binding) is no failure —
+// the job does not need our lock, and the handle then comes back as ''.
+const locked = await bindings.lock(
+  { bindingName: 'ZAC_SRVB01' },
+  { analyse: analysePublicationLock },
+);
 if (!locked.ok) throw new Error(locked.getError().message);
 const lockHandle = locked.getResult().value;
 
@@ -1091,10 +1099,14 @@ try {
   );
   if (!answer.ok) throw new Error(answer.getError().message);
 } finally {
-  await bindings.unlock({ bindingName: 'ZAC_SRVB01' }, lockHandle);
+  if (lockHandle) await bindings.unlock({ bindingName: 'ZAC_SRVB01' }, lockHandle);
 }
 ```
 
+A binding just created has no active version, and publishing it answers `200`
+with *"Service Binding … does not exist"*: `activate()` it first. See
+[ERRATA.md](ERRATA.md#a-service-binding-is-locked-to-publish-it).
+
 Why the library does not do that for you: **how long a lock is held is a
 policy**, and it is not one policy. Eclipse holds a binding's lock for as long
 as an editor is open — across several publishes, if that is what the person

package/docs/usage/{WORKAROUNDS.md → ERRATA.md}

@@ -1,7 +1,8 @@
-# Workarounds for SAP-side behaviour
+# SAP ADT errata
 
-This document collects behaviour of the SAP system and its ADT endpoints that a
-consumer has to work around. Each case is **surprising, not a defect of this
+Known behaviour of the SAP system and its ADT endpoints that a consumer has to
+work around — errata in the sense a platform vendor publishes them: the defect
+is the platform's, each entry says how to live with it. Each case is **surprising, not a defect of this
 library**, and has a **workaround on the consumer side**. The knowledge used to
 be scattered across guides and code comments; it lives here now, and the other
 documents link to it.
@@ -26,9 +27,194 @@ a second session, retry, poll or judge an answer on your behalf. Where a
 workaround needs a reading, `@mcp-abap-adt/adt-strategies` usually has one, and
 each entry names it.
 
+Start with **[the object tree](#the-object-tree)**: find the object you were
+working on, and its branch says what SAP answers for it that it does not answer
+for the others. The numbered entries under [Contents](#contents) carry the
+evidence, and some of them apply to every object.
+
 Every entry has the same sections: **Symptom** (what the caller sees),
 **Cause**, **Rule**, **Workaround**, **Evidence** and **Where it bites**.
 
+## The object tree
+
+The objects this library addresses, as they hang together: a child lives in
+its parent or is built on it. A **⚠** marks a node where SAP answers something
+it does not answer for the others; follow the link. A node without one has shown
+nothing beyond the entries that apply to every type — see [Contents](#contents).
+
+- [Transport request](#transport-request) `getRequest()` ⚠
+- [Package](#package) `getPackage()` ⚠
+  - Source code
+    - [Class](#class) `getClass()` ⚠
+      - [local test class, local types, local definitions, local macros](#class-includes) `getLocalTestClass()` `getLocalTypes()` `getLocalDefinitions()` `getLocalMacros()` ⚠
+      - ABAP Unit run `getUnitTest()`
+    - Interface `getInterface()`
+    - Program `getProgram()`
+      - Include `getInclude()`
+    - [Function group](#function-group) `getFunctionGroup()` ⚠
+      - [Function module](#function-module) `getFunctionModule()` ⚠
+      - Function include `getFunctionInclude()`
+    - Transformation `getTransformation()`
+    - Enhancement `getEnhancement()`
+  - Dictionary
+    - [Domain](#domain-and-data-element) `getDomain()` ⚠
+      - [Data element](#domain-and-data-element) `getDataElement()` ⚠
+    - Structure `getStructure()`
+    - Table `getTable()`
+      - Append structure `getAppendStructure()`
+    - [Table type](#table-type) `getTableType()` ⚠
+    - Authorization field `getAuthorizationField()`
+  - CDS and RAP
+    - [DDL source](#ddl-source) `getDdl()` ⚠
+      - Access control `getAccessControl()`
+      - Metadata extension `getMetadataExtension()`
+      - CDS unit test `getCdsUnitTest()`
+      - Behavior definition `getBehaviorDefinition()`
+        - Behavior implementation `getBehaviorImplementation()`
+    - Scalar function `getScalarFunction()`
+      - Scalar function implementation `getScalarFunctionImplementation()`
+  - Services
+    - [Service definition](#service-definition) `getServiceDefinition()` ⚠
+      - [Service binding](#service-binding) `getServiceBinding()` ⚠
+  - Other
+    - Message class `getMessageClass()`
+      - [Message](#message) `getMessageClassMessage()` ⚠
+    - Feature toggle `getFeatureToggle()`
+- Runtime (`AdtRuntimeClient`)
+  - [ATC](#atc) `getAtc()` ⚠
+
+## By object
+
+In the order of the tree.
+
+### Transport request
+
+`getRequest()`. A list by user or status answers an empty `<tm:root/>` — the
+list is a search over a saved configuration; the tree under a request has no
+fixed nesting; a task made by hand refuses objects until it is typed. See
+ERRATA on [the transport list](#the-transport-list-is-a-saved-configuration-search),
+[the tree](#the-transport-tree-has-no-fixed-nesting) and
+[hand-made tasks](#a-hand-made-task-is-unclassified-and-refuses-objects).
+
+### Package
+
+`getPackage()`.
+
+- **"already locked" (PAK/058) on a second save in one ABAP session** — not an
+  enqueue lock. See
+  [below](#a-package-can-be-saved-only-once-per-abap-session).
+- **A metadata read too soon after a write answers `200` with no body** — as for
+  the other document types, see [Domain and data element](#domain-and-data-element).
+
+### Class
+
+`getClass()`.
+
+- **`400` "wrong input data for processing" on every read** of a class created
+  and not yet written — see
+  [below](#what-a-bare-create-leaves-depends-on-the-type).
+- **"Class … does not have a TMDIR entry" on an activation** — the class does
+  not exist; see [below](#activationexecuted-false-is-not-a-failure).
+
+#### Class includes
+
+`getLocalTestClass()`, `getLocalTypes()`, `getLocalDefinitions()`,
+`getLocalMacros()`. **Written under the class's lock**, not one of their own:
+lock the class. See
+[below](#a-class-include-is-written-under-the-class-lock).
+
+### Function group
+
+`getFunctionGroup()`.
+
+- **`validate()` answers `200` for a taken name**, with the verdict in the body —
+  see [below](#a-validation-answers-a-taken-name-inside-a-200).
+- **A metadata read too soon after a write answers `200` with no body** — see
+  [Domain and data element](#domain-and-data-element).
+
+#### Function module
+
+`getFunctionModule()`. **`500` "An exception was raised" on a source read** of a
+module that does not exist; only the long text says *"does not exist"* (FL651).
+Ask existence of `readMetadata()`, which answers `404`. See
+[below](#a-function-modules-source-answers-500-for-a-module-that-does-not-exist).
+
+### Domain and data element
+
+`getDomain()`, `getDataElement()` — and the other document types:
+`getPackage()`, `getTableType()`, `getFunctionGroup()`. **A metadata read too
+soon after a write answers `200` with no body.** Before a read-modify-write,
+reject an empty document rather than patching it. See
+[below](#a-read-answers-200-with-an-empty-body-instead-of-404).
+
+### Table type
+
+`getTableType()`. A document type — see
+[Domain and data element](#domain-and-data-element).
+
+### DDL source
+
+`getDdl()`. **`validate()` answers `200` for a taken name**, with the verdict in
+the body — see [below](#a-validation-answers-a-taken-name-inside-a-200).
+
+### Service definition
+
+`getServiceDefinition()`.
+
+- **A create is a POST that leaves the object empty**: its source reads `200`
+  with no body until you write it. See
+  [below](#what-a-bare-create-leaves-depends-on-the-type).
+- **`400` "Check of condition failed" on a create** means the request carried an
+  empty responsible person — a client built without
+  `IAdtClientOptions.responsible`. A create of a name that exists answers
+  `ExceptionResourceAlreadyExists` instead. See
+  [below](#an-empty-responsible-person-is-refused-as-check-of-condition-failed).
+
+#### Service binding
+
+`getServiceBinding()`. Built on a service definition; it is not edited, only
+activated, published and unpublished.
+
+- **`403` on the LOCK before a publish or unpublish — ignore it.** It means an
+  editing session holds the binding: an open Eclipse editor keeps its lock after
+  a publication, until the editor closes. The publication job does not need
+  your lock, and Eclipse itself posts the job after its own LOCK's `403`. Pass
+  `analysePublicationLock` (adt-strategies) to `lock()`: the `403` then answers a
+  lock without a handle (`''`), you publish, and you send no UNLOCK. Every other
+  refusal stays one. If the `403` should stop you, pass `analyseException`
+  instead. See
+  [below](#a-service-binding-is-locked-to-publish-it).
+- **"Service Binding … does not exist" on a publish** — inside a `200` — means
+  the binding is not active yet; a binding just created has only an inactive
+  version. `activate()` it, then publish. See
+  [below](#a-binding-publishes-only-once-it-is-active).
+- **"Error while creating service interface <BINDING>_0001_G4BA" on an
+  unpublish**, within a second, means the unpublish came too soon after a
+  publish. Repeat it minutes later; do not change the request. See
+  [below](#an-unpublish-straight-after-a-publish-is-refused).
+- **A publication takes minutes.** About 133 s on an idle system, longer on a
+  loaded one — pass a `timeout` above the 120 s default and wait for the job's
+  own answer (`analysePublication`); nothing needs polling.
+- **"You are already editing <BINDING>" on a delete** — the lock an editor holds.
+  Close the editor that holds it.
+
+### Message
+
+`getMessageClassMessage()`. **`OBJECT_NOT_FOUND` for a message** is this
+library reading the class document, not SAP reporting absence. A message class
+is a container and its messages are rows in it: only the container has existence
+on the wire — 404 before it is created, 404 after it is deleted — while a row has
+none. Measured, `POST …/messages/001?_action=LOCK_MSG` answers `200` before
+message 001 exists, because the PUT after it is what creates it. So the member
+fetches the class document and looks for the number itself; a consumer who
+replaces the reading replaces that verdict with it.
+
+### ATC
+
+`getAtc()` (runtime). **The check variant comes from customizing**, not from
+the run request. See
+[below](#atc-takes-its-check-variant-from-customizing).
+
 ## Contents
 
 Sessions and locks
@@ -37,33 +223,41 @@ Sessions and locks
 2. [The session-type header is per request](#the-session-type-header-is-per-request)
 3. [A class include is written under the class lock](#a-class-include-is-written-under-the-class-lock)
 4. [A service binding is locked to publish it](#a-service-binding-is-locked-to-publish-it)
+5. [A binding publishes only once it is active](#a-binding-publishes-only-once-it-is-active)
+6. [An unpublish straight after a publish is refused](#an-unpublish-straight-after-a-publish-is-refused)
 
 Reading answers
 
-5. [A refusal can arrive with a 2xx, and an error status names the fix](#a-refusal-can-arrive-with-a-2xx-and-an-error-status-names-the-fix)
-6. [A read answers 200 with an empty body instead of 404](#a-read-answers-200-with-an-empty-body-instead-of-404)
-7. [A successful delete can carry an untyped message](#a-successful-delete-can-carry-an-untyped-message)
-8. [S_ABPLNGVS refuses a create into a package that does not exist](#s_abplngvs-refuses-a-create-into-a-package-that-does-not-exist)
+7. [A refusal can arrive with a 2xx, and an error status names the fix](#a-refusal-can-arrive-with-a-2xx-and-an-error-status-names-the-fix)
+8. [A read answers 200 with an empty body instead of 404](#a-read-answers-200-with-an-empty-body-instead-of-404)
+9. [A successful delete can carry an untyped message](#a-successful-delete-can-carry-an-untyped-message)
+10. [A function module's source answers 500 for a module that does not exist](#a-function-modules-source-answers-500-for-a-module-that-does-not-exist)
+11. [A validation answers a taken name inside a 200](#a-validation-answers-a-taken-name-inside-a-200)
+12. [A deletion check that says no is not a failure](#a-deletion-check-that-says-no-is-not-a-failure)
+13. ["No URI-Mapping defined for URI" inside a 200](#no-uri-mapping-defined-for-uri-inside-a-200)
+14. [S_ABPLNGVS refuses a create into a package that does not exist](#s_abplngvs-refuses-a-create-into-a-package-that-does-not-exist)
 
 Creating and checking objects
 
-9. [What a bare create leaves depends on the type](#what-a-bare-create-leaves-depends-on-the-type)
-10. [A check run compiles source for objects that do not exist](#a-check-run-compiles-source-for-objects-that-do-not-exist)
+15. [What a bare create leaves depends on the type](#what-a-bare-create-leaves-depends-on-the-type)
+16. [An empty responsible person is refused as "Check of condition failed"](#an-empty-responsible-person-is-refused-as-check-of-condition-failed)
+17. [An object created without a package cannot be deleted](#an-object-created-without-a-package-cannot-be-deleted)
+18. [A check run compiles source for objects that do not exist](#a-check-run-compiles-source-for-objects-that-do-not-exist)
 
 Activation
 
-11. [activationExecuted false is not a failure](#activationexecuted-false-is-not-a-failure)
-12. [Activation settles inside the POST](#activation-settles-inside-the-post)
+19. [activationExecuted false is not a failure](#activationexecuted-false-is-not-a-failure)
+20. [Activation settles inside the POST](#activation-settles-inside-the-post)
 
 Transports
 
-13. [The transport list is a saved-configuration search](#the-transport-list-is-a-saved-configuration-search)
-14. [The transport tree has no fixed nesting](#the-transport-tree-has-no-fixed-nesting)
-15. [A hand-made task is Unclassified and refuses objects](#a-hand-made-task-is-unclassified-and-refuses-objects)
+21. [The transport list is a saved-configuration search](#the-transport-list-is-a-saved-configuration-search)
+22. [The transport tree has no fixed nesting](#the-transport-tree-has-no-fixed-nesting)
+23. [A hand-made task is Unclassified and refuses objects](#a-hand-made-task-is-unclassified-and-refuses-objects)
 
 ATC
 
-16. [ATC takes its check variant from customizing](#atc-takes-its-check-variant-from-customizing)
+24. [ATC takes its check variant from customizing](#atc-takes-its-check-variant-from-customizing)
 
 ---
 
@@ -300,11 +494,16 @@ publish job finishes. An open Eclipse editor on the binding holds the lock for
 the same user from a different session.
 
 **Rule.** The lock spans an editing session. From elsewhere, a held lock looks
-like a 403; it is usually someone's open Eclipse, not a leaked lock.
+like a 403; it is usually someone's open Eclipse, not a leaked lock. Eclipse
+itself meets a `403` on its own LOCK when its editor already holds the binding,
+and posts the job anyway: the job does not need the caller's lock.
 
 **Workaround.** For a library there is no editor, so the edit is the operation:
 `lock()`, `update()` with the desired publication state, `unlock()` in a
-`finally`. The publish job took about 133 seconds on the systems measured,
+`finally`. Pass `analysePublicationLock` to the `lock()`: a `403` then answers
+a lock without a handle (`''`), the publication goes ahead, and there is
+nothing to unlock. A caller who wants the `403` to stop them passes
+`analyseException` instead. The publish job took about 133 seconds on the systems measured,
 above the 120 s default — pass a larger `timeout`. Read the job's own answer
 (`analysePublication` from `@mcp-abap-adt/adt-strategies` reads its
 `SEVERITY`); nothing needs polling. For a binding locked elsewhere, close the
@@ -315,12 +514,74 @@ Eclipse editor that holds it. The full example is in
 `LOCK` → `200` on session *"stateful, enqueue"*; `POST
 …/odatav4/publishjobs` → `200` stateless, 133 057 ms; `UNLOCK` → `200` on
 *"Closing editor"*; a second `LOCK` before the unpublish → `403` while the
-first was held.
+first was held. Eclipse, cloud system, 2026-09-27: after a publish its editor
+kept the lock (a LOCK from another session → `403`); the unpublish that followed
+sent its own `LOCK` → `403` on the enqueue session and then `POST
+…/unpublishjobs` → `200`, 132 s. Between the two, the enqueue session was kept
+alive with `GET /sap/bc/adt/core/http/sessions`.
 
 **Where it bites.** `getServiceBinding()`: `lock`, `update`, `delete`.
 
 ---
 
+## A binding publishes only once it is active
+
+**Symptom.** Publishing a binding straight after creating it answers `200`
+with `<SEVERITY>ERROR</SEVERITY>`: *"Local Publish of <SERVICE_BINDING>
+failed"*, long text *"Service Binding <SERVICE_BINDING> does not exist."* The
+binding is there; its metadata reads back.
+
+**Cause.** A created binding has only an inactive version, and the publication
+looks for the active one.
+
+**Rule.** "Does not exist" here means "not active". Taking the lock first does
+not change it, and neither does reading the service's information
+(`generateServiceBinding`, a `GET` on `/businessservices/odatav4/<binding>` that
+Eclipse sends to refresh its view, after a publication).
+
+**Workaround.** `activate()` the binding, then publish it.
+
+**Evidence.** Cloud system, 2026-09-27, one binding deleted and created again:
+publish after the create → the refusal above; lock, then publish → the same;
+the information `GET`, then publish → the same; activate, then publish →
+*"<SERVICE_BINDING> published locally"*, 134 s.
+
+**Where it bites.** `getServiceBinding().create()` followed by `update()` with
+`desiredPublicationState: 'published'`.
+
+---
+
+## An unpublish straight after a publish is refused
+
+**Symptom.** An unpublish answers `200` with `<SEVERITY>ERROR</SEVERITY>`
+within a second: *"Local un-publish of <SERVICE_BINDING> failed"*, long text
+*"Error while creating service interface <SERVICE_BINDING>_0001_G4BA"*.
+
+**Cause.** The publication job answers before the system has finished with
+the binding; an unpublish in that window fails. The request is the same one
+that succeeds later.
+
+**Rule.** A fast `ERROR` from an unpublish is not a verdict on the binding. The
+job itself takes minutes when it runs; an answer in under a second means it did
+not run.
+
+**Workaround.** Leave time between a publish and an unpublish of the same
+binding — minutes, not seconds — and repeat an unpublish that failed this way
+later rather than changing the request.
+
+**Evidence.** Cloud system, 2026-09-27, one binding and the same request each
+time: publish → *"published locally"*, 133 s; unpublish straight after → the
+refusal above, 0.6 s; unpublish seven minutes later → *"un-published
+locally"*, 134 s. An unpublish from Eclipse several minutes after its publish
+took 132 s and succeeded. How long the window is, was not measured more
+closely.
+
+**Where it bites.** `getServiceBinding().update()` with `desiredPublicationState:
+'unpublished'` soon after a publication — a test that publishes and unpublishes
+in one run.
+
+---
+
 ## A refusal can arrive with a 2xx, and an error status names the fix
 
 **Symptom.** A deletion check, an activation or a validation answers **`200`**
@@ -448,6 +709,117 @@ CDS sources; any deletion reading.
 
 ---
 
+## A function module's source answers 500 for a module that does not exist
+
+**Symptom.** A read of a function module's source answers **`500`**, *"An
+exception was raised"* (`SY/530`), for a module that is simply not there. The
+same question asked of the module's metadata answers `404`.
+
+```
+GET …/fmodules/<FUNCTION_MODULE>/source/main  → 500  <type id="FUNCTION"/>
+    "An exception was raised"; LONGTEXT: "Function module <FUNCTION_MODULE>
+    does not exist" (FL651)
+GET …/fmodules/<FUNCTION_MODULE>              → 404  ExceptionResourceNotFound
+    "Function module <FUNCTION_MODULE> does not exist" (FL110)
+```
+
+**Cause.** The source resource raises the function builder's own exception
+instead of answering absence; the reason travels only in the long text.
+
+**Rule.** The status is the least of the answer — the text says "does not
+exist", even under a `500`. And a source is the wrong place to ask about
+existence at all: this one answers `500`, and a source that was never written
+answers `200` and no body
+([above](#a-read-answers-200-with-an-empty-body-instead-of-404)). Ask the
+object's own URI.
+
+**Workaround.** Decide existence with `readMetadata()`: a document means the
+object is there, `ExceptionResourceNotFound` or "does not exist" means it is
+not, and only an answer without a text is judged by its status. Where a source
+read has already failed, read the document in `response.data` — not the
+transport's "Request failed with status code 500".
+
+**Evidence.** Cloud system, 2026-09-27: both reads above, for a module in a new
+function group and for one in a long-active group; an existing module's source
+answered `200` with its code.
+
+**Where it bites.** `getFunctionModule().read()` used as an existence check.
+
+---
+
+## A validation answers a taken name inside a 200
+
+**Symptom.** `validate()` answers `200` for a name that is taken, and the create
+that follows is refused because the name exists.
+
+**Cause.** A validation refuses a taken name two different ways. A domain, a
+structure, a table, a class and a service definition answer a failing status. A
+**function group and a DDL source answer `200`** with the verdict in the body:
+
+```xml
+<SEVERITY>ERROR</SEVERITY>
+<SHORT_TEXT>Data definition <NAME> already exists</SHORT_TEXT>
+```
+
+**Rule.** A `validate()` that returns `200` has not told you the name is free —
+the body has. And `validate()` never answers whether the object exists: a free
+name validates fine either way, and a name is held from the POST onward whatever
+state the object is in.
+
+**Workaround.** Pass `analyseValidation` (adt-strategies), which reads both
+forms, or read `<SEVERITY>` yourself.
+
+**Evidence.** The recorded answers `refusal-validation-name-taken-ddl`,
+`-functiongroup`, `-class`, `-domain` and `-table` in the corpus.
+
+**Where it bites.** `getDdl().validate()`, `getFunctionGroup().validate()`.
+
+---
+
+## A deletion check that says no is not a failure
+
+**Symptom.** `checkDeletion()` answers `200` with `del:isDeletable="false"` and a
+reason.
+
+**Cause.** That is the answer the check exists to produce.
+
+**Rule.** A *check* that says "no" has answered. A *delete* that reports
+`del:isDeleted="false"` is a different thing: the objects are still on the
+system, and that is a failure.
+
+**Workaround.** Read the check's verdict with `analyseDeletion`; treat a refused
+delete as a failure, a refusing check as information.
+
+**Evidence.** The recorded answers `refusal-deletion-check-refuses` and
+`refusal-delete-refused` in the corpus.
+
+**Where it bites.** `checkDeletion()` and `delete()` on every type;
+`getUtils()` group deletion.
+
+---
+
+## "No URI-Mapping defined for URI" inside a 200
+
+**Symptom.** A group operation — deletion check, delete, activation — does
+nothing and reports nothing; the body of its `200` says *"No URI-Mapping defined
+for URI"*.
+
+**Cause.** The address named in the request does not exist on the server. It was
+seen when an object URI was built by lowercasing the type code — `DEVC/K` became
+`/sap/bc/adt/devc/k/<NAME>` — where the real resource is
+`/sap/bc/adt/packages/<NAME>`.
+
+**Rule.** A success that did nothing has its complaint in the body.
+
+**Workaround.** Take an object's URI from the system's own answers (search,
+node structure), not from its type code.
+
+**Evidence.** The package URI built from `DEVC/K`, answered as above.
+
+**Where it bites.** `getUtils()` group operations over hand-built references.
+
+---
+
 ## S_ABPLNGVS refuses a create into a package that does not exist
 
 **Symptom.** A create answers `403 ExceptionResourceNoAccess`, *"You are not
@@ -467,8 +839,53 @@ scenario `ABAP_LANGUAGE_VERSION` is switched on.
 **Workaround.** Before going to PFCG, check that the package in the request
 exists and that its software component allows the language version you are
 writing; then that the user holds that value in `ABP_LNG_VS` and the `ACTVT` for
-the step that failed. The authorization side is explained in
-[TROUBLESHOOTING.md](TROUBLESHOOTING.md#you-are-not-authorized-to-make-changes-authorization-object-s_abplngvs).
+the step that failed.
+
+**What the object is.** `S_ABPLNGVS` is not a role — it is an authorization
+object for the ABAP **language version**:
+
+| field | meaning |
+|---|---|
+| `ABP_LNG_VS` | the language version — *ABAP for Cloud Development*, *Standard ABAP* |
+| `ACTVT` | the permitted operations — create, change, activate, execute, ABAP Unit |
+
+The template role `SAP_BC_ABAP_DEVELOPER_5` carries it restricted to *ABAP for
+Cloud Development*. Allowing *Standard ABAP* as well means adding that value in
+PFCG.
+
+**It may be inert.** The check applies only when the SACF authorization scenario
+`ABAP_LANGUAGE_VERSION` is switched on. Otherwise the object sitting in a role
+restricts nothing, so finding it in a role proves nothing about behaviour.
+
+**It is not `S_DEVELOP`.** `S_DEVELOP` governs access to development objects at
+all; `S_ABPLNGVS` additionally governs *which language version* they may be
+created, changed and run in.
+
+**What "access to a language version" actually grants.**
+
+The object is checked as a pair, and both halves have to match the request:
+
+- **`ABP_LNG_VS` — which language.** An object is written in one ABAP language
+  version, fixed by the software component its package belongs to. Writing into a
+  package whose component is *ABAP for Cloud Development* requires that value;
+  writing a Standard ABAP object requires the Standard ABAP value. Holding one
+  does not grant the other, and this is the usual cause on BTP ABAP Environment,
+  where a developer is typically granted the cloud value only.
+- **`ACTVT` — which operation, per language.** Access is granted per activity:
+  create, change, activate, execute, run ABAP Unit. A user can hold *change* for
+  a language version and not *activate* it, so a chain can write successfully and
+  then fail at the activation step with the same object named.
+
+That second half is what makes the failure look intermittent: the same user, the
+same package, refused at one step of a create chain and not at the earlier ones.
+Read which step the failure carries — `IAdtError.request` names it — before
+concluding the whole language version is denied.
+
+**What to check, in order.** Whether the package in the request exists; which
+language version its software component fixes; whether the user holds that value
+in `ABP_LNG_VS`; and whether they hold the specific `ACTVT` for the operation
+that failed rather than for the one that succeeded.
+
 
 **Evidence.** Cloud trial, 2026-09-03: a class create into a package that did
 not exist answered this refusal. The meaning of the object is SAP's
@@ -485,8 +902,7 @@ mistyped `packageName`.
 `400 ExceptionResourceWrongData`, `SADT_RESOURCE/007`, *"Resource  <CLASS>: wrong
 input data for processing"* (note the double space) — for `active`, `inactive`,
 metadata and source alike. Waiting 30 seconds does not help, and neither does
-lock + unlock. Other types answer differently, and a service definition's
-create is refused outright with *"Check of condition failed"*.
+lock + unlock. Other types answer differently.
 
 **Cause.** What the POST leaves is a property of the type:
 
@@ -496,7 +912,7 @@ create is refused outright with *"Check of condition failed"*.
 | `interface` | generated skeleton | 53 bytes |
 | `class` | generated skeleton | **refused** `400 ExceptionResourceWrongData` |
 | `ddl` | object, no content | `200`, empty |
-| `serviceDefinition` | **nothing — the POST is refused** | — |
+| `serviceDefinition` | object, no content | `200`, empty source |
 
 The class does have a skeleton; it becomes readable at the first source write
 (`version=active` → SAP's `class <CLASS> definition`, `version=inactive` → what
@@ -509,16 +925,23 @@ the unreadable class), and `validate()` answers neither "name is free" nor
 "object exists" — the name is held from the POST onward regardless. Absence has
 three wordings (*"Error while importing object … from the database"*,
 *"Resource INTERFACE … does not exist."*, *"Data definition … of version  does
-not exist"*); do not match on the text.
+not exist"*); do not match on one wording. The metadata read marks absence
+with `<type id="ExceptionResourceNotFound"/>` whatever the sentence; a function
+module's source is the exception, where only the long text says it
+([below](#a-function-modules-source-answers-500-for-a-module-that-does-not-exist)).
 
 **Workaround.** After creating a class, write its source; do not retry the read.
 The first check worth making is after the write: read the version you wrote and
-compare. A service definition is created with its source in the same flow, not
-bare. If a sequence stops between the POST and the write, `delete()` the object
+compare. A service definition is created empty; write its source before
+activating it. If a sequence stops between the POST and the write, `delete()` the object
 while it is still bound to its package.
 
 **Evidence.** Cloud trial, 2026-09-05, `scripts/probe-unfinished-create.ts` and
-`scripts/probe-inactive-metadata.ts` (the table above). `program` could not be
+`scripts/probe-inactive-metadata.ts` (the table above). The service definition
+row was corrected on 2026-09-27: that probe's client carried no responsible
+person, and its "refused" was
+[that refusal](#an-empty-responsible-person-is-refused-as-check-of-condition-failed);
+with the user set, the POST answers `201` and the source reads empty. `program` could not be
 measured there — an ABAP Cloud system refuses it with `S_DEVELOP`. The class, in
 order:
 
@@ -540,6 +963,70 @@ read inactive       200   CLASS <class> DEFINITION …    ← as written
 
 ---
 
+## An empty responsible person is refused as "Check of condition failed"
+
+**Symptom.** A create answers `400 ExceptionInvalidData`, *"Check of condition
+failed"* (`00/001`), with `XML_PATH` `srvd:srvdSource(1)` and an `XML_OFFSET`
+that points at the end of the root element's start tag. Nothing names a field.
+
+**Cause.** The request carried `adtcore:responsible=""`. The empty attribute is
+the only difference from a request that is accepted: with the user in it the
+same POST answers `201`.
+
+**Rule.** The offset is the pointer: it names the root element's attributes,
+not its content. A create of a name that exists is a different answer —
+`400 ExceptionResourceAlreadyExists`, *"Resource Service Definition <NAME> does
+already exist."* — so this sentence is not "already exists" either.
+
+**Workaround.** Give the client the responsible person: `IAdtClientOptions.responsible`
+(on a cloud system, `userName` from `getSystemInformation()`; on-premise, the
+logon user, upper-cased). A client built without options sends it empty.
+
+**Evidence.** Cloud system, 2026-09-27, the same service definition POST three
+ways: `responsible=""` → `400` "Check of condition failed", `XML_OFFSET 330`,
+which is the end of the start tag; `responsible` set → `201`; the same again →
+`400 ExceptionResourceAlreadyExists`. The earlier measurement that called a
+service definition's create "refused outright" came from a client built
+without options, so it measured this.
+
+**Where it bites.** `create` on a client without `responsible` — most visibly
+`getServiceDefinition().create()`.
+
+---
+
+## An object created without a package cannot be deleted
+
+**Symptom.** A name is taken — every create of it is refused — and the deletion
+check says the object does not exist:
+
+```xml
+<del:object del:isDeletable="false" adtcore:name="<NAME>">
+  <del:message del:type="E"><del:text>Object does not exist</del:text></del:message>
+```
+
+**Cause.** The object was created but never bound to a package. The deletion
+check resolves through the package; one it can resolve names it
+(`adtcore:packageName="<PACKAGE>"`), and an unbound object gets the same answer
+as an absent one.
+
+**Rule.** "Object does not exist" from the deletion check is not proof of
+absence. Nothing reachable through ADT removes such an object — there is no
+resource that re-binds it — so cleaning it up is SAP GUI territory.
+
+**Workaround.** Prevention. `create` is one POST and never leaves such an object
+itself; a sequence that stops between the POST and the write can. Wrap the
+steps after a create so a failure calls `delete` while the object is still bound;
+treat a create as unfinished until `getUtils().search({ query: name })` answers
+`adtcore:packageName` for it. The one input guard this library keeps is exactly
+this: `create` without `packageName` throws before any request.
+
+**Evidence.** The two deletion-check shapes above. Not reproduced on purpose: the
+experiment leaves exactly the undeletable object it describes.
+
+**Where it bites.** Any `create` followed by steps that can fail.
+
+---
+
 ## A check run compiles source for objects that do not exist
 
 **Symptom.** A check of a name that does not exist answers `200` with no

package/docs/usage/OBJECT_LIFECYCLE.md

@@ -289,7 +289,7 @@ to a package. The deletion check resolves an object through its package — its
 answer carries `adtcore:packageName` when it found one and says "Object does not
 exist" when it did not — so an unbound object is reported absent while its name
 stays taken, and there is nothing for the delete to act on. See
-[TROUBLESHOOTING.md](TROUBLESHOOTING.md#an-object-that-exists-holds-its-name-and-cannot-be-deleted).
+[ERRATA.md](ERRATA.md#an-object-created-without-a-package-cannot-be-deleted).
 
 ### A behavior implementation needs a second write, and it is the class's
 
@@ -396,7 +396,7 @@ system gives.
 Two things worth knowing while you write it: `activationExecuted="false"` with
 no message means "nothing to do", and a locked object refuses with HTTP 403,
 which never reaches a body-reading strategy at all — see
-[WORKAROUNDS.md](WORKAROUNDS.md#activationexecuted-false-is-not-a-failure).
+[ERRATA.md](ERRATA.md#activationexecuted-false-is-not-a-failure).
 `analyseActivation` in `@mcp-abap-adt/adt-strategies` reads both.
 
 ## How to check a created object, and when
@@ -530,10 +530,12 @@ A POST sometimes builds a minimal working object and sometimes builds nothing,
 and which one you get is a property of the type: a domain is complete, an
 interface has a generated skeleton, a DDL source answers `200` with an empty
 body, a class has a skeleton that **no read can see until its first source
-write**, and a service definition's create is refused outright.
+write**, and a service definition is created with an empty source (a create
+that sends no responsible person is refused — a different thing, see
+[ERRATA.md](ERRATA.md#an-empty-responsible-person-is-refused-as-check-of-condition-failed)).
 `getVersions()` answers `ok` in every one of those states. The measured table,
 the class's read sequence and what to do are in
-[WORKAROUNDS.md](WORKAROUNDS.md#what-a-bare-create-leaves-depends-on-the-type).
+[ERRATA.md](ERRATA.md#what-a-bare-create-leaves-depends-on-the-type).
 
 ## The name is taken from the POST onward, and `validate()` may not say so
 
@@ -572,7 +574,7 @@ Deleting an object and reading it again answers a different sentence per type
 INTERFACE … does not exist."*, *"Data definition … of version  does not
 exist"*. All mean the same thing, and none is worth matching on: branch on the
 failure your own `analyse` decided. See
-[WORKAROUNDS.md](WORKAROUNDS.md#what-a-bare-create-leaves-depends-on-the-type).
+[ERRATA.md](ERRATA.md#what-a-bare-create-leaves-depends-on-the-type).
 
 Reproduce with `npx ts-node scripts/probe-inactive-metadata.ts` and
 `npx ts-node scripts/probe-unfinished-create.ts`.

package/docs/usage/RFC_CONNECTION.md

@@ -189,4 +189,4 @@ A package can be saved only once per ABAP session: the next update or delete
 from that session is refused with `PAK/058`. Over RFC every call shares one
 session, so an update straight after a create is already refused. The rule for
 both transports and the workaround are in
-[WORKAROUNDS.md](WORKAROUNDS.md#a-package-can-be-saved-only-once-per-abap-session).
+[ERRATA.md](ERRATA.md#a-package-can-be-saved-only-once-per-abap-session).

package/docs/usage/STATEFUL_SESSION_GUIDE.md

@@ -97,7 +97,7 @@ only once per ABAP session — the next update or delete from that session is
 refused with `PAK/058`, and the same request from any other session succeeds at
 once. It is `CL_PACKAGE`'s session buffer, not a delay: retrying never helps.
 The rule for HTTP and RFC, the evidence and the workaround are in
-[WORKAROUNDS.md](WORKAROUNDS.md#a-package-can-be-saved-only-once-per-abap-session).
+[ERRATA.md](ERRATA.md#a-package-can-be-saved-only-once-per-abap-session).
 
 So when an operation refuses in a way that names editing or locking, and the
 object is one your session has just changed, the fix is a different session —

package/package.json

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

package/docs/usage/TROUBLESHOOTING.md

@@ -1,193 +0,0 @@
-# Troubleshooting
-
-ADT answers are often accurate about the wrong thing. Everything below was
-observed against a running system, and each entry says what the message looks
-like, what it actually means, and how to tell the two apart.
-
-SAP-side behaviour with a consumer-side workaround is collected in
-[WORKAROUNDS.md](WORKAROUNDS.md); the entries below that belong there are short
-and link to it.
-
-## "You are not authorized to make changes (authorization object S_ABPLNGVS)"
-
-Arrives as a `403` with an `<exc:exception>` document, `adtType`
-`ExceptionResourceNoAccess`. It reads as a missing role. Often it is not.
-
-**What the object is.** `S_ABPLNGVS` is not a role — it is an authorization
-object for the ABAP **language version**:
-
-| field | meaning |
-|---|---|
-| `ABP_LNG_VS` | the language version — *ABAP for Cloud Development*, *Standard ABAP* |
-| `ACTVT` | the permitted operations — create, change, activate, execute, ABAP Unit |
-
-The template role `SAP_BC_ABAP_DEVELOPER_5` carries it restricted to *ABAP for
-Cloud Development*. Allowing *Standard ABAP* as well means adding that value in
-PFCG.
-
-**It may be inert.** The check applies only when the SACF authorization scenario
-`ABAP_LANGUAGE_VERSION` is switched on. Otherwise the object sitting in a role
-restricts nothing, so finding it in a role proves nothing about behaviour.
-
-**It is not `S_DEVELOP`.** `S_DEVELOP` governs access to development objects at
-all; `S_ABPLNGVS` additionally governs *which language version* they may be
-created, changed and run in.
-
-### What "access to a language version" actually grants
-
-The object is checked as a pair, and both halves have to match the request:
-
-- **`ABP_LNG_VS` — which language.** An object is written in one ABAP language
-  version, fixed by the software component its package belongs to. Writing into a
-  package whose component is *ABAP for Cloud Development* requires that value;
-  writing a Standard ABAP object requires the Standard ABAP value. Holding one
-  does not grant the other, and this is the usual cause on BTP ABAP Environment,
-  where a developer is typically granted the cloud value only.
-- **`ACTVT` — which operation, per language.** Access is granted per activity:
-  create, change, activate, execute, run ABAP Unit. A user can hold *change* for
-  a language version and not *activate* it, so a chain can write successfully and
-  then fail at the activation step with the same object named.
-
-That second half is what makes the failure look intermittent: the same user, the
-same package, refused at one step of a create chain and not at the earlier ones.
-Read which step the failure carries — `IAdtError.request` names it — before
-concluding the whole language version is denied.
-
-**What to check, in order.** Whether the package in the request exists; which
-language version its software component fixes; whether the user holds that value
-in `ABP_LNG_VS`; and whether they hold the specific `ACTVT` for the operation
-that failed rather than for the one that succeeded.
-
-**The trap.** It is also raised for a create into a package **that does not
-exist** — before going to PFCG, check the package. See
-[WORKAROUNDS.md](WORKAROUNDS.md#s_abplngvs-refuses-a-create-into-a-package-that-does-not-exist).
-
-## A read of an object that is not there returns 200 and an empty body
-
-`source/main` never answers 404, and a not-yet-ready metadata read answers the
-same `200` with zero bytes, so "not there" and "there and empty" are one answer.
-A read-modify-write that trusts the status erases the object. See
-[WORKAROUNDS.md](WORKAROUNDS.md#a-read-answers-200-with-an-empty-body-instead-of-404).
-
-## "Resource  ZCL_X: wrong input data for processing" on a read
-
-A `400 ExceptionResourceWrongData`, `SADT_RESOURCE/007`, on every read of a
-class that was created and has no source written yet. It is unfinished, not
-absent or broken: write the source, do not retry. See
-[WORKAROUNDS.md](WORKAROUNDS.md#what-a-bare-create-leaves-depends-on-the-type).
-
-## "Class ZCL_X does not have a TMDIR entry" on an activation
-
-A `200` carrying `<msg type="E" code="OO(045)">`: the object **does not exist**.
-Distinguish it from the entry above — `wrong input data` is an object that
-exists with nothing in it, `TMDIR` is an object that is not there at all. See
-[WORKAROUNDS.md](WORKAROUNDS.md#activationexecuted-false-is-not-a-failure).
-
-## A message class exists; its messages do not
-
-`getMessageClassMessage().read()` answering `OBJECT_NOT_FOUND` is **this library
-reading content**, not SAP reporting absence. A message class is a container and
-its messages are rows in it: only the container has existence on the wire — 404
-before it is created, 404 after it is deleted — while a row has none. Measured,
-`POST …/messages/001?_action=LOCK_MSG` answers `200` before message 001 exists,
-because the PUT after it is what creates it.
-
-So there is nothing to ask about a row, and nothing refuses. The member fetches
-the class document and looks for the number itself. A consumer who replaces the
-reading replaces that verdict along with it.
-
-## `validate()` passed and the create says the name is taken
-
-Fixed in this package, and worth knowing if you are on an older version or
-reading raw ADT traffic: a validation refuses a taken name two different ways.
-A domain, a structure, a table, a class and a service definition answer a
-failing status. A **function group and a DDL source answer `200`** with the
-verdict in the body:
-
-```xml
-<SEVERITY>ERROR</SEVERITY>
-<SHORT_TEXT>Data definition ZAC_X already exists</SHORT_TEXT>
-```
-
-A `validate()` that returns `200` has therefore not told you the name is free —
-the body has. This package reads none of it: supply an `analyse` that looks for
-`<SEVERITY>` if a rejected name should reach you as a failure, or read the
-document yourself.
-
-Note what `validate()` still does not answer: whether the object exists. A free
-name validates fine either way. And note what an abandoned create leaves — the
-name is held from the POST onward whatever state the object is in, including a
-class that no read can see.
-
-## An object that exists, holds its name, and cannot be deleted
-
-`delete()` works on anything you can name — with one exception, and it is the
-expensive one: **an object that was created but never bound to a package.** It
-holds its name against every future create, and nothing removes it.
-
-The mechanism shows in the deletion check's own answer. When it can resolve the
-object it names the package:
-
-```xml
-<del:object del:isDeletable="true"  adtcore:name="ZAC_X" adtcore:packageName="ZADT_BLD_PKG03"/>
-<del:object del:isDeletable="false" adtcore:name="ZAC_X">
-  <del:message del:type="E"><del:text>Object does not exist</del:text></del:message>
-```
-
-The second shape is what an absent object gets — and an unbound one gets it too,
-because the check resolves through the package. So the system reports "does not
-exist" about something whose name is demonstrably taken, and the delete has
-nothing to work on.
-
-**This page does not reproduce it on purpose.** The experiment succeeds by
-leaving exactly the undeletable object it is describing.
-
-**Prevention is the whole remedy this library offers:**
-
-- since 18.0.0 `create` is one POST, so it cannot leave a half-made object of
-  its own; what can is *your* sequence stopping between the POST and the write.
-  Wrap the steps that follow a create so a failure calls `delete` while the
-  object is still bound to its package;
-- treat a create as unfinished until you have seen the object *in its package* —
-  `getUtils().search({ query: name })` answers `adtcore:packageName` for an
-  object that resolved, and that is the attribute to look for;
-- do not abandon a create halfway on purpose.
-
-There is no member for re-binding an object to a package, and adding one would
-not help: the resource that would accept it is reached the same way. Cleaning up
-an object already in this state is SAP GUI territory.
-
-## A refusal can arrive with a 2xx
-
-The status is the channel; the document is the verdict. ADT has at least three
-refusal shapes, and a `200` can carry any of them. See
-[WORKAROUNDS.md](WORKAROUNDS.md#a-refusal-can-arrive-with-a-2xx-and-an-error-status-names-the-fix).
-
-## Activation reports `activationExecuted="false"` and nothing is wrong
-
-The flag says whether ADT did any work, not whether it succeeded; only
-`<msg type="E">` is the verdict. See
-[WORKAROUNDS.md](WORKAROUNDS.md#activationexecuted-false-is-not-a-failure).
-
-## A deletion check that says "no" is not a failure
-
-`/deletion/check` answers **200** with `del:isDeletable="false"` and a reason.
-That is the answer the check exists to produce, not a failure to answer.
-
-A *delete* that reports `del:isDeleted="false"` is a different thing entirely —
-the objects are still on the system, and that is a failure.
-
-## 406 and 415 name the exact content type in their text
-
-The status number says nothing actionable; the sentence names the header. See
-[WORKAROUNDS.md](WORKAROUNDS.md#a-refusal-can-arrive-with-a-2xx-and-an-error-status-names-the-fix).
-
-## "No URI-Mapping defined for URI", inside a 200
-
-The address does not exist on the server. Historically this came from building an
-object URI by lowercasing its type code — `DEVC/K` became
-`/sap/bc/adt/devc/k/{name}` — where the real resource is
-`/sap/bc/adt/packages/{name}`.
-
-If a group operation (deletion check, delete, activate) does nothing and reports
-nothing, read the body: the complaint is in there, inside a success.