@compforge/harness-toolbox 0.3.2 → 0.3.4

package/README.md

@@ -156,3 +156,93 @@ is not an arbitrary-SQL sandbox. This API requires MySQL 5.7.8+ `max_execution_t
 fall back to Pod Python. Completion, truncation, timeout, and cancellation destroy the disposable
 session without replay or changes to ordinary borrowed sessions. Disconnect does not prove immediate
 server cancellation. The byte budget limits retained JSON rows, not individual wire packets or fields.
+
+## Reusable bounded queries and read caches
+
+For trusted, caller-owned SELECT statements, `queryLimited(database, target, statement, maxRows)`
+appends an integer `LIMIT maxRows + 1` and returns `{ rows, truncated }`. SQL must not already have
+LIMIT or a trailing terminator; the helper does not parse or rewrite arbitrary SQL. Business values
+stay bound parameters. `limitedStatement` and `limitedRows` expose the same preparation/projection
+for `Database.queryBatch`. `maxRows` must be a positive integer below 2147483647. These helpers
+bound row count only: use `queryReadonly` when a disposable readonly session and byte/time budgets
+are required.
+
+`DataLoader` shares results, failures and in-flight work within one explicit read scope, similar to
+Guava's LoadingCache but scoped to a single collection round. Consumers must not mutate shared results.
+Use `withReadScope` to bind caller-approved database reads; do not use it for writes or polling.
+
+```ts
+import { DataLoader } from '@compforge/harness-toolbox/data-loader';
+import { withReadScope, queryLimited } from '@compforge/harness-toolbox/mysql';
+
+const scope = new DataLoader({
+  maxEntries: 256, maxBytes: 4 * 1024 * 1024, signal: client.signal,
+});
+const reads = withReadScope(client.database, scope);
+try {
+  const page = await queryLimited(reads, client.target, {
+    sql: 'SELECT id FROM items WHERE owner = ? ORDER BY id', values: [owner],
+  }, 100);
+} finally {
+  await scope.close(); // Root still owns client.dispose().
+}
+```
+
+Keys include full database identity, SQL and typed parameters as an opaque digest. Nonserializable
+parameters bypass caching. Batch reads reuse cached entries and send misses as one ordered native
+batch, or sequential queries when batching is unavailable. Failures are shared without replay;
+use a new scope for fresh observations. This is not a consistent database snapshot.
+
+Entry capacity includes failures and pending reads; new keys bypass caching when full. Serialized
+result bytes bound retained results, excluding keys/errors and active operation memory. Oversized
+or nonserializable results are returned but not retained. Scope close signals cancellation and joins
+operations, including uncached reads. Operations must honor the signal for prompt cancellation;
+MySQL reads retain their underlying client's timeout/cancellation policy. Adapter close owns neither
+the scope nor the database. A waiter's optional signal to `scope.read` cancels only that waiter.
+
+## Shared Pod relay transport
+
+`PodRelayTransport` opens TCP routes through an existing Running/Ready Pod. It discovers an
+eligible container in the selected namespace (optionally restricted by a label selector); the
+current implementation uses Python 3.8+ standard-library asyncio. Callers supply endpoints,
+not a Pod name or interpreter. It creates no Pods and installs no packages. The selected Pod
+must be able to resolve and reach each destination.
+
+Create one transport in the root execution's ClientManager and lend it to all Service/protocol
+clients. Its key describes cluster access and relay policy, never a Service or database identity.
+Concurrent callers share Pod discovery, one relay process and one forward per host/port. Database
+credentials and connections remain owned by their protocol clients.
+
+```ts
+import { ClientManager } from '@compforge/harness-toolbox';
+import { PodRelayTransport } from '@compforge/harness-toolbox/transport';
+
+const clients = new ClientManager();
+try {
+  const relay = await clients.get({
+    clientKey: 'transport:customer-cluster:app',
+    createClient: (_clients, signal) => new PodRelayTransport({
+      kubeconfig: '/config/cluster', context: 'customer', namespace: 'app',
+      selector: 'diagnostic-relay=eligible',
+      startupTimeoutMs: 5000, connectTimeoutMs: 5000,
+      maxConnections: 16, maxTargets: 8, maxCandidatePods: 8, signal,
+    }),
+  });
+  // The same instance belongs in each protocol client's ConnectionSource.transports.
+  const address = await relay.connect({host: 'database.internal', port: 3306});
+  // Connect the native protocol client to address; do not dispose relay in a Service.
+} finally {
+  await clients.dispose();
+}
+```
+
+The host must authorize `list pods`, `create pods/exec` and `create pods/portforward`, including
+running a temporary process in the selected container. List/discovery and each readiness operation
+use startupTimeoutMs; candidate Pod count, target count and aggregate live relay connections are
+bounded separately. List pods is namespace scoped. Relay listeners bind only to Pod loopback and
+local forwards only to host loopback. Control messages contain destinations, never DB credentials.
+
+Disposal closes forwards and the exec stream; EOF closes remote listeners/connections. If an exec
+connection is lost without EOF, a 30-second heartbeat lease bounds remote process lifetime.
+A dead relay invalidates its routes and fails callers; no SQL or other protocol operation is replayed.
+The root should finish or cancel protocol work before disposing the transport.

package/dist/chunk-1gyshqd9.js

@@ -0,0 +1,20 @@
+// src/mysql/limited.ts
+function validateLimit(maxRows) {
+  if (!Number.isSafeInteger(maxRows) || maxRows < 1 || maxRows >= 2147483647) {
+    throw new Error("maxRows must be a positive integer < 2147483647");
+  }
+}
+function limitedStatement(statement, maxRows) {
+  validateLimit(maxRows);
+  return { sql: `${statement.sql} LIMIT ${maxRows + 1}`, values: statement.values };
+}
+function limitedRows(rows, maxRows) {
+  validateLimit(maxRows);
+  return { rows: rows.slice(0, maxRows), truncated: rows.length > maxRows };
+}
+async function queryLimited(database, target, statement, maxRows) {
+  const bounded = limitedStatement(statement, maxRows);
+  return limitedRows(await database.query(target, bounded.sql, bounded.values), maxRows);
+}
+
+export { limitedStatement, limitedRows, queryLimited };

package/dist/{chunk-0cq1gx86.js → chunk-35cjec9z.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-zp1s833x.js";
 import {
   DirectTransport
-} from "./chunk-xy4g56g4.js";
+} from "./chunk-h8fwx0k7.js";
 
 // src/s3/datasource.ts
 class S3DataSource {

package/dist/chunk-4sqvppz7.js

@@ -0,0 +1,51 @@
+// src/mysql/scoped.ts
+import { createHash } from "node:crypto";
+import { serialize } from "node:v8";
+function queryKey(kind, target, statement) {
+  try {
+    return createHash("sha256").update(serialize([
+      kind,
+      target.host,
+      target.port,
+      target.database,
+      target.user,
+      target.password,
+      statement.sql,
+      statement.values
+    ])).digest("hex");
+  } catch {
+    return;
+  }
+}
+function withReadScope(database, scope) {
+  const query = (target, sql, values) => scope.read(queryKey("query", target, { sql, values }), () => database.query(target, sql, values));
+  return {
+    query,
+    queryOne: (target, sql, values) => scope.read(queryKey("one", target, { sql, values }), () => database.queryOne(target, sql, values)),
+    queryBatch: async (target, statements) => {
+      const misses = [];
+      let batch;
+      if (!statements.length)
+        return scope.read(undefined, async () => []);
+      return Promise.all(statements.map((statement) => scope.read(queryKey("query", target, statement), (signal) => {
+        const position = misses.length;
+        misses.push(statement);
+        batch ??= Promise.resolve().then(async () => {
+          signal.throwIfAborted();
+          if (database.queryBatch)
+            return database.queryBatch(target, misses);
+          const rows = [];
+          for (const item of misses) {
+            signal.throwIfAborted();
+            rows.push(await database.query(target, item.sql, item.values));
+          }
+          return rows;
+        });
+        return batch.then((rows) => rows[position]);
+      })));
+    },
+    close: async () => {}
+  };
+}
+
+export { withReadScope };

package/dist/{chunk-ssdxknsk.js → chunk-56t4qyp7.js}

@@ -1,17 +1,17 @@
-import {
-  queryReadonlySession,
-  validateQueryLimits
-} from "./chunk-kbewz29a.js";
 import {
   queryMysqlViaPod,
   queryMysqlViaPodBatch
 } from "./chunk-m91t44jh.js";
+import {
+  queryReadonlySession,
+  validateQueryLimits
+} from "./chunk-kbewz29a.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";
 import {
   isConnectionNetworkError
-} from "./chunk-xy4g56g4.js";
+} from "./chunk-h8fwx0k7.js";
 
 // src/mysql/client.ts
 import { createConnection } from "mysql2/promise";

package/dist/chunk-5fgbhx2r.js

@@ -0,0 +1,253 @@
+import {
+  startPortForward
+} from "./chunk-xh3zwhjh.js";
+import {
+  KubectlExecutor
+} from "./chunk-hmah9t8e.js";
+import {
+  POD_RELAY_SCRIPT
+} from "./chunk-ssj93brx.js";
+
+// src/transport/pod-relay.ts
+class PodRelayTransport {
+  options;
+  kind = "tcp";
+  name = "pod-relay";
+  #controller = new AbortController;
+  #signal;
+  #executor;
+  #startForward;
+  #targets = new Map;
+  #pending = new Map;
+  #forwards = [];
+  #startup;
+  #execution;
+  #input;
+  #heartbeat;
+  #failure;
+  #disposal;
+  #sequence = 0;
+  constructor(options, dependencies) {
+    this.options = options;
+    for (const key of ["startupTimeoutMs", "connectTimeoutMs", "maxConnections", "maxTargets", "maxCandidatePods"]) {
+      if (!Number.isSafeInteger(options[key]) || options[key] <= 0)
+        throw new Error(`${key} must be a positive integer`);
+    }
+    this.#executor = dependencies?.executor ?? new KubectlExecutor(options);
+    this.#startForward = dependencies?.startForward ?? startPortForward;
+    this.#signal = options.signal ? AbortSignal.any([options.signal, this.#controller.signal]) : this.#controller.signal;
+    this.#signal.addEventListener("abort", this.#onAbort, { once: true });
+  }
+  async initialize() {
+    this.#check();
+  }
+  #check() {
+    this.#signal.throwIfAborted();
+    if (this.#failure)
+      throw this.#failure;
+  }
+  #onAbort = () => {
+    this.#fail(new Error("Pod relay aborted"));
+  };
+  #fail(error) {
+    this.#failure ??= error;
+    if (this.#heartbeat)
+      clearInterval(this.#heartbeat);
+    if (this.#input) {
+      try {
+        this.#input.close();
+      } catch {}
+    }
+    this.#input = undefined;
+    for (const pending of this.#pending.values())
+      pending.reject(this.#failure);
+    this.#pending.clear();
+    for (const forward of this.#forwards.splice(0))
+      forward.stop();
+  }
+  async#select() {
+    const command = ["get", "pods", "--field-selector=status.phase=Running", "-o", "json"];
+    if (this.options.selector)
+      command.push("-l", this.options.selector);
+    const listed = await this.#executor.run(command, { timeoutMs: this.options.startupTimeoutMs, signal: this.#signal });
+    if (!listed.ok)
+      throw new Error("Cannot discover an existing Pod for relay");
+    const pods = JSON.parse(listed.stdout).items.filter((pod) => pod.status?.phase === "Running" && !pod.metadata?.deletionTimestamp).sort((a, b) => (a.metadata?.name ?? "").localeCompare(b.metadata?.name ?? "")).slice(0, this.options.maxCandidatePods);
+    for (const pod of pods) {
+      if (!pod.metadata?.name)
+        continue;
+      for (const container of pod.status?.containerStatuses ?? []) {
+        if (!container.ready)
+          continue;
+        const target = { pod: pod.metadata.name, container: container.name };
+        for (const executable of ["python3", "python"]) {
+          this.#check();
+          const probe = await this.#executor.exec(target, [executable, "-c", "import asyncio,sys; assert sys.version_info >= (3, 8); print('relay-ready')"], { timeoutMs: this.options.startupTimeoutMs, signal: this.#signal });
+          if (probe.ok && probe.stdout.trim() === "relay-ready")
+            return { target, executable };
+        }
+      }
+    }
+    throw new Error("No eligible existing Pod can run the TCP relay");
+  }
+  async#start() {
+    const pod = await this.#select();
+    this.#check();
+    const input = new ReadableStream({ start: (controller) => {
+      this.#input = controller;
+    } });
+    let ready;
+    let rejectReady;
+    const readiness = new Promise((resolve, reject) => {
+      ready = resolve;
+      rejectReady = reject;
+    });
+    let buffered = "";
+    const config = {
+      connectTimeoutMs: this.options.connectTimeoutMs,
+      maxConnections: this.options.maxConnections,
+      maxTargets: this.options.maxTargets,
+      leaseMs: 30000
+    };
+    this.#execution = this.#executor.exec(pod.target, [pod.executable, "-u", "-c", POD_RELAY_SCRIPT, JSON.stringify(config)], {
+      stdin: input,
+      signal: this.#signal,
+      timeoutMs: 2147483647,
+      collectStdout: false,
+      onStdout: (chunk) => {
+        buffered += chunk;
+        if (buffered.length > 65536) {
+          this.#fail(new Error("Pod relay control response exceeded limit"));
+          return;
+        }
+        while (buffered.includes(`
+`)) {
+          const end = buffered.indexOf(`
+`);
+          const line = buffered.slice(0, end);
+          buffered = buffered.slice(end + 1);
+          try {
+            const response = JSON.parse(line);
+            if (response.ready)
+              ready();
+            else if (response.id !== undefined) {
+              const pending = this.#pending.get(response.id);
+              this.#pending.delete(response.id);
+              if (Number.isInteger(response.port) && response.port > 0 && response.port <= 65535)
+                pending?.resolve(response.port);
+              else
+                pending?.reject(new Error("Pod relay listener unavailable"));
+            }
+          } catch {
+            this.#fail(new Error("Invalid Pod relay control response"));
+          }
+        }
+      }
+    }).then(() => {
+      const error = new Error("Pod relay execution ended");
+      rejectReady(error);
+      this.#fail(error);
+    }, () => {
+      const error = new Error("Pod relay execution failed");
+      rejectReady(error);
+      this.#fail(error);
+    });
+    this.#heartbeat = setInterval(() => {
+      try {
+        this.#send({ heartbeat: true });
+      } catch {
+        this.#fail(new Error("Pod relay control channel closed"));
+      }
+    }, 5000);
+    const timer = setTimeout(() => rejectReady(new Error("Pod relay startup timed out")), this.options.startupTimeoutMs);
+    try {
+      await readiness;
+      this.#check();
+      return pod;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  #send(value) {
+    this.#check();
+    if (!this.#input)
+      throw new Error("Pod relay control channel unavailable");
+    this.#input.enqueue(new TextEncoder().encode(`${JSON.stringify(value)}
+`));
+  }
+  connect(endpoint) {
+    this.#check();
+    if (!endpoint.host || !Number.isInteger(endpoint.port) || endpoint.port < 1 || endpoint.port > 65535) {
+      return Promise.reject(new Error("Invalid relay endpoint"));
+    }
+    const key = JSON.stringify([endpoint.host, endpoint.port]);
+    let pending = this.#targets.get(key);
+    if (!pending) {
+      if (this.#targets.size >= this.options.maxTargets)
+        return Promise.reject(new Error("Pod relay target limit reached"));
+      this.#startup ??= this.#start().catch((error) => {
+        this.#fail(error instanceof Error ? error : new Error("Pod relay startup failed"));
+        throw error;
+      });
+      pending = this.#connect(endpoint, this.#startup);
+      this.#targets.set(key, pending);
+    }
+    return pending.then((local) => ({ ...local, servername: endpoint.servername ?? endpoint.host }));
+  }
+  async#connect(endpoint, startup) {
+    const pod = await startup;
+    this.#check();
+    const id = ++this.#sequence;
+    const remotePort = await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(new Error("Pod relay listener timed out"));
+      }, this.options.startupTimeoutMs);
+      this.#pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      });
+      try {
+        this.#send({ id, host: endpoint.host, port: endpoint.port });
+      } catch (error) {
+        this.#pending.get(id)?.reject(error);
+        this.#pending.delete(id);
+      }
+    });
+    this.#check();
+    const forwarded = await this.#startForward({
+      ...this.options,
+      target: { kind: "pod", name: pod.target.pod },
+      remotePort,
+      timeoutMs: this.options.startupTimeoutMs
+    });
+    if (!forwarded.ok || !forwarded.value)
+      throw new Error("Pod relay port-forward unavailable");
+    try {
+      this.#check();
+    } catch (error) {
+      forwarded.value.stop();
+      throw error;
+    }
+    this.#forwards.push(forwarded.value);
+    return { host: "127.0.0.1", port: forwarded.value.localPort };
+  }
+  dispose() {
+    return this.#disposal ??= (async () => {
+      this.#controller.abort(new Error("Pod relay disposed"));
+      this.#fail(new Error("Pod relay disposed"));
+      await Promise.allSettled(this.#targets.values());
+      await this.#execution;
+      this.#signal.removeEventListener("abort", this.#onAbort);
+      this.#targets.clear();
+    })();
+  }
+}
+
+export { PodRelayTransport };

package/dist/{chunk-0rs1aacd.js → chunk-hmah9t8e.js}

@@ -1,6 +1,6 @@
 import {
   spawnProcess
-} from "./chunk-ztenxgjv.js";
+} from "./chunk-mn6dwsvh.js";
 
 // src/kubernetes/executor.ts
 function buildKubectlArgs(opts, sub) {

package/dist/{chunk-ztenxgjv.js → chunk-mn6dwsvh.js}

@@ -8,7 +8,14 @@ function spawnProcess(argv, opts) {
     stdio: "pipe",
     env: opts?.env
   });
-  child.stdin.end(opts?.stdin);
+  if (opts?.stdin instanceof ReadableStream) {
+    const input = Readable.fromWeb(opts.stdin);
+    input.on("error", () => child.stdin.destroy());
+    child.stdin.on("error", () => input.destroy());
+    child.once("close", () => input.destroy());
+    input.pipe(child.stdin);
+  } else
+    child.stdin.end(opts?.stdin);
   const exited = new Promise((resolve, reject) => {
     child.once("error", reject);
     child.once("close", (code) => resolve(code ?? 1));

package/dist/{chunk-205a4vma.js → chunk-qhpqse1y.js}

@@ -1,6 +1,3 @@
-import {
-  PortForwardScope
-} from "./chunk-hv2kx47y.js";
 import {
   findPodsForService,
   findService,
@@ -9,6 +6,9 @@ import {
 import {
   findPod
 } from "./chunk-6fnhzhdb.js";
+import {
+  PortForwardScope
+} from "./chunk-xh3zwhjh.js";
 
 // src/kubernetes/service-port-forward.ts
 class ServicePortForwarder {

package/dist/chunk-ssj93brx.js

@@ -0,0 +1,89 @@
+// src/transport/pod-relay-script.ts
+var POD_RELAY_SCRIPT = String.raw`
+import asyncio, json, sys
+
+async def main():
+    config = json.loads(sys.argv[1])
+    loop = asyncio.get_running_loop()
+    reader = asyncio.StreamReader(limit=4096)
+    await loop.connect_read_pipe(lambda: asyncio.StreamReaderProtocol(reader), sys.stdin.buffer)
+    servers = []
+    active = set()
+
+    async def pipe(source, destination):
+        while True:
+            chunk = await source.read(65536)
+            if not chunk:
+                if destination.can_write_eof():
+                    destination.write_eof()
+                return
+            destination.write(chunk)
+            await destination.drain()
+
+    async def relay(source, destination, host, port):
+        task = asyncio.current_task()
+        if len(active) >= config["maxConnections"]:
+            destination.close()
+            await destination.wait_closed()
+            return
+        active.add(task)
+        upstream = None
+        pumps = []
+        try:
+            remote, upstream = await asyncio.wait_for(
+                asyncio.open_connection(host, port), config["connectTimeoutMs"] / 1000)
+            pumps = [asyncio.create_task(pipe(source, upstream)), asyncio.create_task(pipe(remote, destination))]
+            await asyncio.gather(*pumps)
+        except (OSError, asyncio.TimeoutError):
+            pass
+        finally:
+            for pump in pumps:
+                pump.cancel()
+            await asyncio.gather(*pumps, return_exceptions=True)
+            for writer in (upstream, destination):
+                if writer:
+                    writer.close()
+            for writer in (upstream, destination):
+                if writer:
+                    try:
+                        await writer.wait_closed()
+                    except OSError:
+                        pass
+            active.discard(task)
+
+    print(json.dumps({"ready": True}), flush=True)
+    try:
+        while True:
+            # EOF cleans up normal shutdown; lease expiry bounds an orphan after lost exec transport.
+            line = await asyncio.wait_for(reader.readline(), config["leaseMs"] / 1000)
+            if not line:
+                break
+            request = json.loads(line)
+            if request.get("heartbeat"):
+                continue
+            identifier = request["id"]
+            try:
+                if len(servers) >= config["maxTargets"]:
+                    raise ValueError("target limit")
+                host, port = request["host"], request["port"]
+                server = await asyncio.start_server(
+                    lambda r, w, h=host, p=port: relay(r, w, h, p), "127.0.0.1", 0)
+                servers.append(server)
+                print(json.dumps({"id": identifier, "port": server.sockets[0].getsockname()[1]}), flush=True)
+            except (OSError, ValueError):
+                print(json.dumps({"id": identifier, "error": "relay listener unavailable"}), flush=True)
+    except asyncio.TimeoutError:
+        pass
+    finally:
+        for server in servers:
+            server.close()
+        await asyncio.gather(*(server.wait_closed() for server in servers))
+        tasks = list(active)
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+asyncio.run(main())
+`;
+
+export { POD_RELAY_SCRIPT };

package/dist/{chunk-4pdwsfcx.js → chunk-td11zjfb.js}

@@ -1,18 +1,18 @@
 import {
-  ServicePortForwarder
-} from "./chunk-205a4vma.js";
+  resolveWorkload
+} from "./chunk-y3dx8jh6.js";
 import {
-  KubectlExecutor
-} from "./chunk-0rs1aacd.js";
+  ServicePortForwarder
+} from "./chunk-qhpqse1y.js";
 import {
   resourceAccess
-} from "./chunk-1kpbvat9.js";
-import {
-  resolveWorkload
-} from "./chunk-y3dx8jh6.js";
+} from "./chunk-2m0mh09h.js";
 import {
   KubernetesError
 } from "./chunk-ntfm5e85.js";
+import {
+  KubectlExecutor
+} from "./chunk-hmah9t8e.js";
 
 // src/kubernetes/client.ts
 class KubernetesClient {

package/dist/{chunk-hv2kx47y.js → chunk-xh3zwhjh.js}

@@ -1,10 +1,10 @@
 import {
   buildKubectlArgs
-} from "./chunk-0rs1aacd.js";
+} from "./chunk-hmah9t8e.js";
 import {
   sleep,
   spawnProcess
-} from "./chunk-ztenxgjv.js";
+} from "./chunk-mn6dwsvh.js";
 
 // src/kubernetes/port-forward.ts
 async function startPortForward(opts) {

package/dist/data-loader.d.ts

@@ -0,0 +1,21 @@
+export interface DataLoaderOptions {
+    maxEntries: number;
+    /** Serialized result bytes retained, excluding keys/errors and active operation memory. */
+    maxBytes: number;
+    signal: AbortSignal;
+}
+/** A scoped async loading cache, similar to Guava's LoadingCache.
+ * Shares results, failures and in-flight reads until close; consumers must not mutate results.
+ * Unlike a long-lived LoadingCache, this scope has no refresh/expiry or automatic batching.
+ * Keys and loading operations belong to adapters; the same key must have the same result type.
+ * Operations must honor their signal for prompt cancellation. No underlying client is owned.
+ */
+export declare class DataLoader {
+    #private;
+    private readonly options;
+    constructor(options: DataLoaderOptions);
+    /** Undefined keys bypass caching. A waiter's signal cancels only that wait, not shared work. */
+    read<T>(key: unknown, operation: (signal: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /** Abort cooperative operations and join all reads, including capacity-bypass reads. */
+    close(reason?: unknown): Promise<void>;
+}

package/dist/data-loader.js

@@ -0,0 +1,91 @@
+// src/data-loader.ts
+import { serialize } from "node:v8";
+
+class DataLoader {
+  options;
+  #entries = new Map;
+  #pending = new Set;
+  #controller = new AbortController;
+  #bytes = 0;
+  #closing;
+  constructor(options) {
+    this.options = options;
+    for (const name of ["maxEntries", "maxBytes"]) {
+      if (!Number.isSafeInteger(options[name]) || options[name] < 1)
+        throw new Error(`${name} must be a positive safe integer`);
+    }
+    options.signal.throwIfAborted();
+    options.signal.addEventListener("abort", this.#abort, { once: true });
+  }
+  #abort = () => {
+    this.close(this.options.signal.reason);
+  };
+  async read(key, operation, signal) {
+    this.#controller.signal.throwIfAborted();
+    signal?.throwIfAborted();
+    let pending = key === undefined ? undefined : this.#entries.get(key);
+    if (!pending) {
+      const retain = key !== undefined && this.#entries.size < this.options.maxEntries;
+      pending = Promise.resolve().then(async () => {
+        this.#controller.signal.throwIfAborted();
+        const value = await operation(this.#controller.signal);
+        this.#controller.signal.throwIfAborted();
+        if (retain) {
+          let bytes;
+          try {
+            bytes = serialize(value).byteLength;
+          } catch {
+            bytes = Infinity;
+          }
+          if (this.#bytes + bytes <= this.options.maxBytes)
+            this.#bytes += bytes;
+          else
+            this.#entries.delete(key);
+        }
+        return value;
+      });
+      if (retain)
+        this.#entries.set(key, pending);
+      this.#pending.add(pending);
+      const done = () => {
+        this.#pending.delete(pending);
+      };
+      pending.then(done, done);
+    }
+    if (!signal)
+      return await pending;
+    return new Promise((resolve, reject) => {
+      const abort = () => {
+        cleanup();
+        reject(signal.reason);
+      };
+      const cleanup = () => {
+        signal.removeEventListener("abort", abort);
+      };
+      signal.addEventListener("abort", abort, { once: true });
+      pending.then((value) => {
+        cleanup();
+        resolve(value);
+      }, (error) => {
+        cleanup();
+        reject(error);
+      });
+    });
+  }
+  close(reason = new Error("DataLoader scope is closed")) {
+    if (!this.#closing) {
+      this.#closing = Promise.resolve().then(async () => {
+        await Promise.allSettled([...this.#pending]);
+        this.#entries.clear();
+        this.#bytes = 0;
+      });
+      this.options.signal.removeEventListener("abort", this.#abort);
+      this.#controller.abort(reason);
+      this.#entries.clear();
+    }
+    return this.#closing;
+  }
+}
+export {
+  DataLoader
+};

package/dist/kubernetes/client.js

@@ -1,16 +1,16 @@
 import {
   KubernetesClient
-} from "../chunk-4pdwsfcx.js";
-import"../chunk-205a4vma.js";
-import"../chunk-hv2kx47y.js";
+} from "../chunk-td11zjfb.js";
+import"../chunk-y3dx8jh6.js";
+import"../chunk-qhpqse1y.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-0rs1aacd.js";
-import"../chunk-ztenxgjv.js";
-import"../chunk-1kpbvat9.js";
-import"../chunk-y3dx8jh6.js";
-import"../chunk-v3hxvnrc.js";
+import"../chunk-2m0mh09h.js";
 import"../chunk-ntfm5e85.js";
+import"../chunk-v3hxvnrc.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
 export {
   KubernetesClient
 };

package/dist/kubernetes/environment.js

@@ -1,19 +1,19 @@
 import {
   KubernetesClient
-} from "../chunk-4pdwsfcx.js";
-import"../chunk-205a4vma.js";
-import"../chunk-hv2kx47y.js";
+} from "../chunk-td11zjfb.js";
+import"../chunk-y3dx8jh6.js";
+import"../chunk-qhpqse1y.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-0rs1aacd.js";
-import"../chunk-ztenxgjv.js";
-import"../chunk-1kpbvat9.js";
-import"../chunk-y3dx8jh6.js";
+import"../chunk-2m0mh09h.js";
 import {
   clientKey
 } from "../chunk-a9htb6cr.js";
-import"../chunk-v3hxvnrc.js";
 import"../chunk-ntfm5e85.js";
+import"../chunk-v3hxvnrc.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
 
 // src/kubernetes/environment.ts
 class KubernetesEnvironment {

package/dist/kubernetes/executor.d.ts

@@ -9,7 +9,7 @@ export interface ExecTarget {
     container?: string;
 }
 export interface RunOptions {
-    stdin?: string | Uint8Array;
+    stdin?: string | Uint8Array | ReadableStream<Uint8Array>;
     timeoutMs?: number;
     signal?: AbortSignal;
     onStdout?: (chunk: string) => void;

package/dist/kubernetes/executor.js

@@ -3,8 +3,8 @@ import {
   buildExecArgs,
   buildKubectlArgs,
   runArgv
-} from "../chunk-0rs1aacd.js";
-import"../chunk-ztenxgjv.js";
+} from "../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
 export {
   runArgv,
   buildKubectlArgs,

package/dist/kubernetes/pod-log-datasource.js

@@ -8,8 +8,8 @@ import"../chunk-a9htb6cr.js";
 import {
   clientKey
 } from "../chunk-z5pm2emz.js";
-import"../chunk-v3hxvnrc.js";
 import"../chunk-ntfm5e85.js";
+import"../chunk-v3hxvnrc.js";
 
 // src/kubernetes/pod-log-datasource.ts
 class PodLogDataSource {

package/dist/kubernetes/port-forward.js

@@ -1,9 +1,9 @@
 import {
   PortForwardScope,
   startPortForward
-} from "../chunk-hv2kx47y.js";
-import"../chunk-0rs1aacd.js";
-import"../chunk-ztenxgjv.js";
+} from "../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
 export {
   startPortForward,
   PortForwardScope

package/dist/kubernetes/resources.js

@@ -1,8 +1,8 @@
 import {
   resourceAccess
-} from "../chunk-1kpbvat9.js";
-import"../chunk-v3hxvnrc.js";
+} from "../chunk-2m0mh09h.js";
 import"../chunk-ntfm5e85.js";
+import"../chunk-v3hxvnrc.js";
 export {
   resourceAccess
 };

package/dist/kubernetes/service-port-forward.js

@@ -1,11 +1,11 @@
 import {
   ServicePortForwarder
-} from "../chunk-205a4vma.js";
-import"../chunk-hv2kx47y.js";
+} from "../chunk-qhpqse1y.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-0rs1aacd.js";
-import"../chunk-ztenxgjv.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
 export {
   ServicePortForwarder
 };

package/dist/mysql/client.js

@@ -2,11 +2,16 @@ import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-ssdxknsk.js";
-import"../chunk-kbewz29a.js";
+} from "../chunk-56t4qyp7.js";
 import"../chunk-m91t44jh.js";
+import"../chunk-kbewz29a.js";
 import"../chunk-v3hxvnrc.js";
-import"../chunk-xy4g56g4.js";
+import"../chunk-h8fwx0k7.js";
+import"../chunk-5fgbhx2r.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   openMysql,
   MysqlDatabase,

package/dist/mysql/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./types";
 export * from "./target";
 export * from "./client";
+export * from "./limited";
+export * from "./scoped";

package/dist/mysql/index.js

@@ -1,19 +1,36 @@
-import {
-  parseMysqlEnvTarget
-} from "../chunk-qq77x9ek.js";
 import"../chunk-pfar9cm3.js";
+import {
+  withReadScope
+} from "../chunk-4sqvppz7.js";
 import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-ssdxknsk.js";
-import"../chunk-kbewz29a.js";
+} from "../chunk-56t4qyp7.js";
 import"../chunk-m91t44jh.js";
+import"../chunk-kbewz29a.js";
+import {
+  parseMysqlEnvTarget
+} from "../chunk-qq77x9ek.js";
+import {
+  limitedRows,
+  limitedStatement,
+  queryLimited
+} from "../chunk-1gyshqd9.js";
 import"../chunk-v3hxvnrc.js";
-import"../chunk-xy4g56g4.js";
+import"../chunk-h8fwx0k7.js";
+import"../chunk-5fgbhx2r.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
+  withReadScope,
+  queryLimited,
   parseMysqlEnvTarget,
   openMysql,
+  limitedStatement,
+  limitedRows,
   MysqlDatabase,
   MysqlClient
 };

package/dist/mysql/limited.d.ts

@@ -0,0 +1,13 @@
+import type { Database, DatabaseRow, DatabaseTarget, SqlStatement } from "./types";
+export interface LimitedRows {
+    rows: DatabaseRow[];
+    truncated: boolean;
+}
+/** Append to caller-owned SQL without an existing LIMIT or trailing terminator; never rewrite SQL.
+ * An integer literal avoids driver/server differences in numeric LIMIT parameter binding.
+ */
+export declare function limitedStatement(statement: SqlStatement, maxRows: number): SqlStatement;
+/** The extra row proves truncation; batch callers can use the same projection. */
+export declare function limitedRows(rows: DatabaseRow[], maxRows: number): LimitedRows;
+/** Row-count bound for trusted reads on the existing session, not a readonly transaction or byte cap. */
+export declare function queryLimited(database: Pick<Database, "query">, target: DatabaseTarget, statement: SqlStatement, maxRows: number): Promise<LimitedRows>;

package/dist/mysql/limited.js

@@ -0,0 +1,10 @@
+import {
+  limitedRows,
+  limitedStatement,
+  queryLimited
+} from "../chunk-1gyshqd9.js";
+export {
+  queryLimited,
+  limitedStatement,
+  limitedRows
+};

package/dist/mysql/scoped.d.ts

@@ -0,0 +1,7 @@
+import type { DataLoader } from "../data-loader";
+import type { Database } from "./types";
+/** Bind caller-approved reads to a borrowed scope. Results are shared and must not be mutated.
+ * Close is a no-op: the root owns both scope and database lifetimes. Database operations retain
+ * their client's cancellation/timeout policy; they cannot be individually aborted by this adapter.
+ */
+export declare function withReadScope(database: Database, scope: DataLoader): Database & Required<Pick<Database, "queryBatch">>;

package/dist/mysql/scoped.js

@@ -0,0 +1,6 @@
+import {
+  withReadScope
+} from "../chunk-4sqvppz7.js";
+export {
+  withReadScope
+};

package/dist/mysql/types.d.ts

@@ -29,5 +29,7 @@ export interface DatabaseQueryResult {
 export interface Database {
     query(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow[]>;
     queryOne(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow | undefined>;
+    /** Independent statements in submission order; fail-fast, without atomicity or replay. */
+    queryBatch?(target: DatabaseTarget, statements: readonly SqlStatement[]): Promise<DatabaseRow[][]>;
     close(): Promise<void>;
 }

package/dist/process/index.d.ts

@@ -5,7 +5,7 @@ export interface RuntimeProcess {
     kill(): void;
 }
 export interface SpawnProcessOptions {
-    stdin?: string | Uint8Array;
+    stdin?: string | Uint8Array | ReadableStream<Uint8Array>;
     env?: NodeJS.ProcessEnv;
 }
 /** 使用 Node-compatible 子进程 API，不要求调用方使用 Bun runtime。 */

package/dist/process/index.js

@@ -1,7 +1,7 @@
 import {
   sleep,
   spawnProcess
-} from "../chunk-ztenxgjv.js";
+} from "../chunk-mn6dwsvh.js";
 export {
   spawnProcess,
   sleep

package/dist/redis/index.js

@@ -1,3 +1,7 @@
+import {
+  collectRedisKeyStats,
+  redisGroupedSampleSizes
+} from "../chunk-jr9y0ghr.js";
 import {
   discoverRedisTopology
 } from "../chunk-c6z919qb.js";
@@ -8,10 +12,6 @@ import {
   openRedis,
   parseRedisInfo
 } from "../chunk-ajhdd4hp.js";
-import {
-  collectRedisKeyStats,
-  redisGroupedSampleSizes
-} from "../chunk-jr9y0ghr.js";
 export {
   redisGroupedSampleSizes,
   parseRedisInfo,

package/dist/s3/datasource.js

@@ -1,12 +1,17 @@
 import {
   S3DataSource
-} from "../chunk-0cq1gx86.js";
+} from "../chunk-35cjec9z.js";
 import"../chunk-z5pm2emz.js";
+import"../chunk-ntfm5e85.js";
 import"../chunk-zp1s833x.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-x4ntb898.js";
-import"../chunk-xy4g56g4.js";
-import"../chunk-ntfm5e85.js";
+import"../chunk-h8fwx0k7.js";
+import"../chunk-5fgbhx2r.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   S3DataSource
 };

package/dist/s3/index.js

@@ -1,14 +1,19 @@
 import {
   S3DataSource
-} from "../chunk-0cq1gx86.js";
+} from "../chunk-35cjec9z.js";
 import"../chunk-z5pm2emz.js";
+import"../chunk-ntfm5e85.js";
 import {
   S3Client
 } from "../chunk-zp1s833x.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-x4ntb898.js";
-import"../chunk-xy4g56g4.js";
-import"../chunk-ntfm5e85.js";
+import"../chunk-h8fwx0k7.js";
+import"../chunk-5fgbhx2r.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   S3DataSource,
   S3Client

package/dist/transport/index.d.ts

@@ -38,3 +38,4 @@ export declare class PodPythonTransport {
 export type Transport = TcpTransport | PodPythonTransport;
 /** Only failure to establish a connection permits a route change; never replay protocol operations. */
 export declare function isConnectionNetworkError(error: unknown): boolean;
+export { PodRelayTransport, type PodRelayOptions } from "./pod-relay";

package/dist/transport/index.js

@@ -3,10 +3,18 @@ import {
   PodPythonTransport,
   PortForwardTransport,
   isConnectionNetworkError
-} from "../chunk-xy4g56g4.js";
+} from "../chunk-h8fwx0k7.js";
+import {
+  PodRelayTransport
+} from "../chunk-5fgbhx2r.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   isConnectionNetworkError,
   PortForwardTransport,
+  PodRelayTransport,
   PodPythonTransport,
   DirectTransport
 };

package/dist/transport/pod-relay-script.d.ts

@@ -0,0 +1,2 @@
+/** Private wire protocol: control travels over exec stdin; database bytes only over TCP. */
+export declare const POD_RELAY_SCRIPT: string;

package/dist/transport/pod-relay-script.js

@@ -0,0 +1,6 @@
+import {
+  POD_RELAY_SCRIPT
+} from "../chunk-ssj93brx.js";
+export {
+  POD_RELAY_SCRIPT
+};

package/dist/transport/pod-relay.d.ts

@@ -0,0 +1,31 @@
+import type { Client } from "../client";
+import { type Executor, type KubectlOptions } from "../kubernetes/executor";
+import { type StartPortForward } from "../kubernetes/port-forward";
+import type { Endpoint, TcpTransport } from "./index";
+export interface PodRelayOptions extends KubectlOptions {
+    namespace: string;
+    /** Restrict eligible existing Pods without coupling callers to the relay runtime. */
+    selector?: string;
+    startupTimeoutMs: number;
+    connectTimeoutMs: number;
+    maxConnections: number;
+    maxTargets: number;
+    maxCandidatePods: number;
+    signal?: AbortSignal;
+}
+/** Execution-scoped TCP transport borrowed by all Service clients; only its root owner disposes it.
+ * Python is private. Requires list pods, pods/exec and pods/portforward, never pods/create.
+ */
+export declare class PodRelayTransport implements TcpTransport, Client {
+    #private;
+    private readonly options;
+    readonly kind = "tcp";
+    readonly name = "pod-relay";
+    constructor(options: PodRelayOptions, dependencies?: {
+        executor?: Executor;
+        startForward?: StartPortForward;
+    });
+    initialize(): Promise<void>;
+    connect(endpoint: Endpoint): Promise<Endpoint>;
+    dispose(): Promise<void>;
+}

package/dist/transport/pod-relay.js

@@ -0,0 +1,10 @@
+import {
+  PodRelayTransport
+} from "../chunk-5fgbhx2r.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
+export {
+  PodRelayTransport
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -80,6 +80,10 @@
     "./concurrency": {
       "types": "./dist/concurrency.d.ts",
       "import": "./dist/concurrency.js"
+    },
+    "./data-loader": {
+      "types": "./dist/data-loader.d.ts",
+      "import": "./dist/data-loader.js"
     }
   },
   "files": [

package/dist/{chunk-1kpbvat9.js → chunk-2m0mh09h.js}

@@ -1,11 +1,11 @@
-import {
-  ConcurrencyPool
-} from "./chunk-v3hxvnrc.js";
 import {
   KubernetesError,
   ToolboxError,
   kubernetesHttpError
 } from "./chunk-ntfm5e85.js";
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
 
 // src/kubernetes/resources.ts
 import { KubeConfig } from "@kubernetes/client-node";