@mcp-abap-adt/connection 4.0.0 → 5.0.0

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

@@ -8,8 +8,23 @@
  * 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-31-teardown-policy-design.md in
- * @mcp-abap-adt/adt-clients.
+ * What it guarantees, since the design note it used to point at lived in another
+ * package and has been deleted with the work it described:
+ *
+ *   - **One transition at a time**, on a serializing tail. Connects join
+ *     connects and disconnects join disconnects, so concurrent callers share one
+ *     establishment or one teardown rather than racing to build and demolish the
+ *     same session.
+ *   - **Admission is synchronous.** A request is admitted, or refused, in the
+ *     same step that counts it — so nothing can be admitted and still be
+ *     invisible to a teardown draining at that instant.
+ *   - **A teardown waits for nothing.** In-flight requests run to completion
+ *     untouched; their results are fenced by session generation so a late answer
+ *     cannot write over a session established since.
+ *   - **Identity is observed, never assumed.** A changed fingerprint means the
+ *     session we had is gone and this is a different one, which is fatal to
+ *     anything held against the old one;
+ *     an unchanged one says nothing about whether the server still has it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SessionLifecycle = void 0;

package/dist/session/SessionStrategy.d.ts

@@ -0,0 +1,86 @@
+/**
+ * How a session is opened on the server, and how the server is told we are
+ * done with it.
+ *
+ * Two systems, two mechanisms, one meaning. On ABAP Cloud a session is a
+ * resource: it is asked for at `/sap/bc/adt/core/http/sessions` and the
+ * response publishes its own address, which is what a `DELETE` is sent to. On
+ * on-prem there is no such resource — the logon call is the establishing
+ * request itself, and the platform's `/sap/public/bc/icf/logoff` is how it is
+ * given back.
+ *
+ * **Both are notifications, not commands.** They say "we have finished with
+ * this session". Whether the system frees it now, later, or keeps it to reuse
+ * is the system's business, and nothing here checks afterwards or depends on
+ * the answer. Measured on a trial: the `DELETE` is answered `200` and the
+ * session is still listed a moment later; the logoff is answered `200` and it
+ * is not. Neither is a failure — they are two systems deciding differently
+ * about a message they both accepted.
+ *
+ * Split by what the server publishes rather than by which system we think we
+ * are talking to: `openSession()` asks, and a system that has no such resource
+ * says so. Guessing the platform would be a guess; asking is not.
+ */
+import type { ILogger } from '../logger.js';
+/** What a strategy needs from the connection to talk to the server. */
+export interface ISessionTransport {
+    /** Absolute base URL of the system. */
+    baseUrl: string;
+    /** Auth headers for a request made outside the normal request path. */
+    authHeaders(): Promise<Record<string, string>>;
+    /** Cookies held for this connection, or null before any have arrived. */
+    cookies(): string | null;
+    /** The CSRF token held, if one has been fetched. */
+    csrfToken(): string | null;
+    /** Issue a raw request and hand back status, headers and body. */
+    send(request: {
+        method: 'GET' | 'DELETE';
+        url: string;
+        headers: Record<string, string>;
+        /**
+         * A deadline for the REQUEST, and only where one belongs.
+         *
+         * The open is a preflight that `connect()` waits for, so it is bounded.
+         * The close must not be: a request timeout aborts the socket, which would
+         * cancel the very message it was waiting for and leave the session open —
+         * the caller's own deadline bounds the WAIT instead, elsewhere.
+         */
+        timeoutMs?: number;
+        /**
+         * Whether the cookies this answers with become the connection's.
+         *
+         * True for the open — its `SAP_SESSIONID` **is** the session. False for a
+         * close: a teardown's response must not feed the session identity, or the
+         * cookies it sets read as the session having been replaced under a
+         * connection that is on its way out.
+         */
+        adoptCookies?: boolean;
+    }): Promise<{
+        status: number;
+        headers: unknown;
+        data: unknown;
+    }>;
+}
+export declare abstract class SessionStrategy {
+    protected readonly logger: ILogger | null;
+    constructor(logger: ILogger | null);
+    /** A name for logs, so which one ran is never a guess. */
+    abstract readonly kind: 'cloud-security-session' | 'icf';
+    /**
+     * Ask the server to open a session, before anything needs one.
+     *
+     * Returns whether a session resource was actually opened and its address
+     * captured — `false` is not a failure, it is a system saying it has none, and
+     * the close then falls to the mechanism that needs no address. Never throws: a system that
+     * will not open one is a fact for the establishment that follows to report,
+     * with the whole picture, not a transport error raised from a preflight.
+     */
+    abstract openSession(transport: ISessionTransport): Promise<boolean>;
+    /**
+     * Tell the server we are done with the session.
+     *
+     * Never throws, and says nothing about what the server then did with it.
+     */
+    abstract closeSession(transport: ISessionTransport): Promise<void>;
+}
+//# sourceMappingURL=SessionStrategy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SessionStrategy.d.ts","sourceRoot":"","sources":["../../src/session/SessionStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,yEAAyE;IACzE,OAAO,IAAI,MAAM,GAAG,IAAI,CAAC;IACzB,oDAAoD;IACpD,SAAS,IAAI,MAAM,GAAG,IAAI,CAAC;IAC3B,kEAAkE;IAClE,IAAI,CAAC,OAAO,EAAE;QACZ,MAAM,EAAE,KAAK,GAAG,QAAQ,CAAC;QACzB,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC;;;;;;;WAOG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB;;;;;;;WAOG;QACH,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAClE;AAED,8BAAsB,eAAe;IACvB,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;gBAAtB,MAAM,EAAE,OAAO,GAAG,IAAI;IAErD,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,wBAAwB,GAAG,KAAK,CAAC;IAEzD;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,SAAS,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpE;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,SAAS,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CACnE"}

