@geodedb/client 1.1.0 → 1.3.1

package/dist/index.d.ts

@@ -74,7 +74,17 @@ interface GeodeConfig {
     keepAliveInterval?: number;
     /** Maximum idle time in milliseconds (default: 30000) */
     maxIdleTime?: number;
-    /** Inline receive timeout in milliseconds (default: 5000) */
+    /**
+     * How long to wait for the data page the server sends inline after SCHEMA
+     * before falling back to an explicit PULL, in milliseconds (default: 5000).
+     * DSN key: `inline_timeout`.
+     *
+     * The inline response is never discarded when this deadline passes: the
+     * client keeps track of it and reconciles it with the PULL answer, so a slow
+     * first page can never leak into the next query (ENG-3916). Lower it only to
+     * make the client fall back to PULL sooner; `requestTimeout` still bounds
+     * the whole exchange.
+     */
     inlineTimeout?: number;
     /** Enable TLS for gRPC (default: true) */
     tls?: boolean;
@@ -311,6 +321,12 @@ declare const ERR_NO_ROWS_MESSAGE = "geode: no rows in result set";
 declare function ErrInvalidIdent(): Error;
 declare function ErrInvalidString(): Error;
 declare function ErrClosed(): Error;
+/**
+ * @deprecated No longer thrown by `Connection`. Concurrent requests on one
+ * connection are serialized on the connection's exchange lock instead of
+ * failing fast (ENG-3916). Kept exported so existing identity checks still
+ * compile.
+ */
 declare function ErrQueryInProgress(): Error;
 declare function ErrTxInProgress(): Error;
 declare function ErrNoTx(): Error;
@@ -451,7 +467,7 @@ interface Param {
 }
 declare const Param: MessageFns<Param>;
 interface PullRequest {
-    requestId: number;
+    requestId: bigint;
     pageSize: number;
     /** Required for gRPC; ignored for QUIC */
     sessionId: string;
@@ -530,7 +546,7 @@ interface NullValue {
 }
 declare const NullValue: MessageFns<NullValue>;
 interface IntValue {
-    value: number;
+    value: bigint;
     kind: IntKind;
 }
 declare const IntValue: MessageFns<IntValue>;
@@ -571,15 +587,15 @@ interface MapValue {
 }
 declare const MapValue: MessageFns<MapValue>;
 interface NodeValue {
-    id: number;
+    id: bigint;
     labels: string[];
     properties: MapEntry[];
 }
 declare const NodeValue: MessageFns<NodeValue>;
 interface EdgeValue {
-    id: number;
-    fromId: number;
-    toId: number;
+    id: bigint;
+    fromId: bigint;
+    toId: bigint;
     label: string;
     properties: MapEntry[];
 }
@@ -593,7 +609,7 @@ interface ExtendedValue {
     typeName: string;
     text?: string | undefined;
     bytes?: Uint8Array | undefined;
-    intVal?: number | undefined;
+    intVal?: bigint | undefined;
     doubleVal?: number | undefined;
     boolVal?: boolean | undefined;
 }
@@ -607,28 +623,28 @@ interface Error$1 {
 }
 declare const Error$1: MessageFns<Error$1>;
 interface ExecutionMetrics {
-    parseDurationNs: number;
-    planDurationNs: number;
-    executeDurationNs: number;
-    totalDurationNs: number;
+    parseDurationNs: bigint;
+    planDurationNs: bigint;
+    executeDurationNs: bigint;
+    totalDurationNs: bigint;
 }
 declare const ExecutionMetrics: MessageFns<ExecutionMetrics>;
 interface ExplainOp {
     idx: number;
     kind: string;
-    estRows: number;
-    cost: number;
+    estRows: bigint;
+    cost: bigint;
 }
 declare const ExplainOp: MessageFns<ExplainOp>;
 interface ExplainTotals {
-    estRows: number;
-    cost: number;
+    estRows: bigint;
+    cost: bigint;
 }
 declare const ExplainTotals: MessageFns<ExplainTotals>;
 interface ExplainProperties {
     ordered: boolean;
-    limit: number;
-    offset: number;
+    limit: bigint;
+    offset: bigint;
     distinct: boolean;
     unionMode: string;
     unionPartCount: number;
@@ -659,53 +675,53 @@ interface ProfileOp {
     phase: string;
     id: number;
     opIndex: number;
-    inputRows: number;
-    rows: number;
-    timeNs: number;
-    cpuTimeNs: number;
-    bytesOut: number;
-    bytesAlloc: number;
-    estimateBytes: number;
-    estimateVsActual: number;
-    percentPeak: number;
-    percentNet: number;
-    cumulativeTimeNs: number;
-    freedBytes: number;
-    netAfterOp: number;
-    errorBytes: number;
-    errorAbsPct: number;
+    inputRows: bigint;
+    rows: bigint;
+    timeNs: bigint;
+    cpuTimeNs: bigint;
+    bytesOut: bigint;
+    bytesAlloc: bigint;
+    estimateBytes: bigint;
+    estimateVsActual: bigint;
+    percentPeak: bigint;
+    percentNet: bigint;
+    cumulativeTimeNs: bigint;
+    freedBytes: bigint;
+    netAfterOp: bigint;
+    errorBytes: bigint;
+    errorAbsPct: bigint;
     indexName: string;
     selectivityEst: number;
 }
 declare const ProfileOp: MessageFns<ProfileOp>;
 interface ProfilePeakContributor {
     op: string;
-    bytesAlloc: number;
+    bytesAlloc: bigint;
 }
 declare const ProfilePeakContributor: MessageFns<ProfilePeakContributor>;
 interface ProfileTotals {
-    timeNs: number;
-    peakBytes: number;
+    timeNs: bigint;
+    peakBytes: bigint;
 }
 declare const ProfileTotals: MessageFns<ProfileTotals>;
 interface ProfileSpills {
-    sortSpills: number;
-    distinctSpills: number;
-    unionSpills: number;
+    sortSpills: bigint;
+    distinctSpills: bigint;
+    unionSpills: bigint;
     spillReason: string;
-    peakBytesAtSpill: number;
+    peakBytesAtSpill: bigint;
     firstSpillOpIndex: number;
 }
 declare const ProfileSpills: MessageFns<ProfileSpills>;
 interface ProfileMemory {
-    netBytes: number;
-    peakBytes: number;
-    totalAllocBytes: number;
+    netBytes: bigint;
+    peakBytes: bigint;
+    totalAllocBytes: bigint;
 }
 declare const ProfileMemory: MessageFns<ProfileMemory>;
 interface ProfilePlannerEstimates {
-    sumEstimateBytes: number;
-    sumActualBytes: number;
+    sumEstimateBytes: bigint;
+    sumActualBytes: bigint;
     countEstimatedOps: number;
     minErrorAbsPct: number;
     maxErrorAbsPct: number;
@@ -717,16 +733,16 @@ interface ProfilePlannerEstimates {
 declare const ProfilePlannerEstimates: MessageFns<ProfilePlannerEstimates>;
 interface ProfileMemCurvePoint {
     opIndex: number;
-    netAfterOp: number;
+    netAfterOp: bigint;
 }
 declare const ProfileMemCurvePoint: MessageFns<ProfileMemCurvePoint>;
 interface ProfileSetOp {
     type: string;
     mode: string;
-    inputRows: number;
-    outputRows: number;
-    hashDedupSize: number;
-    distinctFillPct: number;
+    inputRows: bigint;
+    outputRows: bigint;
+    hashDedupSize: bigint;
+    distinctFillPct: bigint;
 }
 declare const ProfileSetOp: MessageFns<ProfileSetOp>;
 interface ProfilePayload {
@@ -734,17 +750,17 @@ interface ProfilePayload {
     ops: ProfileOp[];
     peakContributors: ProfilePeakContributor[];
     totals?: ProfileTotals | undefined;
-    totalTimeNs: number;
+    totalTimeNs: bigint;
     spills?: ProfileSpills | undefined;
     memory?: ProfileMemory | undefined;
     plannerEstimates?: ProfilePlannerEstimates | undefined;
     memCurve: ProfileMemCurvePoint[];
     setop?: ProfileSetOp | undefined;
-    hashaggSpills: number;
+    hashaggSpills: bigint;
     hashaggSpillReason: string;
-    committedTxns: number;
-    graphStoreNodes: number;
-    graphStoreEdges: number;
+    committedTxns: bigint;
+    graphStoreNodes: bigint;
+    graphStoreEdges: bigint;
     graphStoreDirty: boolean;
     flaggerFindings: string[];
     compact: boolean;
@@ -825,67 +841,69 @@ declare const RollbackToResponse: MessageFns<RollbackToResponse>;
  * ============================================================================
  */
 interface CdcDiagnosticsRequest {
+    sessionId: string;
 }
 declare const CdcDiagnosticsRequest: MessageFns<CdcDiagnosticsRequest>;
 interface CdcDiagnosticsConfig {
     enabled: boolean;
-    malformedSnapshotInterval: number;
+    malformedSnapshotInterval: bigint;
     malformedHashRetain: number;
     malformedWarnPct: number;
     malformedAbortPct: number;
     flushIntervalMs: number;
     batchSize: number;
-    pendingBackpressureWatermark: number;
+    pendingBackpressureWatermark: bigint;
 }
 declare const CdcDiagnosticsConfig: MessageFns<CdcDiagnosticsConfig>;
 interface CdcDiagnosticsEngine {
     isRunning: boolean;
-    lastFlushMs: number;
-    peakBuffer: number;
-    currentBuffer: number;
+    lastFlushMs: bigint;
+    peakBuffer: bigint;
+    currentBuffer: bigint;
     dynamicBatchSize: number;
     batchAdjustments: number;
 }
 declare const CdcDiagnosticsEngine: MessageFns<CdcDiagnosticsEngine>;
 interface CdcMalformedSnapshot {
-    count: number;
-    tsMs: number;
+    count: bigint;
+    tsMs: bigint;
 }
 declare const CdcMalformedSnapshot: MessageFns<CdcMalformedSnapshot>;
 interface CdcMalformedHash {
-    count: number;
-    hash: number;
-    tsMs: number;
+    count: bigint;
+    hash: bigint;
+    tsMs: bigint;
     prefixHex: string;
 }
 declare const CdcMalformedHash: MessageFns<CdcMalformedHash>;
 interface CdcDiagnosticsResponse {
-    malformedChangeRecords: number;
-    totalChangeAttempts: number;
+    malformedChangeRecords: bigint;
+    totalChangeAttempts: bigint;
     malformedRatio: number;
     guardrailWarnTriggered: boolean;
     guardrailAbortTriggered: boolean;
-    firstWarnTsMs: number;
-    firstAbortTsMs: number;
-    guardrailEpoch: number;
-    uptimeMs: number;
+    firstWarnTsMs: bigint;
+    firstAbortTsMs: bigint;
+    guardrailEpoch: bigint;
+    uptimeMs: bigint;
     backpressure: boolean;
     config?: CdcDiagnosticsConfig | undefined;
     engine?: CdcDiagnosticsEngine | undefined;
     malformedSnapshots: CdcMalformedSnapshot[];
     malformedHashes: CdcMalformedHash[];
     version: string;
-    timestampMs: number;
+    timestampMs: bigint;
 }
 declare const CdcDiagnosticsResponse: MessageFns<CdcDiagnosticsResponse>;
 interface CdcControlRequest {
     action: string;
+    sessionId: string;
 }
 declare const CdcControlRequest: MessageFns<CdcControlRequest>;
 interface CdcControlResponse {
     success: boolean;
     status: string;
-    guardrailEpoch: number;
+    guardrailEpoch: bigint;
 }
 declare const CdcControlResponse: MessageFns<CdcControlResponse>;
 /**
@@ -905,7 +923,7 @@ interface BackupResponse {
     message: string;
     backupId: string;
     backupType: string;
-    sizeBytes: number;
+    sizeBytes: bigint;
     compression: string;
     checksum: string;
 }
@@ -921,11 +939,11 @@ interface RestoreResponse {
     message: string;
     restoreDir: string;
     targetTime: string;
-    restoreTimestamp: number;
+    restoreTimestamp: bigint;
 }
 declare const RestoreResponse: MessageFns<RestoreResponse>;
 interface UploadBackupRequest {
-    sizeBytes: number;
+    sizeBytes: bigint;
     checksum: string;
     sessionId: string;
     /**
@@ -941,7 +959,7 @@ interface UploadBackupResponse {
     uploadPath: string;
 }
 declare const UploadBackupResponse: MessageFns<UploadBackupResponse>;
-type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+type Builtin = Date | Function | Uint8Array | string | number | boolean | bigint | undefined;
 type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
     [K in keyof T]?: DeepPartial<T[K]>;
 } : Partial<T>;
@@ -1029,7 +1047,7 @@ declare function buildExecuteRequest(sessionId: string, query: string, params?:
 /**
  * Build a PullRequest message.
  */
-declare function buildPullRequest(requestId: number, pageSize: number, sessionId: string): QuicClientMessage;
+declare function buildPullRequest(requestId: number | bigint, pageSize: number, sessionId: string): QuicClientMessage;
 /**
  * Build a PingRequest message.
  */
@@ -1120,6 +1138,25 @@ declare class QuicTransport extends BaseTransport {
     private _maxBufferBytes;
     private _pendingProtoReads;
     private _pendingResponses;
+    /**
+     * Decode failure that arrived while no reader was parked. Surfaced by the
+     * next receiveProto() once the already-decoded backlog has been drained.
+     */
+    private _pendingDecodeError;
+    /**
+     * Sticky failure latched when the read pump ends or throws. The pump is the
+     * ONLY producer of responses, so once it is gone nothing can ever settle a
+     * parked reader: report the failure instead of hanging (ENG-3918).
+     */
+    private _readFailure;
+    /** True once close() has released the QUIC client and buffers. */
+    private _disposed;
+    /**
+     * Serializes writes to the single bidirectional stream. `getWriter()` throws
+     * "WritableStream is locked" while another write holds the lock, so queued
+     * exchanges must take turns (ENG-3916).
+     */
+    private _writeChain;
     constructor(address: string, maxMessageSize?: number, maxBufferBytes?: number);
     /**
      * Connect to the Geode server using QUIC.
@@ -1129,6 +1166,15 @@ declare class QuicTransport extends BaseTransport {
      * Start reading from the stream in the background.
      */
     private startReading;
+    /**
+     * Latch the transport dead after the read pump ends or throws.
+     *
+     * Nothing can produce a response once the pump is gone, so leaving
+     * `isClosed()` false makes the connection (and the pool, whose only liveness
+     * predicate is that flag) believe a dead socket is healthy, and parks every
+     * later reader on a producer that will never run again (ENG-3918).
+     */
+    private failFromReadPump;
     /**
      * Reject all pending reads with an error.
      */
@@ -1409,6 +1455,10 @@ declare class QueryResult implements AsyncIterable<Row> {
     private _closed;
     private _bufferIndex;
     private _rowCount;
+    /** Settles once the connection is back in phase after this result closed. */
+    private _drained;
+    /** Owner hook (used by the pool to hold its member for the result's life). */
+    private _onCloseHooks;
     constructor(conn: Connection, columns: ColumnInfo[], initialRows: Record<string, unknown>[], final: boolean, ordered: boolean, orderKeys: string[], pageSize: number, signal?: AbortSignal);
     /**
      * Get column definitions.
@@ -1481,8 +1531,27 @@ declare class QueryResult implements AsyncIterable<Row> {
     reduce<T>(fn: (acc: T, row: Row, index: number) => T | Promise<T>, initial: T): Promise<T>;
     /**
      * Close the result set.
+     *
+     * When the server still owes pages, closing hands the connection the job of
+     * draining them; use {@link QueryResult._settle} (or simply iterate to the
+     * end) to await that. A caller that walks away never observes a connection
+     * that is silently out of phase (ENG-3916).
      */
     close(): void;
+    /**
+     * @internal Whether the result still needs the connection.
+     *
+     * False once every page is buffered client-side: the connection is then free
+     * and its pool member can be released immediately.
+     */
+    get _needsConnection(): boolean;
+    /**
+     * @internal Register a callback fired exactly once when this result closes.
+     * Fires immediately when the result is already closed.
+     */
+    _onClose(hook: () => void): void;
+    /** Close the result and wait for the connection to be back in phase. */
+    private _settle;
     /**
      * Internal close (called by connection).
      */
@@ -1967,11 +2036,11 @@ declare function batchMap(conn: Connection, queryTemplate: string, items: QueryP
  * Unlike the sequential batch(), this executes multiple queries concurrently
  * up to the specified limit.
  *
- * **Important:** A single `Connection` can only execute one query at a time
- * (the connection state machine throws `ErrQueryInProgress` for concurrent
- * queries). When a single connection is provided with concurrency > 1, this
- * function automatically falls back to sequential execution (concurrency=1)
- * to prevent runtime errors.
+ * **Important:** A single `Connection` owns one bidirectional stream and can
+ * only execute one query at a time; concurrent requests queue on its exchange
+ * lock rather than overlapping (ENG-3916). When a single connection is
+ * provided with concurrency > 1, this function falls back to sequential
+ * execution (concurrency=1) because the extra concurrency buys nothing.
  *
  * For true parallel execution, use a connection pool or connection factory
  * that provides separate connections per concurrent query.
@@ -2021,6 +2090,21 @@ declare class Connection {
     private _requestId;
     private _sessionId;
     private _columns;
+    private _delivery;
+    /**
+     * FIFO exchange lock.
+     *
+     * The connection owns ONE bidirectional stream and the wire protocol carries
+     * no request/response correlation id, so two overlapping exchanges would read
+     * each other's answers. Callers therefore queue instead of racing: an
+     * exchange holds the lock for its FULL request -> final-response round trip,
+     * and a streaming QueryResult keeps holding it until it is closed or drained
+     * (ENG-3916).
+     */
+    private _exchangeHeld;
+    private _exchangeWaiters;
+    /** Lock release handed to the active streaming result, if any. */
+    private _activeRelease;
     private constructor();
     /**
      * Create a new connection to the Geode server.
@@ -2040,6 +2124,16 @@ declare class Connection {
     get isClosed(): boolean;
     /** Get session ID. */
     get sessionId(): string;
+    /**
+     * Take the exchange lock, returning its (idempotent) release function.
+     *
+     * Registration is synchronous, so waiters are served strictly in call order.
+     */
+    private acquireExchange;
+    /** Run one complete exchange under the connection's exchange lock. */
+    private withExchange;
+    /** Wake every queued exchange so it can observe the closed state. */
+    private drainExchangeWaiters;
     /** Perform the HELLO handshake. */
     private hello;
     /** Execute a query that returns rows. */
@@ -2058,20 +2152,78 @@ declare class Connection {
         rows: Record<string, unknown>[];
         final: boolean;
     }>;
-    /** Try to receive an inline response with short timeout. */
+    /**
+     * Read the next page off the stream.
+     *
+     * Accepts either envelope: the server pushes pages as `execute` responses and
+     * wraps a PULL's answer in `pull`. Anything else means the stream is out of
+     * phase with the request being served, so the connection fails closed instead
+     * of silently swallowing the message.
+     */
+    private _readNextPage;
+    /**
+     * Wait for the response the server sends after SCHEMA.
+     *
+     * Returns `null` when the inline deadline (`inlineTimeout`) expires. That
+     * response is then STILL in flight - the caller must reconcile it before
+     * returning, because the transport is a FIFO stream without request/response
+     * correlation and anything left behind is read by the next request
+     * (ENG-3916).
+     */
     private _tryReceiveInline;
-    /** Read inline execute responses until a page, error, heartbeat, or timeout arrives. */
+    /** Read inline execute responses until a page, error, heartbeat, or the inline deadline. */
     private _readInlineExecute;
-    /** Drain remaining data pages until final=true to prevent query corruption (QUAL-T7). */
+    /**
+     * Send a PULL and consume responses until every outstanding response has
+     * been accounted for.
+     *
+     * The wire protocol is a FIFO stream with no request/response correlation
+     * id, so the client must reconcile the whole exchange before it returns:
+     * a response left in the transport is read by the NEXT request, which then
+     * sees this query's schema and rows (ENG-3916). Up to two responses can be
+     * outstanding here:
+     *
+     *  - the inline page the server sends after SCHEMA, when the inline read
+     *    gave up waiting for it (`inlinePending`), and
+     *  - the answer to the PULL sent below, which QUIC servers always send as a
+     *    `pull`-wrapped message.
+     *
+     * Because the server writes its responses in order, a `pull`-wrapped answer
+     * also proves that nothing is still coming for the EXECUTE, which is what
+     * makes the reconciliation exact.
+     *
+     * When the exchange cannot be reconciled - a timeout, an abort or a
+     * transport failure while a response is still owed - the connection is
+     * closed instead of returned to the caller (and to the pool).
+     *
+     * NOTE (server team, ENG-3916): the durable fix is a request/response
+     * correlation id in the proto. Until the wire protocol carries one, the
+     * client can only reconcile by message type plus stream ordering.
+     */
+    private _pullFirstPage;
+    /**
+     * Drain remaining data pages until final=true to prevent query corruption
+     * (QUAL-T7). Honours the current delivery mode: pushed pages are read,
+     * parked results are pulled one page at a time.
+     */
     private _drainRemainingPages;
-    /** @internal Release the active result, returning the connection to idle. */
-    _releaseResult(result: QueryResult): void;
+    /**
+     * @internal Release the active result, returning the connection to idle.
+     *
+     * A result abandoned before `final = true` leaves pages the server still owes
+     * on the stream. They are drained here - under the exchange lock the result
+     * still holds - so the next caller cannot read them as its own (ENG-3916).
+     * The returned promise settles once the connection is back in phase.
+     */
+    _releaseResult(result: QueryResult, final: boolean): Promise<void>;
     /** Begin a transaction. */
     begin(signal?: AbortSignal): Promise<Transaction>;
     /** @internal Commit the current transaction. Called by Transaction. */
     _commit(signal?: AbortSignal): Promise<void>;
     /** @internal Rollback the current transaction. Called by Transaction. */
     _rollback(signal?: AbortSignal): Promise<void>;
+    /** Send ROLLBACK and consume its answer. The exchange lock must be held. */
+    private _rollbackExchange;
     /** @internal Create a named savepoint. Called by Transaction. */
     _savepoint(name: string, signal?: AbortSignal): Promise<void>;
     /** @internal Rollback to a previously created savepoint. Called by Transaction. */
@@ -2082,6 +2234,8 @@ declare class Connection {
     reset(signal?: AbortSignal): Promise<void>;
     /** Close the connection. */
     close(): Promise<void>;
+    /** Drop the active result and hand its exchange lock back. */
+    private _abandonActiveResult;
     /** Create a prepared statement. */
     prepare(query: string): Promise<PreparedStatement>;
     /** Get the query execution plan without executing. */
@@ -2090,7 +2244,12 @@ declare class Connection {
     profile(query: string, options?: ExplainOptions): Promise<QueryProfile>;
     /** Execute multiple queries in a batch. */
     batch(queries: BatchQuery[], options?: BatchOptions): Promise<BatchSummary>;
-    /** Check connection state before operation. */
+    /**
+     * Check connection state before operation.
+     *
+     * Concurrent requests are NOT rejected any more: they queue on the exchange
+     * lock (ENG-3916). Only genuinely illegal states fail fast here.
+     */
     private checkState;
     /** Send a protobuf message with request timeout enforcement. */
     private _sendWithTimeout;
@@ -2098,7 +2257,38 @@ declare class Connection {
     private _receiveWithTimeout;
     /** Create a combined abort signal from requestTimeout and optional caller signal (CWE-703). */
     private _withRequestTimeout;
+    /**
+     * Tear the connection down after a transport failure.
+     *
+     * `responseOwed` marks the cases where the server may still answer: a request
+     * deadline that elapsed, or any aborted receive. Those leave the stream out
+     * of phase, so the connection must not be reused (or returned to the pool)
+     * even though the underlying socket is still open (ENG-3918).
+     */
     private _closeOnTransportError;
+    /**
+     * Whether the server answers every PULL with its own message.
+     *
+     * QUIC servers reply to a PULL with a `pull`-wrapped response, so that
+     * response has to be consumed before the connection is back in phase. The
+     * gRPC transport has no PULL RPC: it serves PULLs from the Execute stream
+     * that is already open, so no extra message is produced.
+     */
+    private get _pullIsAcknowledged();
+    /**
+     * Tear the connection down after a protocol desync and build the error.
+     *
+     * The stream carries no correlation ids, so a message that cannot belong to
+     * the request being served means client and server are out of phase: every
+     * later response would answer an earlier request, silently handing one
+     * caller another caller's rows. Failing closed makes the connection
+     * unusable, and the pool drops closed connections instead of reusing them.
+     */
+    private _protocolDesync;
+    /** Close the transport and drop any active result, ignoring teardown errors. */
+    private _forceClose;
+    /** Return to the resting state, unless the connection was torn down. */
+    private _restoreIdleState;
 }
 
 /**
@@ -2678,6 +2868,11 @@ declare class ConnectionPool {
     withConnection<T>(fn: (conn: Connection) => Promise<T>, signal?: AbortSignal): Promise<T>;
     /**
      * Execute a query using a pooled connection.
+     *
+     * A streaming result keeps fetching pages from the connection it was created
+     * on, so the pooled member stays checked out until the result is closed
+     * (ENG-3916). A result whose rows are already buffered needs nothing further
+     * from the connection and releases the member right away.
      */
     query(query: string, options?: QueryOptions): Promise<QueryResult>;
     /**
@@ -2709,6 +2904,17 @@ declare class ConnectionPool {
      * Add a new connection to the pool with rate limiting and exponential backoff.
      */
     private addConnection;
+    /**
+     * Drop every idle member whose connection is no longer usable.
+     *
+     * `Connection.isClosed` is the pool's only liveness predicate, and a
+     * connection torn down after a desync reports closed: leaving those members
+     * in place both risks reuse and starves the pool of its maxConnections slots
+     * until the next maintenance tick (ENG-3918).
+     */
+    private evictBrokenConnections;
+    /** Close a discarded connection, ignoring teardown failures. */
+    private closeQuietly;
     /**
      * Remove a connection from the pool.
      */