@mcp-abap-adt/connection 2.0.0 → 4.0.0

package/dist/connection/JwtAbapConnection.js

@@ -1,18 +1,66 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JwtAbapConnection = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+const interfaces_1 = require("@mcp-abap-adt/interfaces");
 const axios_1 = require("axios");
+const SessionLifecycle_js_1 = require("../session/SessionLifecycle.js");
 const AbstractAbapConnection_js_1 = require("./AbstractAbapConnection.js");
+const csrfConfig_js_1 = require("./csrfConfig.js");
+/**
+ * Is this worth refreshing a token for?
+ *
+ * 401 only. A 403 means the server authenticated the caller and refused the
+ * action anyway — a new token is the same caller, so refreshing answers a
+ * question nobody asked and, worse, used to end with the original error
+ * replaced by "JWT token has expired". See issue #30.
+ */
+function isTokenExpiryCandidate(error) {
+    return error instanceof axios_1.AxiosError && error.response?.status === 401;
+}
 /**
  * JWT Authentication connection for SAP BTP Cloud systems
  *
  * Supports automatic token refresh via ITokenRefresher injection:
- * - If tokenRefresher is provided, 401/403 errors trigger automatic token refresh
- * - If tokenRefresher is not provided, 401/403 errors throw an error (legacy behavior)
+ * - a **401** triggers a token refresh when a tokenRefresher is available;
+ * - without one, or when the refresh does not help, the server's own error is
+ *   thrown unchanged — status and body intact;
+ * - a **403** is never a token problem. It propagates as it arrived, because a
+ *   new token is the same caller and cannot change a permissions answer.
  */
 class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnection {
     tokenRefresher;
     currentToken;
+    /** Bumped by any token refresh, token-only ones included. */
+    tokenGeneration = 0;
+    /** Single-flight over the token fetch alone. Touches no session state. */
+    tokenRefreshInFlight;
+    /**
+     * The `tokenGeneration` a completed session recovery was built for. Only
+     * `performRenewal` moves it, and only after `recoverSession` resolves.
+     *
+     * Separate from `tokenGeneration` because a token-only refresh — which
+     * `fetchCsrfToken` does, from inside an establishment — bumps that counter
+     * without rebuilding anything. Reading it as "the session is settled" made
+     * the outer handler retry a request whose session was never rebuilt.
+     */
+    recoveredGeneration = 0;
+    /**
+     * Single-flight over the whole credential renewal, session included.
+     *
+     * Sharing only the token fetch leaves the expensive half racing: `recover`
+     * and `cleanup` never join (`SessionLifecycle.transition`), so two concurrent
+     * renewals queue as cleanup A → recover A → cleanup B → recover B, and A's
+     * retry meets a session B has just torn down.
+     */
+    renewalInFlight;
+    /**
+     * Per connection, deliberately NOT static. `baseline` is compared against
+     * `this.tokenGeneration`, which is instance state — a store shared between
+     * instances would let one connection's operation hand its baseline to
+     * another's, and the comparison would be between unrelated counters.
+     */
+    recoveryScope = new node_async_hooks_1.AsyncLocalStorage();
     constructor(config, logger, sessionId, tokenRefresher) {
         JwtAbapConnection.validateConfig(config);
         super(config, logger || null, sessionId);
@@ -31,18 +79,90 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
         return `Bearer ${this.currentToken}`;
     }
     /**
-     * Refresh the JWT token using the injected tokenRefresher
-     * @returns true if token was refreshed, false if no refresher available
+     * For the public entry point: this call is its own operation, always.
+     *
+     * A re-entrant `makeAdtRequest` — from a logger or a refresher callback the
+     * connection itself invokes while a scope is live — is a new caller-visible
+     * operation. Inheriting there would hand it a baseline from somebody else's
+     * refresh, which reads as "already refreshed for me" and skips a refresh it
+     * needs.
+     */
+    inNewRecoveryScope(fn) {
+        const scope = {
+            baseline: this.tokenGeneration,
+            active: true,
+        };
+        return this.recoveryScope.run(scope, async () => {
+            try {
+                return await fn();
+            }
+            finally {
+                scope.active = false;
+            }
+        });
+    }
+    /** For the inner levels: join the operation in progress, or start one. */
+    inRecoveryScope(fn) {
+        const inherited = this.recoveryScope.getStore();
+        // Only a scope that is still running. A store reached through an async
+        // resource that outlived its operation is stale, and its baseline describes
+        // a credential state that has since moved.
+        if (inherited?.active)
+            return fn();
+        return this.inNewRecoveryScope(fn);
+    }
+    /**
+     * The baseline this operation is reasoning from.
+     *
+     * The `active` check here and the one in `inRecoveryScope` OVERLAP: each
+     * compensates for the other, and the stale-context test only fails when both
+     * are removed. Kept as two because they answer different questions — "may I
+     * join this scope" and "may I trust this baseline" — and a reader who finds
+     * one redundant would be deleting half a guarantee.
+     */
+    currentBaseline() {
+        const scope = this.recoveryScope.getStore();
+        // No live scope means a caller reached a handler by a path that does not
+        // open one, or through a stale async context. Either way, treat it as its
+        // own operation rather than trusting a baseline nobody is standing behind.
+        return scope?.active ? scope.baseline : this.tokenGeneration;
+    }
+    /**
+     * Fetch a new token, unless somebody already did for this operation.
+     *
+     * Single-flighted so two concurrent handlers — including two nested
+     * `fetchCsrfToken` calls, which is a level `renewalInFlight` cannot reach —
+     * share one network call instead of racing and leaving `currentToken` as
+     * whichever settled last.
+     *
+     * @returns true when the caller may retry.
      */
-    async tryRefreshToken() {
+    refreshTokenOnce(baseline) {
+        if (this.tokenGeneration > baseline)
+            return Promise.resolve(true);
+        if (this.tokenRefreshInFlight)
+            return this.tokenRefreshInFlight;
         if (!this.tokenRefresher) {
             this.logger?.debug(`[DEBUG] JwtAbapConnection - No tokenRefresher available, cannot refresh token`);
-            return false;
+            return Promise.resolve(false);
         }
+        // Identity-checked clear, as SessionLifecycle.transition does with its
+        // tail: a joiner settling late must not clear a fetch somebody started
+        // after it.
+        const inFlight = this.performTokenRefresh().finally(() => {
+            if (this.tokenRefreshInFlight === inFlight) {
+                this.tokenRefreshInFlight = undefined;
+            }
+        });
+        this.tokenRefreshInFlight = inFlight;
+        return inFlight;
+    }
+    async performTokenRefresh() {
         try {
             this.logger?.debug(`[DEBUG] JwtAbapConnection - Refreshing token via tokenRefresher...`);
-            const newToken = await this.tokenRefresher.refreshToken();
-            this.currentToken = newToken;
+            // biome-ignore lint/style/noNonNullAssertion: refreshTokenOnce checks it
+            this.currentToken = await this.tokenRefresher.refreshToken();
+            this.tokenGeneration += 1;
             this.logger?.debug(`[DEBUG] JwtAbapConnection - Token refreshed successfully`);
             return true;
         }
@@ -51,6 +171,68 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
             return false;
         }
     }
+    /**
+     * Renew the credential and the session it belongs to, once, shared.
+     */
+    renewCredential(baselineEpoch, baseline) {
+        if (this.renewalInFlight)
+            return this.renewalInFlight;
+        // Identity-checked clear, as SessionLifecycle.transition does with its
+        // tail: a joiner settling late must not clear a renewal somebody started
+        // after it.
+        const inFlight = this.performRenewal(baselineEpoch, baseline).finally(() => {
+            if (this.renewalInFlight === inFlight)
+                this.renewalInFlight = undefined;
+        });
+        this.renewalInFlight = inFlight;
+        return inFlight;
+    }
+    async performRenewal(baselineEpoch, baseline) {
+        // Shared with the token-only path, and a no-op when the token is already
+        // newer than the one that failed — then what is missing is the session, and
+        // a second fetch answers a question nobody asked.
+        if (!(await this.refreshTokenOnce(baseline)))
+            return false;
+        this.logger?.debug(`[DEBUG] JwtAbapConnection - 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);
+        // Only here: a session now exists that was built with this token.
+        this.recoveredGeneration = this.tokenGeneration;
+        return true;
+    }
+    /**
+     * May this operation retry?
+     *
+     * The order of the checks is the design, not style.
+     */
+    async ensureRecovered(baselineEpoch) {
+        // 1. A renewal in flight is joined REGARDLESS of generation. A newer token
+        //    is no use while the session it belongs to is still being rebuilt:
+        //    retrying now is how a caller meets a closed admission door.
+        //
+        //    This overlaps check 2 as the counters stand — `recoveredGeneration`
+        //    only moves after `recoverSession` resolves, so check 2 cannot report a
+        //    rebuild that has not finished, and removing either guard alone leaves
+        //    the concurrency test green. Both are kept on purpose: this one states
+        //    the rule ("never decide anything while a renewal is running") without
+        //    depending on when some other counter happens to move, and it is what
+        //    keeps the invariant true if check 2's counter is ever changed.
+        if (this.renewalInFlight)
+            return this.renewalInFlight;
+        const baseline = this.currentBaseline();
+        // 2. A full renewal COMPLETED since this operation began — token, and the
+        //    session built with it. Not `tokenGeneration`: that moves on a
+        //    token-only refresh, which rebuilds nothing.
+        if (this.recoveredGeneration > baseline)
+            return true;
+        // 3. Nobody has. Renew, and let everyone else join.
+        return this.renewCredential(baselineEpoch, baseline);
+    }
     /**
      * Establishes the session for this auth type. Called by
      * AbstractAbapConnection.connect(), which owns the lifecycle around it.
@@ -61,7 +243,7 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
         this.logger?.debug(`[DEBUG] JwtAbapConnection - Connecting to SAP system: ${discoveryUrl}`);
         try {
             // Try to get CSRF token (this will also get cookies)
-            const token = await this.fetchCsrfToken(discoveryUrl, 3, 1000);
+            const token = await this.fetchCsrfToken(discoveryUrl);
             this.setCsrfToken(token);
             this.logger?.debug('Successfully connected to SAP system', {
                 hasCsrfToken: !!this.getCsrfToken(),
@@ -70,31 +252,9 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
             });
         }
         catch (error) {
-            // Handle JWT auth errors (401/403) during connect
-            if (error instanceof axios_1.AxiosError &&
-                (error.response?.status === 401 || error.response?.status === 403)) {
-                // Check if this is really an auth error, not a permissions error
-                const responseData = error.response?.data;
-                const responseText = typeof responseData === 'string'
-                    ? responseData
-                    : JSON.stringify(responseData || '');
-                // Don't retry on "No Access" errors
-                if (responseText.includes('ExceptionResourceNoAccess') ||
-                    responseText.includes('No authorization') ||
-                    responseText.includes('Missing authorization')) {
-                    throw error;
-                }
-                // Try to refresh token if tokenRefresher is available
-                if (await this.tryRefreshToken()) {
-                    // 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.');
+            if (isTokenExpiryCandidate(error)) {
+                this.logger?.error('[ERROR] JwtAbapConnection.establishSession - 401 while establishing; fetchCsrfToken has already refreshed and retried for this');
             }
-            // Re-throw other errors
             throw error;
         }
     }
@@ -102,6 +262,10 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
      * Override makeAdtRequest to handle JWT auth errors with automatic token refresh
      */
     async makeAdtRequest(options) {
+        // A public call is its own operation, whatever scope it starts in.
+        return this.inNewRecoveryScope(() => this.attemptRequest(options));
+    }
+    async attemptRequest(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;
@@ -113,34 +277,32 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
         }
         catch (error) {
             this.logger?.debug(`[DEBUG] JwtAbapConnection.makeAdtRequest - Request failed: ${error instanceof Error ? error.message : String(error)}`);
-            // Handle JWT auth errors (401/403)
-            if (error instanceof axios_1.AxiosError &&
-                (error.response?.status === 401 || error.response?.status === 403)) {
-                this.logger?.debug(`[DEBUG] JwtAbapConnection.makeAdtRequest - Got ${error.response.status}, attempting token refresh...`);
-                // Check if this is really an auth error, not a permissions error
-                const responseData = error.response?.data;
-                const responseText = typeof responseData === 'string'
-                    ? responseData
-                    : JSON.stringify(responseData || '');
-                // Don't retry on "No Access" errors - these are permission issues, not auth issues
-                if (responseText.includes('ExceptionResourceNoAccess') ||
-                    responseText.includes('No authorization') ||
-                    responseText.includes('Missing authorization')) {
-                    throw error;
-                }
-                // Try to refresh token if tokenRefresher is available
-                if (await this.tryRefreshToken()) {
-                    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);
+            if (isTokenExpiryCandidate(error)) {
+                this.logger?.debug(`[DEBUG] JwtAbapConnection.makeAdtRequest - Got 401, attempting token refresh...`);
+                if (await this.ensureRecovered(baselineEpoch)) {
+                    // A renewal this operation joined was fenced against the STARTER's
+                    // baseline, not this one's, and establishAndCommit's own epoch checks
+                    // belong to the establishment that ran. Between the last of them and
+                    // this retry there is a gap nothing else watches: the connection can
+                    // be torn down by its caller and made usable again, and a retry would
+                    // then go out on a session that caller discarded.
+                    if (this.teardownEpoch !== baselineEpoch) {
+                        throw (0, SessionLifecycle_js_1.sessionError)(interfaces_1.ADT_SESSION_ERROR.NOT_CONNECTED, 'Retry abandoned: a teardown was requested for this connection');
+                    }
+                    try {
+                        return await super.makeAdtRequest(options);
+                    }
+                    catch (retryError) {
+                        // A 401 that survived a renewal is the case the deleted message
+                        // was about, and it only shows up here — the log below fires when
+                        // the renewal never happened, which is a different fact.
+                        if (isTokenExpiryCandidate(retryError)) {
+                            this.logger?.error('[ERROR] JwtAbapConnection.makeAdtRequest - 401 persists after a credential renewal; the credential may need re-authentication');
+                        }
+                        throw retryError;
+                    }
                 }
-                throw new Error('JWT token has expired. Please re-authenticate.');
+                this.logger?.error('[ERROR] JwtAbapConnection.makeAdtRequest - 401 persists and the token could not be refreshed; the credential may need re-authentication');
             }
             throw error;
         }
@@ -148,33 +310,37 @@ class JwtAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnecti
     /**
      * Override fetchCsrfToken to handle JWT auth errors with automatic token refresh
      */
-    async fetchCsrfToken(url, retryCount = 3, retryDelay = 1000) {
+    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) {
+        // An inner level: join the operation in progress, or start one when
+        // reached directly — a bare connect() is still an operation with a
+        // baseline.
+        return this.inRecoveryScope(() => this.attemptCsrfToken(url, retryCount, retryDelay, generation));
+    }
+    async attemptCsrfToken(url, retryCount, retryDelay, generation) {
         try {
             // Try to fetch CSRF token using parent implementation
-            return await super.fetchCsrfToken(url, retryCount, retryDelay);
+            return await super.fetchCsrfToken(url, retryCount, retryDelay, generation);
         }
         catch (error) {
-            // Handle JWT auth errors (401/403) during CSRF token fetch
-            if (error instanceof axios_1.AxiosError &&
-                (error.response?.status === 401 || error.response?.status === 403)) {
-                // Check if this is really an auth error, not a permissions error
-                const responseData = error.response?.data;
-                const responseText = typeof responseData === 'string'
-                    ? responseData
-                    : JSON.stringify(responseData || '');
-                // Don't retry on "No Access" errors
-                if (responseText.includes('ExceptionResourceNoAccess') ||
-                    responseText.includes('No authorization') ||
-                    responseText.includes('Missing authorization')) {
-                    throw error;
-                }
-                // Try to refresh token if tokenRefresher is available
-                if (await this.tryRefreshToken()) {
+            // A 401 here may be an expired token; anything else is not ours to
+            // interpret — a 403 least of all, since a new token is the same caller.
+            if (isTokenExpiryCandidate(error)) {
+                if (await this.refreshTokenOnce(this.currentBaseline())) {
                     // Retry CSRF token fetch with new token
                     this.logger?.debug(`[DEBUG] JwtAbapConnection.fetchCsrfToken - Retrying after token refresh...`);
-                    return super.fetchCsrfToken(url, retryCount, retryDelay);
+                    try {
+                        return await super.fetchCsrfToken(url, retryCount, retryDelay, generation);
+                    }
+                    catch (retryError) {
+                        if (isTokenExpiryCandidate(retryError)) {
+                            this.logger?.error('[ERROR] JwtAbapConnection.fetchCsrfToken - 401 persists after a token refresh; the credential may need re-authentication');
+                        }
+                        throw retryError;
+                    }
                 }
-                throw new Error('JWT token has expired. Please re-authenticate.');
+                this.logger?.error('[ERROR] JwtAbapConnection.fetchCsrfToken - 401 persists and the token could not be refreshed; the credential may need re-authentication');
             }
             // Re-throw other errors
             throw error;

package/dist/connection/SamlAbapConnection.js

@@ -29,7 +29,7 @@ class SamlAbapConnection extends AbstractAbapConnection_js_1.AbstractAbapConnect
         const discoveryUrl = `${baseUrl}/sap/bc/adt/discovery`;
         this.logger?.debug(`[DEBUG] SamlAbapConnection - Connecting to SAP system: ${discoveryUrl}`);
         try {
-            const token = await this.fetchCsrfToken(discoveryUrl, 3, 1000);
+            const token = await this.fetchCsrfToken(discoveryUrl);
             this.setCsrfToken(token);
             this.logger?.debug('Successfully connected to SAP system', {
                 hasCsrfToken: !!this.getCsrfToken(),

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");

package/dist/session/SessionLifecycle.d.ts

@@ -1,118 +1,108 @@
 /**
  * Owns the session lifecycle: what state the session is in, who may use it, and
- * when it is safe to tear it down.
+ * when it stops being current.
  *
  * 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.
+ * are opaque maps of name → value that someone else computed. That is what makes
+ * this unit testable without a server, and it is where the hard part lives:
+ * ordering, admission, and telling one session from the next.
  *
- * Design: docs/superpowers/specs/2026-07-27-session-lifecycle-design.md in
+ * Design: docs/superpowers/specs/2026-07-31-teardown-policy-design.md in
  * @mcp-abap-adt/adt-clients.
  */
-import { type AdtSessionErrorCode, type WindowToken } from '@mcp-abap-adt/interfaces';
+import { type AdtSessionErrorCode } 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;
+    /**
+     * Session generation at admission — the baseline a RESPONSE compares against
+     * before touching shared state. Distinct from `epoch` on purpose: see
+     * `sessionGeneration`.
+     */
+    readonly generation: 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. */
+    /** A lost session cannot be spoken to again; its identity is dropped at once. */
     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 generation;
     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.
-     */
+    /** Whether a caller may start work. False throughout a pending teardown. */
     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[];
+    /**
+     * Which session is current, counted from zero.
+     *
+     * Two counters answer two different questions, and one cannot do both:
+     *
+     * - `epoch` — did the CALLER ask to stop? It moves only on a caller-initiated
+     *   teardown, because a recovery must not cancel itself.
+     * - `generation` — is this still the session you were issued against? It moves
+     *   on every change of which session is current, however caused.
+     *
+     * A fence built on `epoch` misses every internal teardown: after a session
+     * loss and a successful recovery, requests from the dead session carry the
+     * same epoch as the new one and sail straight through.
+     */
+    get sessionGeneration(): number;
     /**
      * 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;
+    /**
+     * Drops the tracked identity without touching state or generation.
+     *
+     * For a session the caller discarded ON PURPOSE — a credential renewal, a
+     * cache invalidation. The next fingerprint then reads as `established` rather
+     * than `replaced`, which is the truth: nothing was taken from us.
+     */
+    forgetIdentity(): 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.
+     * new session and condemn the operation it just covered.
      */
     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;
+    /** How many admitted requests have not settled. Diagnostics only — nothing waits on it. */
+    get requestsInFlight(): number;
     /**
-     * A lock outlives the request that takes it, so it is the one thing a pending
-     * teardown refuses outright.
+     * Whether a lease may still touch shared state.
+     *
+     * A request outliving its session is ordinary now that a teardown does not
+     * wait: its response must not write cookies over a newer session's, and must
+     * not be read as a replacement — which would raise a session-lost teardown
+     * against a session that is perfectly healthy.
      */
-    beginWindow(label: string): WindowToken;
-    /** A token matching no open window is ignored: double close, foreign token. */
-    endWindow(token: WindowToken): void;
+    isCurrent(lease: Pick<RequestLease, 'generation'>): boolean;
     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.
      *
@@ -121,11 +111,8 @@ export declare class SessionLifecycle {
      * 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.
+     * internal cleanup owes its result to nobody.
      */
     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

@@ -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":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAEL,KAAK,mBAAmB,EACzB,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;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,0FAA0F;IAC1F,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC9B,iFAAiF;IACjF,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,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAAgD;IAC7D,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,UAAU,CAAK;IAEvB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAK;IAErB,OAAO,CAAC,IAAI,CAAuC;IACnD,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,WAAW,CAAiC;IAIpD,4EAA4E;IAC5E,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,0EAA0E;IAC1E,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAM5B;IAED,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;;;;;;;;;;;;OAaG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED;;;;;OAKG;IACH,aAAa,CAAC,WAAW,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa,GAAG,IAAI;IAOzE;;;;;;OAMG;IACH,cAAc,IAAI,IAAI;IAItB,gBAAgB,IAAI,IAAI;IAKxB;;;;;;OAMG;IACH,OAAO,CACL,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACvC,WAAW,GAAG,aAAa,GAAG,UAAU;IAiB3C,YAAY,IAAI,IAAI;IAMpB,4EAA4E;IAC5E,YAAY,IAAI,YAAY;IAiB5B,2FAA2F;IAC3F,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,GAAG,OAAO;IAM3D,aAAa,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,oBAAoB,GAAG,IAAI;IAelE,IAAI,iBAAiB,IAAI,OAAO,CAE/B;IAID;;;;;;;;;OASG;IACH,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAuBvE"}