package/dist/session/SessionStrategy.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * How a session is opened on the server, and how the server is told we are
+ * done with it.
+ *
+ * Two systems, two mechanisms, one meaning. On ABAP Cloud a session is a
+ * resource: it is asked for at `/sap/bc/adt/core/http/sessions` and the
+ * response publishes its own address, which is what a `DELETE` is sent to. On
+ * on-prem there is no such resource — the logon call is the establishing
+ * request itself, and the platform's `/sap/public/bc/icf/logoff` is how it is
+ * given back.
+ *
+ * **Both are notifications, not commands.** They say "we have finished with
+ * this session". Whether the system frees it now, later, or keeps it to reuse
+ * is the system's business, and nothing here checks afterwards or depends on
+ * the answer. Measured on a trial: the `DELETE` is answered `200` and the
+ * session is still listed a moment later; the logoff is answered `200` and it
+ * is not. Neither is a failure — they are two systems deciding differently
+ * about a message they both accepted.
+ *
+ * Split by what the server publishes rather than by which system we think we
+ * are talking to: `openSession()` asks, and a system that has no such resource
+ * says so. Guessing the platform would be a guess; asking is not.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStrategy = void 0;
+class SessionStrategy {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+}
+exports.SessionStrategy = SessionStrategy;

package/dist/utils/cookies.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Join two `Cookie` header values, later wins on a repeated name.
+ *
+ * Used wherever a request already carries cookies and more are added: a
+ * credential can BE cookies — a SAML session is handed over as `MYSAPSSO2` —
+ * so writing the session jar over the header drops the very thing the request
+ * authenticates with. Both belong on the wire: one says who we are, the other
+ * which session we are in. A name in both is the session's, because that is the
+ * one the server just issued.
+ */
+export declare function mergeCookieHeaders(existing: string | undefined, incoming: string | undefined): string;
+//# sourceMappingURL=cookies.d.ts.map

package/dist/utils/cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/utils/cookies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,CASR"}

