@mcp-abap-adt/connection 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -7,6 +7,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-08-03
+
+Undoes two mistakes from 2.0.0, four days old. Everything else that release
+carried — mandatory `connect()`, replaced-session detection, session verdicts
+surviving the retry layers, the Kerberos diagnosis — is unchanged.
+
+### Changed — BREAKING
+- **`disconnect()` returns `Promise<void>` and waits for nothing.** It used to
+  drain in-flight requests before clearing anything, and that drain had an
+  unbounded tail: a request whose caller chose no timeout — a legitimate choice
+  for a long poll — could hold a teardown open forever. Because lifecycle
+  transitions are serialized, every later `connect()` queued behind it. We
+  published a `disconnect()` that resolves; that path could not.
+
+  Deciding when to disconnect is the caller's, and so is preparing for it.
+  Requests in flight now run to completion untouched — nothing is aborted — and
+  the session state is cleared at once. Requires `@mcp-abap-adt/interfaces`
+  **^12.0.0**.
+- **A replaced session is always fatal.** It used to be tolerated when no lock
+  window was open. Windows are gone (below), and this layer does not know that a
+  lock exists, what object it covers or what would release it — so the rule is
+  written from what it can know: the ABAP session we were speaking to is not the
+  one we are speaking to now, and anything held against the old one is dead.
+  Being wrong in this direction costs a reconnect; being wrong the other way
+  costs a lock nobody can find.
+
+### Removed — BREAKING
+- **`beginWindow()` / `endWindow()`**, and the window accounting in
+  `SessionLifecycle`. They were added in 2.0.0 and never worked: `beginWindow()`
+  put a label in a map and touched no timeout. The protection they were assumed
+  to provide — a span where a short per-request timeout must not abort a
+  request — is `beginCriticalSection()` / `endCriticalSection()`, which has done
+  it since 1.9.0, is reference-counted, and is **unchanged by this release**. Two
+  mechanisms for one idea, and the one promoted into the public API was the
+  no-op. Nothing called it: zero callers across every repository that depends on
+  this package.
+
+### Added
+- **Session-generation fencing.** Removing the wait means a request can settle
+  after a later `connect()` established a new session, and the response path
+  mutates shared state — cookies, the identity policy, the CSRF cache. A stale
+  response would write over the new session and could be read as a replacement,
+  tearing down a session that is perfectly healthy. Every lease now carries the
+  generation it was admitted under, and a response whose generation is not
+  current has its effects skipped. It still resolves normally to its own caller:
+  fencing suppresses effects, not results.
+
+  Deliberately not the teardown epoch. Only a caller-initiated teardown moves the
+  epoch — a recovery must not cancel itself — so after a session loss and a
+  successful recovery, requests from the dead session carry the same epoch as the
+  new one and pass straight through a fence built on it.
+
+  The fence sits at the **top of the error path**, before anything reads or
+  writes shared state — not merely before the response headers are applied.
+  Everything below it acts on the connection rather than on the request: a late
+  400 "session not found" would tear down the healthy session established since,
+  and a late 401/403 would clear the live session's state, fetch a fresh CSRF
+  token and **retry** — replaying a mutation from a dead session inside the live
+  one. A stale request now gets its error back and nothing else happens.
+
+### Fixed
+- **Our own re-establishment no longer reads as someone else's replacement.**
+  With a replacement now always fatal, a deliberate re-authentication would have
+  torn the connection down: `invalidateSession()` dropped the cookies but kept
+  the tracked identity, so the next cookie looked foreign. Both it and the
+  establishment path now forget the identity first. The distinction that matters
+  is not "was a lock held" but "did we cause this".
+
 ## [2.0.0] - 2026-07-29
 
 The connection owns its session now, and says so. Before this release a stateful
@@ -718,7 +786,8 @@ const connection = createAbapConnection(config, logger);
 - JWT token refresh now properly handles connection errors (401/403 during initial connect)
 - Permission errors (403 with "ExceptionResourceNoAccess") no longer trigger JWT refresh loops
 - Proper separation: base class handles HTTP/session, concrete classes handle auth-specific errors
