@mcp-abap-adt/connection 1.10.1 → 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

@@ -0,0 +1,131 @@
+/**
+ * Owns the session lifecycle: what state the session is in, who may use it, and
+ * when it is safe to tear it down.
+ *
+ * Deliberately knows nothing about SAP, HTTP, RFC, cookies or ADT. Identities
+ * are opaque maps of name → value that someone else computed; windows are
+ * opaque labels. That is what makes this unit testable without a server, and it
+ * is where the hard part of the design lives: ordering, admission, deadlines.
+ *
+ * Design: docs/superpowers/specs/2026-07-27-session-lifecycle-design.md in
+ * @mcp-abap-adt/adt-clients.
+ */
+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. */
+    readonly epoch: number;
+    /** Call once the request settles. Safe to call twice. */
+    release(): void;
+}
+export interface DrainResult {
+    /** Labels of windows still open when the wait gave up, deduplicated. */
+    abandonedWindows: string[];
+}
+export interface BeginTeardownOptions {
+    /** Decides the epoch: a caller's request cancels recoveries, an internal one must not. */
+    origin: 'caller' | 'internal';
+    /** Decides admission: a lost session cannot let an open window finish. */
+    sessionLost: boolean;
+}
+export declare function sessionError(code: AdtSessionErrorCode, message?: string): Error & {
+    code: AdtSessionErrorCode;
+};
+export interface SessionLifecycleOptions {
+    /** Ceiling for the window wait, from the moment a teardown is requested. */
+    ceilingMs?: number;
+    /** Injected clock, so tests need no real time. */
+    now?: () => number;
+}
+export declare class SessionLifecycle {
+    private state;
+    private fingerprint;
+    private epoch;
+    private teardownPending;
+    private teardownLostSession;
+    private teardownAt;
+    /** Set at expiry: admission is shut regardless of open windows. */
+    private admissionForcedShut;
+    private readonly windows;
+    private inFlight;
+    private tail;
+    private tailKind;
+    private tailPromise;
+    private waiters;
+    private readonly ceilingMs;
+    private readonly now;
+    constructor(options?: SessionLifecycleOptions);
+    /**
+     * Whether a caller may start work. False throughout a teardown, including
+     * while a grandfathered window is still finishing: finishing is not starting.
+     */
+    get connected(): boolean;
+    /** Derived from the tracked fingerprint; null when nothing is tracked. */
+    get identity(): string | null;
+    get teardownEpoch(): number;
+    /** One entry per open window, abandoned ones included. */
+    get openWindows(): readonly string[];
+    /**
+     * Publishes a freshly established session, which also ENDS any teardown that
+     * was pending: the flags describe the session being torn down, and this is a
+     * different one. Without this, `connect()` after `disconnect()` — which the
+     * design allows explicitly — leaves the lifecycle permanently unusable.
+     *
+     * Windows are dropped for the same reason: they belonged to the old session,
+     * nothing here can close them, and a teardown that gave up on them has
+     * already carried their labels out in its report. Keeping them would make
+     * every future drain re-report locks from a session that no longer exists.
+     */
+    markConnected(fingerprint?: ReadonlyMap<string, string>): void;
+    markDisconnected(): void;
+    /**
+     * Classifies a freshly observed fingerprint.
+     *
+     * Additive: a name appearing where none was tracked is `established`, never
+     * `replaced` — otherwise the identifier a LOCK response adds would read as a
+     * new session and blow up the window it just opened.
+     */
+    observe(fingerprint: ReadonlyMap<string, string>): 'unchanged' | 'established' | 'replaced';
+    /** True while an already-open window is allowed to finish its work. */
+    private get finishingWindowOpen();
+    private get admits();
+    assertUsable(): void;
+    /** Asserts usability and counts the request in, in one synchronous step. */
+    admitRequest(): RequestLease;
+    /**
+     * A lock outlives the request that takes it, so it is the one thing a pending
+     * teardown refuses outright.
+     */
+    beginWindow(label: string): WindowToken;
+    /** A token matching no open window is ignored: double close, foreign token. */
+    endWindow(token: WindowToken): void;
+    beginTeardown({ origin, sessionLost }: BeginTeardownOptions): void;
+    get teardownRequested(): boolean;
+    /**
+     * Resolves when nothing is in flight and no window is still worth waiting
+     * for. Bounded by the ceiling measured from the teardown request — absolute,
+     * never extended by request activity.
+     *
+     * On expiry, before resolving and without yielding in between: shuts
+     * admission, gives up on the remaining windows, then waits once more for the
+     * already-admitted requests to settle.
+     */
+    drain(): Promise<DrainResult>;
+    private get liveWindows();
+    private abandonedLabels;
+    /**
+     * Runs a transition on the serializing tail.
+     *
+     * `connect` and `disconnect` join the tail of their own kind — two callers
+     * wanting the same thing get one execution and the same answer — but only
+     * when nothing is queued behind it, so a join can never overtake a queued
+     * transition of another kind. `recover` and `cleanup` never join and are
+     * never joined: a recovery carries its own request's baseline, and an
+     * internal cleanup owes its result to nobody while a caller's teardown owes a
+     * report.
+     */
+    transition<T>(kind: TransitionKind, run: () => Promise<T>): Promise<T>;
+    private wake;
+    private changed;
+}
+//# sourceMappingURL=SessionLifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SessionLifecycle.d.ts","sourceRoot":"","sources":["../../src/session/SessionLifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,WAAW,EACjB,MAAM,0BAA0B,CAAC;AAElC,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9E,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,0FAA0F;IAC1F,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC9B,0EAA0E;IAC1E,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,mBAAmB,EACzB,OAAO,CAAC,EAAE,MAAM,GACf,KAAK,GAAG;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,CAMvC;AAED,MAAM,WAAW,uBAAuB;IACtC,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAQD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAAgD;IAC7D,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,KAAK,CAAK;IAElB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,UAAU,CAAuB;IACzC,mEAAmE;IACnE,OAAO,CAAC,mBAAmB,CAAS;IAEpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAK;IAErB,OAAO,CAAC,IAAI,CAAuC;IACnD,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,WAAW,CAAiC;IAEpD,OAAO,CAAC,OAAO,CAAyB;IAExC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,OAAO,GAAE,uBAA4B;IAOjD;;;OAGG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,0EAA0E;IAC1E,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAM5B;IAED,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,0DAA0D;IAC1D,IAAI,WAAW,IAAI,SAAS,MAAM,EAAE,CAEnC;IAED;;;;;;;;;;OAUG;IACH,aAAa,CAAC,WAAW,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa,GAAG,IAAI;IAWzE,gBAAgB,IAAI,IAAI;IAMxB;;;;;;OAMG;IACH,OAAO,CACL,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACvC,WAAW,GAAG,aAAa,GAAG,UAAU;IAiB3C,uEAAuE;IACvE,OAAO,KAAK,mBAAmB,GAO9B;IAED,OAAO,KAAK,MAAM,GAIjB;IAED,YAAY,IAAI,IAAI;IAMpB,4EAA4E;IAC5E,YAAY,IAAI,YAAY;IAkB5B;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW;IASvC,+EAA+E;IAC/E,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAOnC,aAAa,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,oBAAoB,GAAG,IAAI;IAkBlE,IAAI,iBAAiB,IAAI,OAAO,CAE/B;IAED;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;IA2BnC,OAAO,KAAK,WAAW,GAItB;IAED,OAAO,CAAC,eAAe;IAUvB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA8BtE,OAAO,CAAC,IAAI;IAMZ,OAAO,CAAC,OAAO;CAehB"}