package/dist/utils/cookies.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeCookieHeaders = mergeCookieHeaders;
+/**
+ * Join two `Cookie` header values, later wins on a repeated name.
+ *
+ * Used wherever a request already carries cookies and more are added: a
+ * credential can BE cookies — a SAML session is handed over as `MYSAPSSO2` —
+ * so writing the session jar over the header drops the very thing the request
+ * authenticates with. Both belong on the wire: one says who we are, the other
+ * which session we are in. A name in both is the session's, because that is the
+ * one the server just issued.
+ */
+function mergeCookieHeaders(existing, incoming) {
+    const parts = [existing, incoming].filter(Boolean).join('; ');
+    const byName = new Map();
+    for (const part of parts.split(';')) {
+        const pair = part.trim();
+        if (!pair)
+            continue;
+        byName.set(pair.slice(0, pair.indexOf('=')), pair);
+    }
+    return [...byName.values()].join('; ');
+}

package/dist/utils/timeouts.d.ts

@@ -12,4 +12,20 @@ export declare function getTimeout(type?: 'default' | 'csrf' | 'long' | number):
  * permanently dead socket hanging forever.
  */
 export declare function getCriticalSectionTimeout(): number;
+/**
+ * How long `disconnect()` may spend telling the server the session is done.
+ *
+ * **Zero by default: after a disconnect nothing waits on the answer.** Waiting
+ * is for steps whose successor depends on the server having caught up — lock,
+ * update, unlock, activate, each needing the one before it to have landed.
+ * A teardown has no successor: the session is marked unneeded, the server
+ * reclaims it whenever it reclaims it, and a caller blocked on that round trip
+ * has bought nothing while holding up the serializing tail, where every later
+ * connect and disconnect queues behind it.
+ *
+ * The knob exists for a caller that wants a bounded wait anyway — a test
+ * asserting the logoff landed, a script that would rather see the failure —
+ * and is theirs to set per call via `ISessionLifecycleAware.disconnect`.
+ */
+export declare function getReleaseDeadline(): number;
 //# sourceMappingURL=timeouts.d.ts.map

