@mcp-abap-adt/connection 2.0.0 → 4.0.0

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/INDEX.md

@@ -15,6 +15,7 @@ mcp-abap-connection/
 │   ├── INSTALLATION.md             # Setup and installation guide
 │   ├── USAGE.md                    # API documentation and examples
 │   ├── MIGRATION-2.0.md            # Moving to the explicit session lifecycle
+│   ├── MIGRATION-4.0.md            # JWT error classification: 401 refreshes, 403 propagates
 │   ├── SCOPE.md                    # What this package does and does not own
 │   ├── STATEFUL_SESSION_GUIDE.md   # Stateful requests and lock windows
 │   └── JWT_AUTH_TOOLS.md           # CLI tool for authentication
@@ -41,6 +42,10 @@ mcp-abap-connection/
 ### Core Features
 - 🔑 [JWT Auth Tools](./JWT_AUTH_TOOLS.md) - CLI tool for browser-based authentication
 
+### Upgrading
+- 🧱 [Migrating to 4.0.0](./MIGRATION-4.0.md) - JWT error classification: a 401 refreshes, a 403 propagates with the server's message
+- 🧱 [Migrating to 2.0.0](./MIGRATION-2.0.md) - The explicit session lifecycle: `connect()` is required
+
 ### Version Information
 - 📋 [CHANGELOG](../CHANGELOG.md) - Complete version history, including what the latest release changed
 

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/MIGRATION-4.0.md

@@ -0,0 +1,95 @@
+# Migrating to 4.0.0: the server's error reaches you
+
+A JWT connection used to answer some failures with an error of its own making:
+
+```
+Error: JWT token has expired. Please re-authenticate.
+```
+
+It said that for a **401** and for a **403** alike, and it threw the original `AxiosError` away
+along with the status and the body. Now the server's error reaches the caller unchanged, and only
+a 401 is treated as a credential problem.
+
+## What breaks, and what to do
+
+### 1. That message is gone
+
+If anything matches on it, it will stop matching.
+
+```typescript
+// before
+catch (error) {
+  if (error.message.includes('JWT token has expired')) {
+    await reauthenticate();
+  }
+}
+
+// after
+catch (error) {
+  if (error.response?.status === 401) {
+    await reauthenticate();
+  }
+}
+```
+
+`error.response.status` and `error.response.data` are available now — they were not before,
+because the replacement error carried neither.
+
+**Why it changed.** The message was wrong about half the cases it was used for. A 403 is not an
+expired token, and telling a caller to re-authenticate for one sends them to fix the single thing
+that is not broken.
+
+### 2. A 403 no longer triggers a token refresh
+
+It propagates as it arrived. If your code relied on a refresh happening after a 403 — for
+instance to recover from an authorization gap that a *different* principal would not have — that
+no longer happens, and it never worked for the reason you may have assumed: a refreshed token
+belongs to the same caller and cannot change a permissions answer.
+
+What a 403 usually carries is worth reading:
+
+```xml
+<exc:exception>
+  <type id="ExceptionResourceNoAuthorization"/>
+  <message lang="EN">You are not authorized to make changes (authorization object S_DEVELOP)</message>
+</exc:exception>
+```
+
+The authorization object is named. That is actionable; "please re-authenticate" was not.
+
+### 3. A 401 still refreshes, and now says so when it does not help
+
+The happy path is unchanged: a 401 with an injected `ITokenRefresher` fetches a new token,
+re-establishes the session and retries. What changed is the unhappy one — when the retry comes
+back 401 as well, the original error is rethrown and an `ERROR`-level log line explains that the
+credential may genuinely need re-authentication.
+
+## What did not change
+
+- `ITokenRefresher` and how it is injected;
+- that a credential renewal replaces the SAP session — with a lock window open, a request still
+  fails with `ADT_SESSION_REPLACED` rather than continuing on a session your lock is not in (see
+  [STATEFUL_SESSION_GUIDE.md](./STATEFUL_SESSION_GUIDE.md));
+- every other authentication type. `BaseAbapConnection`, `SamlAbapConnection`,
+  `CertificateAbapConnection` and `KerberosAbapConnection` never refreshed tokens and never
+  synthesised an error in place of the server's.
+
+## Under the hood, if you are debugging
+
+Concurrent requests that hit the same expired token now share **one** renewal — one token fetch
+and one session re-establishment between them — rather than each running its own teardown and
+recovery in sequence. If you have log-line counts or timing expectations built around the old
+behaviour, they will change; the observable contract does not.
+
+## Where this came from
+
+Issue [#30](https://github.com/fr0ster/mcp-abap-connection/issues/30), found while probing ATC on
+a cloud trial: creating a classic program was reported as an expired token on three consecutive
+runs, while the same session was answering other requests with 200. It took bypassing the
+connector on the same credential to see the 403 and the `S_DEVELOP` message underneath.
+
+One question is deliberately left open and tracked in
+[#32](https://github.com/fr0ster/mcp-abap-connection/issues/32): whether some BTP setup answers an
+*invalid* token with 403 rather than 401. Nothing captured shows that it does, and preserving the
+original error is what makes the assumption safe to be wrong about — a caller would then see the
+server's own 403 instead of a misleading message.

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).
 
 
@@ -81,6 +82,12 @@ Every ADT request issued through `makeAdtRequest` automatically:
 
 This logic is transparent to callers (Builders, handlers, CLI scripts).
 
+On a JWT connection one case is **not** transparent, and cannot be: a 401 that leads to a token
+refresh also replaces the SAP session, because the renewed credential cannot keep the old one.
+Inside a lock window that surfaces as `ADT_SESSION_REPLACED` rather than a request quietly
+continuing on a session your lock is not in. A 403 never does this — it is an authorization
+answer, not a credential one, and nothing is torn down for it.
+
 ---
 
 ## Interaction With ADT Clients