@mcp-abap-adt/connection 1.10.2 → 2.0.0

package/dist/connection/JwtAbapConnection.js

@@ -52,9 +52,10 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
         }
     }
     /**
-     * Override connect to handle JWT token refresh on errors
+     * Establishes the session for this auth type. Called by
+     * AbstractAbapConnection.connect(), which owns the lifecycle around it.
      */
-    async connect() {
+    async establishSession() {
         const baseUrl = await this.getBaseUrl();
         const discoveryUrl = `${baseUrl}/sap/bc/adt/discovery`;
         this.logger?.debug(`[DEBUG] JwtAbapConnection - Connecting to SAP system: ${discoveryUrl}`);
@@ -85,9 +86,11 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
                 }
                 // Try to refresh token if tokenRefresher is available
                 if (await this.tryRefreshToken()) {
-                    // Retry connect with new token
-                    this.logger?.debug(`[DEBUG] JwtAbapConnection - Retrying connect after token refresh...`);
-                    return this.connect();
+                    // Retry the ESTABLISHMENT, not connect(): connect() runs this as a
+                    // joinable transition, so a nested call joins the transition already
+                    // in flight — this one — and waits for itself forever.
+                    this.logger?.debug(`[DEBUG] JwtAbapConnection - Retrying establishment after token refresh...`);
+                    return this.establishSession();
                 }
                 throw new Error('JWT token has expired. Please re-authenticate.');
             }
