@mcp-abap-adt/connection 2.0.0 → 3.0.0

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":"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"}
+{"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"}

package/dist/session/SessionLifecycle.js

@@ -1,14 +1,14 @@
 "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.
+ * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -24,28 +24,14 @@ class SessionLifecycle {
     state = 'disconnected';
     fingerprint = new Map();
     epoch = 0;
+    generation = 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.
-     */
+    /** Whether a caller may start work. False throughout a pending teardown. */
     get connected() {
         return this.state === 'connected' && !this.teardownPending;
     }
@@ -61,42 +47,55 @@ class SessionLifecycle {
     get teardownEpoch() {
         return this.epoch;
     }
-    /** One entry per open window, abandoned ones included. */
-    get openWindows() {
-        return [...this.windows.values()].map((w) => w.label);
+    /**
+     * 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() {
+        return this.generation;
     }
     /**
      * 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();
+        this.generation += 1;
+    }
+    /**
+     * 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() {
+        this.fingerprint.clear();
     }
     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.
+     * new session and condemn the operation it just covered.
      */
     observe(fingerprint) {
         let established = false;
@@ -114,22 +113,8 @@ class SessionLifecycle {
         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) {
+        if (this.state !== 'connected' || this.teardownPending) {
             throw sessionError(interfaces_1.ADT_SESSION_ERROR.NOT_CONNECTED);
         }
     }
@@ -138,107 +123,52 @@ class SessionLifecycle {
         this.assertUsable();
         this.inFlight += 1;
         const epoch = this.epoch;
+        const generation = this.generation;
         let released = false;
         return {
             epoch,
+            generation,
             release: () => {
                 if (released)
                     return;
                 released = true;
                 this.inFlight -= 1;
-                this.wake();
             },
         };
     }
-    // -------------------------------------------------------------- windows ---
+    /** How many admitted requests have not settled. Diagnostics only — nothing waits on it. */
+    get requestsInFlight() {
+        return this.inFlight;
+    }
     /**
-     * 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) {
-        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();
+    isCurrent(lease) {
+        return lease.generation === this.generation;
     }
     // ------------------------------------------------------------- teardown ---
     beginTeardown({ origin, sessionLost }) {
-        if (!this.teardownPending) {
-            this.teardownAt = this.now();
-        }
         this.teardownPending = true;
         if (origin === 'caller') {
             this.epoch += 1;
         }
+        // The moment a session stops being current is the moment leases against it
+        // go stale — whether or not a replacement exists yet. Counting only at
+        // markConnected() leaves the gap between a teardown and the next connect,
+        // where a late response would write into state just cleared.
+        this.generation += 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.
@@ -248,16 +178,11 @@ 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(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);
@@ -273,29 +198,5 @@ class SessionLifecycle {
         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;

package/docs/MIGRATION-2.0.md

@@ -46,50 +46,39 @@ later, on the first request, as an unrelated-looking 401.
 
 ### 3. Requests are refused after a teardown
 
-`disconnect()` and `reset()` stop the connection from serving requests until
-the next `connect()`. An in-flight request is not cut off: a teardown drains
-before it clears anything.
+`disconnect()` and `reset()` stop the connection from serving requests until the
+next `connect()`. An in-flight request is not cut off and not waited for either:
+it runs to completion, and its result is fenced so it cannot touch a session
+established since.
 
-### 4. If you hold locks, tell the connection
+### 4. If you hold locks, do not let a timeout cut the span
 
-Available on the HTTP connection classes; see the availability note in
-[USAGE.md — Session Lifecycle](./USAGE.md#session-lifecycle).
+The connection does **not** track your locks. It does not know one exists, what
+object it covers, or what would release it — pairing every LOCK with its UNLOCK
+belongs to `@mcp-abap-adt/adt-clients`, which holds the handles.
 
-```typescript
-const token = connection.beginWindow('Class/ZCL_MY_CLASS');
-
-let lockHandle: string | undefined;
-try {
-  lockHandle = await lock(connection, 'ZCL_MY_CLASS');
-} catch (error) {
-  connection.endWindow(token);   // confirmed NOT locked: nothing is held
-  throw error;
-}
+What this layer can do is not let a short timeout abort a request mid-span, which
+would leave an operation whose outcome you cannot determine — a `LOCK` that may
+have succeeded server-side, with a handle you never received:
 
+```typescript
+connection.beginCriticalSection();
 try {
-  await update(connection, 'ZCL_MY_CLASS', lockHandle);
-  await unlock(connection, 'ZCL_MY_CLASS', lockHandle);
-  connection.endWindow(token);   // confirmed unlocked: the lock is released
-} catch (error) {
-  // Left open on purpose: the unlock may have failed, never gone out, or come
-  // back with an unknown outcome. Do NOT use a finally here.
-  throw error;
+  const handle = await lock(connection, 'ZCL_MY_CLASS');
+  await update(connection, 'ZCL_MY_CLASS', handle);
+  await unlock(connection, 'ZCL_MY_CLASS', handle);
+} finally {
+  connection.endCriticalSection();
 }
 ```
 
-You are not required to use windows at all. Without them a teardown cannot know
-a lock is open, so it will not wait for your unlock and will not report the lock
-if it gives up — it simply tears down, and the object stays locked on the server.
-
-But do not open a window and forget to close it on success: every later teardown
-then waits out `SAP_TIMEOUT_CRITICAL` before reporting it as abandoned.
+This is not new in 2.x — it has been available since 1.9.0 and is unchanged.
 
 ### 5. A new error you should handle
 
-`ADT_SESSION_REPLACED` means the SAP session is gone. It is raised when a
-replacement happens **while you hold a lock window**, and whenever the server
-itself says the session no longer exists — that second case regardless of any
-window. **Your lock handle is dead**: unlocking with it will not work, and the
+`ADT_SESSION_REPLACED` means the SAP session is gone. It is raised whenever the
+session identity changes under us, and whenever the server itself says the session
+no longer exists. **Your lock handle is dead**: unlocking with it will not work, and the
 object may still be locked on the server. The connector does not retry such
 a request — retrying blindly is what produced further orphaned locks in the
 field.

package/docs/STATEFUL_SESSION_GUIDE.md

@@ -2,10 +2,11 @@
 
 > **The header is not what tracks your lock.** `setSessionType('stateful')` sets
 > a per-request header and nothing more — another handler can flip it back while
-> your lock is genuinely open, and a batch never sets it at all. Tell the
-> connection about the lock itself with `beginWindow()` / `endWindow()`: that is
-> what a teardown waits for, what refuses to be abandoned silently, and what
-> makes a replaced session fatal instead of unnoticed. See
+> your lock is genuinely open, and a batch never sets it at all. Nothing in this
+> layer tracks locks: that belongs to `@mcp-abap-adt/adt-clients`, which holds the
+> handles and pairs each LOCK with its UNLOCK per object. What the connection
+> offers is `beginCriticalSection()` / `endCriticalSection()`, so a short timeout
+> cannot abort a request mid-span. See
 > [USAGE.md — Session Lifecycle](./USAGE.md#session-lifecycle).