-[Unreleased]: https://github.com/fr0ster/mcp-abap-connection/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/fr0ster/mcp-abap-connection/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v2.0.0...v3.0.0
 [2.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v1.10.2...v2.0.0
 [1.10.2]: https://github.com/fr0ster/mcp-abap-connection/compare/v1.10.1...v1.10.2
 [1.10.1]: https://github.com/fr0ster/mcp-abap-connection/compare/v1.10.0...v1.10.1

package/README.md

@@ -409,24 +409,26 @@ interface AbapConnection {
 ```
 
 The HTTP connection classes carry the rest of the session lifecycle. It is on the
-shared contract as two **capability atoms** in `@mcp-abap-adt/interfaces` (11.5.0+)
-rather than as methods on `IAbapConnection`, which is why `RfcAbapConnection` — a
-transport that owns no HTTP session — is unaffected by their existence:
+shared contract as a **capability atom** in `@mcp-abap-adt/interfaces` rather than
+as methods on `IAbapConnection`, which is why `RfcAbapConnection` — a transport
+that owns no HTTP session — is unaffected by its existence:
 
 ```typescript
 // ISessionLifecycleAware
-disconnect(): Promise<ITeardownReport>; // never throws; reports what it could not finish
+disconnect(): Promise<void>;         // never throws, and waits for nothing
 isConnected(): boolean;
-getSessionIdentity(): string | null;    // WHICH SAP session; null is not "disconnected"
-
-// ILockWindowAware
-beginWindow(label: string): WindowToken;
-endWindow(token: WindowToken): void;
+getSessionIdentity(): string | null; // WHICH SAP session; null is not "disconnected"
 ```
 
 Import those names from `@mcp-abap-adt/interfaces`, not from this package: a
 contract type re-exported under a second name is a contract type that can drift.
 
+**The connection does not track locks.** Deciding when to disconnect, and
+preparing for it, belongs to the caller; pairing every LOCK with its UNLOCK
+belongs to `@mcp-abap-adt/adt-clients`, which holds the handles. What this layer
+owns is not being interrupted by a timeout mid-operation — see
+`beginCriticalSection()` below.
+
 See [docs/USAGE.md — Session Lifecycle](./docs/USAGE.md#session-lifecycle).
 
 **Session Management:**

package/dist/connection/AbstractAbapConnection.d.ts

@@ -1,4 +1,4 @@
-import { type IAdtResponse, type ILockWindowAware, type ISessionLifecycleAware, type ITeardownReport, type WindowToken } from '@mcp-abap-adt/interfaces';
+import { type IAdtResponse, type ISessionLifecycleAware } from '@mcp-abap-adt/interfaces';
 import type { SapConfig } from '../config/sapConfig.js';
 import type { ILogger } from '../logger.js';
 import { SessionLifecycle } from '../session/SessionLifecycle.js';
@@ -9,7 +9,7 @@ import type { AbapConnection, AbapRequestOptions } from './AbapConnection.js';
  * the HTTP session's own, and naming them means a signature that drifts from
  * the published contract fails to compile here instead of at the consumer.
  */
-declare abstract class AbstractAbapConnection implements AbapConnection, ISessionLifecycleAware, ILockWindowAware {
+declare abstract class AbstractAbapConnection implements AbapConnection, ISessionLifecycleAware {
     private readonly config;
     protected readonly logger: ILogger | null;
     /**
@@ -108,10 +108,20 @@ declare abstract class AbstractAbapConnection implements AbapConnection, ISessio
      */
     connect(): Promise<void>;
     /**
-     * Tears the session down. Never throws: the report says what did not finish
-     * rather than failing. Sends no ADT session-close — see the design's D2.
+     * Tears the session down. Never throws, and always settles.
+     *
+     * It waits for NOTHING. Deciding when to disconnect is the caller's, and so is
+     * preparing for it — finishing chains, releasing locks. Waiting here on a
+     * request whose caller chose no timeout is what made a teardown unbounded, and
+     * an unbounded teardown blocks every later transition on the serialized tail.
+     *
+     * Requests already in flight run to completion untouched. Generation fencing
+     * (see `SessionLifecycle.isCurrent`) keeps their results from reaching this
+     * connection afterwards.
+     *
+     * Sends no ADT session-close — see the design's D2.
      */
-    disconnect(): Promise<ITeardownReport>;
+    disconnect(): Promise<void>;
     isConnected(): boolean;
     /**
      * Fingerprint of the SAP-side session, or null when none is known.
@@ -124,9 +134,6 @@ declare abstract class AbstractAbapConnection implements AbapConnection, ISessio
      * learned; only a CHANGED value means the session was replaced.
      */
     getSessionIdentity(): string | null;
-    /** Opens a lock window. See the design: a lock outlives its request. */
-    beginWindow(label: string): WindowToken;
-    endWindow(token: WindowToken): void;
     /**
      * Discards the session at a caller's request: cancels queued recoveries and
      * queues the cleanup rather than tearing down under a live request.
@@ -179,8 +186,8 @@ declare abstract class AbstractAbapConnection implements AbapConnection, ISessio
      * immediately — a later comparison must see the change, and on a dead session
      * the cookie is unchanged, so only the state can tell.
      *
-     * Does not await: it is called from inside a request, and the queued cleanup
-     * drains that very request.
+     * Does not await: it is called from inside a request, and the cleanup must not
+     * wait for the very request that raised it.
      */
     protected raiseSessionLost(reason: string): void;
     /** The credential-renewal raiser; see raiseSessionLost(). */
@@ -207,11 +214,18 @@ declare abstract class AbstractAbapConnection implements AbapConnection, ISessio
     /**
      * Acts on what a response said about the session identity.
      *
-     * A replacement is fatal only while a lock is held — and "a lock is held"
-     * means an open window, not `sessionMode`: a mode flag cannot represent
-     * windows, another handler can flip it back, and a batch never sets it.
-     * With no lock held the same replacement is not a loss: nothing was being
-     * held, so the new identity simply becomes the current one.
+     * A replacement is always fatal, and that is a narrowing: an earlier version
+     * tolerated it "when no lock is held", deciding from the connection's own
+     * lock windows. Those are gone, and rightly — this layer does not know that a
+     * lock exists, what object it covers or what would release it. Locks are
+     * tracked a layer up, per object, by the code that took them.
+     *
+     * So the rule is written from what this layer CAN know: the ABAP session we
+     * were speaking to is not the one we are speaking to now. Anything the caller
+     * held against the old one is dead, and continuing quietly would hand them a
+     * session they never opened — the failure this whole design exists to prevent.
+     * Being wrong in this direction costs a reconnect; being wrong the other way
+     * costs a lock nobody can find.
      */
     private applyIdentityPolicy;
     /**
@@ -244,7 +258,9 @@ declare abstract class AbstractAbapConnection implements AbapConnection, ISessio
      * Fetch CSRF token from SAP system
      * Protected method for use by concrete implementations in their connect() method
      */
-    protected fetchCsrfToken(url: string, retryCount?: number, retryDelay?: number): Promise<string>;
+    protected fetchCsrfToken(url: string, retryCount?: number, retryDelay?: number, 
+    /** Fences the response effects; omitted during connect(), which has no lease. */
+    generation?: number): Promise<string>;
     /**
      * Fetch CSRF token from a specific endpoint with retries
      */

package/dist/connection/AbstractAbapConnection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/AbstractAbapConnection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AbstractAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/AbstractAbapConnection.ts"],"names":[],"mappings":"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"}

package/dist/connection/AbstractAbapConnection.js

@@ -197,22 +197,27 @@ class AbstractAbapConnection {
         });
     }
     /**
-     * Tears the session down. Never throws: the report says what did not finish
-     * rather than failing. Sends no ADT session-close — see the design's D2.
+     * Tears the session down. Never throws, and always settles.
+     *
+     * It waits for NOTHING. Deciding when to disconnect is the caller's, and so is
+     * preparing for it — finishing chains, releasing locks. Waiting here on a
+     * request whose caller chose no timeout is what made a teardown unbounded, and
+     * an unbounded teardown blocks every later transition on the serialized tail.
+     *
+     * Requests already in flight run to completion untouched. Generation fencing
+     * (see `SessionLifecycle.isCurrent`) keeps their results from reaching this
+     * connection afterwards.
+     *
+     * Sends no ADT session-close — see the design's D2.
      */
     async disconnect() {
+        // Synchronous, at the call: admission shuts and the generation moves before
+        // anything is queued, so a caller who has asked to disconnect cannot have
+        // requests still going through while this waits its turn.
         this.lifecycle.beginTeardown({ origin: 'caller', sessionLost: false });
-        // The report travels THROUGH the transition, so a joining caller gets the
-        // same one. Building it outside would leave every caller but the first
-        // reporting an empty teardown — the abandoned locks reported to nobody.
-        return this.lifecycle.transition('disconnect', async () => {
-            const drained = await this.lifecycle.drain();
+        await this.lifecycle.transition('disconnect', async () => {
             this.clearSessionState();
             this.lifecycle.markDisconnected();
-            return {
-                abandonedWindows: drained.abandonedWindows,
-                releasePending: false,
-            };
         });
     }
     isConnected() {
@@ -231,13 +236,6 @@ class AbstractAbapConnection {
     getSessionIdentity() {
         return this.lifecycle.identity;
     }
-    /** Opens a lock window. See the design: a lock outlives its request. */
-    beginWindow(label) {
-        return this.lifecycle.beginWindow(label);
-    }
-    endWindow(token) {
-        this.lifecycle.endWindow(token);
-    }
     /**
      * Discards the session at a caller's request: cancels queued recoveries and
      * queues the cleanup rather than tearing down under a live request.
@@ -245,7 +243,6 @@ class AbstractAbapConnection {
     reset() {
         this.lifecycle.beginTeardown({ origin: 'caller', sessionLost: true });
         void this.lifecycle.transition('cleanup', async () => {
-            await this.lifecycle.drain();
             this.clearSessionState();
             this.lifecycle.markDisconnected();
         });
@@ -285,6 +282,12 @@ class AbstractAbapConnection {
         if (this.lifecycle.teardownEpoch !== baselineEpoch) {
             throw (0, SessionLifecycle_js_1.sessionError)(interfaces_1.ADT_SESSION_ERROR.NOT_CONNECTED, 'Establishment abandoned: a teardown was requested for this connection');
         }
+        // Whatever session arrives from here is one we are deliberately
+        // establishing, so it must not read as a replacement: the identity policy
+        // treats a changed fingerprint as fatal, and it cannot tell our own
+        // re-establishment from a session taken out from under us. Forgetting first
+        // makes the new fingerprint `established`, which is what it is.
+        this.lifecycle.forgetIdentity();
         try {
             await this.establishSession();
         }
@@ -342,14 +345,13 @@ class AbstractAbapConnection {
      * immediately — a later comparison must see the change, and on a dead session
      * the cookie is unchanged, so only the state can tell.
      *
-     * Does not await: it is called from inside a request, and the queued cleanup
-     * drains that very request.
+     * Does not await: it is called from inside a request, and the cleanup must not
+     * wait for the very request that raised it.
      */
     raiseSessionLost(reason) {
         this.logger?.warn(`Session lost: ${reason}`);
         this.lifecycle.beginTeardown({ origin: 'internal', sessionLost: true });
         void this.lifecycle.transition('cleanup', async () => {
-            await this.lifecycle.drain();
             this.clearSessionState();
             this.lifecycle.markDisconnected();
         });
@@ -381,27 +383,44 @@ class AbstractAbapConnection {
      * later check reads `unchanged`. That is one call site forgetting, and it
      * happened — on the error path and on every retry response.
      */
-    observeResponse(headers) {
+    observeResponse(headers, generation) {
+        // Fenced by SESSION GENERATION, not by the teardown epoch. Only a
+        // caller-initiated teardown moves the epoch — a recovery deliberately does
+        // not — so after a session loss and a successful recovery, a request from
+        // the dead session carries the same epoch as the new one and would sail
+        // straight through. The generation moves whenever the current session does.
+        //
+        // `undefined` means "not issued against a session": the CSRF fetch during
+        // connect() has no lease and must apply, since it is establishing the very
+        // session this would compare against.
+        if (generation !== undefined &&
+            generation !== this.lifecycle.sessionGeneration) {
+            this.logger?.debug('Ignoring a response from a previous session: its effects are fenced');
+            return;
+        }
         this.applyIdentityPolicy(this.updateCookiesFromResponse(headers));
     }
     /**
      * Acts on what a response said about the session identity.
      *
-     * A replacement is fatal only while a lock is held — and "a lock is held"
-     * means an open window, not `sessionMode`: a mode flag cannot represent
-     * windows, another handler can flip it back, and a batch never sets it.
-     * With no lock held the same replacement is not a loss: nothing was being
-     * held, so the new identity simply becomes the current one.
+     * A replacement is always fatal, and that is a narrowing: an earlier version
+     * tolerated it "when no lock is held", deciding from the connection's own
+     * lock windows. Those are gone, and rightly — this layer does not know that a
+     * lock exists, what object it covers or what would release it. Locks are
+     * tracked a layer up, per object, by the code that took them.
+     *
+     * So the rule is written from what this layer CAN know: the ABAP session we
+     * were speaking to is not the one we are speaking to now. Anything the caller
+     * held against the old one is dead, and continuing quietly would hand them a
+     * session they never opened — the failure this whole design exists to prevent.
+     * Being wrong in this direction costs a reconnect; being wrong the other way
+     * costs a lock nobody can find.
      */
     applyIdentityPolicy(classification) {
         if (classification !== 'replaced')
             return;
-        if (this.lifecycle.openWindows.length === 0) {
-            this.logger?.debug('Session identity changed with no lock held; continuing on the new one');
-            return;
-        }
-        this.raiseSessionLost('the session cookie changed while a lock was held');
-        throw (0, SessionLifecycle_js_1.sessionError)(interfaces_1.ADT_SESSION_ERROR.SESSION_REPLACED, 'The SAP session was replaced while a lock was held; the lock handle is dead');
+        this.raiseSessionLost('the session cookie changed under us');
+        throw (0, SessionLifecycle_js_1.sessionError)(interfaces_1.ADT_SESSION_ERROR.SESSION_REPLACED, 'The SAP session was replaced; anything held against the previous one is dead');
     }
     /**
      * Whether the server is telling us the session it was given no longer exists.
@@ -476,13 +495,13 @@ class AbstractAbapConnection {
         // shut the door.
         const lease = this.lifecycle.admitRequest();
         try {
-            return await this.performRequest(options);
+            return await this.performRequest(options, lease);
         }
         finally {
             lease.release();
         }
     }
-    async performRequest(options) {
+    async performRequest(options, lease) {
         const { url: endpoint, method, timeout, data, params, headers: customHeaders, } = options;
         const normalizedMethod = method.toUpperCase();
         // Build full URL: baseUrl + endpoint
@@ -578,7 +597,7 @@ class AbstractAbapConnection {
         });
         try {
             const response = await this.getAxiosInstance()(requestConfig);
-            this.observeResponse(response.headers);
+            this.observeResponse(response.headers, lease.generation);
             this.logger?.debug(`Request succeeded with status ${response.status}`, {
                 type: 'REQUEST_SUCCESS',
                 status: response.status,
@@ -588,6 +607,20 @@ class AbstractAbapConnection {
             return response;
         }
         catch (error) {
+            // FENCE FIRST, before anything reads or writes shared state.
+            //
+            // Fencing observeResponse() alone was not enough, and the gap was wide:
+            // everything below acts on this connection, not on the request. A late
+            // 400 "session not found" would call raiseSessionLost() and tear down the
+            // healthy session established since; a late 401/403 would call
+            // invalidateSession(), write a fresh CSRF token, and RETRY — replaying a
+            // mutation from a dead session inside the live one.
+            //
+            // A stale request gets its error back and nothing else happens.
+            if (!this.lifecycle.isCurrent(lease)) {
+                this.logger?.debug('A request from a previous session failed; its recovery is fenced');
+                throw error;
+            }
             const errorDetails = {
                 type: 'REQUEST_ERROR',
                 message: error instanceof Error ? error.message : String(error),
@@ -601,7 +634,7 @@ class AbstractAbapConnection {
                     typeof error.response.data === 'string'
                         ? error.response.data.slice(0, 200)
                         : JSON.stringify(error.response.data).slice(0, 200);
-                this.observeResponse(error.response.headers);
+                this.observeResponse(error.response.headers, lease.generation);
             }
             // The server telling us the session is gone is invisible to the identity
             // comparison: the cookie, and therefore the fingerprint, is unchanged.
@@ -653,7 +686,7 @@ class AbstractAbapConnection {
                     delete requestHeaders.cookie;
                 }
                 try {
-                    this.setCsrfToken(await this.fetchCsrfToken(requestUrl, 5, 2000));
+                    this.setCsrfToken(await this.fetchCsrfToken(requestUrl, 5, 2000, lease.generation));
                     const refreshedToken = this.getCsrfToken();
                     if (refreshedToken) {
                         requestHeaders['x-csrf-token'] = refreshedToken;
@@ -663,7 +696,7 @@ class AbstractAbapConnection {
                         requestHeaders.Cookie = refreshedCookies;
                     }
                     const retryResponse = await this.getAxiosInstance()(requestConfig);
-                    this.observeResponse(retryResponse.headers);
+                    this.observeResponse(retryResponse.headers, lease.generation);
                     return retryResponse;
                 }
                 catch (retryError) {
@@ -691,19 +724,19 @@ class AbstractAbapConnection {
                     this.logger?.debug(`[DEBUG] BaseAbapConnection - 401 on GET request, retrying with cookies from error response`);
                     requestHeaders.Cookie = this.cookies;
                     const retryResponse = await this.getAxiosInstance()(requestConfig);
-                    this.observeResponse(retryResponse.headers);
+                    this.observeResponse(retryResponse.headers, lease.generation);
                     return retryResponse;
                 }
                 // If no cookies, try to get them via CSRF token fetch
                 this.logger?.debug(`[DEBUG] BaseAbapConnection - 401 on GET request, attempting to get cookies via CSRF token fetch`);
                 try {
                     // Try to get CSRF token (this will also get cookies)
-                    this.csrfToken = await this.fetchCsrfToken(requestUrl, 3, 1000);
+                    this.csrfToken = await this.fetchCsrfToken(requestUrl, 3, 1000, lease.generation);
                     if (this.cookies) {
                         requestHeaders.Cookie = this.cookies;
                         this.logger?.debug(`[DEBUG] BaseAbapConnection - Retrying GET request with cookies from CSRF fetch`);
                         const retryResponse = await this.getAxiosInstance()(requestConfig);
-                        this.observeResponse(retryResponse.headers);
+                        this.observeResponse(retryResponse.headers, lease.generation);
                         return retryResponse;
                     }
                 }
@@ -722,7 +755,9 @@ class AbstractAbapConnection {
      * Fetch CSRF token from SAP system
      * Protected method for use by concrete implementations in their connect() method
      */
-    async fetchCsrfToken(url, retryCount = csrfConfig_js_1.CSRF_CONFIG.RETRY_COUNT, retryDelay = csrfConfig_js_1.CSRF_CONFIG.RETRY_DELAY) {
+    async fetchCsrfToken(url, retryCount = csrfConfig_js_1.CSRF_CONFIG.RETRY_COUNT, retryDelay = csrfConfig_js_1.CSRF_CONFIG.RETRY_DELAY, 
+    /** Fences the response effects; omitted during connect(), which has no lease. */
+    generation) {
         // Try primary endpoint first, then fallback for older systems
         const baseUrl = url.includes('/sap/bc/adt/')
             ? url.split('/sap/bc/adt')[0]
@@ -746,7 +781,7 @@ class AbstractAbapConnection {
         let lastError;
         for (const csrfUrl of endpoints) {
             try {
-                return await this.fetchCsrfTokenFromEndpoint(csrfUrl, retryCount, retryDelay);
+                return await this.fetchCsrfTokenFromEndpoint(csrfUrl, retryCount, retryDelay, generation);
             }
             catch (error) {
                 // Third layer with a catch on this path, and the last one that could
@@ -766,7 +801,7 @@ class AbstractAbapConnection {
     /**
      * Fetch CSRF token from a specific endpoint with retries
      */
-    async fetchCsrfTokenFromEndpoint(csrfUrl, retryCount, retryDelay) {
+    async fetchCsrfTokenFromEndpoint(csrfUrl, retryCount, retryDelay, generation) {
         this.logger?.debug(`Fetching CSRF token from: ${csrfUrl}`);
         for (let attempt = 0; attempt <= retryCount; attempt++) {
             try {
@@ -804,7 +839,7 @@ class AbstractAbapConnection {
                     headers,
                     timeout: (0, timeouts_js_1.getTimeout)('csrf'),
                 });
-                this.observeResponse(response.headers);
+                this.observeResponse(response.headers, generation);
                 const token = response.headers['x-csrf-token'];
                 if (!token) {
                     this.logger?.error('No CSRF token in response headers', {
@@ -818,7 +853,7 @@ class AbstractAbapConnection {
                     throw new Error(csrfConfig_js_1.CSRF_ERROR_MESSAGES.NOT_IN_HEADERS);
                 }
                 if (response.headers['set-cookie']) {
-                    this.observeResponse(response.headers);
+                    this.observeResponse(response.headers, generation);
                     if (this.cookies) {
                         this.logger?.debug(`[DEBUG] BaseAbapConnection - Cookies received from CSRF response (first 100 chars): ${this.cookies.substring(0, 100)}...`);
                         this.logger?.debug('Cookies extracted from response', {
@@ -842,7 +877,7 @@ class AbstractAbapConnection {
                     // Always try to extract cookies from error response, even on 401
                     // This ensures cookies are available for subsequent requests
                     if (error.response?.headers) {
-                        this.observeResponse(error.response.headers);
+                        this.observeResponse(error.response.headers, generation);
                         if (this.cookies) {
                             this.logger?.debug('Cookies extracted from error response', {
                                 status: error.response.status,
@@ -861,14 +896,14 @@ class AbstractAbapConnection {
                         this.logger?.debug('CSRF: SAP returned 405 (Method Not Allowed) — not critical, token found in header');
                         const token = error.response.headers['x-csrf-token'];
                         if (token) {
-                            this.observeResponse(error.response.headers);
+                            this.observeResponse(error.response.headers, generation);
                             return token;
                         }
                     }
                     if (error.response?.headers['x-csrf-token']) {
                         this.logger?.debug(`Got CSRF token despite error (status: ${error.response?.status})`);
                         const token = error.response.headers['x-csrf-token'];
-                        this.observeResponse(error.response.headers);
+                        this.observeResponse(error.response.headers, generation);
                         return token;
                     }
                     if (error.response) {
@@ -1037,6 +1072,13 @@ class AbstractAbapConnection {
         this.setCsrfToken(null);
         this.cookies = null;
         this.cookieStore.clear();
+        // And the tracked identity, because WE discarded the session. Without this
+        // the cookie that arrives next reads as a foreign replacement — and since a
+        // replacement is now always fatal, our own deliberate re-authentication
+        // would tear the connection down. The distinction that matters is not
+        // "was a lock held" but "did we cause this": what we discarded on purpose
+        // is not a session taken from under us.
+        this.lifecycle.forgetIdentity();
     }
     shouldRetryCsrf(error) {
         if (!(error instanceof axios_1.AxiosError)) {

package/dist/index.js

@@ -7,10 +7,10 @@ Object.defineProperty(exports, "FileCertificateMaterialLoader", { enumerable: tr
 // Config utilities
 var sapConfig_js_1 = require("./config/sapConfig.js");
 Object.defineProperty(exports, "sapConfigSignature", { enumerable: true, get: function () { return sapConfig_js_1.sapConfigSignature; } });
-// The session lifecycle vocabulary — ISessionLifecycleAware, ILockWindowAware,
-// ITeardownReport, WindowToken, ADT_SESSION_ERROR — is deliberately NOT exported
-// here. It lives in @mcp-abap-adt/interfaces, and a consumer imports it from
-// there: re-exporting a contract type gives it two names and lets the two drift.
+// The session lifecycle vocabulary — ISessionLifecycleAware, ADT_SESSION_ERROR —
+// is deliberately NOT exported here. It lives in @mcp-abap-adt/interfaces, and a
+// consumer imports it from there: re-exporting a contract type gives it two
+// names and lets the two drift.
 // Connection classes - only final implementations
 // Deprecated aliases for backward compatibility
 var BaseAbapConnection_js_1 = require("./connection/BaseAbapConnection.js");