package/dist/utils/timeouts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeouts.d.ts","sourceRoot":"","sources":["../../src/utils/timeouts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC;AAE3C,wBAAgB,gBAAgB,IAAI,cAAc,CAajD;AAED,wBAAgB,UAAU,CACxB,IAAI,GAAE,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAkB,GACrD,MAAM,CAOR;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD"}
+{"version":3,"file":"timeouts.d.ts","sourceRoot":"","sources":["../../src/utils/timeouts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC;AAE3C,wBAAgB,gBAAgB,IAAI,cAAc,CAajD;AAED,wBAAgB,UAAU,CACxB,IAAI,GAAE,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAkB,GACrD,MAAM,CAOR;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C"}

package/dist/utils/timeouts.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getTimeoutConfig = getTimeoutConfig;
 exports.getTimeout = getTimeout;
 exports.getCriticalSectionTimeout = getCriticalSectionTimeout;
+exports.getReleaseDeadline = getReleaseDeadline;
 function getTimeoutConfig() {
     const defaultTimeout = parseInt(process.env.SAP_TIMEOUT_DEFAULT || '45000', 10);
     const csrfTimeout = parseInt(process.env.SAP_TIMEOUT_CSRF || '15000', 10);
@@ -32,3 +33,21 @@ function getTimeout(type = 'default') {
 function getCriticalSectionTimeout() {
     return parseInt(process.env.SAP_TIMEOUT_CRITICAL || '600000', 10);
 }
+/**
+ * How long `disconnect()` may spend telling the server the session is done.
+ *
+ * **Zero by default: after a disconnect nothing waits on the answer.** Waiting
+ * is for steps whose successor depends on the server having caught up — lock,
+ * update, unlock, activate, each needing the one before it to have landed.
+ * A teardown has no successor: the session is marked unneeded, the server
+ * reclaims it whenever it reclaims it, and a caller blocked on that round trip
+ * has bought nothing while holding up the serializing tail, where every later
+ * connect and disconnect queues behind it.
+ *
+ * The knob exists for a caller that wants a bounded wait anyway — a test
+ * asserting the logoff landed, a script that would rather see the failure —
+ * and is theirs to set per call via `ISessionLifecycleAware.disconnect`.
+ */
+function getReleaseDeadline() {
+    return parseInt(process.env.SAP_RELEASE_DEADLINE_MS || '0', 10);
+}

package/docs/INSTALLATION.md

@@ -163,7 +163,9 @@ const logger = {
   debug: (msg) => console.log('[DEBUG]', msg),
 };
 
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: 'onprem', // or 'cloud' — said by you, never detected
+});
 
 connection.connect()
   .then(() =>
@@ -231,7 +233,9 @@ const logger: ILogger = {
   debug: (msg: string) => console.log(msg),
 };
 
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: 'onprem', // or 'cloud' — said by you, never detected
+});
 ```
 
 ## Troubleshooting

package/docs/MIGRATION-2.0.md

@@ -46,7 +46,7 @@ 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
+`disconnect()` stops 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.

package/docs/MIGRATION-5.0.md

@@ -0,0 +1,116 @@
+# Migrating to 5.0.0
+
+Two things changed, and the second is why the first was possible.
+
+**A connection now closes what it opened.** `disconnect()` tells the server the
+session is finished instead of only dropping the cookie, and `connect()` fails
+when the server opened no session rather than handing back a connection whose
+first lock would be dead.
+
+**The class you take says which system you are dialling, not which credential
+you hold.** `AdtOnPremConnector` and `AdtCloudConnector` are handed an auth
+provider; the five auth classes still work and are deprecated.
+
+---
+
+## If you use `createAbapConnection()`
+
+It still works, unchanged, and now warns once per call that the connection is
+being chosen from `authType`. Say which system instead:
+
+```ts
+// before
+const conn = createAbapConnection(config, logger, undefined, tokenRefresher);
+
+// after
+const conn = createAbapConnection(config, logger, undefined, tokenRefresher, {
+  system: 'cloud',   // or 'onprem'
+});
+```
+
+Nothing is detected. The two systems do not manage sessions the same way, and
+asking the server which it is does not work: `/sap/bc/adt/core/http/sessions`
+answers on on-prem too, and its `DELETE` there leaves the session open while the
+platform logoff removes it. Only you know where you are pointing.
+
+## If you build a connection class directly
+
+```ts
+// before                                    // after
+new BaseAbapConnection(cfg, log)             new AdtOnPremConnector(cfg, new BasicAuthProvider(user, pass), log)
+new JwtAbapConnection(cfg, log, id, refr)    new AdtCloudConnector(cfg, new TokenAuthProvider(refr), log)
+new SamlAbapConnection(cfg, log)             new AdtOnPremConnector(cfg, new SamlAuthProvider(cookies), log)
+new CertificateAbapConnection(cfg, log)      new AdtOnPremConnector(cfg, new CertificateAuthProvider(loader, cfg), log)
+```
+
+`KerberosAbapConnection` has no provider yet — its SPNEGO exchange *is* the CSRF
+fetch — so keep using the class. See #35.
+
+The old classes are not removed and not scheduled for removal here.
+
+## `reset()` is gone — BREAKING
+
+There is no local-only discard, because there is no local-only session: it lives
+on the server, and dropping the cookie leaves it there.
+
+```ts
+conn.reset();                 // before
+await conn.disconnect();      // after — and connect() again to carry on
+```
+
+A caller that does not want to wait simply does not `await` it, which is what
+`reset()` was mostly used for. `RfcAbapConnection` keeps `close()`.
+
+## `connect()` can now fail where it used to warn — BREAKING
+
+When the server authenticates the request but opens no session, `connect()`
+rejects with `ADT_NOT_CONNECTED` and a message saying what happened, what still
+works, and the usual cause. It used to log a warning and hand the connection
+back — and the failure then surfaced a request later, as `400 Session not found`
+with the object half-edited.
+
+Verified rather than assumed: a connection that received no `SAP_SESSIONID` is
+listed in the server's own session list as **nothing at all**.
+
+Nothing is retried on your behalf. Whether to wait, retry, or release sessions
+the user still holds depends on things only you know.
+
+## `disconnect()` now makes a network call
+
+It tells the server the session is finished. Two consequences:
+
+- **It can wait.** By default it does not: `SAP_RELEASE_DEADLINE_MS` is `0`,
+  because waiting is for steps whose successor needs the server to have caught
+  up, and a teardown has none. Pass `disconnect({ deadlineMs })` if you want a
+  bounded wait — the deadline bounds the **wait**, never the request.
+- **Requests still in flight will start failing.** The session they are running
+  on is the one being released. That is you having asked to disconnect, not a
+  race — finish or abandon your chains first.
+
+It still never throws, including on a nonsense `deadlineMs`: its place is a
+`finally`, where an exception would replace the error that sent you there.
+
+## Token renewal, if you use a provider
+
+Nothing to do, but worth knowing what changed. The connector no longer caches
+the token it was given. It asks the provider per request — cheap, because the
+provider caches — and on a `401` it tells the provider its answer was refused
+(`refreshToken()`, per that contract), asks again, and only if the answer
+changed rebuilds the session and retries once. An unchanged answer means the
+server refused those credentials, and the `401` reaches you.
+
+So a password does the right thing with no configuration, and a bearer token is
+renewed without a class of its own.
+
+## Sessions are a shared, per-user resource
+
+Not an API change, a fact worth having. The limit is per user and the pool is
+shared with everything else logged on as them, a SAP GUI session included. The
+timeout is **idle-based**: a connection that keeps working keeps its session,
+one that goes quiet past the window loses it. There is no keepalive timer here,
+deliberately — how long to hold a session is yours to decide.
+
+And the shape of the problem this release addresses, seen from the other end: a
+process that opens a connection per check and never disconnects filled a
+system's session list at one session every ten seconds. Releasing what you open
+is half of it; opening one connection instead of one per check is the other.

package/docs/STATEFUL_SESSION_GUIDE.md

@@ -29,7 +29,9 @@ The connection layer **does not** decide when to lock/unlock objects—that logi
 ```ts
 import { createAbapConnection } from '@mcp-abap-adt/connection';
 
