chore(spanner): add a channel pool prototype

handwritten/spanner/src/channel-pool/affinity.ts

@@ -0,0 +1,49 @@
+/*!
+ * Copyright 2026 Google LLC. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {ChannelEntry} from './types';
+
+/**
+ * Kind of affinity required by an operation.
+ */
+export enum AffinityKind {
+  /** Multi-statement Read/Write transactions require hard stickiness. */
+  ReadWrite = 0,
+  /** Read-Only transactions prefer soft stickiness for warmth. */
+  ReadOnly = 1,
+}
+
+/**
+ * Caller-owned handle managing channel affinity across multi-statement transactions.
+ */
+export class TransactionAffinity {
+  pinnedEntry: ChannelEntry | null = null;
+
+  constructor(readonly kind: AffinityKind = AffinityKind.ReadWrite) {}
+
+  /**
+   * Resets affinity upon transaction commit, rollback, or close.
+   */
+  reset(): void {
+    if (this.pinnedEntry && this.kind === AffinityKind.ReadWrite) {
+      this.pinnedEntry.activeRwTransactions = Math.max(
+        0,
+        this.pinnedEntry.activeRwTransactions - 1,
+      );
+    }
+    this.pinnedEntry = null;
+  }
+}

handwritten/spanner/src/channel-pool/channel-adapter.ts

@@ -0,0 +1,103 @@
+/*!
+ * Copyright 2026 Google LLC. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as grpc from '@grpc/grpc-js';
+import {ChannelPool} from './types';
+
+/**
+ * Adapter that presents a ChannelPool as a grpc.Channel to the gRPC client runtime.
+ */
+export class ChannelPoolChannelAdapter implements grpc.ChannelInterface {
+  constructor(readonly pool: ChannelPool) {}
+
+  close(): void {
+    // No-op: the underlying ChannelPool lifecycle is managed by its owner
+    // (e.g. Spanner or caller), not by individual client stubs using this adapter.
+  }
+
+  getTarget(): string {
+    return this.pool.getTarget();
+  }
+
+  getConnectivityState(tryToConnect?: boolean): grpc.connectivityState {
+    return this.pool.getConnectivityState(tryToConnect);
+  }
+
+  watchConnectivityState(
+    currentState: grpc.connectivityState,
+    deadline: Date | number,
+    callback: (error?: Error) => void,
+  ): void {
+    this.pool.watchConnectivityState(currentState, deadline, callback);
+  }
+
+  getChannelzRef(): any {
+    return null;
+  }
+
+  get channelRefs(): Array<{channel: grpc.Channel}> {
+    if ('entries' in (this.pool as any)) {
+      return (this.pool as any).entries.map((entry: any) => ({
+        channel: entry.channel,
+      }));
+    }
+    if ('activeEntries' in (this.pool as any)) {
+      return (this.pool as any).activeEntries.map((entry: any) => ({
+        channel: entry.channel,
+      }));
+    }
+    return [];
+  }
+
+  createCall(
+    method: string,
+    deadline: any,
+    host: any,
+    parentCall: any,
+    propagateFlags: any,
+  ): any {
+    // Fallback if call is initiated outside of callInvocationTransformer
+    const lease = this.pool.acquire();
+    const call = (lease.entry.channel as any).createCall(
+      method,
+      deadline,
+      host,
+      parentCall,
+      propagateFlags,
+    );
+    let released = false;
+    const releaseOnce = () => {
+      if (!released) {
+        released = true;
+        lease.release();
+      }
+    };
+    return new grpc.InterceptingCall(call, {
+      start: (metadata, listener, next) => {
+        next(metadata, {
+          onReceiveStatus: (status, nextStatus) => {
+            releaseOnce();
+            nextStatus(status);
+          },
+        });
+      },
+      cancel: next => {
+        releaseOnce();
+        next();
+      },
+    });
+  }
+}