@@ -99,6 +102,9 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
      * Override makeAdtRequest to handle JWT auth errors with automatic token refresh
      */
     async makeAdtRequest(options) {
+        // Captured before the attempt: a recovery asks "has the caller asked to
+        // stop since this request began", not since some later bookkeeping step.
+        const baselineEpoch = this.teardownEpoch;
         this.logger?.debug(`[DEBUG] JwtAbapConnection.makeAdtRequest - Starting request: ${options.method} ${options.url}`);
         try {
             const response = await super.makeAdtRequest(options);
@@ -124,9 +130,14 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
                 }
                 // Try to refresh token if tokenRefresher is available
                 if (await this.tryRefreshToken()) {
-                    // Reset connection state and retry request with new token
-                    this.logger?.debug(`[DEBUG] JwtAbapConnection.makeAdtRequest - Retrying request after token refresh...`);
-                    this.reset();
+                    this.logger?.debug(`[DEBUG] JwtAbapConnection.makeAdtRequest - Recovering session after token refresh...`);
+                    // The renewed credential cannot keep the old ABAP session, so this is
+                    // a session-lost teardown — internal, or it would cancel the very
+                    // recovery it is setting up. reset() would be the caller-origin one.
+                    this.discardSession();
+                    // Re-establish before retrying: the retry goes through admission, and
+                    // a discarded session admits nothing.
+                    await this.recoverSession(baselineEpoch);
                     return super.makeAdtRequest(options);
                 }
                 throw new Error('JWT token has expired. Please re-authenticate.');

package/dist/connection/KerberosAbapConnection.d.ts

@@ -14,7 +14,11 @@ export declare class KerberosAbapConnection extends AbstractAbapConnection {
      * request — the first request carries the Negotiate header; SAP then issues a session
      * cookie which is reused for subsequent requests.
      */
-    connect(): Promise<void>;
+    /**
+     * Establishes the session for this auth type. Called by
+     * AbstractAbapConnection.connect(), which owns the lifecycle around it.
+     */
+    protected establishSession(): Promise<void>;
     protected buildAuthorizationHeader(): string;
 }
 //# sourceMappingURL=KerberosAbapConnection.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"KerberosAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/KerberosAbapConnection.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAErE,uGAAuG;AACvG,qBAAa,sBAAuB,SAAQ,sBAAsB;IAChE,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,YAAY,CAAM;gBAEd,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,EAAE,SAAS,CAAC,EAAE,MAAM;IAQ1E,OAAO,CAAC,MAAM,CAAC,cAAc;IAa7B,mDAAmD;cACnC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5C;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAiC9B,SAAS,CAAC,wBAAwB,IAAI,MAAM;CAS7C"}
+{"version":3,"file":"KerberosAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/KerberosAbapConnection.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAErE,uGAAuG;AACvG,qBAAa,sBAAuB,SAAQ,sBAAsB;IAChE,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,YAAY,CAAM;gBAEd,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,EAAE,SAAS,CAAC,EAAE,MAAM;IAQ1E,OAAO,CAAC,MAAM,CAAC,cAAc;IAa7B,mDAAmD;cACnC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5C;;;;OAIG;IACH;;;OAGG;cACa,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAqFjD,SAAS,CAAC,wBAAwB,IAAI,MAAM;CAS7C"}

package/dist/connection/KerberosAbapConnection.js

@@ -34,16 +34,38 @@ class KerberosAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapCon
      * request — the first request carries the Negotiate header; SAP then issues a session
      * cookie which is reused for subsequent requests.
      */
-    async connect() {
+    /**
+     * Establishes the session for this auth type. Called by
+     * AbstractAbapConnection.connect(), which owns the lifecycle around it.
+     */
+    async establishSession() {
         await this.ensureToken();
         const baseUrl = await this.getBaseUrl();
         const discoveryUrl = `${baseUrl}/sap/bc/adt/discovery`;
         this.logger?.debug(`[DEBUG] KerberosAbapConnection - Connecting to SAP system: ${discoveryUrl}`);
         try {
-            const token = await this.fetchCsrfToken(discoveryUrl, 3, 1000);
+            // ONE attempt, deliberately — the shared default is 3 retries a second
+            // apart, and every one of them corrupts this exchange:
+            //
+            //  - A GSS token is one-shot. Replaying it is meaningless at best, and
+            //    replay protection may answer it differently than the original.
+            //  - Worse, a 401 that sets a cookie silences buildAuthorizationHeader()
+            //    (a cookie carries auth after the first round trip), so the retry
+            //    goes out with NO Authorization at all and draws the server's plain
+            //    opening challenge.
+            //
+            // Either way the classifier below would read the LAST response and name
+            // the wrong cause. The retry cannot help here anyway: nothing about a
+            // rejected token changes by waiting a second. Retrying a transient
+            // network failure is the caller's business now that connect() is
+            // explicit, and a fresh connect() mints a fresh token.
+            const token = await this.fetchCsrfToken(discoveryUrl, 0, 0);
             this.setCsrfToken(token);
         }
         catch (error) {
+            // The token went out and was not accepted, so it is spent. Keeping it
+            // would make every later connect() replay a token already known to fail.
+            this.currentToken = '';
             if (error instanceof axios_1.AxiosError && error.response?.headers) {
                 const wwwAuth = error.response.headers['www-authenticate'];
                 if ((0, ntlm_js_1.isNtlmChallenge)(wwwAuth)) {
@@ -53,8 +75,37 @@ class KerberosAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapCon
                 if (this.getCookies()) {
                     this.logger?.debug('[DEBUG] KerberosAbapConnection - cookies captured from error response during connect');
                 }
+                // A 401 carrying a Negotiate token is a CONTINUATION, not a success.
+                //
+                // Per RFC 4559 the server is handing back gssapi-data for the client to
+                // feed into its GSS context and retry. This client cannot do that:
+                // generateSpnegoToken() calls step('') once and discards the context,
+                // so there is nothing to continue with. The token it holds is the
+                // initial one, and sending it again produces the same 401.
+                //
+                // So this fails, and says why — resolving here would claim a readiness
+                // that does not exist and move the failure to the first real request,
+                // where it reads as an unrelated auth error.
+                if ((0, ntlm_js_1.isNegotiateContinuation)(wwwAuth)) {
+                    throw new Error('KerberosAbapConnection: the server continued the SPNEGO exchange ' +
+                        '(401 with a Negotiate token), which requires feeding that token ' +
+                        'back into the GSS context and retrying. This client performs a ' +
+                        'single-leg exchange only — the context is discarded after the ' +
+                        'first step — so multi-leg SPNEGO is not supported. See ' +
+                        'https://www.rfc-editor.org/rfc/rfc4559');
+                }
+                // A BARE Negotiate is a different problem with a different fix: the
+                // initial Authorization has already gone out, so an empty challenge is
+                // the server declining it. No token came back, so there is nothing to
+                // step even for a client that supports multi-leg.
+                if ((0, ntlm_js_1.isBareNegotiateChallenge)(wwwAuth)) {
+                    throw new Error('KerberosAbapConnection: the server rejected the SPNEGO token ' +
+                        '(401 with a bare Negotiate challenge, no token returned). The ' +
+                        'credentials were not accepted — check the SPN, the ticket ' +
+                        '(klist / kinit), and that the user is permitted Kerberos logon.');
+                }
             }
-            this.logger?.warn(`[WARN] KerberosAbapConnection - connect deferred: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
         }
     }
     buildAuthorizationHeader() {

package/dist/connection/SamlAbapConnection.d.ts

@@ -13,7 +13,11 @@ export declare class SamlAbapConnection extends AbstractAbapConnection {
      * Connect to SAP system using existing session cookies
      * Fetches CSRF token to establish session context
      */
-    connect(): Promise<void>;
+    /**
+     * Establishes the session for this auth type. Called by
+     * AbstractAbapConnection.connect(), which owns the lifecycle around it.
+     */
+    protected establishSession(): Promise<void>;
     protected buildAuthorizationHeader(): string;
     getAuthHeaders(): Promise<Record<string, string>>;
     private static validateConfig;

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

@@ -1 +1 @@
-{"version":3,"file":"SamlAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/SamlAbapConnection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAErE;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,sBAAsB;IAC5D,OAAO,CAAC,cAAc,CAAS;gBAG7B,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,EACvB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE;IAUzC;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAiC9B,SAAS,CAAC,wBAAwB,IAAI,MAAM;IAItC,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAQvD,OAAO,CAAC,MAAM,CAAC,cAAc;CAW9B"}
+{"version":3,"file":"SamlAbapConnection.d.ts","sourceRoot":"","sources":["../../src/connection/SamlAbapConnection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAErE;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,sBAAsB;IAC5D,OAAO,CAAC,cAAc,CAAS;gBAG7B,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,EACvB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE;IAUzC;;;OAGG;IACH;;;OAGG;cACa,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAwCjD,SAAS,CAAC,wBAAwB,IAAI,MAAM;IAItC,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAQvD,OAAO,CAAC,MAAM,CAAC,cAAc;CAW9B"}

package/dist/connection/SamlAbapConnection.js

@@ -20,7 +20,11 @@ class SamlAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnect
      * Connect to SAP system using existing session cookies
      * Fetches CSRF token to establish session context
      */
-    async connect() {
+    /**
+     * Establishes the session for this auth type. Called by
+     * AbstractAbapConnection.connect(), which owns the lifecycle around it.
+     */
+    async establishSession() {
         const baseUrl = await this.getBaseUrl();
         const discoveryUrl = `${baseUrl}/sap/bc/adt/discovery`;
         this.logger?.debug(`[DEBUG] SamlAbapConnection - Connecting to SAP system: ${discoveryUrl}`);
@@ -41,6 +45,12 @@ class SamlAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnect
                     this.logger?.debug(`[DEBUG] SamlAbapConnection - Cookies extracted from error response during connect (first 100 chars): ${this.getCookies()?.substring(0, 100)}...`);
                 }
             }
+            // Rethrow: a resolved connect() must mean a usable session exists. This
+            // used to swallow and resolve anyway, deferring establishment to the
+            // first request — coherent only while that lazy path existed. Without it,
+            // swallowing would leave a connection that reports success, holds
+            // nothing, and refuses every request.
+            throw error;
         }
     }
     buildAuthorizationHeader() {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,6BAA6B,EAAE,MAAM,yCAAyC,CAAC;AACxF,YAAY,EACV,WAAW,EACX,SAAS,EACT,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,YAAY,EACV,cAAc,EACd,kBAAkB,GACnB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,IAAI,oBAAoB,GAC3C,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC;AAEtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EACL,yBAAyB,EACzB,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,IAAI,mBAAmB,GACzC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,6BAA6B,EAAE,MAAM,yCAAyC,CAAC;AACxF,YAAY,EACV,WAAW,EACX,SAAS,EACT,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,YAAY,EACV,cAAc,EACd,kBAAkB,GACnB,MAAM,gCAAgC,CAAC;AAOxC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,IAAI,oBAAoB,GAC3C,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC;AAEtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EACL,yBAAyB,EACzB,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,IAAI,mBAAmB,GACzC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -7,6 +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.
 // Connection classes - only final implementations
 // Deprecated aliases for backward compatibility
 var BaseAbapConnection_js_1 = require("./connection/BaseAbapConnection.js");

package/dist/session/SessionLifecycle.d.ts

@@ -10,8 +10,7 @@
  * Design: docs/superpowers/specs/2026-07-27-session-lifecycle-design.md in
  * @mcp-abap-adt/adt-clients.
  */
-/** Opaque handle for one open lock window: `Symbol(label)`. */
-export type WindowToken = symbol;
+import { type AdtSessionErrorCode, type WindowToken } from '@mcp-abap-adt/interfaces';
 export type TransitionKind = 'connect' | 'disconnect' | 'recover' | 'cleanup';
 export interface RequestLease {
     /** Teardown epoch at admission — the baseline a recovery compares against. */
@@ -29,12 +28,6 @@ export interface BeginTeardownOptions {
     /** Decides admission: a lost session cannot let an open window finish. */
     sessionLost: boolean;
 }
-export declare const ADT_SESSION_ERROR: {
-    readonly NOT_CONNECTED: "ADT_NOT_CONNECTED";
-    readonly SESSION_REPLACED: "ADT_SESSION_REPLACED";
-    readonly RELEASE_PENDING: "ADT_RELEASE_PENDING";
-};
-export type AdtSessionErrorCode = (typeof ADT_SESSION_ERROR)[keyof typeof ADT_SESSION_ERROR];
 export declare function sessionError(code: AdtSessionErrorCode, message?: string): Error & {
     code: AdtSessionErrorCode;
 };
@@ -131,7 +124,7 @@ export declare class SessionLifecycle {
      * internal cleanup owes its result to nobody while a caller's teardown owes a
      * report.
      */
-    transition(kind: TransitionKind, run: () => Promise<void>): Promise<void>;
+    transition<T>(kind: TransitionKind, run: () => Promise<T>): Promise<T>;
     private wake;
     private changed;
 }

package/dist/session/SessionLifecycle.d.ts.map

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

package/dist/session/SessionLifecycle.js

@@ -12,13 +12,9 @@
  * @mcp-abap-adt/adt-clients.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionLifecycle = exports.ADT_SESSION_ERROR = void 0;
+exports.SessionLifecycle = void 0;
 exports.sessionError = sessionError;
-exports.ADT_SESSION_ERROR = {
-    NOT_CONNECTED: 'ADT_NOT_CONNECTED',
-    SESSION_REPLACED: 'ADT_SESSION_REPLACED',
-    RELEASE_PENDING: 'ADT_RELEASE_PENDING',
-};
+const interfaces_1 = require("@mcp-abap-adt/interfaces");
 function sessionError(code, message) {
     const error = new Error(message ?? code);
     error.code = code;
@@ -134,7 +130,7 @@ class SessionLifecycle {
     }
     assertUsable() {
         if (!this.admits) {
-            throw sessionError(exports.ADT_SESSION_ERROR.NOT_CONNECTED);
+            throw sessionError(interfaces_1.ADT_SESSION_ERROR.NOT_CONNECTED);
         }
     }
     /** Asserts usability and counts the request in, in one synchronous step. */
@@ -161,7 +157,7 @@ class SessionLifecycle {
      */
     beginWindow(label) {
         if (this.state !== 'connected' || this.teardownPending) {
-            throw sessionError(exports.ADT_SESSION_ERROR.NOT_CONNECTED);
+            throw sessionError(interfaces_1.ADT_SESSION_ERROR.NOT_CONNECTED);
         }
         const token = Symbol(label);
         this.windows.set(token, { label, abandoned: false });
@@ -258,6 +254,10 @@ class SessionLifecycle {
     transition(kind, run) {
         const joinable = kind === 'connect' || kind === 'disconnect';
         if (joinable && this.tailKind === kind && this.tailPromise) {
+            // Joining shares the ANSWER, not just the execution: a joiner that got a
+            // resolved promise carrying nothing would have to invent a result, and
+            // for a teardown that means reporting no abandoned locks when there were
+            // some. Callers of one kind ask the same question, so they get one reply.
             return this.tailPromise;
         }
         const queued = this.tail.then(run, run);

package/docs/INDEX.md

@@ -0,0 +1,106 @@
+# Documentation Index
+
+**Package:** `@mcp-abap-adt/connection`  
+**Version:** see [CHANGELOG.md](../CHANGELOG.md) — kept there rather than
+duplicated here, where it went stale by eight minor versions.
+
+## Package Structure
+
+```
+mcp-abap-connection/
+├── README.md                 # Main package documentation
+├── CHANGELOG.md             # Version history and changes
+├── docs/                    # Detailed documentation
+│   ├── INDEX.md                    # This file - documentation overview
+│   ├── INSTALLATION.md             # Setup and installation guide
+│   ├── USAGE.md                    # API documentation and examples
+│   ├── MIGRATION-2.0.md            # Moving to the explicit session lifecycle
+│   ├── SCOPE.md                    # What this package does and does not own
+│   ├── STATEFUL_SESSION_GUIDE.md   # Stateful requests and lock windows
+│   └── JWT_AUTH_TOOLS.md           # CLI tool for authentication
+├── examples/               # Working code examples
+│   ├── README.md          # Examples overview
+│   └── basic-connection.js # Simple connection example
+├── bin/                   # CLI tools
+│   └── sap-abap-auth.js  # JWT authentication CLI
+└── src/                  # Source code
+    ├── connection/       # Connection classes
+    ├── config/          # Configuration utilities
+    ├── utils/           # Helper functions
+    └── __tests__/       # Unit tests
+```
+
+## Quick Links
+
+### Getting Started
+- 📦 [Installation Guide](./INSTALLATION.md) - How to install and set up the package
+- 📚 [Usage Guide](./USAGE.md) - Basic usage and comprehensive API documentation
+- 📖 [Main README](../README.md) - Package overview and quick start
+- 🧭 [Scope and Boundaries](./SCOPE.md) - What this package does (and does not), sibling packages, and why there is no RFC to cloud
+
+### Core Features
+- 🔑 [JWT Auth Tools](./JWT_AUTH_TOOLS.md) - CLI tool for browser-based authentication
+
+### Version Information
+- 📋 [CHANGELOG](../CHANGELOG.md) - Complete version history, including what the latest release changed
+
+### Examples
+- 📁 [Examples Overview](../examples/README.md) - All available examples
+- 🔌 [Basic Connection](../examples/basic-connection.js) - Simple connection setup
+
+## Documentation by Topic
+
+### Authentication
+- **Basic Auth**: [USAGE.md - Basic Authentication](./USAGE.md#basic-authentication-on-premise)
+- **JWT/OAuth2**: [USAGE.md - JWT Authentication](./USAGE.md#jwt-authentication-cloudbtp)
+- **Token Refresh**: Handled by `@mcp-abap-adt/auth-broker` package (removed in 0.2.0)
+- **CLI Tool**: [JWT_AUTH_TOOLS.md](./JWT_AUTH_TOOLS.md)
+
+### Session Management
+- **Overview**: [USAGE.md - Session Management](./USAGE.md#session-management)
+- **Stateful Mode**: Use `setSessionType('stateful')` for session headers
+- **Session State Persistence**: Handled by `@mcp-abap-adt/auth-broker` package
+- **API Methods**:
+  - `getSessionId()` - Get current session ID (auto-generated UUID)
+  - `setSessionType()` - Switch between stateful/stateless modes
+
+### API Reference
+- **Connection Interface**: [USAGE.md - API Reference](./USAGE.md#api-reference)
+- **Configuration Types**: [USAGE.md - Configuration Types](./USAGE.md#configuration-types)
+- **Factory Function**: `createAbapConnection()`
+- **Connection Classes**: `BaseAbapConnection`, `JwtAbapConnection`
+
+## Version Highlights
+
+See [CHANGELOG.md](../CHANGELOG.md). This section used to restate it and drifted
+eight minor versions behind — a second copy of a changelog is a changelog that
+is wrong.
+
+## Documentation Standards
+
+### File Organization
+- **README.md** - Package overview, quick start, basic API
+- **CHANGELOG.md** - All changes, following [Keep a Changelog](https://keepachangelog.com/)
+- **docs/** - Detailed documentation, tutorials, guides
+- **examples/** - Working code examples with README
+
+### Naming Conventions
+- `UPPERCASE.md` - Main documentation files (README, CHANGELOG)
+- `PascalCase.md` - Detailed guides in docs/ folder
+- `kebab-case.js` - Example files
+
+### Content Guidelines
+- Keep README concise, link to detailed docs
+- Include working code examples
+- Document environment variables and configuration
+- Provide troubleshooting sections
+- Show both success and error handling
+
+## Contributing Documentation
+
+When adding new features:
+1. Update CHANGELOG.md with changes
+2. Add usage examples to USAGE.md
+3. Create working examples in examples/
+4. Update README.md if API changes
+5. Add troubleshooting to relevant guide