-const connection = createAbapConnection(config, logger);
+const connection = createAbapConnection(config, logger, undefined, undefined, {
+  system: 'onprem', // or 'cloud' — said by you, never detected
+});
 await connection.connect();   // required before any request
 
 // Enable stateful session mode (adds x-sap-adt-sessiontype: stateful header)
@@ -47,11 +49,11 @@ connection.setSessionType('stateless');
 ## Knowing Which Session You Are In
 
 ```ts
-import { BaseAbapConnection } from '@mcp-abap-adt/connection';
+import { AdtOnPremConnector, BasicAuthProvider } from '@mcp-abap-adt/connection';
 
 // getSessionIdentity() is on the HTTP connection classes, NOT on the
 // IAbapConnection type that createAbapConnection() returns.
-const connection = new BaseAbapConnection(config, logger);
+const connection = new AdtOnPremConnector(config, new BasicAuthProvider(user, pass), logger);
 await connection.connect();
 
 // Which SAP session this connection is talking to. Changes only when the
@@ -102,19 +104,83 @@ answer, not a credential one, and nothing is torn down for it.
 
 ---
 
+## What This Layer Actually Solves
+
+The link to the ABAP session is not guaranteed, and that is the whole problem:
+
+- the ABAP session can be terminated by the system while this client still
+  believes it has one — the next lock-bound request answers
+  `400 "Session not found"`;
+- or it is never created at all, because the system will not open another one
+  for this user right now.
+
+Both are reported, neither is worked around. `connect()` fails with the reason
+when no session was opened; a session lost afterwards surfaces as
+`ADT_SESSION_REPLACED` rather than a request quietly continuing somewhere it
+does not belong. What to do about either — wait, retry, reconnect, release
+sessions the user still holds, carry on read-only — is the caller's decision,
+made with the cookies and the answers in hand.
+
+## A Lock Lives In The ABAP Session
+
+There are two sessions here, and they are not the same thing:
+
+- the **HTTP session** — the conversation this client is having. It exists as
+  long as the cookies do, and nothing about it is in doubt;
+- the **ABAP session** — named by `SAP_SESSIONID_<SID>_<CLIENT>`, and the thing
+  locks are bound to.
+
+The doubt is only ever about the second. It may not have been created, or it may
+have been terminated while this client still holds the cookies and believes it
+has one — and a lock is dead in either case, whether or not the client noticed.
+
+Two ways to lose one, and they are different problems:
+
+- **The server never opened one.** No `SAP_SESSIONID` came back, so there is no
+  ABAP session known to this connection and nothing a lock could be bound to —
+  while the HTTP side is perfectly fine, which is why it does not look like a
+  failure at all. `connect()` refuses rather than handing back a connection
+  whose first lock would be dead on arrival. Sessions are limited per user and shared with every other tool
+  logged on as them, so this says nothing about your code — it says the system
+  would not open another one right now.
+- **It timed out while you were quiet.** The timeout is an idle one, and it is
+  the *silence* that spends it, not the elapsed time. Measured on an on-prem
+  system with a 30-minute window: a small request once a minute kept one session
+  alive for 45 minutes with its identity unchanged, straight past the mark.
+
+So a long chain under a lock is safe while it is doing something, and at risk
+while it waits. **Any request in the session resets the window** — a poll, a
+read, a status check. There is deliberately no keepalive timer in this package:
+holding a session alive means holding a scarce, shared slot, and deciding to do
+that belongs to the caller who knows why the session is worth keeping.
+
+**The cookies are the session.** Nothing else ties a caller to one, so a second
+connection given the same cookie jar works in the same ABAP session and can use
+the locks taken in it — that is what makes handing them over a way to continue
+someone else's work. It cuts both ways: `disconnect()` ends the session for
+everyone holding those cookies, not just for the object it was called on, and no
+connection can see the copies. Deciding who may hold them, and who is allowed to
+close, belongs to whoever passes them around.
+
+The server never tells the client how long it has: the session cookie carries no
+expiry and no response header mentions one. The only honest signals are the ones
+you get by asking — `getSessionIdentity()` for which session you are in, and
+`ADT_SESSION_REPLACED` when the one you were in is gone.
+
 ## Troubleshooting
 
-- **CSRF token errors**: discard the session and establish a new one. `reset()`
-  does that, but it lives on the HTTP connection classes and is **not** on the
-  `IAbapConnection` type `createAbapConnection()` returns — reach it through a
-  concrete type:
+- **CSRF token errors**: discard the session and establish a new one. That is
+  `disconnect()` followed by `connect()` — there is no local-only discard, because
+  dropping the cookie leaves the ABAP session open on the server. Both live on
+  the HTTP connection classes and are **not** on the `IAbapConnection` type
+  `createAbapConnection()` returns — reach them through a concrete type:
 
   ```ts
-  import { BaseAbapConnection } from '@mcp-abap-adt/connection';
+  import { AdtOnPremConnector, BasicAuthProvider } from '@mcp-abap-adt/connection';
 
-  const connection = new BaseAbapConnection(config, logger);
-  connection.reset();          // queues the cleanup; refuses requests meanwhile
-  await connection.connect();  // a new session, explicitly
+  const connection = new AdtOnPremConnector(config, new BasicAuthProvider(user, pass), logger);
+  await connection.disconnect(); // ends the session on the server, then clears
+  await connection.connect(); // a new session, explicitly
   ```
 - **Session expired**: reauthenticate to obtain a new session.
 - **Multiple connections**: each `createAbapConnection` instance maintains its own cookie jar; share the instance if you need continuity.