package/dist/session/SessionLifecycle.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * Owns the session lifecycle: what state the session is in, who may use it, and
+ * when it is safe to tear it down.
+ *
+ * Deliberately knows nothing about SAP, HTTP, RFC, cookies or ADT. Identities
+ * are opaque maps of name → value that someone else computed; windows are
+ * opaque labels. That is what makes this unit testable without a server, and it
+ * is where the hard part of the design lives: ordering, admission, deadlines.
+ *
+ * Design: docs/superpowers/specs/2026-07-27-session-lifecycle-design.md in
+ * @mcp-abap-adt/adt-clients.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionLifecycle = void 0;
+exports.sessionError = sessionError;
+const interfaces_1 = require("@mcp-abap-adt/interfaces");
+function sessionError(code, message) {
+    const error = new Error(message ?? code);
+    error.code = code;
+    return error;
+}
+class SessionLifecycle {
+    state = 'disconnected';
+    fingerprint = new Map();
+    epoch = 0;
+    teardownPending = false;
+    teardownLostSession = false;
+    teardownAt = null;
+    /** Set at expiry: admission is shut regardless of open windows. */
+    admissionForcedShut = false;
+    windows = new Map();
+    inFlight = 0;
+    tail = Promise.resolve();
+    tailKind = null;
+    tailPromise = null;
+    waiters = [];
+    ceilingMs;
+    now;
+    constructor(options = {}) {
+        this.ceilingMs = options.ceilingMs ?? 600_000;
+        this.now = options.now ?? (() => Date.now());
+    }
+    // ---------------------------------------------------------------- state ---
+    /**
+     * Whether a caller may start work. False throughout a teardown, including
+     * while a grandfathered window is still finishing: finishing is not starting.
+     */
+    get connected() {
+        return this.state === 'connected' && !this.teardownPending;
+    }
+    /** Derived from the tracked fingerprint; null when nothing is tracked. */
+    get identity() {
+        if (this.fingerprint.size === 0)
+            return null;
+        return [...this.fingerprint.entries()]
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([name, value]) => `${name}=${value}`)
+            .join('; ');
+    }
+    get teardownEpoch() {
+        return this.epoch;
+    }
+    /** One entry per open window, abandoned ones included. */
+    get openWindows() {
+        return [...this.windows.values()].map((w) => w.label);
+    }
+    /**
+     * Publishes a freshly established session, which also ENDS any teardown that
+     * was pending: the flags describe the session being torn down, and this is a
+     * different one. Without this, `connect()` after `disconnect()` — which the
+     * design allows explicitly — leaves the lifecycle permanently unusable.
+     *
+     * Windows are dropped for the same reason: they belonged to the old session,
+     * nothing here can close them, and a teardown that gave up on them has
+     * already carried their labels out in its report. Keeping them would make
+     * every future drain re-report locks from a session that no longer exists.
+     */
+    markConnected(fingerprint = new Map()) {
+        this.state = 'connected';
+        this.fingerprint = new Map(fingerprint);
+        this.teardownPending = false;
+        this.teardownLostSession = false;
+        this.admissionForcedShut = false;
+        this.teardownAt = null;
+        this.windows.clear();
+        this.wake();
+    }
+    markDisconnected() {
+        this.state = 'disconnected';
+        this.fingerprint.clear();
+        this.wake();
+    }
+    /**
+     * Classifies a freshly observed fingerprint.
+     *
+     * Additive: a name appearing where none was tracked is `established`, never
+     * `replaced` — otherwise the identifier a LOCK response adds would read as a
+     * new session and blow up the window it just opened.
+     */
+    observe(fingerprint) {
+        let established = false;
+        for (const [name, value] of fingerprint) {
+            const known = this.fingerprint.get(name);
+            if (known === undefined) {
+                established = true;
+                this.fingerprint.set(name, value);
+            }
+            else if (known !== value) {
+                this.fingerprint.set(name, value);
+                return 'replaced';
+            }
+        }
+        return established ? 'established' : 'unchanged';
+    }
+    // ------------------------------------------------------------ admission ---
+    /** True while an already-open window is allowed to finish its work. */
+    get finishingWindowOpen() {
+        return (this.teardownPending &&
+            !this.teardownLostSession &&
+            !this.admissionForcedShut &&
+            this.windows.size > 0);
+    }
+    get admits() {
+        if (this.state !== 'connected')
+            return false;
+        if (!this.teardownPending)
+            return true;
+        return this.finishingWindowOpen;
+    }
+    assertUsable() {
+        if (!this.admits) {
+            throw sessionError(interfaces_1.ADT_SESSION_ERROR.NOT_CONNECTED);
+        }
+    }
+    /** Asserts usability and counts the request in, in one synchronous step. */
+    admitRequest() {
+        this.assertUsable();
+        this.inFlight += 1;
+        const epoch = this.epoch;
+        let released = false;
+        return {
+            epoch,
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                this.inFlight -= 1;
+                this.wake();
+            },
+        };
+    }
+    // -------------------------------------------------------------- windows ---
+    /**
+     * A lock outlives the request that takes it, so it is the one thing a pending
+     * teardown refuses outright.
+     */
+    beginWindow(label) {
+        if (this.state !== 'connected' || this.teardownPending) {
+            throw sessionError(interfaces_1.ADT_SESSION_ERROR.NOT_CONNECTED);
+        }
+        const token = Symbol(label);
+        this.windows.set(token, { label, abandoned: false });
+        return token;
+    }
+    /** A token matching no open window is ignored: double close, foreign token. */
+    endWindow(token) {
+        if (!this.windows.delete(token))
+            return;
+        this.wake();
+    }
+    // ------------------------------------------------------------- teardown ---
+    beginTeardown({ origin, sessionLost }) {
+        if (!this.teardownPending) {
+            this.teardownAt = this.now();
+        }
+        this.teardownPending = true;
+        if (origin === 'caller') {
+            this.epoch += 1;
+        }
+        if (sessionLost) {
+            this.teardownLostSession = true;
+            // Nothing can finish over a session that is gone: give up on every window
+            // now, and drop the identity so a later comparison sees the change.
+            for (const entry of this.windows.values())
+                entry.abandoned = true;
+            this.fingerprint.clear();
+        }
+        this.wake();
+    }
+    get teardownRequested() {
+        return this.teardownPending;
+    }
+    /**
+     * Resolves when nothing is in flight and no window is still worth waiting
+     * for. Bounded by the ceiling measured from the teardown request — absolute,
+     * never extended by request activity.
+     *
+     * On expiry, before resolving and without yielding in between: shuts
+     * admission, gives up on the remaining windows, then waits once more for the
+     * already-admitted requests to settle.
+     */
+    async drain() {
+        // `??`, not `||`: a teardown requested at timestamp 0 is a real teardown,
+        // and treating it as absent would restart the ceiling from drain() — making
+        // the deadline relative to the wrong event, which is the sliding behaviour
+        // this design rejects.
+        const deadline = (this.teardownAt ?? this.now()) + this.ceilingMs;
+        while (this.inFlight > 0 || this.liveWindows > 0) {
+            const remaining = deadline - this.now();
+            if (remaining <= 0)
+                break;
+            await this.changed(remaining);
+        }
+        if (this.inFlight === 0 && this.liveWindows === 0) {
+            return { abandonedWindows: this.abandonedLabels() };
+        }
+        // Expiry. Synchronous, before any await: no request may enter after this.
+        this.admissionForcedShut = true;
+        for (const entry of this.windows.values())
+            entry.abandoned = true;
+        while (this.inFlight > 0) {
+            await this.changed();
+        }
+        return { abandonedWindows: this.abandonedLabels() };
+    }
+    get liveWindows() {
+        let live = 0;
+        for (const entry of this.windows.values())
+            if (!entry.abandoned)
+                live += 1;
+        return live;
+    }
+    abandonedLabels() {
+        const labels = new Set();
+        for (const entry of this.windows.values()) {
+            if (entry.abandoned)
+                labels.add(entry.label);
+        }
+        return [...labels];
+    }
+    // ---------------------------------------------------------- transitions ---
+    /**
+     * Runs a transition on the serializing tail.
+     *
+     * `connect` and `disconnect` join the tail of their own kind — two callers
+     * wanting the same thing get one execution and the same answer — but only
+     * when nothing is queued behind it, so a join can never overtake a queued
+     * transition of another kind. `recover` and `cleanup` never join and are
+     * never joined: a recovery carries its own request's baseline, and an
+     * internal cleanup owes its result to nobody while a caller's teardown owes a
+     * report.
+     */
+    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);
+        this.tail = queued.then(() => undefined, () => undefined);
+        this.tailKind = kind;
+        this.tailPromise = queued;
+        const settle = () => {
+            if (this.tailPromise === queued) {
+                this.tailKind = null;
+                this.tailPromise = null;
+            }
+        };
+        queued.then(settle, settle);
+        return queued;
+    }
+    // ----------------------------------------------------------- internals ---
+    wake() {
+        const waiters = this.waiters;
+        this.waiters = [];
+        for (const resolve of waiters)
+            resolve();
+    }
+    changed(timeoutMs) {
+        return new Promise((resolve) => {
+            let done = false;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                resolve();
+            };
+            this.waiters.push(finish);
+            if (timeoutMs !== undefined) {
+                const timer = setTimeout(finish, timeoutMs);
+                if (typeof timer.unref === 'function')
+                    timer.unref();
+            }
+        });
+    }
+}
+exports.SessionLifecycle = SessionLifecycle;